whisper-transcribe-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

whisper-transcribe-mcp is a Python MCP (Model Context Protocol) server that exposes audio transcription tools using either faster-whisper (local, offline) or the OpenAI Whisper API (cloud). Published on PyPI and consumed via uvx or pip.

Development Setup

# Install the locked development environment with all optional backends
uv sync --group dev --extra all

# Run the same checks as CI
uv run ruff check .
uv run ruff format --check .
uv run pytest -q

Running the Server Locally

# Local backend
WHISPER_MODEL=base python -m whisper_transcribe.server

# OpenAI backend
OPENAI_API_KEY=sk-... python -m whisper_transcribe.server

Building and Publishing

# Build the package
uv build

# Release a new version from a clean main branch. This synchronizes pyproject.toml,
# uv.lock, and server.json, waits for CI, tags the release, and creates the GitHub release.
./release.sh 1.2.3

Pushing the version tag triggers .github/workflows/publish.yml, which publishes first to PyPI and then to the official MCP Registry using OIDC. See docs/publishing.md for the full checklist.

Architecture

The entire server lives in a single file: whisper_transcribe/server.py.

• Built on FastMCP (fastmcp>=3.2.0, the first release without known advisories), which handles MCP protocol, tool registration, and stdio transport.
• Backend selection is determined at startup by the presence of OPENAI_API_KEY — there is no runtime switching.
• The local WhisperModel is lazily loaded and cached in _local_model (module-level global), and reloaded only if the requested model_size changes.
• transcribe_base64 delegates to transcribe_file after writing a temp file, then cleans it up.
• Tool inputs (language, model_size, extension) are validated against allowlists before use; OpenAI errors are summarized (type + HTTP status) and the raw message only goes to stderr.