@forgemeshlabs/voice-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial x402 Voice MCP release.
+- Added free voice discovery and paid standard, pro, persona, OpenAI-shaped, and batch speech tools.
+- Added Glama registry metadata and Docker build files.

package/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:22-slim
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY index.js README.md server.json ./
+
+ENV NODE_ENV=production
+CMD ["node", "index.js"]

package/README.md

@@ -0,0 +1,76 @@
+# Voice MCP
+
+[![npm version](https://img.shields.io/npm/v/@forgemeshlabs/voice-mcp)](https://www.npmjs.com/package/@forgemeshlabs/voice-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@forgemeshlabs/voice-mcp)](https://www.npmjs.com/package/@forgemeshlabs/voice-mcp)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![payments](https://img.shields.io/badge/payments-x402%20USDC-0052FF)](https://x402.org)
+[![network](https://img.shields.io/badge/network-Base-0052FF)](https://base.org)
+
+Give Your Agent A Voice: x402 pay-per-call speech with 20 voices, 10 personas, 31 languages, granular speed and quality controls, OpenAI-shaped requests, and batch audio.
+
+This MCP wraps `https://voice.forgemesh.io`, an x402 Voice API with standard voices, persona voices, OpenAI-shaped speech requests, 31 languages, speed controls, quality controls, and batch generation. Payments are made per call in USDC on Base.
+
+## Voice Coverage
+
+- 10 standard voices: `M1`-`M5`, `F1`-`F5`
+- 10 persona voices: `Storyteller`, `Narrator`, `Announcer`, `Assistant`, `Urgent`, `Sage`, `Spark`, `Anchor`, `Velvet`, `Echo`
+- 31 languages: `en`, `ko`, `ja`, `ar`, `bg`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `hi`, `hr`, `hu`, `id`, `it`, `lt`, `lv`, `nl`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sv`, `tr`, `uk`, `vi`
+- Granular control: speed `0.7x`-`2.0x`, quality steps `1`-`100`, persona selection, OpenAI-shaped audio format requests, and batch generation for up to 20 texts
+- Voice samples are generated on demand by the paid speech tools and returned as `audio_base64` WAV output
+
+## Voice Samples
+
+- [Assistant sample](https://voice.forgemesh.io/samples/_expressive/combo_assistant.wav)
+- [Urgent sample](https://voice.forgemesh.io/samples/_expressive/combo_urgent.wav)
+- [Narrator sample](https://voice.forgemesh.io/samples/_expressive/combo_narrator.wav)
+- [Storyteller sample](https://voice.forgemesh.io/samples/_expressive/combo_storyteller.wav)
+
+## Tools
+
+| Tool | Price | Purpose |
+|------|-------|---------|
+| `list_tts_voices` | Free | Voices, personas, languages, pricing |
+| `speak_standard` | $0.001 / $0.003 | Standard voices |
+| `speak_pro` | $0.003 / $0.006 | Speed and quality controls |
+| `speak_persona` | $0.005 / $0.01 | Storyteller, Velvet, Narrator, Announcer, Assistant, Urgent, and more |
+| `openai_speech` | $0.001 / $0.003 | OpenAI-shaped `/v1/audio/speech` request |
+| `batch_speak` | $0.002 / $0.005 | Up to 20 texts per call |
+
+Short prices apply to 1-500 characters. Long prices apply to 501-2000 characters.
+
+## Install
+
+```bash
+npm install -g @forgemeshlabs/voice-mcp
+```
+
+## MCP Config
+
+```json
+{
+  "mcpServers": {
+    "voice": {
+      "command": "voice-mcp",
+      "env": {
+        "WALLET_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+Optional:
+
+```json
+{
+  "X402_VOICE_BASE_URL": "https://voice.forgemesh.io",
+  "BASE_RPC_URL": "https://mainnet.base.org"
+}
+```
+
+## Notes
+
+- Paid tools require a Base wallet private key with USDC.
+- The server returns `audio_base64` for audio tools so MCP clients can store, play, or forward the WAV bytes.
+- No API keys or subscriptions are required for the voice service itself.

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Report security issues privately to clawdbotworker@gmail.com.
+
+Do not include private keys, payment headers, or wallet seed phrases in reports. This MCP reads `WALLET_PRIVATE_KEY` only from the runtime environment and does not store secrets.

package/glama.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "name": "voice-mcp",
+  "version": "0.1.0",
+  "description": "Give Your Agent A Voice: x402 pay-per-call speech with 20 voices, 10 personas, 31 languages, granular speed and quality controls, OpenAI-shaped requests, and batch audio.",
+  "homepage": "https://voice.forgemesh.io",
+  "repository": "https://github.com/forgemeshlabs/voice-mcp",
+  "maintainers": [
+    "clawdbotworker"
+  ],
+  "transport": {
+    "type": "stdio",
+    "command": "voice-mcp"
+  },
+  "env": {
+    "WALLET_PRIVATE_KEY": {
+      "description": "Base wallet private key used by the MCP client for paid x402 calls.",
+      "required": true
+    },
+    "X402_VOICE_BASE_URL": {
+      "description": "Optional Voice API base URL.",
+      "required": false,
+      "default": "https://voice.forgemesh.io"
+    },
+    "BASE_RPC_URL": {
+      "description": "Optional Base mainnet RPC URL.",
+      "required": false,
+      "default": "https://mainnet.base.org"
+    }
+  }
+}

package/index.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+"use strict";
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+const { x402Client, x402HTTPClient } = require("@x402/core/client");
+const { ExactEvmScheme } = require("@x402/evm/exact/client");
+const { toClientEvmSigner } = require("@x402/evm");
+const { privateKeyToAccount } = require("viem/accounts");
+const { createPublicClient, http } = require("viem");
+const { base } = require("viem/chains");
+
+const BASE_URL = (
+  process.env.X402_VOICE_BASE_URL ||
+  "https://voice.forgemesh.io"
+).replace(/\/+$/, "");
+const BASE_RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+
+const TOOLS = [
+  {
+    name: "list_tts_voices",
+    description: "List voices, persona voices, languages, prices, and character buckets. Free.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "speak_standard",
+    description: "Give an agent a standard voice using 10 voices and 31 languages. Costs $0.001 for <=500 chars or $0.003 for 501-2000 chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text to synthesize, max 2000 characters" },
+        voice: { type: "string", description: "Standard voice: M1-M5 or F1-F5" },
+        lang: { type: "string", description: "Language code, default en" },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "speak_pro",
+    description: "Generate tuned agent speech with speed and quality controls. Costs $0.003 for <=500 chars or $0.006 for 501-2000 chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text to synthesize, max 2000 characters" },
+        voice: { type: "string", description: "Standard voice: M1-M5 or F1-F5" },
+        lang: { type: "string", description: "Language code, default en" },
+        speed: { type: "number", description: "Speech speed, 0.7-2.0" },
+        steps: { type: "integer", description: "Quality steps, 1-100" },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "speak_persona",
+    description: "Give an agent a persona voice such as Storyteller, Velvet, Narrator, Announcer, Assistant, or Urgent. Costs $0.005 for <=500 chars or $0.01 for 501-2000 chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Text to synthesize, max 2000 characters" },
+        voice: { type: "string", description: "Persona voice name, default Storyteller" },
+        lang: { type: "string", description: "Language code, default en" },
+        speed: { type: "number", description: "Speech speed, 0.7-2.0" },
+        steps: { type: "integer", description: "Quality steps, 1-100" },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "openai_speech",
+    description: "OpenAI-shaped speech request for agents already wired to /v1/audio/speech. Costs $0.001 for <=500 chars or $0.003 for 501-2000 chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        input: { type: "string", description: "Text to synthesize, max 2000 characters" },
+        voice: { type: "string", description: "Standard voice: M1-M5 or F1-F5" },
+        model: { type: "string", description: "Optional model field; service uses ForgeMesh Voice" },
+        response_format: { type: "string", description: "wav, flac, or ogg" },
+      },
+      required: ["input"],
+    },
+  },
+  {
+    name: "batch_speak",
+    description: "Generate audio for up to 20 standard-voice texts in one paid call. Costs $0.002 for <=500 total chars or $0.005 for 501-2000 total chars.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        items: {
+          type: "array",
+          description: "Array of text items: { text, voice?, lang? }",
+          items: { type: "object" },
+        },
+        defaults: { type: "object", description: "Default standard voice and language" },
+      },
+      required: ["items"],
+    },
+  },
+];
+
+const TOOL_SCHEMAS = {
+  list_tts_voices: {},
+  speak_standard: {
+    text: z.string().describe("Text to synthesize, max 2000 characters"),
+    voice: z.string().optional().describe("Standard voice: M1-M5 or F1-F5"),
+    lang: z.string().optional().describe("Language code, default en"),
+  },
+  speak_pro: {
+    text: z.string().describe("Text to synthesize, max 2000 characters"),
+    voice: z.string().optional().describe("Standard voice: M1-M5 or F1-F5"),
+    lang: z.string().optional().describe("Language code, default en"),
+    speed: z.number().optional().describe("Speech speed, 0.7-2.0"),
+    steps: z.number().int().optional().describe("Quality steps, 1-100"),
+  },
+  speak_persona: {
+    text: z.string().describe("Text to synthesize, max 2000 characters"),
+    voice: z.string().optional().describe("Persona voice name, default Storyteller"),
+    lang: z.string().optional().describe("Language code, default en"),
+    speed: z.number().optional().describe("Speech speed, 0.7-2.0"),
+    steps: z.number().int().optional().describe("Quality steps, 1-100"),
+  },
+  openai_speech: {
+    input: z.string().describe("Text to synthesize, max 2000 characters"),
+    voice: z.string().optional().describe("Standard voice: M1-M5 or F1-F5"),
+    model: z.string().optional().describe("Optional model field; service uses ForgeMesh Voice"),
+    response_format: z.string().optional().describe("wav, flac, or ogg"),
+  },
+  batch_speak: {
+    items: z.array(z.object({
+      text: z.string(),
+      voice: z.string().optional(),
+      lang: z.string().optional(),
+    })).min(1).max(20).describe("Array of text items"),
+    defaults: z.object({
+      voice: z.string().optional(),
+      lang: z.string().optional(),
+    }).optional().describe("Default standard voice and language"),
+  },
+};
+
+function pickBucketEndpoint(shortPath, longPath, length) {
+  if (length > 2000) throw new Error("Text is over the 2000 character maximum");
+  return length > 500 ? longPath : shortPath;
+}
+
+function requireWalletClient() {
+  const key = process.env.WALLET_PRIVATE_KEY;
+  if (!key) throw new Error("WALLET_PRIVATE_KEY required for paid voice tools");
+  const pk = key.startsWith("0x") ? key : "0x" + key;
+  const account = privateKeyToAccount(pk);
+  const coreClient = new x402Client().register("eip155:*", new ExactEvmScheme(toClientEvmSigner(account)));
+  return { httpClient: new x402HTTPClient(coreClient), account };
+}
+
+async function createChainTimedPaymentPayload(httpClient, paymentRequired) {
+  try {
+    const publicClient = createPublicClient({ chain: base, transport: http(BASE_RPC_URL) });
+    const block = await publicClient.getBlock();
+    const chainNow = Number(block.timestamp);
+    const originalNow = Date.now;
+    const localNow = Math.floor(originalNow() / 1000);
+    const timeout = Number(paymentRequired.accepts?.[0]?.maxTimeoutSeconds || 300);
+    const lowerBound = localNow + 30 - timeout;
+    const upperBound = chainNow + 600;
+    const signingNow = Math.min(Math.max(chainNow, lowerBound), upperBound);
+    Date.now = () => signingNow * 1000;
+    try {
+      return await httpClient.createPaymentPayload(paymentRequired);
+    } finally {
+      Date.now = originalNow;
+    }
+  } catch (_) {
+    return httpClient.createPaymentPayload(paymentRequired);
+  }
+}
+
+async function paidPost(path, body) {
+  const { httpClient } = requireWalletClient();
+  const url = BASE_URL + path;
+  const init = {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  };
+  const challengeRes = await fetch(url, init);
+  if (challengeRes.status !== 402) {
+    const text = await challengeRes.text().catch(() => "");
+    throw new Error(`Expected x402 challenge, got ${challengeRes.status}: ${text.slice(0, 240)}`);
+  }
+
+  let challengeBody;
+  try {
+    challengeBody = await challengeRes.clone().json();
+  } catch (_) {}
+  const paymentRequired = httpClient.getPaymentRequiredResponse(
+    (name) => challengeRes.headers.get(name),
+    challengeBody
+  );
+  const paymentPayload = await createChainTimedPaymentPayload(httpClient, paymentRequired);
+  const paidRes = await fetch(url, {
+    ...init,
+    headers: {
+      ...init.headers,
+      ...httpClient.encodePaymentSignatureHeader(paymentPayload),
+    },
+  });
+  if (!paidRes.ok) {
+    const text = await paidRes.text().catch(() => paidRes.statusText);
+    throw new Error(`Paid TTS call failed: ${paidRes.status} ${text.slice(0, 240)}`);
+  }
+
+  const paymentReceipt = paidRes.headers.get("payment-response");
+  const contentType = paidRes.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    const json = await paidRes.json();
+    return { content_type: contentType, response: json, payment_response: paymentReceipt };
+  }
+  const audio = Buffer.from(await paidRes.arrayBuffer());
+  return {
+    content_type: contentType || "audio/wav",
+    audio_base64: audio.toString("base64"),
+    bytes: audio.length,
+    payment_response: paymentReceipt,
+  };
+}
+
+async function freeGet(path) {
+  const res = await fetch(BASE_URL + path);
+  if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
+  return res.json();
+}
+
+function textResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+async function callTool(name, args = {}) {
+  if (name === "list_tts_voices") return freeGet("/v1/voices");
+
+  if (name === "speak_standard") {
+    const text = String(args.text || "");
+    const path = pickBucketEndpoint("/v1/tts/base", "/v1/tts/base-long", text.length);
+    return paidPost(path, { text, voice: args.voice || "M1", lang: args.lang || "en" });
+  }
+
+  if (name === "speak_pro") {
+    const text = String(args.text || "");
+    const path = pickBucketEndpoint("/v1/tts/pro", "/v1/tts/pro-long", text.length);
+    return paidPost(path, {
+      text,
+      voice: args.voice || "M1",
+      lang: args.lang || "en",
+      speed: args.speed,
+      steps: args.steps,
+    });
+  }
+
+  if (name === "speak_persona") {
+    const text = String(args.text || "");
+    const path = pickBucketEndpoint("/v1/tts/custom", "/v1/tts/custom-long", text.length);
+    return paidPost(path, {
+      text,
+      voice: args.voice || "Storyteller",
+      lang: args.lang || "en",
+      speed: args.speed,
+      steps: args.steps,
+    });
+  }
+
+  if (name === "openai_speech") {
+    const input = String(args.input || "");
+    const path = pickBucketEndpoint("/v1/audio/speech", "/v1/audio/speech-long", input.length);
+    return paidPost(path, {
+      input,
+      voice: args.voice || "M1",
+      model: args.model || "forgemesh-voice",
+      response_format: args.response_format || "wav",
+    });
+  }
+
+  if (name === "batch_speak") {
+    if (!Array.isArray(args.items) || args.items.length === 0) throw new Error("items must be a non-empty array");
+    const totalChars = args.items.reduce((sum, item) => sum + String(item?.text || "").length, 0);
+    const path = pickBucketEndpoint("/v1/tts/batch", "/v1/tts/batch-long", totalChars);
+    return paidPost(path, { items: args.items, defaults: args.defaults || { voice: "F2", lang: "en" } });
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+const server = new McpServer({ name: "voice-mcp", version: "0.1.0" });
+server.server.onerror = (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+};
+for (const tool of TOOLS) {
+  server.registerTool(
+    tool.name,
+    {
+      title: tool.name,
+      description: tool.description,
+      inputSchema: TOOL_SCHEMAS[tool.name],
+    },
+    async (args) => {
+      try {
+        return textResult(await callTool(tool.name, args || {}));
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+        };
+      }
+    }
+  );
+}
+
+async function main() {
+  await server.connect(new StdioServerTransport());
+  process.stdin.resume();
+  const keepAlive = setInterval(() => {}, 2 ** 30);
+  process.stdin.on("end", () => clearInterval(keepAlive));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  TOOL_SCHEMAS,
+  callTool,
+  pickBucketEndpoint,
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@forgemeshlabs/voice-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.forgemeshlabs/voice-mcp",
+  "description": "Give Your Agent A Voice: x402 pay-per-call speech with 20 voices, 10 personas, 31 languages, granular speed and quality controls, OpenAI-shaped requests, and batch audio",
+  "main": "index.js",
+  "bin": {
+    "voice-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "Dockerfile",
+    "glama.json",
+    "server.json"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "check": "node --check index.js",
+    "test": "npm run check && node scripts/test-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "text-to-speech",
+    "tts",
+    "voice",
+    "agent-voice",
+    "openai-compatible",
+    "forgemesh",
+    "coinbase",
+    "base",
+    "usdc",
+    "micropayments"
+  ],
+  "author": "clawdbotworker <clawdbotworker@gmail.com>",
+  "maintainers": [
+    "clawdbotworker <clawdbotworker@gmail.com>"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forgemeshlabs/voice-mcp.git"
+  },
+  "homepage": "https://voice.forgemesh.io",
+  "bugs": {
+    "url": "https://github.com/forgemeshlabs/voice-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "@x402/core": "2.11.0",
+    "@x402/evm": "2.11.0",
+    "zod": "^3.25.76",
+    "viem": "^2.0.0"
+  },
+  "overrides": {
+    "ws": "8.21.0"
+  }
+}

package/server.json

@@ -0,0 +1,11 @@
+{
+  "name": "voice-mcp",
+  "version": "0.1.0",
+  "description": "Give Your Agent A Voice: x402 pay-per-call speech with 20 voices, 10 personas, 31 languages, granular speed and quality controls, OpenAI-shaped requests, and batch audio",
+  "homepage": "https://voice.forgemesh.io",
+  "repository": "https://github.com/forgemeshlabs/voice-mcp",
+  "transport": {
+    "type": "stdio",
+    "command": "voice-mcp"
+  }
+}