transdex-mcp

Contents

• What Is This?

• Client Modes

• Architecture

• Remote Tool Contract

• Quick Start

• Connect an MCP Client

• Configuration

• Security and Privacy

• Local Workflow

• Project Structure

• Testing

• Troubleshooting

• Roadmap

• License

Related MCP server: whisper-transcribe-mcp

What Is This?

transdex-mcp is a standalone MCP codebase for transcription and translation workflows. It has its own Git history, package identity, configuration path, model cache, server entry points, and deployment policy.

The default transcription profile is:

This repository is a pre-release implementation. It is not ready for public directory submission or untrusted multi-instance deployment.

Client Modes

MCP is the product boundary. Client-specific behavior is kept at the connection edge.

Codex and ChatGPT both support MCP servers. The repository does not require a custom widget; clients can call the tools directly. See OpenAI's MCP documentation for current client configuration behavior.

Architecture

MCP client
  |
  +-- Local stdio
  |     +-- Workspace roots
  |     +-- Plan / preview / confirm
  |     +-- Translation and transcription jobs
  |
  +-- Remote Streamable HTTP
        +-- Validate and stage a remote media reference
        +-- Enforce byte, duration, queue, and session limits
        +-- Run whisper.cpp asynchronously
        +-- Return opaque signed result links

Both transports use the same validated JobSpec, safe sidecar writer, transcription providers, subtitle preservation rules, and cancellation path.

Remote Tool Contract

Compatible OpenAI hosts can inject a top-level file parameter declared through openai/fileParams:

{
  "download_url": "https://temporary.example/media",
  "file_id": "file_example",
  "mime_type": "video/mp4",
  "file_name": "recording.mp4"
}

The server downloads the bytes during start_transcription; it never stores a temporary URL for a background worker. Nested file parameters are intentionally unsupported.

Quick Start

1. Install Node dependencies

npm ci

Node.js 20 or newer is required.

2. Build whisper.cpp

git clone https://github.com/ggml-org/whisper.cpp.git "$HOME/.local/share/whisper.cpp"
cmake -S "$HOME/.local/share/whisper.cpp" \
  -B "$HOME/.local/share/whisper.cpp/build" \
  -DCMAKE_BUILD_TYPE=Release
cmake --build "$HOME/.local/share/whisper.cpp/build" -j 4

Pin a reviewed whisper.cpp revision for deployment rather than building an unpinned branch.

3. Provision models

cd "$HOME/.local/share/whisper.cpp"
bash ./models/download-ggml-model.sh large-v3-turbo-q5_0
bash ./models/download-vad-model.sh silero-v6.2.0

Model weights and the whisper.cpp binary are not bundled. Remote deployments should provision them while building the service image and keep request-time auto-download disabled.

4. Configure the runtime

export TRANSDEX_WHISPER_CPP_BIN="$HOME/.local/share/whisper.cpp/build/bin/whisper-cli"
export TRANSDEX_WHISPER_CPP_MODEL_DIR="$HOME/.local/share/whisper.cpp/models"
export TRANSDEX_WHISPER_CPP_MODEL=large-v3-turbo-q5_0
export TRANSDEX_WHISPER_CPP_VAD=1
export TRANSDEX_WHISPER_CPP_VAD_MODEL="$HOME/.local/share/whisper.cpp/models/ggml-silero-v6.2.0.bin"
export TRANSDEX_WHISPER_CPP_AUTO_DOWNLOAD=0

Use .env.example as the remote deployment checklist. The application does not load dotenv files automatically.

5. Start a transport

Local stdio:

npm run mcp

Local HTTP development server:

npm start

The default development endpoints are:

http://127.0.0.1:8787/mcp
http://127.0.0.1:8787/healthz

Connect an MCP Client

Codex with local stdio

Use an absolute checkout path:

codex mcp add transdex -- node /absolute/path/to/transdex-mcp/src/mcp/main.js
codex mcp list

The checked-in .mcp.json contains the equivalent repository-local definition for clients that read project MCP configuration.

Codex with Streamable HTTP

Add the deployed endpoint to ~/.codex/config.toml:

[mcp_servers.transdex]
url = "https://transdex.example.com/mcp"
bearer_token_env_var = "TRANSDEX_REMOTE_TOKEN"
tool_timeout_sec = 1800

Other remote MCP clients

Expose /mcp through HTTPS, set TRANSDEX_PUBLIC_BASE_URL and TRANSDEX_HTTP_ALLOWED_HOSTS, and configure one authentication mode. A static bearer token is only appropriate for one trusted tenant. Multi-user deployments must validate OAuth at a trusted reverse proxy and forward a stable principal header after stripping client-supplied copies.

Configuration

HTTP and session settings

Whisper settings

Remote callers can select only models in TRANSDEX_PUBLIC_WHISPER_MODELS and cannot provide arbitrary local paths. Media ceilings and the auto-download switch are parsed strictly at startup.

Security and Privacy

Implemented safeguards include:

• HTTPS-only remote media URLs with hostname allowlisting

• DNS rejection for private, loopback, link-local, and reserved destinations

• DNS-pinned HTTPS connections and redirect revalidation

• Whole-download deadlines, streamed byte limits, and atomic staging

• ffprobe duration checks plus ffmpeg decoded-PCM limits

• Local-only ffmpeg/ffprobe protocol and demuxer allowlists

• Minimal child-process environments that omit application secrets

• Private per-session workspaces with ownership and symlink checks

• Bounded per-session and service-wide queues

• Per-principal session and artifact quotas in trusted-proxy mode

• Stable public errors without server-local paths

• Opaque signed artifact links

• Process-group cancellation and graceful shutdown

Current limitations:

• Jobs and artifact metadata are in memory and local to one process.

• Static bearer authentication is single-tenant, not public user OAuth.

• Trusted principal mode depends on a correctly configured reverse proxy.

• The reverse proxy must enforce request and bandwidth rate limits.

• ffmpeg, ffprobe, and whisper.cpp still require a low-privilege, no-network worker boundary with OS or container resource limits.

• Remote translation is not yet adapted to the direct remote-file flow.

Do not expose this pre-release directly to untrusted users or deploy multiple replicas until worker isolation, edge rate limiting, durable shared storage, and authenticated tenant ownership are in place.

Local Workflow

The local stdio server retains the plan-preview-confirm workflow for text, Markdown, subtitle, directory, and media jobs.

npm run mcp

The compatibility CLI remains available for direct terminal use:

npm run cli -- --help

Project Structure

src/
|-- mcp-http/             # Remote Streamable HTTP tools and artifact service
|-- mcp/                  # Local stdio planning and job workflow
|-- providers/            # whisper.cpp and optional cloud providers
|-- jobs/                 # JobSpec runner and safe artifact writing
|-- media/                # ffmpeg preparation and segment merging
|-- safety/               # Path and exclusive-write guards
+-- workers/              # Translation and subtitle preservation

test/
|-- mcp-http.test.js
|-- mcp-http-server.test.js
|-- remote-file-staging.test.js
|-- mcp.test.js
+-- whisper-public-profile.test.js

Testing

Run the complete test suite:

npm test

The suite mocks whisper-cli. Before deployment, run a real smoke test with the exact pinned whisper.cpp binary, model, VAD file, ffmpeg version, and target server architecture.

Troubleshooting

whisper.cpp model is missing

Pre-provision the selected model in TRANSDEX_WHISPER_CPP_MODEL_DIR. Keep request-time auto-download disabled for remote deployments.

VAD is enabled but no model is configured

Set TRANSDEX_WHISPER_CPP_VAD_MODEL to the downloaded Silero model or disable VAD.

A remote file is rejected

Check that download_url uses HTTPS, resolves only to public addresses, has a supported media extension, and matches TRANSDEX_FILE_HOSTS.

An MCP client cannot connect

For stdio, verify the absolute Node and repository paths. For HTTP, verify the HTTPS /mcp URL, reverse proxy streaming, Host allowlist, and authentication policy. In Codex, use /mcp or codex mcp list to inspect configured servers.

A job remains queued

Inspect both the per-session queue and the service-wide gate. Increase global concurrency only after benchmarking CPU, memory, disk expansion, and cancellation behavior.

Roadmap

• Adapt host-assisted subtitle translation to the remote file flow

• Add an optional MCP progress and download widget

• Replace in-memory jobs with a durable queue

• Move artifacts to tenant-scoped object storage

• Add native OAuth metadata and durable per-user accounting

• Add model and binary digest pinning

• Add a real whisper.cpp integration smoke test

• Add container and deployment manifests

• Complete privacy-policy and directory-submission review

License

This repository currently has no chosen redistribution license. package.json is marked private and UNLICENSED. Do not publish the npm package or redistribute the repository until the owner chooses a license and reviews third-party notices.

whisper.cpp, Whisper model weights, ffmpeg, and optional cloud providers have their own licenses and distribution requirements.