@pyai/mcp 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @pyai/mcp — PyAI Model Context Protocol server
+
+Exposes the PyAI voice API as [MCP](https://modelcontextprotocol.io) tools so AI
+coding agents (Cursor, Claude Code, Codex) can **go from zero to a working PyAI
+call with no human steps** — the agent can mint its own free sandbox key and then
+call PyAI directly instead of guessing endpoints. Zero runtime dependencies.
+
+## Tools
+
+| Tool | Needs a key? | Maps to |
+|------|--------------|---------|
+| `create_sandbox_key` | No | `POST /v1/sandbox/keys` — mint a free `pyai_test_` key (no email/card), adopted for the session |
+| `get_started` | No | Curated quickstart (auth, SDK install, TTS/STT/realtime snippets) — no network/credits |
+| `whoami` | Yes | `GET /v1/me` (scopes, env, credit posture) |
+| `list_models` | Yes | `GET /v1/models` |
+| `list_voices` | Yes | `GET /v1/voices` (optional `gender`, `region`) |
+| `synthesize_speech` | Yes | `POST /v1/audio/speech` → writes audio to `output_path` |
+| `create_transcription_job` | Yes | `POST /v1/transcription/jobs` (async STT for an `audio_url`) |
+| `get_transcription_job` | Yes | `GET /v1/transcription/jobs/{id}` |
+
+The contract is `https://api.pyai.com/openapi.json`; these tools wrap a curated
+subset. **No key is required to start** — if `PYAI_API_KEY` is unset, an agent
+calls `create_sandbox_key` first and the server adopts the minted key for the
+rest of the session. Errors (402 credit, 429 rate limit, etc.) surface as MCP
+tool errors with the stable `code`.
+
+## Install
+
+The server runs straight from npm with `npx` — no clone, no build.
+
+### Cursor — one click
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=pyai&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBweWFpL21jcCJdfQ==)
+
+Click the button (Cursor decodes the install config and prompts you), or add
+this to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "pyai": {
+      "command": "npx",
+      "args": ["-y", "@pyai/mcp"]
+    }
+  }
+}
+```
+
+Add `"env": { "PYAI_API_KEY": "pyai_test_..." }` to pin a key, or leave it out
+and let the agent call `create_sandbox_key`.
+
+### Claude Code
+
+```bash
+claude mcp add pyai -- npx -y @pyai/mcp
+# or pin a key:
+claude mcp add pyai --env PYAI_API_KEY=pyai_test_... -- npx -y @pyai/mcp
+```
+
+### Codex / other MCP hosts
+
+Point the host at the stdio command `npx -y @pyai/mcp`, optionally with
+`PYAI_API_KEY` in the environment. The transport is newline-delimited
+JSON-RPC 2.0 over stdio.
+
+## Config (env)
+
+- `PYAI_API_KEY` — *optional*. A `pyai_live_`/`pyai_test_` key. Omit it to let
+  the agent mint a sandbox key.
+- `PYAI_BASE_URL` — optional, defaults to `https://api.pyai.com`.
+- `PORT` — optional, HTTP transport only (default `8080`).
+
+## HTTP transport (experimental)
+
+`npx @pyai/mcp --http` starts a minimal HTTP JSON-RPC endpoint (`POST /`,
+`GET /health`) — the basis for a hosted remote server at `mcp.pyai.com`. A
+per-request `Authorization: Bearer <key>` overrides the env key. Each HTTP
+request gets an isolated client, so a key minted by `create_sandbox_key` is
+returned to that caller but is not retained globally for later callers. This is
+**not yet** a full MCP Streamable HTTP server (SSE, session ids, and OAuth are
+deploy-time follow-ups); the supported install today is `npx` over stdio.
+
+## Develop
+
+```bash
+npm install        # dev-only: typescript + @types/node
+npm test           # node --test (no network; fetch is injected)
+npm run typecheck
+npm run build      # emit dist/ (tsc rewrites .ts imports → .js)
+```
+
+`src/rpc.ts` (`dispatch`) is transport-pure and unit-tested; `src/tools.ts`
+holds the tool definitions + operation logic; `src/client.ts` is the fetch
+wrapper; `src/http.ts` is the experimental HTTP transport. Add a tool by
+extending `TOOLS` + the `callTool` switch.

package/dist/client.js

@@ -0,0 +1,82 @@
+/**
+ * Thin PyAI API client used by the MCP tools. Wraps fetch with the bearer key
+ * and surfaces errors in a shape the tool layer can turn into MCP tool errors.
+ * No external deps — runs on Node 20+'s global fetch.
+ *
+ * The key is OPTIONAL: the server can start without one so an agent can call the
+ * `create_sandbox_key` tool first, which mints a sandbox key and adopts it on
+ * this client for the rest of the session (`setApiKey`).
+ */
+export class PyAIError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.name = "PyAIError";
+        this.status = status;
+        this.code = code;
+    }
+}
+export class PyAIClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey && opts.apiKey.length > 0 ? opts.apiKey : undefined;
+        this.baseUrl = (opts.baseUrl ?? "https://api.pyai.com").replace(/\/$/, "");
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    /** Whether a key is configured (env or adopted from create_sandbox_key). */
+    get hasKey() {
+        return this.apiKey !== undefined;
+    }
+    /** Adopt a key for the rest of the session (used after create_sandbox_key). */
+    setApiKey(key) {
+        this.apiKey = key && key.length > 0 ? key : undefined;
+    }
+    headers(extra = {}) {
+        return this.apiKey ? { Authorization: `Bearer ${this.apiKey}`, ...extra } : { ...extra };
+    }
+    /** Parse an error body (OpenAI envelope OR RFC 7807 problem) into a PyAIError. */
+    async toError(res) {
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            return new PyAIError(res.status, `HTTP ${res.status}`);
+        }
+        const b = body;
+        if (b.error)
+            return new PyAIError(res.status, b.error.message ?? `HTTP ${res.status}`, b.error.code);
+        const code = typeof b.type === "string" ? b.type.split("/").pop() : undefined;
+        return new PyAIError(res.status, b.detail ?? b.title ?? `HTTP ${res.status}`, code);
+    }
+    async getJson(path) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, { headers: this.headers() });
+        if (!res.ok)
+            throw await this.toError(res);
+        return (await res.json());
+    }
+    async postJson(path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return (await res.json());
+    }
+    /** POST that returns binary audio (text-to-speech). Returns the raw bytes. */
+    async postForBytes(path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+}

package/dist/http.js

@@ -0,0 +1,74 @@
+/**
+ * Experimental HTTP transport for hosting pyai-mcp remotely (the basis for a
+ * one-click remote MCP at mcp.pyai.com).
+ *
+ * This is a minimal single-response JSON-RPC endpoint: POST a JSON-RPC message,
+ * get the JSON-RPC response back. It is intentionally small and dependency-free.
+ * NOT YET a full MCP Streamable HTTP server — SSE streaming, session ids
+ * (`Mcp-Session-Id`), and OAuth are deploy-time follow-ups before public
+ * hosting. The supported install today is `npx @pyai/mcp` over stdio.
+ *
+ * A per-request `Authorization: Bearer <key>` overrides the env key, so a hosted
+ * instance can serve multiple tenants. Each request gets its own client instance:
+ * if `create_sandbox_key` adopts a key, that mutation is confined to the single
+ * request and cannot leak into the next caller. Full remote MCP session support
+ * still needs Streamable HTTP session ids before public hosting.
+ */
+import { createServer } from "node:http";
+import { PyAIClient } from "./client.js";
+import { dispatch } from "./rpc.js";
+const MAX_BODY_BYTES = 1_000_000;
+export function startHttpServer(opts) {
+    const server = createServer((req, res) => {
+        if (req.method === "GET" && (req.url === "/health" || req.url === "/healthz")) {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ status: "ok", server: "pyai-mcp" }));
+            return;
+        }
+        if (req.method !== "POST") {
+            res.writeHead(405, { "content-type": "application/json", allow: "POST" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Use POST for JSON-RPC" } }));
+            return;
+        }
+        const auth = req.headers["authorization"];
+        const bearer = typeof auth === "string" && auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+        const client = new PyAIClient({ apiKey: bearer || opts.apiKey, baseUrl: opts.baseUrl });
+        let raw = "";
+        let aborted = false;
+        req.on("data", (chunk) => {
+            raw += chunk;
+            if (raw.length > MAX_BODY_BYTES) {
+                aborted = true;
+                res.writeHead(413, { "content-type": "application/json" });
+                res.end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Payload too large" } }));
+                req.destroy();
+            }
+        });
+        req.on("end", () => {
+            if (aborted)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(raw);
+            }
+            catch {
+                res.writeHead(400, { "content-type": "application/json" });
+                res.end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }));
+                return;
+            }
+            dispatch(msg, { client })
+                .then((out) => {
+                res.writeHead(200, { "content-type": "application/json" });
+                // Notifications (no id) get an empty 200 ack.
+                res.end(out ? JSON.stringify(out) : "");
+            })
+                .catch(() => {
+                res.writeHead(500, { "content-type": "application/json" });
+                res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id ?? null, error: { code: -32603, message: "Internal error" } }));
+            });
+        });
+    });
+    server.listen(opts.port, opts.host ?? "0.0.0.0", () => {
+        process.stderr.write(`pyai-mcp: HTTP transport listening on ${opts.host ?? "0.0.0.0"}:${opts.port}\n`);
+    });
+}

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * pyai-mcp — Model Context Protocol server for the PyAI API.
+ *
+ * Exposes PyAI operations (sandbox key minting, models, voices, TTS, async
+ * transcription) as MCP tools so AI coding agents (Cursor, Claude Code, Codex)
+ * can call them directly. Default transport is stdio: reads newline-delimited
+ * JSON-RPC from stdin, writes responses to stdout. All diagnostics go to stderr
+ * so they never corrupt the protocol. Pass `--http` for the experimental HTTP
+ * transport (for hosting a remote server).
+ *
+ * Config (env):
+ *   PYAI_API_KEY   (OPTIONAL) — a pyai_live_ or pyai_test_ key. If absent, the
+ *                  server still starts; call the `create_sandbox_key` tool to
+ *                  mint one with no human steps.
+ *   PYAI_BASE_URL  (optional) — defaults to https://api.pyai.com.
+ *   PORT           (optional, --http only) — defaults to 8080.
+ */
+import { createInterface } from "node:readline";
+import { PyAIClient } from "./client.js";
+import { dispatch } from "./rpc.js";
+import { startHttpServer } from "./http.js";
+function startStdio(client) {
+    const rl = createInterface({ input: process.stdin });
+    const write = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+    rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+            return;
+        }
+        // Process sequentially; each line is an independent JSON-RPC message.
+        dispatch(msg, { client })
+            .then((res) => {
+            if (res)
+                write(res);
+        })
+            .catch((err) => {
+            process.stderr.write(`pyai-mcp: dispatch error: ${err.message}\n`);
+            if (msg.id !== undefined && msg.id !== null) {
+                write({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: "Internal error" } });
+            }
+        });
+    });
+    rl.on("close", () => process.exit(0));
+    process.stderr.write("pyai-mcp: ready on stdio\n");
+}
+function main() {
+    const apiKey = process.env.PYAI_API_KEY;
+    const baseUrl = process.env.PYAI_BASE_URL;
+    if (!apiKey) {
+        process.stderr.write("pyai-mcp: no PYAI_API_KEY set — call the create_sandbox_key tool to mint a free key.\n");
+    }
+    if (process.argv.includes("--http")) {
+        const port = Number(process.env.PORT ?? 8080);
+        startHttpServer({ apiKey, baseUrl, port });
+        return;
+    }
+    startStdio(new PyAIClient({ apiKey, baseUrl }));
+}
+main();

package/dist/rpc.js

@@ -0,0 +1,52 @@
+/**
+ * Minimal MCP (Model Context Protocol) JSON-RPC 2.0 dispatcher over stdio.
+ *
+ * Implements just the methods an MCP host (Cursor, Claude Code, Codex) needs to
+ * discover and call tools: `initialize`, `notifications/initialized`, `ping`,
+ * `tools/list`, `tools/call`. Zero deps so it runs on plain Node 22.
+ *
+ * The stdio transport is newline-delimited JSON-RPC: one JSON object per line.
+ * dispatch() is pure w.r.t. transport (takes a parsed message, returns a parsed
+ * response or null for notifications) so it unit-tests without spawning a process.
+ */
+import { callTool, TOOLS } from "./tools.js";
+export const PROTOCOL_VERSION = "2024-11-05";
+export const SERVER_INFO = { name: "pyai-mcp", version: "0.2.0" };
+function ok(id, result) {
+    return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function fail(id, code, message) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+/**
+ * Handle one JSON-RPC message. Returns the response to write, or null for
+ * notifications (no id) which must not be answered.
+ */
+export async function dispatch(msg, deps) {
+    switch (msg.method) {
+        case "initialize":
+            return ok(msg.id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: SERVER_INFO,
+            });
+        case "notifications/initialized":
+            return null; // notification — no response
+        case "ping":
+            return ok(msg.id, {});
+        case "tools/list":
+            return ok(msg.id, { tools: TOOLS });
+        case "tools/call": {
+            const params = (msg.params ?? {});
+            if (!params.name)
+                return fail(msg.id, -32602, "Missing tool name");
+            const result = await callTool(params.name, params.arguments ?? {}, deps.client);
+            return ok(msg.id, result);
+        }
+        default:
+            // Notifications we don't handle: ignore. Requests: method-not-found.
+            if (msg.id === undefined || msg.id === null)
+                return null;
+            return fail(msg.id, -32601, `Method not found: ${msg.method}`);
+    }
+}

package/dist/tools.js

@@ -0,0 +1,253 @@
+/**
+ * PyAI MCP tools. Each tool maps to a public OpenAPI operation
+ * (https://api.pyai.com/openapi.json) or returns curated, dependency-free
+ * context. callTool runs the operation against a PyAIClient and returns MCP
+ * tool-result content.
+ *
+ * Onboarding-first ordering: `create_sandbox_key` and `get_started` need NO key,
+ * so an agent can go from zero to a working PyAI call with no human steps. The
+ * remaining tools require a key (env `PYAI_API_KEY` or one adopted from
+ * `create_sandbox_key`).
+ */
+import { writeFile } from "node:fs/promises";
+import { PyAIError } from "./client.js";
+function text(value) {
+    const s = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    return { content: [{ type: "text", text: s }] };
+}
+/** Tools that need a configured key. create_sandbox_key + get_started do not. */
+const KEY_REQUIRED = new Set([
+    "list_models",
+    "list_voices",
+    "synthesize_speech",
+    "create_transcription_job",
+    "get_transcription_job",
+    "whoami",
+]);
+const GET_STARTED = [
+    "# Build with the PyAI voice API",
+    "",
+    "Source of truth (fetch it; never invent endpoints):",
+    "- OpenAPI spec: https://api.pyai.com/openapi.json",
+    "- Curated agent index: https://api.pyai.com/llms.txt",
+    "- Docs: https://docs.pyai.com",
+    "",
+    "## 1. Get a key (zero steps)",
+    "Call the `create_sandbox_key` MCP tool — it returns a free `pyai_test_...` key",
+    "that works on the first call (no card, no 402). Store it in `PYAI_API_KEY`.",
+    "For production, create a live key at https://console.pyai.com.",
+    "",
+    "## 2. Install the SDK (preferred over hand-rolled fetch)",
+    "- TypeScript/JS: `npm install @pyai/sdk` then `import PyAI from \"@pyai/sdk\"`",
+    "- Python: `pip install pyai-sdk` then `from pyai import PyAI`",
+    "Keys are opaque (<=512 chars): never parse/split/decode/log them; read from env.",
+    "",
+    "## 3. Text-to-speech (Speak)",
+    "```ts",
+    "import PyAI from \"@pyai/sdk\";",
+    "const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });",
+    "const audio = await pyai.audio.speech({ input: \"Hello from PyAI\", response_format: \"mp3\" });",
+    "// `audio` is an ArrayBuffer of MP3 bytes — write it to a file or stream it.",
+    "```",
+    "",
+    "## 4. Speech-to-text (Hear)",
+    "```ts",
+    "const res = await pyai.audio.transcriptions.create({ file: blob, filename: \"audio.wav\" });",
+    "console.log(res.text);",
+    "```",
+    "",
+    "## 5. Realtime voice agent (Omni)",
+    "Open a WebSocket to `wss://api.pyai.com/v1/omni?format=pcm16&rate=24000`,",
+    "authenticate with the subprotocol `pyai-key.<key>` (browser-safe) or `?api_key=<key>`",
+    "(server). Omni is zero-state — send a `{type:\"configure\"}` frame after connect.",
+    "In the browser, mint a short-lived token server-side with `pyai.omni.createSession(...)`",
+    "instead of shipping a secret key.",
+    "",
+    "## 6. Errors — branch on the stable `error.code`",
+    "`402 credit_exhausted` (add credit / use a sandbox key), `403 forbidden` (missing scope),",
+    "`429 rate_limit_exceeded` (back off, honor `Retry-After`). Don't retry 4xx except 429.",
+].join("\n");
+export const TOOLS = [
+    {
+        name: "create_sandbox_key",
+        description: "Get a FREE PyAI sandbox key with no human steps (no email, card, or signup). " +
+            "Returns a pyai_test_ key that works on the first call and is adopted for the rest " +
+            "of this session, so the other tools work immediately. Call this FIRST if no " +
+            "PYAI_API_KEY is set. The returned key should be stored in the app's PYAI_API_KEY env var.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                label: { type: "string", description: "Optional label (e.g. your app name) shown in the PyAI console." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_started",
+        description: "Return a concise, correct quickstart for building with PyAI (auth, SDK install, " +
+            "TTS/STT/realtime snippets, error handling). No key or network needed — read this " +
+            "before writing PyAI code so you use the right endpoints and the official SDK.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "whoami",
+        description: "Introspect the active key (GET /v1/me): org, environment (test/live), granted scopes, " +
+            "and rate-limit/credit posture. Use it to self-diagnose a 401/403/402.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "list_models",
+        description: "List the available PyAI models (catalog). No arguments.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "list_voices",
+        description: "List PyAI stock + cloned voices. Optionally filter by gender or region. " +
+            "Use a returned voice id as the `voice` for synthesize_speech.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                gender: { type: "string", description: "Filter by voice gender (e.g. female, male)." },
+                region: { type: "string", description: "Filter by accent/region (e.g. en_us, en_gb)." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "synthesize_speech",
+        description: "Text-to-speech. Synthesizes `input` with `voice` and writes the audio to " +
+            "`output_path`. Returns the file path and byte count. Note: consumes sandbox " +
+            "usage quota — for writing app code, prefer get_started over running this.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                input: { type: "string", description: "Text to synthesize." },
+                voice: { type: "string", description: "Voice id from list_voices. Omit for the account default." },
+                output_path: { type: "string", description: "Absolute file path to write the audio to." },
+                model: { type: "string", description: "Defaults to pyai-voice." },
+                response_format: { type: "string", enum: ["wav", "mp3", "opus", "pcm"], description: "Defaults to wav." },
+            },
+            required: ["input", "output_path"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_transcription_job",
+        description: "Submit an async speech-to-text job for an audio URL (https). Returns a " +
+            "job_id; poll with get_transcription_job. Supports diarization.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                audio_url: { type: "string", description: "https URL of the audio to transcribe." },
+                model: { type: "string" },
+                diarize: { type: "boolean", description: "Single-track speaker diarization." },
+                channel: { type: "boolean", description: "Dual-channel (stereo) per-channel speakers." },
+                output_formats: {
+                    type: "array",
+                    items: { type: "string", enum: ["json", "srt", "vtt"] },
+                    description: "Defaults to [json].",
+                },
+            },
+            required: ["audio_url"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_transcription_job",
+        description: "Get the status + result of a transcription job by id.",
+        inputSchema: {
+            type: "object",
+            properties: { job_id: { type: "string", description: "The job_id from create_transcription_job." } },
+            required: ["job_id"],
+            additionalProperties: false,
+        },
+    },
+];
+function str(args, key) {
+    const v = args[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+export async function callTool(name, args, client) {
+    if (KEY_REQUIRED.has(name) && !client.hasKey) {
+        return toolError("No PyAI key configured. Call the `create_sandbox_key` tool first to get a free key with no setup, " +
+            "or set the PYAI_API_KEY env var to a pyai_test_/pyai_live_ key.");
+    }
+    try {
+        switch (name) {
+            case "get_started":
+                return text(GET_STARTED);
+            case "create_sandbox_key": {
+                const label = str(args, "label");
+                const result = await client.postJson("/v1/sandbox/keys", label ? { label } : {});
+                if (result && typeof result.api_key === "string")
+                    client.setApiKey(result.api_key);
+                return text(result);
+            }
+            case "whoami":
+                return text(await client.getJson("/v1/me"));
+            case "list_models":
+                return text(await client.getJson("/v1/models"));
+            case "list_voices": {
+                const q = new URLSearchParams();
+                if (str(args, "gender"))
+                    q.set("gender", str(args, "gender"));
+                if (str(args, "region"))
+                    q.set("region", str(args, "region"));
+                const qs = q.toString();
+                return text(await client.getJson(`/v1/voices${qs ? `?${qs}` : ""}`));
+            }
+            case "synthesize_speech": {
+                const input = str(args, "input");
+                const outputPath = str(args, "output_path");
+                if (!input)
+                    return toolError("`input` is required.");
+                if (!outputPath)
+                    return toolError("`output_path` is required.");
+                const body = { model: str(args, "model") ?? "pyai-voice", input };
+                if (str(args, "voice"))
+                    body.voice = str(args, "voice");
+                if (str(args, "response_format"))
+                    body.response_format = str(args, "response_format");
+                const bytes = await client.postForBytes("/v1/audio/speech", body);
+                await writeFile(outputPath, bytes);
+                return text({ output_path: outputPath, bytes: bytes.byteLength, status: "ok" });
+            }
+            case "create_transcription_job": {
+                const audioUrl = str(args, "audio_url");
+                if (!audioUrl)
+                    return toolError("`audio_url` is required.");
+                const body = { audio_url: audioUrl };
+                if (str(args, "model"))
+                    body.model = str(args, "model");
+                if (typeof args.diarize === "boolean")
+                    body.diarize = args.diarize;
+                if (typeof args.channel === "boolean")
+                    body.channel = args.channel;
+                if (Array.isArray(args.output_formats))
+                    body.output_formats = args.output_formats;
+                return text(await client.postJson("/v1/transcription/jobs", body));
+            }
+            case "get_transcription_job": {
+                const jobId = str(args, "job_id");
+                if (!jobId)
+                    return toolError("`job_id` is required.");
+                return text(await client.getJson(`/v1/transcription/jobs/${encodeURIComponent(jobId)}`));
+            }
+            default:
+                return toolError(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof PyAIError) {
+            if (name === "create_sandbox_key" && err.status === 404) {
+                return toolError("Sandbox-key minting is not enabled on this deployment. Create a free key at " +
+                    "https://console.pyai.com and set it as PYAI_API_KEY.");
+            }
+            return toolError(`PyAI API error ${err.status}${err.code ? ` (${err.code})` : ""}: ${err.message}`);
+        }
+        return toolError(`Tool failed: ${err.message}`);
+    }
+}
+function toolError(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pyai/mcp",
+  "version": "0.2.0",
+  "description": "Model Context Protocol server for the PyAI voice API — lets AI coding agents (Cursor, Claude Code, Codex) get a sandbox key and call PyAI (TTS, STT, voices) directly instead of guessing endpoints.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://docs.pyai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pyai/pyai-platform-backend.git",
+    "directory": "mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pyai",
+    "voice",
+    "tts",
+    "stt",
+    "cursor",
+    "claude",
+    "codex"
+  ],
+  "bin": {
+    "pyai-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node src/index.ts",
+    "start:http": "node src/index.ts --http",
+    "test": "node --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}