transcribego-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+TranscribeGo MCP License
+
+Copyright (c) 2026 Rather Labs. All rights reserved.
+
+1. Definitions.
+   "Software" means the transcribego-mcp software made available by Rather Labs
+   under this License, in source or object form, together with its
+   documentation. "You" means the individual or entity exercising rights under
+   this License.
+
+2. Grant of Use.
+   Rather Labs grants You a worldwide, royalty-free, non-exclusive,
+   non-transferable, and non-sublicensable license to install and run
+   unmodified copies of the Software, for any purpose including commercial
+   purposes, solely as distributed by Rather Labs. This grant includes the
+   right to make the incidental copies strictly necessary to install and run
+   the Software (for example, downloading it from a package registry and
+   loading it into memory for execution).
+
+3. Restrictions.
+   Except as expressly permitted in Section 2, or to the extent applicable law
+   prohibits the restriction, You may not:
+   (a) copy, publish, distribute, sublicense, sell, rent, lease, or otherwise
+       make the Software available to any third party;
+   (b) modify, adapt, translate, or create derivative works based on the
+       Software;
+   (c) reverse engineer, decompile, or disassemble the Software, except to the
+       extent applicable law expressly permits despite this limitation;
+   (d) remove, obscure, or alter any copyright, trademark, or other proprietary
+       notice contained in the Software.
+
+4. Reservation of Rights.
+   The Software is licensed, not sold. Rather Labs retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   No rights are granted to You except as expressly set out in this License.
+
+5. Termination.
+   This License terminates automatically if You breach any of its terms. Upon
+   termination You must cease all use of the Software and destroy all copies in
+   Your possession or control.
+
+6. Disclaimer of Warranty and Limitation of Liability.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   RATHER LABS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+   AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# transcribego-mcp
+
+Local MCP (stdio) proxy for [TranscribeGo](https://transcribego.com). It forwards every tool of the remote TranscribeGo MCP (`transcribe_audio`, `transcribe_url`, `get_transcription_job`) and adds one local tool:
+
+- **`transcribe_file { path }`** — transcribe an audio/video file from your disk. The file is uploaded directly to blob storage (up to 1 GB; the bytes never pass through the TranscribeGo server) and a transcription job is created. Poll `get_transcription_job` with the returned `jobId`.
+
+## Usage
+
+### Claude Code
+
+```sh
+claude mcp add transcribego -- npx -y transcribego-mcp
+```
+
+### Claude Desktop / Cursor (`mcpServers` config)
+
+```json
+{
+  "mcpServers": {
+    "transcribego": {
+      "command": "npx",
+      "args": ["-y", "transcribego-mcp"]
+    }
+  }
+}
+```
+
+On first use the proxy opens your browser to authorize with your TranscribeGo account (OAuth + PKCE). Tokens are stored in `~/.transcribego-mcp/credentials.json` (owner-only permissions) and refreshed automatically.
+
+## Supported files
+
+`.mp3`, `.mpga`, `.m4a`, `.mp4`, `.m4v`, `.ogg`, `.oga`, `.opus`, `.wav`, `.webm` — up to 1 GB. For other containers pass an explicit `mimeType` accepted by TranscribeGo.
+
+Rate limits are enforced server-side (~5 files/min).
+
+## Configuration
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `TRANSCRIBEGO_URL` | `https://transcribego.com` | TranscribeGo origin (use a preview deployment URL for testing) |
+| `TRANSCRIBEGO_MCP_DIR` | `~/.transcribego-mcp` | Where credentials are stored |
+
+## CLI
+
+```sh
+npx transcribego-mcp              # start the stdio MCP server (what MCP clients run)
+npx transcribego-mcp --reset-auth # forget stored credentials (forces a fresh login)
+npx transcribego-mcp --help
+```
+
+## Troubleshooting
+
+- **Browser never opened** — the authorization URL is also printed to stderr; open it manually.
+- **Stuck or invalid credentials** — run `npx transcribego-mcp --reset-auth` and retry.
+- **Multiple MCP clients** — each running proxy shares the same credentials file. Token refresh is serialized across processes with a file lock (`refresh.lock` in the credentials directory), so concurrent instances never invalidate each other's tokens.
+
+## Development
+
+```sh
+npm install
+npm test         # vitest
+npm run build    # tsc → dist/
+node dist/index.js
+```
+
+Upload parameters (per-user pathname prefix, upload URL, size limits, supported MIME types) come from the remote `get_upload_info` tool at transcription time — the proxy never hardcodes them. The flow for `transcribe_file` is: validate the local file → `get_upload_info` → direct-to-Blob upload → `transcribe_audio { blobUrl, fileSizeBytes, … }`.

package/dist/auth/lock.js

@@ -0,0 +1,60 @@
+import { mkdirSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+/**
+ * Inter-process mutex via atomic mkdir. Needed because refresh tokens rotate
+ * on use and the server revokes the whole token family on reuse detection —
+ * two transcribego-mcp instances (e.g. Claude Desktop + Cursor) refreshing
+ * concurrently with the same stored token would revoke each other. The
+ * instance holding the lock refreshes; the others then re-read the rotated
+ * tokens from the store.
+ */
+const RETRY_INTERVAL_MS = 150;
+/** A refresh is a single HTTP round trip; anything older than this is a crashed holder. */
+const STALE_LOCK_MS = 30_000;
+const ACQUIRE_TIMEOUT_MS = 60_000;
+export class LockTimeoutError extends Error {
+    constructor(lockPath) {
+        super(`Timed out waiting for lock ${lockPath}`);
+        this.name = 'LockTimeoutError';
+    }
+}
+function tryAcquire(lockPath) {
+    try {
+        mkdirSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        // First run: the data directory itself may not exist yet.
+        if (error.code === 'ENOENT') {
+            mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+            return tryAcquire(lockPath);
+        }
+        return false;
+    }
+}
+function removeIfStale(lockPath) {
+    try {
+        if (Date.now() - statSync(lockPath).mtimeMs > STALE_LOCK_MS) {
+            rmSync(lockPath, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // Already gone — the holder released it between our check and removal.
+    }
+}
+export async function withFileLock(lockPath, fn) {
+    const deadline = Date.now() + ACQUIRE_TIMEOUT_MS;
+    while (!tryAcquire(lockPath)) {
+        if (Date.now() > deadline)
+            throw new LockTimeoutError(lockPath);
+        removeIfStale(lockPath);
+        await sleep(RETRY_INTERVAL_MS);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        rmSync(lockPath, { recursive: true, force: true });
+    }
+}

package/dist/auth/oauth.js

@@ -0,0 +1,304 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { CALLBACK_PORTS, CALLBACK_PATH, OAUTH_SCOPES, callbackUri } from '../config.js';
+import { log } from '../log.js';
+import { withFileLock } from './lock.js';
+import { generatePkcePair } from './pkce.js';
+/** Refresh slightly before the 15-minute expiry to absorb clock skew and latency. */
+const EXPIRY_SLACK_MS = 30_000;
+const AUTHORIZE_TIMEOUT_MS = 5 * 60_000;
+export class OAuthError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'OAuthError';
+    }
+}
+async function fetchJson(url, init) {
+    const response = await fetch(url, init);
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Non-JSON body (e.g. HTML error page); leave null.
+    }
+    return { status: response.status, body };
+}
+/**
+ * RFC 9728 + RFC 8414 discovery. The resource URL (and therefore the `resource`
+ * parameter, which the server matches exactly) may live on a different origin
+ * than the issuer, so never derive it from baseUrl — always read the metadata.
+ */
+export async function discoverEndpoints(baseUrl) {
+    const candidates = [
+        `${baseUrl}/.well-known/oauth-protected-resource/mcp`,
+        `${baseUrl}/.well-known/oauth-protected-resource`,
+    ];
+    let resource = null;
+    let issuer = null;
+    for (const url of candidates) {
+        const { status, body } = await fetchJson(url);
+        if (status !== 200 || typeof body !== 'object' || body === null)
+            continue;
+        const metadata = body;
+        if (typeof metadata.resource === 'string' && Array.isArray(metadata.authorization_servers)) {
+            resource = metadata.resource;
+            issuer = String(metadata.authorization_servers[0]);
+            break;
+        }
+    }
+    if (!resource || !issuer) {
+        throw new OAuthError(`Could not discover OAuth metadata from ${baseUrl} — is the URL correct?`);
+    }
+    const { status, body } = await fetchJson(`${issuer}/.well-known/oauth-authorization-server`);
+    if (status !== 200 || typeof body !== 'object' || body === null) {
+        throw new OAuthError(`Could not fetch authorization server metadata from ${issuer}`);
+    }
+    const as = body;
+    const authorizationEndpoint = as.authorization_endpoint;
+    const tokenEndpoint = as.token_endpoint;
+    const registrationEndpoint = as.registration_endpoint;
+    if (typeof authorizationEndpoint !== 'string' ||
+        typeof tokenEndpoint !== 'string' ||
+        typeof registrationEndpoint !== 'string') {
+        throw new OAuthError('Authorization server metadata is missing required endpoints');
+    }
+    return { resource, authorizationEndpoint, tokenEndpoint, registrationEndpoint };
+}
+async function registerClient(endpoints) {
+    const redirectUris = CALLBACK_PORTS.map((port) => callbackUri(port));
+    const { status, body } = await fetchJson(endpoints.registrationEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            client_name: 'TranscribeGo local MCP',
+            redirect_uris: redirectUris,
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        }),
+    });
+    const registered = body;
+    if (status !== 201 || typeof registered?.client_id !== 'string') {
+        throw new OAuthError(`Dynamic client registration failed (HTTP ${status})`);
+    }
+    return {
+        clientId: registered.client_id,
+        redirectUris: Array.isArray(registered.redirect_uris)
+            ? registered.redirect_uris.map(String)
+            : redirectUris,
+    };
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        spawn(command, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // Browser launch is best-effort; the URL is also printed to stderr.
+    }
+}
+function listenOnFirstFreePort(redirectUris) {
+    const loopbackUris = redirectUris.filter((uri) => uri.startsWith('http://127.0.0.1:'));
+    if (loopbackUris.length === 0) {
+        throw new OAuthError('Stored client has no loopback redirect URIs; run with --reset-auth');
+    }
+    return new Promise((resolve, reject) => {
+        const tryNext = (index) => {
+            const uri = loopbackUris[index];
+            if (!uri) {
+                reject(new OAuthError('All registered callback ports are busy; close other transcribego-mcp instances'));
+                return;
+            }
+            const port = Number(new URL(uri).port);
+            const server = createServer();
+            server.once('error', () => {
+                server.close();
+                tryNext(index + 1);
+            });
+            server.listen(port, '127.0.0.1', () => resolve({ server, redirectUri: uri }));
+        };
+        tryNext(0);
+    });
+}
+function waitForCallback(server, expectedState) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new OAuthError('Timed out waiting for the browser authorization (5 minutes)'));
+            server.close();
+        }, AUTHORIZE_TIMEOUT_MS);
+        server.on('request', (req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname !== CALLBACK_PATH) {
+                res.writeHead(404).end();
+                return;
+            }
+            const finish = (message) => {
+                res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(`<html><body style="font-family:sans-serif"><p>${message}</p><p>You can close this tab.</p></body></html>`);
+                clearTimeout(timeout);
+                // Let the response flush before tearing the server down.
+                setImmediate(() => server.close());
+            };
+            const error = url.searchParams.get('error');
+            if (error) {
+                finish('Authorization failed.');
+                reject(new OAuthError(`Authorization was rejected: ${url.searchParams.get('error_description') ?? error}`, error));
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (url.searchParams.get('state') !== expectedState || !code) {
+                finish('Invalid authorization response.');
+                reject(new OAuthError('Authorization response had a missing code or mismatched state'));
+                return;
+            }
+            finish('TranscribeGo MCP is now connected.');
+            resolve(code);
+        });
+    });
+}
+function parseTokenResponse(status, body) {
+    const data = body;
+    if (status !== 200 || !data || typeof data.access_token !== 'string' || typeof data.refresh_token !== 'string') {
+        throw new OAuthError(`Token request failed (HTTP ${status}): ${data?.error_description ?? data?.error ?? 'unknown error'}`, data?.error);
+    }
+    return data;
+}
+/**
+ * Manages the whole public-client OAuth lifecycle against the TranscribeGo
+ * authorization server: one-time dynamic registration, interactive PKCE
+ * authorization through a loopback redirect, and refresh-token rotation.
+ */
+export class OAuthClient {
+    baseUrl;
+    store;
+    endpoints = null;
+    inFlight = null;
+    constructor(baseUrl, store) {
+        this.baseUrl = baseUrl;
+        this.store = store;
+    }
+    async getEndpoints() {
+        if (!this.endpoints) {
+            this.endpoints = await discoverEndpoints(this.baseUrl);
+        }
+        return this.endpoints;
+    }
+    /**
+     * Returns a currently-valid access token, refreshing or running the
+     * interactive flow as needed. Concurrent callers share one attempt so a
+     * burst of tool calls cannot trigger parallel refreshes (rotation would
+     * revoke the whole token family).
+     */
+    async getAccessToken() {
+        if (!this.inFlight) {
+            this.inFlight = this.acquireToken().finally(() => {
+                this.inFlight = null;
+            });
+        }
+        return this.inFlight;
+    }
+    /** Drops the cached access token so the next call refreshes (e.g. after a 401). */
+    invalidateAccessToken() {
+        this.store.update({ accessToken: undefined, accessTokenExpiresAt: undefined });
+    }
+    async acquireToken() {
+        // Refresh tokens rotate on use and reuse revokes the whole family, so the
+        // read-refresh-persist sequence must be exclusive across processes. The
+        // interactive flow stays outside the lock: it can take minutes and starts
+        // a fresh token family, so it cannot race a rotation.
+        const refreshed = await withFileLock(this.store.lockPath, async () => {
+            // Re-read under the lock: another instance may have just rotated.
+            const stored = this.store.read();
+            if (stored?.accessToken && (stored.accessTokenExpiresAt ?? 0) > Date.now() + EXPIRY_SLACK_MS) {
+                return stored.accessToken;
+            }
+            if (!stored?.refreshToken)
+                return null;
+            try {
+                return await this.refresh(stored);
+            }
+            catch (error) {
+                if (error instanceof OAuthError && error.code === 'invalid_grant') {
+                    log('Refresh token is no longer valid; starting interactive login');
+                    return null;
+                }
+                throw error;
+            }
+        });
+        if (refreshed)
+            return refreshed;
+        return this.interactiveAuthorize();
+    }
+    async refresh(stored) {
+        const endpoints = await this.getEndpoints();
+        const { status, body } = await fetchJson(endpoints.tokenEndpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'refresh_token',
+                refresh_token: stored.refreshToken ?? '',
+                client_id: stored.clientId,
+                resource: endpoints.resource,
+            }),
+        });
+        const tokens = parseTokenResponse(status, body);
+        this.persistTokens(stored, tokens);
+        return tokens.access_token;
+    }
+    async interactiveAuthorize() {
+        const endpoints = await this.getEndpoints();
+        let stored = this.store.read();
+        if (!stored?.clientId) {
+            const registration = await registerClient(endpoints);
+            stored = { ...registration };
+            this.store.write(stored);
+            log('Registered as a new OAuth client');
+        }
+        const { server, redirectUri } = await listenOnFirstFreePort(stored.redirectUris);
+        const pkce = generatePkcePair();
+        const state = randomBytes(16).toString('base64url');
+        const authorizeUrl = new URL(endpoints.authorizationEndpoint);
+        authorizeUrl.search = new URLSearchParams({
+            response_type: 'code',
+            client_id: stored.clientId,
+            redirect_uri: redirectUri,
+            scope: OAUTH_SCOPES.join(' '),
+            state,
+            code_challenge: pkce.challenge,
+            code_challenge_method: 'S256',
+            resource: endpoints.resource,
+        }).toString();
+        log(`Opening browser to authorize: ${authorizeUrl.toString()}`);
+        openBrowser(authorizeUrl.toString());
+        const code = await waitForCallback(server, state);
+        const { status, body } = await fetchJson(endpoints.tokenEndpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: redirectUri,
+                client_id: stored.clientId,
+                code_verifier: pkce.verifier,
+                resource: endpoints.resource,
+            }),
+        });
+        const tokens = parseTokenResponse(status, body);
+        this.persistTokens(stored, tokens);
+        log('Authorization complete');
+        return tokens.access_token;
+    }
+    persistTokens(base, tokens) {
+        this.store.write({
+            ...base,
+            accessToken: tokens.access_token,
+            accessTokenExpiresAt: Date.now() + tokens.expires_in * 1000,
+            refreshToken: tokens.refresh_token,
+        });
+    }
+}

package/dist/auth/pkce.js

@@ -0,0 +1,9 @@
+import { createHash, randomBytes } from 'node:crypto';
+/** RFC 7636 S256: verifier is 43-128 chars of base64url; challenge = BASE64URL(SHA256(verifier)). */
+export function generatePkcePair() {
+    const verifier = randomBytes(32).toString('base64url');
+    return { verifier, challenge: challengeFromVerifier(verifier) };
+}
+export function challengeFromVerifier(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}

package/dist/auth/token-store.js

@@ -0,0 +1,49 @@
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+const FILE_NAME = 'credentials.json';
+export class TokenStore {
+    dataDir;
+    baseUrl;
+    filePath;
+    /** Mutex directory used to serialize token refresh across processes. */
+    lockPath;
+    constructor(dataDir, baseUrl) {
+        this.dataDir = dataDir;
+        this.baseUrl = baseUrl;
+        this.filePath = path.join(dataDir, FILE_NAME);
+        this.lockPath = path.join(dataDir, 'refresh.lock');
+    }
+    read() {
+        const file = this.readFile();
+        return file.servers[this.baseUrl] ?? null;
+    }
+    write(auth) {
+        const file = this.readFile();
+        file.servers[this.baseUrl] = auth;
+        mkdirSync(this.dataDir, { recursive: true, mode: 0o700 });
+        writeFileSync(this.filePath, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    }
+    update(patch) {
+        const current = this.read();
+        if (!current)
+            return null;
+        const next = { ...current, ...patch };
+        this.write(next);
+        return next;
+    }
+    clear() {
+        rmSync(this.filePath, { force: true });
+    }
+    readFile() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, 'utf8'));
+            if (parsed && parsed.version === 1 && parsed.servers && typeof parsed.servers === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            // Missing or corrupt file: start fresh.
+        }
+        return { version: 1, servers: {} };
+    }
+}

package/dist/config.js

@@ -0,0 +1,24 @@
+import os from 'node:os';
+import path from 'node:path';
+const DEFAULT_BASE_URL = 'https://transcribego.com';
+/** OAuth scopes the proxy needs: transcribe (also gates /api/upload) + job polling. */
+export const OAUTH_SCOPES = ['mcp:transcribe', 'mcp:jobs:read'];
+/**
+ * Loopback ports for the OAuth redirect. The server requires redirect URIs to
+ * exactly match a registered URI (no wildcard ports), and dynamic client
+ * registration is rate-limited — so we register all of these once and pick
+ * whichever is free at authorization time.
+ */
+export const CALLBACK_PORTS = [43821, 43822, 43823, 43824, 43825];
+export const CALLBACK_PATH = '/callback';
+export function callbackUri(port) {
+    return `http://127.0.0.1:${port}${CALLBACK_PATH}`;
+}
+function stripTrailingSlash(value) {
+    return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+export function resolveConfig(env = process.env) {
+    const baseUrl = stripTrailingSlash(env.TRANSCRIBEGO_URL?.trim() || DEFAULT_BASE_URL);
+    const dataDir = env.TRANSCRIBEGO_MCP_DIR?.trim() || path.join(os.homedir(), '.transcribego-mcp');
+    return { baseUrl, dataDir };
+}

package/dist/files.js

@@ -0,0 +1,63 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Extension → MIME type, restricted to the server's allowed upload content
+ * types (CONFIG.audio.supportedMimeTypes in the TranscribeGo app). The blob
+ * client token rejects anything else at upload time, so we fail fast here
+ * with a clearer message.
+ */
+const EXT_TO_MIME = {
+    '.mp3': 'audio/mpeg',
+    '.mpga': 'audio/mpeg',
+    '.m4a': 'audio/x-m4a',
+    '.mp4': 'video/mp4',
+    '.m4v': 'video/mp4',
+    '.ogg': 'audio/ogg',
+    '.oga': 'audio/ogg',
+    '.opus': 'audio/ogg',
+    '.wav': 'audio/wav',
+    '.webm': 'audio/webm',
+};
+export const SUPPORTED_EXTENSIONS = Object.keys(EXT_TO_MIME);
+export class FileValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FileValidationError';
+    }
+}
+export function mimeTypeForExtension(extension) {
+    return EXT_TO_MIME[extension.toLowerCase()] ?? null;
+}
+/**
+ * Validates a local path for the transcribe_file tool: must exist, be a
+ * regular file, and have a supported audio/video extension (unless the caller
+ * overrides the MIME type explicitly).
+ */
+export function inspectAudioFile(rawPath, mimeTypeOverride) {
+    const absolutePath = path.resolve(rawPath);
+    let stats;
+    try {
+        stats = statSync(absolutePath);
+    }
+    catch {
+        throw new FileValidationError(`File not found: ${absolutePath}`);
+    }
+    if (!stats.isFile()) {
+        throw new FileValidationError(`Not a regular file: ${absolutePath}`);
+    }
+    if (stats.size === 0) {
+        throw new FileValidationError(`File is empty: ${absolutePath}`);
+    }
+    const extension = path.extname(absolutePath).toLowerCase();
+    const mimeType = mimeTypeOverride?.trim() || mimeTypeForExtension(extension);
+    if (!mimeType) {
+        throw new FileValidationError(`Unsupported file extension "${extension || '(none)'}". Supported: ${SUPPORTED_EXTENSIONS.join(', ')} — or pass mimeType explicitly.`);
+    }
+    return {
+        absolutePath,
+        fileName: path.basename(absolutePath),
+        extension,
+        mimeType,
+        sizeBytes: stats.size,
+    };
+}

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { resolveConfig } from './config.js';
+import { log } from './log.js';
+import { OAuthClient } from './auth/oauth.js';
+import { TokenStore } from './auth/token-store.js';
+import { RemoteMcpClient } from './remote-client.js';
+import { BlobUploader } from './upload/upload.js';
+import { ProxyServer } from './server.js';
+function printHelp() {
+    process.stderr.write(`transcribego-mcp — local MCP (stdio) proxy for TranscribeGo
+
+Usage:
+  npx transcribego-mcp              Start the stdio MCP server
+  npx transcribego-mcp --reset-auth Forget stored credentials and exit
+  npx transcribego-mcp --help       Show this help
+
+Environment:
+  TRANSCRIBEGO_URL      TranscribeGo origin (default: https://transcribego.com)
+  TRANSCRIBEGO_MCP_DIR  Credentials directory (default: ~/.transcribego-mcp)
+`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+        printHelp();
+        return;
+    }
+    const config = resolveConfig();
+    const store = new TokenStore(config.dataDir, config.baseUrl);
+    if (argv.includes('--reset-auth')) {
+        store.clear();
+        log(`Cleared stored credentials for ${config.baseUrl}`);
+        return;
+    }
+    const oauth = new OAuthClient(config.baseUrl, store);
+    const remote = new RemoteMcpClient(oauth);
+    const uploader = new BlobUploader(oauth);
+    const server = new ProxyServer(remote, uploader);
+    log(`Proxying to ${config.baseUrl}`);
+    await server.connect();
+}
+main().catch((error) => {
+    log(`Fatal: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/log.js

@@ -0,0 +1,7 @@
+/**
+ * All diagnostics go to stderr: stdout is the MCP stdio transport channel and
+ * must carry nothing but protocol frames.
+ */
+export function log(message) {
+    process.stderr.write(`[transcribego-mcp] ${message}\n`);
+}

package/dist/remote-client.js

@@ -0,0 +1,72 @@
+import { log } from './log.js';
+const JSON_RPC_VERSION = '2.0';
+/** Must match the remote server (MCP_PROTOCOL_VERSION in the TranscribeGo app). */
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+export class RemoteRpcError extends Error {
+    code;
+    data;
+    constructor(message, code, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'RemoteRpcError';
+    }
+}
+/**
+ * Minimal JSON-RPC 2.0 client for the remote TranscribeGo MCP endpoint
+ * (stateless POST per request, no SSE). Attaches the bearer token and
+ * transparently retries once on 401 — access tokens only last 15 minutes,
+ * so mid-session expiry is routine, not exceptional.
+ */
+export class RemoteMcpClient {
+    oauth;
+    nextId = 1;
+    constructor(oauth) {
+        this.oauth = oauth;
+    }
+    async call(method, params) {
+        const endpoints = await this.oauth.getEndpoints();
+        let token = await this.oauth.getAccessToken();
+        let response = await this.post(endpoints.resource, token, method, params);
+        if (response.status === 401) {
+            log('Remote MCP returned 401; refreshing token and retrying');
+            this.oauth.invalidateAccessToken();
+            token = await this.oauth.getAccessToken();
+            response = await this.post(endpoints.resource, token, method, params);
+        }
+        if (response.status === 401) {
+            throw new RemoteRpcError('Not authorized by TranscribeGo even after refreshing credentials. Run "npx transcribego-mcp --reset-auth" and try again.', -32000);
+        }
+        if (response.status === 204 || response.body === null) {
+            return null;
+        }
+        const payload = response.body;
+        if (payload.error) {
+            throw new RemoteRpcError(payload.error.message, payload.error.code, payload.error.data);
+        }
+        return payload.result ?? null;
+    }
+    async post(url, token, method, params) {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: JSON_RPC_VERSION,
+                id: this.nextId++,
+                method,
+                ...(params === undefined ? {} : { params }),
+            }),
+        });
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // 204 or non-JSON error body.
+        }
+        return { status: response.status, body };
+    }
+}

package/dist/server.js

@@ -0,0 +1,130 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, McpError, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { log } from './log.js';
+import { FileValidationError, SUPPORTED_EXTENSIONS, inspectAudioFile } from './files.js';
+import { RemoteRpcError } from './remote-client.js';
+import { OAuthError } from './auth/oauth.js';
+import { UploadInfoError, parseUploadInfo } from './upload/upload-info.js';
+const TRANSCRIBE_FILE_TOOL = {
+    name: 'transcribe_file',
+    description: 'Transcribe a local audio/video file. Uploads the file from disk to TranscribeGo (supports large files, up to 1 GB) and creates a transcription job. Poll get_transcription_job with the returned jobId until it completes.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: `Path to the local audio/video file. Supported extensions: ${SUPPORTED_EXTENSIONS.join(', ')}.`,
+            },
+            mimeType: {
+                type: 'string',
+                description: 'Optional MIME type override when the file extension is missing or misleading.',
+            },
+            durationHintMs: {
+                type: 'number',
+                description: 'Optional known duration in milliseconds, if already available.',
+            },
+        },
+        required: ['path'],
+        additionalProperties: false,
+    },
+};
+function errorResult(message) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error: message }) }], isError: true };
+}
+export class ProxyServer {
+    remote;
+    uploader;
+    server;
+    remoteTools = null;
+    constructor(remote, uploader) {
+        this.remote = remote;
+        this.uploader = uploader;
+        this.server = new Server({ name: 'transcribego-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+        this.server.setRequestHandler(ListToolsRequestSchema, () => this.listTools());
+        this.server.setRequestHandler(CallToolRequestSchema, (request) => this.callTool(request.params.name, request.params.arguments));
+    }
+    async connect() {
+        await this.server.connect(new StdioServerTransport());
+        log('stdio server ready');
+    }
+    async listTools() {
+        if (!this.remoteTools) {
+            const result = (await this.wrapRemote(() => this.remote.call('tools/list')));
+            if (!result || !Array.isArray(result.tools)) {
+                throw new McpError(ErrorCode.InternalError, 'Remote MCP returned an invalid tool list');
+            }
+            this.remoteTools = result.tools;
+        }
+        return { tools: [...this.remoteTools, TRANSCRIBE_FILE_TOOL] };
+    }
+    async callTool(name, args) {
+        if (name === TRANSCRIBE_FILE_TOOL.name) {
+            return this.transcribeFile(args);
+        }
+        const result = await this.wrapRemote(() => this.remote.call('tools/call', { name, arguments: args }));
+        return result;
+    }
+    async transcribeFile(args) {
+        const { path, mimeType, durationHintMs } = (args ?? {});
+        if (typeof path !== 'string' || !path.trim()) {
+            throw new McpError(ErrorCode.InvalidParams, 'transcribe_file requires a "path" string argument');
+        }
+        try {
+            const file = inspectAudioFile(path, typeof mimeType === 'string' ? mimeType : undefined);
+            const info = parseUploadInfo(await this.remote.call('tools/call', { name: 'get_upload_info', arguments: {} }));
+            if (file.sizeBytes > info.maxSizeBytes) {
+                return errorResult(`File is ${Math.ceil(file.sizeBytes / 1024 / 1024)} MB but the maximum upload size is ${Math.floor(info.maxSizeBytes / 1024 / 1024)} MB`);
+            }
+            if (!info.supportedMimeTypes.includes(file.mimeType)) {
+                return errorResult(`MIME type ${file.mimeType} is not supported. Supported types: ${info.supportedMimeTypes.join(', ')}`);
+            }
+            const { blobUrl } = await this.uploader.uploadFile(file, info);
+            // fileSizeBytes always: it lets the server route >100 MB files to
+            // background processing without buffering them first.
+            const result = await this.remote.call('tools/call', {
+                name: 'transcribe_audio',
+                arguments: {
+                    blobUrl,
+                    fileName: file.fileName,
+                    mimeType: file.mimeType,
+                    fileSizeBytes: file.sizeBytes,
+                    ...(typeof durationHintMs === 'number' && durationHintMs > 0
+                        ? { durationHintMs: Math.round(durationHintMs) }
+                        : {}),
+                },
+            });
+            return result;
+        }
+        catch (error) {
+            // Tool-shaped failures (bad file, paywall, rate limit) go back as tool
+            // results so the calling model can read and relay them.
+            if (error instanceof FileValidationError || error instanceof UploadInfoError) {
+                return errorResult(error.message);
+            }
+            if (error instanceof OAuthError) {
+                return errorResult(`TranscribeGo authorization failed: ${error.message}`);
+            }
+            if (error instanceof RemoteRpcError) {
+                throw new McpError(ErrorCode.InternalError, error.message, error.data);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(`Upload failed: ${message}`);
+        }
+    }
+    /** Converts remote/auth failures into MCP protocol errors for proxied methods. */
+    async wrapRemote(operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (error instanceof RemoteRpcError) {
+                throw new McpError(ErrorCode.InternalError, error.message, error.data);
+            }
+            if (error instanceof OAuthError) {
+                throw new McpError(ErrorCode.InternalError, `TranscribeGo authorization failed: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/upload/upload-info.js

@@ -0,0 +1,53 @@
+/**
+ * Upload parameters come from the remote `get_upload_info` tool (scope
+ * mcp:transcribe): the server derives everything from its own config plus the
+ * bearer's userId, so the client never guesses its `mcp-uploads/{userId}/`
+ * prefix. The call has no rate-limit bucket, so we fetch it fresh per upload
+ * instead of caching a value that could go stale.
+ */
+export class UploadInfoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UploadInfoError';
+    }
+}
+/**
+ * Parses the MCP tool result of `get_upload_info` (JSON payload inside
+ * content[0].text, the usual MCP pattern).
+ */
+export function parseUploadInfo(result) {
+    const toolResult = result;
+    const text = toolResult?.content?.[0]?.text;
+    if (typeof text !== 'string') {
+        throw new UploadInfoError('get_upload_info returned no content');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new UploadInfoError('get_upload_info returned non-JSON content');
+    }
+    if (toolResult?.isError) {
+        const message = typeof payload.error === 'string' ? payload.error : text;
+        throw new UploadInfoError(`get_upload_info failed: ${message}`);
+    }
+    const { handleUploadUrl, pathnamePrefix, maxSizeBytes, inlineMaxSizeBytes, supportedMimeTypes, uploadRateLimitPerMinute } = payload;
+    if (typeof handleUploadUrl !== 'string' ||
+        typeof pathnamePrefix !== 'string' ||
+        !pathnamePrefix.endsWith('/') ||
+        typeof maxSizeBytes !== 'number' ||
+        typeof inlineMaxSizeBytes !== 'number' ||
+        !Array.isArray(supportedMimeTypes) ||
+        supportedMimeTypes.some((item) => typeof item !== 'string')) {
+        throw new UploadInfoError('get_upload_info returned an unexpected shape');
+    }
+    return {
+        handleUploadUrl,
+        pathnamePrefix,
+        maxSizeBytes,
+        inlineMaxSizeBytes,
+        supportedMimeTypes: supportedMimeTypes,
+        uploadRateLimitPerMinute: typeof uploadRateLimitPerMinute === 'number' ? uploadRateLimitPerMinute : 5,
+    };
+}

package/dist/upload/upload.js

@@ -0,0 +1,42 @@
+import { createReadStream } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { upload } from '@vercel/blob/client';
+import { log } from '../log.js';
+/** Above this size, split into parallel parts with per-part retry. */
+const MULTIPART_THRESHOLD_BYTES = 32 * 1024 * 1024;
+/**
+ * Uploads a local file straight to Vercel Blob using the client-upload
+ * protocol: the server's handleUploadUrl mints a scoped token (authenticated
+ * with the MCP bearer), then the bytes go directly to Blob storage without
+ * passing through the TranscribeGo server. All parameters (URL, per-user
+ * pathname prefix) come from get_upload_info.
+ */
+export class BlobUploader {
+    oauth;
+    constructor(oauth) {
+        this.oauth = oauth;
+    }
+    async uploadFile(file, info) {
+        const accessToken = await this.oauth.getAccessToken();
+        // Never reuse pathnames: the server expects unique uploads and sweeps
+        // abandoned ones after 24h, so no client-side cleanup is needed.
+        const pathname = `${info.pathnamePrefix}${randomUUID()}${file.extension}`;
+        log(`Uploading ${file.fileName} (${Math.ceil(file.sizeBytes / 1024 / 1024)} MB) to ${pathname}`);
+        let lastLoggedPercent = -10;
+        const result = await upload(pathname, createReadStream(file.absolutePath), {
+            access: 'public',
+            handleUploadUrl: info.handleUploadUrl,
+            headers: { authorization: `Bearer ${accessToken}` },
+            contentType: file.mimeType,
+            multipart: file.sizeBytes > MULTIPART_THRESHOLD_BYTES,
+            onUploadProgress: ({ percentage }) => {
+                if (percentage >= lastLoggedPercent + 10) {
+                    lastLoggedPercent = percentage;
+                    log(`Upload progress: ${Math.floor(percentage)}%`);
+                }
+            },
+        });
+        log(`Upload complete: ${result.url}`);
+        return { blobUrl: result.url };
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "transcribego-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP (stdio) proxy for TranscribeGo: forwards tools to the remote TranscribeGo MCP and adds local audio file uploads via direct-to-Blob transfer.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://transcribego.com",
+  "type": "module",
+  "bin": {
+    "transcribego-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "transcription",
+    "transcribego",
+    "audio"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@vercel/blob": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}