@chamade/mcp-server 1.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @chamade/mcp-server
+
+MCP (Model Context Protocol) server for Chamade — voice gateway for AI agents.
+
+Your agent gets tools to join voice meetings on Discord, Teams, Meet, Telegram, SIP and Nextcloud Talk. Chamade handles STT, TTS and the meeting connection. The agent only sees text.
+
+## Quick start
+
+```bash
+npx @chamade/mcp-server
+```
+
+Requires `CHAMADE_API_KEY` env var. Get one at https://chamade.io/dashboard.
+
+## Configuration
+
+### OpenClaw
+
+```json
+{
+  "agents": {
+    "list": [{
+      "id": "main",
+      "mcp": {
+        "servers": [{
+          "name": "chamade",
+          "command": "npx",
+          "args": ["-y", "@chamade/mcp-server"],
+          "env": {
+            "CHAMADE_API_KEY": "chmd_..."
+          }
+        }]
+      }
+    }]
+  }
+}
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chamade": {
+      "command": "npx",
+      "args": ["-y", "@chamade/mcp-server"],
+      "env": {
+        "CHAMADE_API_KEY": "chmd_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+`.cursor/mcp.json` or `.windsurf/mcp.json` — same format as Claude Desktop.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `chamade_join` | Join a voice meeting (platform + meeting_url). |
+| `chamade_say` | Speak text aloud via TTS in the meeting. |
+| `chamade_chat` | Send a text chat message in the meeting. |
+| `chamade_status` | Get call state and new transcript lines (delta pattern). |
+| `chamade_answer` | Answer a ringing inbound call (SIP, etc.). |
+| `chamade_typing` | Send a typing indicator in chat or DM. |
+| `chamade_leave` | Hang up and leave the meeting. |
+| `chamade_list_calls` | List all active calls. |
+| `chamade_inbox` | Check DM conversations (Discord, Telegram, Teams, etc.). |
+| `chamade_send` | Send a DM message to a conversation. |
+| `chamade_account` | Check account status, plan, credit/quota, and platform readiness. |
+
+## Resources
+
+| URI template | Description |
+|--------------|-------------|
+| `chamade://calls/{call_id}/transcript` | Live transcript. Subscribe for `notifications/resources/updated` push on each new line. Each read returns only new lines since last read. |
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CHAMADE_API_KEY` | Yes | — | API key (`chmd_*`) from chamade.io/dashboard |
+| `CHAMADE_URL` | No | `https://chamade.io` | Chamade API base URL |
+
+## Supported platforms
+
+- **Discord** — voice channels (no OAuth needed, pass channel link)
+- **Microsoft Teams** — requires OAuth connection on dashboard
+- **Google Meet** — requires OAuth connection on dashboard
+- **Telegram** — voice chats (pass invite link)
+- **Zoom** — pass meeting URL
+- **SIP / Phone** — pass phone number or SIP URI
+- **Nextcloud Talk** — pass meeting URL
+- **WhatsApp** — text DM only (pass phone number)
+
+## How it works
+
+```
+Agent (OpenClaw, Claude, ...)
+  │ MCP (stdio JSON-RPC)
+  ▼
+@chamade/mcp-server          (runs locally)
+  │ HTTPS + WSS
+  ▼
+Chamade API                  (chamade.io)
+  │ HTTP + WS
+  ▼
+Maquisard bridge             (handles audio, STT/TTS)
+  │
+  ▼
+Discord / Teams / Meet / ...
+```
+
+The MCP server is a thin client. It calls the Chamade REST API to create/manage calls and poll transcripts. Transcripts are exposed as an MCP resource with a delta-read pattern (only new lines since last read).
+
+## Development
+
+```bash
+npm install
+npm run dev     # runs with tsx (hot reload)
+npm run build   # compiles to dist/
+```

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Chamade MCP Server
+ *
+ * Exposes Chamade voice gateway as MCP tools + resources.
+ * Agents can join meetings on Discord, Teams, Meet, Telegram, SIP
+ * and receive live transcripts via resource subscriptions.
+ *
+ * Two modes:
+ * - Standard MCP (default): agent polls chamade_status for transcripts
+ * - Channel mode (--channel): transcripts and events pushed via notifications
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,826 @@
+#!/usr/bin/env node
+/**
+ * Chamade MCP Server
+ *
+ * Exposes Chamade voice gateway as MCP tools + resources.
+ * Agents can join meetings on Discord, Teams, Meet, Telegram, SIP
+ * and receive live transcripts via resource subscriptions.
+ *
+ * Two modes:
+ * - Standard MCP (default): agent polls chamade_status for transcripts
+ * - Channel mode (--channel): transcripts and events pushed via notifications
+ */
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import WebSocket from "ws";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const CHAMADE_URL = (process.env.CHAMADE_URL || "https://chamade.io").replace(/\/$/, "");
+const API_KEY = process.env.CHAMADE_API_KEY || "";
+if (!API_KEY) {
+    console.error("[chamade-mcp] CHAMADE_API_KEY is required. Get one at https://chamade.io/dashboard");
+    process.exit(1);
+}
+const headers = {
+    "X-API-Key": API_KEY,
+    "Content-Type": "application/json",
+};
+// ---------------------------------------------------------------------------
+// Channel mode
+// ---------------------------------------------------------------------------
+const CHANNEL_MODE = process.env.CHAMADE_CHANNEL === "1" || process.argv.includes("--channel");
+const CHAMADE_WS_URL = CHAMADE_URL.replace(/^http/, "ws");
+const calls = new Map();
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// Ensure path ends with / before query string to avoid Cloudflare 301 redirect
+function _url(path) {
+    const qIdx = path.indexOf("?");
+    if (qIdx === -1) {
+        return `${CHAMADE_URL}${path.endsWith("/") ? path : path + "/"}`;
+    }
+    const base = path.slice(0, qIdx);
+    const query = path.slice(qIdx);
+    return `${CHAMADE_URL}${base.endsWith("/") ? base : base + "/"}${query}`;
+}
+async function chamadePost(path, body) {
+    const res = await fetch(_url(path), {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Chamade ${path} ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+async function chamadeDelete(path) {
+    const res = await fetch(_url(path), {
+        method: "DELETE",
+        headers,
+    });
+    if (!res.ok && res.status !== 404) {
+        const text = await res.text();
+        throw new Error(`Chamade ${path} ${res.status}: ${text}`);
+    }
+}
+async function chamadeGet(path) {
+    const res = await fetch(_url(path), { headers });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Chamade ${path} ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ---------------------------------------------------------------------------
+// Instructions
+// ---------------------------------------------------------------------------
+const CHANNEL_PREAMBLE = [
+    "## Channel mode — events arrive automatically",
+    "",
+    "Transcripts, messages, and calls are pushed to you in real-time.",
+    "Do NOT poll chamade_status in a loop — you will be notified automatically.",
+    "When you receive transcript lines, respond using chamade_say (TTS) or chamade_chat (text).",
+    "When you receive a message, reply using chamade_send.",
+    "When you receive an incoming call, use chamade_answer to pick up.",
+    "You can still call chamade_status manually to catch up on missed transcript.",
+    "",
+].join("\n");
+const BASE_INSTRUCTIONS = [
+    "Chamade is a voice gateway for AI agents. It lets you join voice meetings (Discord, Teams, Meet, Telegram, SIP) and interact via speech and text.",
+    "",
+    "## Voice call workflow",
+    "1. Use chamade_join to enter a meeting — returns a call_id and capabilities.",
+    "2. Poll chamade_status in a loop to read new transcript lines (delta pattern — only new lines since last call).",
+    "3. When you see new transcript, respond to the CONTENT using chamade_say (TTS) or chamade_chat (text).",
+    "4. Repeat step 2-3. Keep the call active — do NOT leave between exchanges.",
+    "5. Use chamade_leave only when explicitly asked or when the meeting ends.",
+    "",
+    "## SIP phone calls",
+    "SIP supports both outbound and inbound calls. Setup depends on the tier:",
+    "- Outbound (Pro plan only): call chamade_join with platform='sip' and meeting_url='sip:+33...@provider'. Uses the user's own SIP trunk (configured in the dashboard).",
+    "- Inbound (répondeur): user activates a phone number (DID) in the dashboard. Incoming calls appear as 'ringing' in chamade_list_calls.",
+    "- Inbound (BYOT): user connects their own SIP trunk + DIDs in the dashboard. Same inbound flow.",
+    "",
+    "Inbound call workflow:",
+    "1. Use chamade_list_calls to see ringing calls (poll regularly).",
+    "2. Use chamade_answer to pick up the call.",
+    "3. Use chamade_say to speak and chamade_status to read transcript (same as outbound).",
+    "4. If auto_answer is enabled, calls go straight to 'active' — no need to answer.",
+    "",
+    "## Recovery from disconnection",
+    "If the bridge restarts or connection is lost, the call state becomes 'disconnected'.",
+    "chamade_status will show instructions to reconnect.",
+    "To recover: call chamade_join again with the same platform and meeting_url.",
+    "A new call_id is issued. Previous transcript is lost.",
+    "",
+    "## DM / Messaging workflow",
+    "1. Use chamade_inbox to check for incoming DM conversations.",
+    "2. Before composing a reply, use chamade_typing to show the user you are working on it.",
+    "3. Use chamade_send to reply to a conversation.",
+    "4. When a conversation has a call_id (voice_started), use chamade_say/chamade_status on it.",
+    "",
+    "## Capabilities",
+    "Each call and conversation returns a capabilities array. Meaning:",
+    "- listen: receive audio transcripts (STT)",
+    "- speak: send audio via TTS (chamade_say)",
+    "- read: receive text chat messages",
+    "- write: send text chat messages (chamade_chat)",
+    "- typing: typing indicator supported (chamade_typing)",
+    "- files: file sharing supported",
+    "",
+    "Per-platform defaults:",
+    "- discord/teams: listen, speak, read, write, typing, files (full voice + chat)",
+    "- meet: listen, read, write (no TTS — use chamade_chat instead). Note: chat (read/write) only works for calendar-scheduled meetings. Ad-hoc Meet links have no chat API access.",
+    "- zoom: listen, speak, read, write, files",
+    "- telegram: read, write, typing, files (text DM only, no voice join)",
+    "- whatsapp: read, write, typing (text DM only, no voice join)",
+    "- sip: listen, speak (voice only, no chat)",
+    "- nctalk: listen, speak, read, write, typing",
+    "",
+    "If 'speak' is not in capabilities, use chamade_chat to send text instead of chamade_say.",
+    "",
+    "## Platform requirements",
+    "Each platform requires specific setup by the user in the Chamade dashboard (https://chamade.io/dashboard):",
+    "- teams: Microsoft OAuth connection (for OnlineMeetings access)",
+    "- meet: Google OAuth connection (for Calendar API access)",
+    "- discord: a Discord bot token registered in the dashboard",
+    "- telegram: a Telegram bot token registered in the dashboard",
+    "- sip outbound: a SIP trunk connected in the dashboard (Pro plan required)",
+    "- sip inbound: a phone number (DID) activated in the dashboard — either répondeur (pool) or BYOT (own trunk)",
+    "- zoom/nctalk/whatsapp: just a meeting_url, no setup needed",
+    "",
+    "## Account status",
+    "Use chamade_account to check platform readiness and remaining credit/quota before making calls.",
+    "Each platform shows: ok, not_configured (needs dashboard setup), or error (connection problem).",
+    "",
+    "## Common errors and what to tell the user",
+    "- \"No discord bot registered\" → user needs to add a Discord bot token in the dashboard",
+    "- \"No telegram bot registered\" → user needs to add a Telegram bot token in the dashboard",
+    "- \"meeting_url required, or connect your account\" → user needs to connect their Microsoft/Google account via OAuth in the dashboard, or provide a meeting URL",
+    "- \"Concurrent call limit reached\" → end an active call first (free plan: 1 concurrent call)",
+    "- \"Voice quota exceeded\" → monthly voice minutes used up (free plan: 10 min/month)",
+    "- \"SIP not available on free plan\" → user needs to upgrade to Pro for SIP calls",
+    "- \"No SIP trunk configured\" → user needs to connect a SIP trunk in the dashboard for outbound SIP",
+    "- \"Direct audio requires a Pro plan\" → direct audio streaming (raw PCM via WebSocket) is Pro only. Free users can still use chamade_say (TTS) within their voice quota",
+    "",
+    "## Speech style",
+    "- Speak naturally and concisely — your text is converted to speech.",
+    "- Avoid markdown, code blocks, bullet lists, or long enumerations.",
+    "- Do NOT echo or repeat what people say — respond to the content.",
+    "- Use punctuation to shape delivery: '...' for hesitation, '!' for energy, '—' for a dramatic pause.",
+    "- Use CAPS sparingly for emphasis on key words (e.g. 'That is VERY important').",
+    "- Short sentences feel snappy and urgent. Longer, flowing sentences slow the pace.",
+    "- One call per Discord server (bot limitation).",
+].join("\n");
+const INSTRUCTIONS = CHANNEL_MODE
+    ? CHANNEL_PREAMBLE + BASE_INSTRUCTIONS
+    : BASE_INSTRUCTIONS;
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "chamade",
+    version: "1.1.0",
+}, {
+    capabilities: CHANNEL_MODE
+        ? { experimental: { "claude/channel": {} } }
+        : undefined,
+    instructions: INSTRUCTIONS,
+});
+// -- Tool: join -------------------------------------------------------------
+server.tool("chamade_join", "Join a voice meeting on any platform (Discord, Teams, Meet, Telegram, SIP, WhatsApp). Returns a call_id. After joining, poll chamade_status regularly to read new transcript lines. Use chamade_say to speak (TTS) and chamade_leave to hang up. Keep the call active — do NOT leave between exchanges.", {
+    platform: z
+        .enum(["discord", "teams", "meet", "telegram", "sip", "nctalk", "zoom", "whatsapp"])
+        .describe("Meeting platform"),
+    meeting_url: z
+        .string()
+        .describe("Meeting URL (e.g. Discord channel link, Teams join link, phone number for SIP)"),
+    agent_name: z
+        .string()
+        .default("AI Agent")
+        .describe("Display name in the meeting"),
+}, async ({ platform, meeting_url, agent_name }) => {
+    const data = (await chamadePost("/api/call", {
+        platform,
+        meeting_url,
+        agent_name,
+    }));
+    const callId = data.call_id;
+    const capabilities = data.capabilities ?? [];
+    const audio = data.audio;
+    calls.set(callId, {
+        callId,
+        platform,
+        meetingUrl: meeting_url,
+        capabilities,
+        lastTranscriptLength: 0,
+    });
+    // Channel mode: auto-watch for transcript push
+    if (CHANNEL_MODE) {
+        channelWatchCall(callId);
+    }
+    const lines = [
+        `Joined ${platform} meeting.`,
+        `Call ID: ${callId}`,
+        `State: ${data.state}`,
+        `Capabilities: ${capabilities.join(", ") || "unknown"}`,
+    ];
+    if (audio) {
+        lines.push(`Audio: ${audio.sample_rate}Hz ${audio.format} (${audio.frame_duration_ms}ms frames, ${audio.frame_bytes} bytes/frame)`);
+    }
+    if (!capabilities.includes("speak")) {
+        lines.push(`Note: TTS (speak) is not supported on ${platform}. Use chamade_chat to send text instead.`);
+    }
+    if (CHANNEL_MODE) {
+        lines.push(``, `Transcript will be pushed automatically. Use chamade_say to speak, chamade_chat to send text, chamade_leave to hang up.`);
+    }
+    else {
+        lines.push(`Transcript: chamade://calls/${callId}/transcript`, ``, `Use chamade_say to speak, chamade_chat to send text, chamade_status to check transcript, chamade_leave to hang up.`);
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: lines.join("\n"),
+            },
+        ],
+    };
+});
+// -- Tool: say --------------------------------------------------------------
+server.tool("chamade_say", "Speak text aloud in the meeting via TTS. Write naturally and concisely — avoid markdown, code blocks, or long lists as the text is converted to speech. Respond to the CONTENT of what people say, do not echo or repeat their words. Use punctuation to shape delivery: '...' for hesitation, '!' for energy, '—' for a pause. Use CAPS sparingly for emphasis.", {
+    call_id: z.string().describe("Call ID from chamade_join"),
+    text: z.string().describe("Text to speak aloud"),
+}, async ({ call_id, text }) => {
+    await chamadePost(`/api/call/${call_id}/say`, { text });
+    return {
+        content: [{ type: "text", text: `Speaking: "${text}"` }],
+    };
+});
+// -- Tool: chat -------------------------------------------------------------
+server.tool("chamade_chat", "Send a text chat message in the meeting.", {
+    call_id: z.string().describe("Call ID from chamade_join"),
+    text: z.string().describe("Chat message to send"),
+}, async ({ call_id, text }) => {
+    await chamadePost(`/api/call/${call_id}/chat`, { text });
+    return {
+        content: [{ type: "text", text: `Chat sent: "${text}"` }],
+    };
+});
+// -- Tool: status -----------------------------------------------------------
+server.tool("chamade_status", "Get call status and new transcript lines since last check. Poll this regularly to listen to what people are saying. Returns only new lines since the previous call (delta pattern).", {
+    call_id: z.string().describe("Call ID from chamade_join"),
+}, async ({ call_id }) => {
+    const state = calls.get(call_id);
+    const since = state?.lastTranscriptLength ?? 0;
+    const data = (await chamadeGet(`/api/call/${call_id}?since=${since}`));
+    const transcriptLength = data.transcript_length ?? 0;
+    if (state) {
+        state.lastTranscriptLength = transcriptLength;
+    }
+    const lines = data.transcript ?? [];
+    let transcript = "";
+    if (lines.length > 0) {
+        transcript = "\n\nNew transcript:\n" + lines.join("\n");
+    }
+    const capabilities = data.capabilities ?? [];
+    // Update local state with capabilities from server
+    if (state && capabilities.length > 0) {
+        state.capabilities = capabilities;
+    }
+    const direction = data.direction || "outbound";
+    const caller = data.caller || "";
+    const statusLines = [
+        `Call: ${data.call_id}`,
+        `Platform: ${data.platform}`,
+        `State: ${data.state}`,
+        direction === "inbound" ? `Direction: inbound` : "",
+        caller ? `Caller: ${caller}` : "",
+        `Capabilities: ${capabilities.join(", ") || "unknown"}`,
+        `Agent: ${data.agent_name}`,
+        `Created: ${data.created_at}`,
+        data.ended_at ? `Ended: ${data.ended_at}` : "",
+    ];
+    if (data.state === "ringing") {
+        statusLines.push(``, `Incoming call! Use chamade_answer to pick up, or chamade_leave to reject.`);
+    }
+    if (data.state === "disconnected") {
+        const meetingUrl = state?.meetingUrl || data.meeting_url || "";
+        const platform = state?.platform || data.platform || "";
+        statusLines.push(``, `⚠ Bridge connection lost. The voice session has been interrupted.`, `To reconnect, call chamade_join again with platform="${platform}" and meeting_url="${meetingUrl}".`, `A new call_id will be issued. Previous transcript is lost.`);
+    }
+    if (!capabilities.includes("speak")) {
+        statusLines.push(`Note: TTS (speak) is not supported on ${data.platform}. Use chamade_chat to send text instead.`);
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: statusLines
+                    .filter(Boolean)
+                    .join("\n") + transcript,
+            },
+        ],
+    };
+});
+// -- Tool: answer -----------------------------------------------------------
+server.tool("chamade_answer", "Answer a ringing inbound call. Use this when chamade_list_calls or chamade_status shows a call in 'ringing' state (incoming phone call). The call transitions to 'active' and you can start speaking.", {
+    call_id: z.string().describe("Call ID of the ringing call"),
+}, async ({ call_id }) => {
+    await chamadePost(`/api/call/${call_id}/answer`, {});
+    // Fetch call details to get real capabilities and platform
+    const data = (await chamadeGet(`/api/call/${call_id}`));
+    const platform = data.platform || "sip";
+    const capabilities = data.capabilities ?? ["listen", "speak"];
+    // Track the call locally
+    calls.set(call_id, {
+        callId: call_id,
+        platform,
+        meetingUrl: data.meeting_url || "",
+        capabilities,
+        lastTranscriptLength: 0,
+    });
+    // Channel mode: auto-watch for transcript push
+    if (CHANNEL_MODE) {
+        channelWatchCall(call_id);
+    }
+    const lines = [
+        `Answered call ${call_id}.`,
+        `State: active`,
+        `Capabilities: ${capabilities.join(", ")}`,
+        ``,
+        `Use chamade_say to speak, chamade_status to check transcript, chamade_leave to hang up.`,
+    ];
+    if (!capabilities.includes("speak")) {
+        lines.push(`Note: TTS (speak) is not supported on ${platform}. Use chamade_chat to send text instead.`);
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: lines.join("\n"),
+            },
+        ],
+    };
+});
+// -- Tool: typing -----------------------------------------------------------
+server.tool("chamade_typing", "Send a typing indicator. Use this before composing a reply so the user sees you are working on it. Only works on platforms with 'typing' in capabilities (Discord, Teams, Telegram, NC Talk).", {
+    call_id: z
+        .string()
+        .optional()
+        .describe("Call ID (for typing in a call's chat)"),
+    conversation_id: z
+        .string()
+        .optional()
+        .describe("Conversation ID (for typing in a DM)"),
+}, async ({ call_id, conversation_id }) => {
+    if (call_id) {
+        await chamadePost(`/api/call/${call_id}/typing`, {});
+    }
+    else if (conversation_id) {
+        await chamadePost("/api/typing", { conversation_id });
+    }
+    else {
+        throw new Error("Either call_id or conversation_id is required");
+    }
+    return {
+        content: [{ type: "text", text: "Typing indicator sent." }],
+    };
+});
+// -- Tool: leave ------------------------------------------------------------
+server.tool("chamade_leave", "Leave the meeting and hang up. Only use when explicitly asked to leave or when the meeting is over.", {
+    call_id: z.string().describe("Call ID from chamade_join"),
+}, async ({ call_id }) => {
+    calls.delete(call_id);
+    // Channel mode: stop watching
+    if (CHANNEL_MODE) {
+        channelUnwatchCall(call_id);
+    }
+    await chamadeDelete(`/api/call/${call_id}`);
+    return {
+        content: [{ type: "text", text: `Left call ${call_id}.` }],
+    };
+});
+// -- Tool: list_calls -------------------------------------------------------
+server.tool("chamade_list_calls", "List all active calls.", {}, async () => {
+    const data = (await chamadeGet("/api/calls"));
+    if (data.calls.length === 0) {
+        return {
+            content: [{ type: "text", text: "No active calls." }],
+        };
+    }
+    const lines = data.calls.map((c) => {
+        const direction = c.direction === "inbound" ? " [inbound]" : "";
+        const caller = c.caller ? ` from ${c.caller}` : "";
+        const url = c.meeting_url ? ` — ${c.meeting_url}` : "";
+        return `- ${c.id} (${c.platform}) — ${c.state}${direction}${caller}${url}`;
+    });
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// -- Tool: account ----------------------------------------------------------
+server.tool("chamade_account", "Check account status: plan, credit/quota remaining, and per-platform readiness (ok, not_configured, error). Use this to diagnose setup issues or check remaining credit before making calls.", {}, async () => {
+    const data = (await chamadeGet("/api/account"));
+    const lines = [`Plan: ${data.plan}`];
+    // Credit or voice quota
+    const credit = data.credit;
+    const voice = data.voice_quota;
+    if (credit) {
+        lines.push(`Credit: ${credit.remaining_eur.toFixed(2)} EUR remaining (${credit.used_eur.toFixed(2)} / ${credit.total_eur.toFixed(2)} EUR used)`);
+    }
+    else if (voice) {
+        lines.push(`Voice quota: ${voice.used_minutes.toFixed(1)} / ${voice.limit_minutes} min used`);
+    }
+    const concurrent = data.concurrent_calls;
+    if (concurrent) {
+        const limitStr = concurrent.limit === 0 ? "unlimited" : String(concurrent.limit);
+        lines.push(`Active calls: ${concurrent.active} / ${limitStr}`);
+    }
+    // Platform statuses
+    const platforms = data.platforms;
+    if (platforms) {
+        lines.push("", "Platforms:");
+        for (const [name, status] of Object.entries(platforms)) {
+            const icon = status.startsWith("ok") ? "+" : status.startsWith("error") ? "!" : "-";
+            lines.push(`  ${icon} ${name}: ${status}`);
+        }
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// -- Tool: inbox ------------------------------------------------------------
+server.tool("chamade_inbox", "Check inbox for DM conversations. Without conversation_id, lists all active conversations. With conversation_id, returns details and message history. When a voice_started event appears, use chamade_say/chamade_status with the provided call_id.", {
+    conversation_id: z
+        .string()
+        .optional()
+        .describe("Optional conversation ID to get details and messages"),
+    limit: z
+        .number()
+        .default(20)
+        .describe("Max messages to return (when viewing a conversation)"),
+}, async ({ conversation_id, limit }) => {
+    if (conversation_id) {
+        const data = (await chamadeGet(`/api/inbox/${conversation_id}?limit=${limit}`));
+        const conv = data.conversation;
+        const messages = data.messages;
+        const capabilities = conv.capabilities ?? [];
+        const lines = [
+            `Conversation: ${conv.id}`,
+            `Platform: ${conv.platform}`,
+            `Contact: ${conv.remote_name || conv.remote_id}`,
+            `Type: ${conv.channel_type}`,
+            `Capabilities: ${capabilities.join(", ") || "text"}`,
+            `Messages: ${conv.message_count}`,
+            conv.call_id ? `Active call: ${conv.call_id}` : "",
+            "",
+        ];
+        if (messages.length > 0) {
+            lines.push("Messages:");
+            for (const m of messages) {
+                const dir = m.direction === "inbound" ? "←" : "→";
+                const name = m.sender_name || (m.direction === "inbound" ? "them" : "you");
+                lines.push(`  ${dir} [${name}] ${m.content}`);
+            }
+        }
+        else {
+            lines.push("(no messages yet)");
+        }
+        return {
+            content: [{ type: "text", text: lines.filter(Boolean).join("\n") }],
+        };
+    }
+    // List conversations
+    const data = (await chamadeGet("/api/inbox"));
+    if (data.conversations.length === 0) {
+        return {
+            content: [{ type: "text", text: "No active conversations." }],
+        };
+    }
+    const lines = data.conversations.map((c) => {
+        const capabilities = c.capabilities ?? [];
+        const cap = capabilities.length > 0 ? ` [${capabilities.join(",")}]` : "";
+        const callInfo = c.call_id ? ` (voice: ${c.call_id})` : "";
+        return `- ${c.id} (${c.platform}) — ${c.remote_name || c.remote_id} — ${c.message_count} msgs${cap}${callInfo}`;
+    });
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+});
+// -- Tool: send -------------------------------------------------------------
+server.tool("chamade_send", "Send a message to a DM conversation. The message will be delivered to the user on their platform (Discord, Telegram, etc.).", {
+    conversation_id: z.string().describe("Conversation ID from chamade_inbox"),
+    text: z.string().describe("Message text to send"),
+}, async ({ conversation_id, text }) => {
+    channelStopTyping(conversation_id);
+    const data = (await chamadePost("/api/send", {
+        conversation_id,
+        text,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Message sent (${data.delivery || "async"}): "${text}"`,
+            },
+        ],
+    };
+});
+// -- Resource: transcript ---------------------------------------------------
+const transcriptTemplate = new ResourceTemplate("chamade://calls/{call_id}/transcript", {
+    list: async () => {
+        return {
+            resources: Array.from(calls.entries()).map(([id, state]) => ({
+                uri: `chamade://calls/${id}/transcript`,
+                name: `Transcript — ${state.platform} call ${id.slice(0, 8)}`,
+                mimeType: "text/plain",
+            })),
+        };
+    },
+});
+server.resource("call-transcript", transcriptTemplate, {
+    description: "Live transcript of an active call. Subscribe for real-time updates. Each read returns only new lines since the last read.",
+    mimeType: "text/plain",
+}, async (uri, params) => {
+    const callId = params.call_id;
+    const state = calls.get(callId);
+    const since = state?.lastTranscriptLength ?? 0;
+    try {
+        const data = (await chamadeGet(`/api/call/${callId}?since=${since}`));
+        const transcriptLength = data.transcript_length ?? 0;
+        const lines = data.transcript ?? [];
+        if (state) {
+            state.lastTranscriptLength = transcriptLength;
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/plain",
+                    text: lines.length
+                        ? lines.join("\n")
+                        : "(no new transcript since last read)",
+                },
+            ],
+        };
+    }
+    catch {
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "text/plain",
+                    text: `No active call with ID: ${callId}`,
+                },
+            ],
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Channel mode — push events via notifications/claude/channel
+// ---------------------------------------------------------------------------
+const _callWatchers = new Map();
+const _closedWatchers = new Set();
+const _typingIntervals = new Map();
+/**
+ * Start repeating typing indicator for a conversation.
+ * Sends immediately then every 2s. Stops after 30s max.
+ */
+function channelStartTyping(conversationId) {
+    channelStopTyping(conversationId);
+    const send = () => chamadePost("/api/typing", { conversation_id: conversationId }).catch(() => { });
+    send();
+    const interval = setInterval(send, 2000);
+    _typingIntervals.set(conversationId, interval);
+    // Safety: stop after 30s even if chamade_send is never called
+    setTimeout(() => channelStopTyping(conversationId), 30_000);
+}
+function channelStopTyping(conversationId) {
+    const interval = _typingIntervals.get(conversationId);
+    if (interval) {
+        clearInterval(interval);
+        _typingIntervals.delete(conversationId);
+    }
+}
+/**
+ * Push a channel notification to Claude Code.
+ * Only active in channel mode — noop otherwise.
+ */
+async function channelPush(content, meta = {}) {
+    if (!CHANNEL_MODE)
+        return;
+    try {
+        await server.server.notification({
+            method: "notifications/claude/channel",
+            params: {
+                content,
+                meta: { source: "chamade", ...meta },
+            },
+        });
+    }
+    catch (e) {
+        console.error("[chamade-channel] Push failed:", e);
+    }
+}
+/**
+ * Watch a call's transcript via WebSocket push.
+ * Opens a WS to /api/call/{id}/stream and pushes each event.
+ */
+function channelWatchCall(callId) {
+    if (_callWatchers.has(callId) || _closedWatchers.has(callId))
+        return;
+    let retryDelay = 1000;
+    let retryCount = 0;
+    const MAX_RETRIES = 5;
+    function connect() {
+        if (_closedWatchers.has(callId))
+            return;
+        const url = `${CHAMADE_WS_URL}/api/call/${callId}/stream?api_key=${API_KEY}`;
+        const ws = new WebSocket(url);
+        ws.on("open", () => {
+            retryDelay = 1000;
+            _callWatchers.set(callId, ws);
+            console.error(`[chamade-channel] Watching call ${callId}`);
+        });
+        ws.on("message", async (raw) => {
+            try {
+                const data = JSON.parse(raw.toString());
+                switch (data.type) {
+                    case "transcript":
+                        retryCount = 0; // Real data — reset retry counter
+                        if (data.is_final !== false) {
+                            await channelPush(`[${data.speaker || "?"}] ${data.text || ""}`, { type: "transcript", call_id: callId });
+                        }
+                        break;
+                    case "chat":
+                    case "chat_received":
+                        await channelPush(`[chat:${data.sender || "?"}] ${data.text || ""}`, { type: "chat", call_id: callId });
+                        break;
+                    case "state":
+                        await channelPush(`Call state: ${data.state}`, { type: "state", call_id: callId });
+                        if (data.state === "ended" || data.state === "error") {
+                            channelUnwatchCall(callId);
+                        }
+                        break;
+                    case "error":
+                        await channelPush(`Call error: ${data.message || data.code || "unknown"}`, { type: "error", call_id: callId });
+                        // Stop watching on any terminal error
+                        channelUnwatchCall(callId);
+                        if (data.code === "bridge_disconnected") {
+                            await channelPush(`Bridge connection lost for call ${callId}. Use chamade_join with the same meeting_url to reconnect.`, { type: "disconnected", call_id: callId });
+                        }
+                        break;
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        });
+        ws.on("close", () => {
+            _callWatchers.delete(callId);
+            retryCount++;
+            if (!_closedWatchers.has(callId) && retryCount <= MAX_RETRIES) {
+                setTimeout(connect, retryDelay);
+                retryDelay = Math.min(retryDelay * 2, 30_000);
+            }
+            else if (!_closedWatchers.has(callId)) {
+                console.error(`[chamade-channel] Call ${callId}: max retries (${MAX_RETRIES}) reached, giving up`);
+                channelUnwatchCall(callId);
+            }
+        });
+        ws.on("error", () => {
+            // Close handler will fire next and handle reconnection
+        });
+    }
+    connect();
+}
+/**
+ * Stop watching a call (on leave or call end).
+ */
+function channelUnwatchCall(callId) {
+    _closedWatchers.add(callId);
+    const ws = _callWatchers.get(callId);
+    if (ws) {
+        try {
+            ws.close();
+        }
+        catch { /* ignore */ }
+        _callWatchers.delete(callId);
+    }
+}
+/**
+ * Watch inbox for DMs, incoming calls, and conversation events.
+ * Reconnects automatically on disconnect.
+ */
+function channelWatchInbox() {
+    let retryDelay = 1000;
+    function connect() {
+        const url = `${CHAMADE_WS_URL}/api/inbox/stream?api_key=${API_KEY}`;
+        const ws = new WebSocket(url);
+        ws.on("open", () => {
+            retryDelay = 1000;
+            console.error("[chamade-channel] Inbox WS connected");
+        });
+        ws.on("message", async (raw) => {
+            try {
+                const data = JSON.parse(raw.toString());
+                switch (data.type) {
+                    case "message":
+                        // Auto-send repeating typing indicator until chamade_send replies
+                        if (data.conversation_id) {
+                            channelStartTyping(data.conversation_id);
+                        }
+                        await channelPush(`New message from ${data.sender_name || "unknown"} on ${data.platform}: "${data.text}"`, {
+                            type: "message",
+                            conversation_id: data.conversation_id || "",
+                            platform: data.platform || "",
+                        });
+                        break;
+                    case "incoming_call":
+                        await channelPush(`Incoming call from ${data.caller || "unknown"}${data.did ? ` on ${data.did}` : ""}. Call ID: ${data.call_id}. Use chamade_answer to pick up.`, { type: "incoming_call", call_id: data.call_id || "" });
+                        // Auto-watch if already active (auto_answer)
+                        if (data.state === "active" && data.call_id) {
+                            channelWatchCall(data.call_id);
+                        }
+                        break;
+                    case "voice_started":
+                        await channelPush(`Voice started. Call ID: ${data.call_id}. Platform: ${data.platform}.`, {
+                            type: "voice_started",
+                            call_id: data.call_id || "",
+                            conversation_id: data.conversation_id || "",
+                        });
+                        if (data.call_id) {
+                            channelWatchCall(data.call_id);
+                        }
+                        break;
+                    case "conversation_started":
+                        await channelPush(`New conversation from ${data.remote_name || "unknown"} on ${data.platform}.`, {
+                            type: "conversation",
+                            conversation_id: data.conversation_id || "",
+                            platform: data.platform || "",
+                        });
+                        break;
+                    case "conversation_ended":
+                        await channelPush(`Conversation ended.`, { type: "conversation_ended", conversation_id: data.conversation_id || "" });
+                        break;
+                    case "call_disconnected":
+                        await channelPush(`Call disconnected: ${data.message || "connection lost"}. Call ID: ${data.call_id}.`, { type: "call_disconnected", call_id: data.call_id || "" });
+                        break;
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        });
+        ws.on("close", () => {
+            setTimeout(connect, retryDelay);
+            retryDelay = Math.min(retryDelay * 2, 30_000);
+        });
+        ws.on("error", () => {
+            // Close handler will fire next and handle reconnection
+        });
+    }
+    connect();
+}
+/**
+ * Sync active calls — watch any calls that existed before channel started.
+ */
+async function channelSyncActiveCalls() {
+    try {
+        const data = (await chamadeGet("/api/calls"));
+        for (const call of data.calls) {
+            if (call.state !== "ended" &&
+                call.state !== "error" &&
+                !_callWatchers.has(call.id) &&
+                !_closedWatchers.has(call.id)) {
+                channelWatchCall(call.id);
+            }
+        }
+    }
+    catch {
+        // Ignore — will retry on next interval
+    }
+}
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (CHANNEL_MODE) {
+        console.error("[chamade-channel] Channel mode active — push events enabled");
+        channelWatchInbox();
+        await channelSyncActiveCalls();
+        setInterval(channelSyncActiveCalls, 15_000);
+    }
+    console.error("[chamade-mcp] Server running on stdio");
+}
+main().catch((err) => {
+    console.error("[chamade-mcp] Fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@chamade/mcp-server",
+  "version": "1.1.0",
+  "description": "MCP server for Chamade — voice gateway for AI agents. Join Discord, Teams, Meet, Telegram, SIP, Zoom meetings and interact via speech and text. Supports Claude Code channel mode for push events.",
+  "type": "module",
+  "bin": {
+    "chamade-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "tsx test/run.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/skilpa/chamade.git",
+    "directory": "chamade-mcp"
+  },
+  "homepage": "https://chamade.io",
+  "bugs": {
+    "url": "https://codeberg.org/skilpa/chamade/issues"
+  },
+  "author": "Nafis <contact@nafis.io>",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "chamade",
+    "voice",
+    "ai-agent",
+    "meeting",
+    "discord",
+    "teams",
+    "meet",
+    "telegram",
+    "sip",
+    "zoom",
+    "whatsapp"
+  ],
+  "license": "MIT"
+}