@trillet-ai/mcp 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trillet AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Trillet MCP Server
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for [Trillet AI](https://trillet.ai). Build and operate production voice agents from Claude: create agents, write call flows, wire in-call API tools, attach knowledge bases, configure post-call analysis, automate follow-ups with workflows, and debug real calls from their transcripts.
+
+Built with the official TypeScript MCP SDK, stdio transport. 71 tools, all annotated with read-only/destructive hints.
+
+## Setup
+
+```bash
+cd Trillet-MCP
+npm install
+npm run build
+```
+
+You need two values from the Trillet dashboard:
+
+| Variable | Where to find it |
+|---|---|
+| `TRILLET_API_KEY` | Settings > API Keys |
+| `TRILLET_WORKSPACE_ID` | Workspace settings (24-char hex id) |
+
+Optional: `TRILLET_API_URL` (defaults to `https://api.trillet.ai`).
+
+### npx (after npm publish)
+
+The package is not on npm until someone with the `trillet-ai` org runs the steps in [PUBLISH.md](./PUBLISH.md). After that:
+
+```bash
+TRILLET_API_KEY=<your key> TRILLET_WORKSPACE_ID=<your workspace id> npx -y @trillet-ai/mcp
+```
+
+Cursor and Grok Bot install it from the public plugin repo [TrilletAI/Trillet-grok](https://github.com/TrilletAI/Trillet-grok) (`npx -y @trillet-ai/mcp@latest`, credentials from Plugins → Configure, not from the repo). The same tree is in `cursor-plugin/` here.
+
+### Claude Code
+
+```bash
+claude mcp add trillet \
+  -e TRILLET_API_KEY=<your key> \
+  -e TRILLET_WORKSPACE_ID=<your workspace id> \
+  -- node /absolute/path/to/Trillet-MCP/dist/index.js
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "trillet": {
+      "command": "node",
+      "args": ["/absolute/path/to/Trillet-MCP/dist/index.js"],
+      "env": {
+        "TRILLET_API_KEY": "<your key>",
+        "TRILLET_WORKSPACE_ID": "<your workspace id>"
+      }
+    }
+  }
+}
+```
+
+Agency accounts: every tool accepts an optional `workspace_id` argument that overrides the default workspace for that call, so one server instance can manage client workspaces (the key's user must be a member of each).
+
+## Tools
+
+**Agents & voices** — `trillet_list_agents`, `trillet_get_agent`, `trillet_create_agent`, `trillet_update_agent`, `trillet_delete_agent` (requires `confirm: true`), `trillet_search_voices` (full multi-provider catalog)
+
+**Call flows** — `trillet_list_call_flows`, `trillet_get_call_flow`, `trillet_create_call_flow`, `trillet_update_call_flow`, `trillet_update_prompt`, `trillet_set_incall_api_tools`, `trillet_set_post_call_analysis`, `trillet_list_drafts`, `trillet_deactivate_drafts`, `trillet_publish_draft`, `trillet_duplicate_call_flow`, `trillet_archive_call_flow`, `trillet_delete_call_flow` (requires `confirm: true`)
+
+**Flow settings** — `trillet_set_transfers` (warm/cold/whisper/agent, condition gates, business-hours routing), `trillet_set_office_hours`, `trillet_set_call_settings` (voicemail detection, IVR navigation, silence, duration, recording), `trillet_set_speech_settings`, `trillet_set_welcome_message`, `trillet_set_code_actions` (feature-gated Python actions; detects silent strips)
+
+**Node flows** — `trillet_node_flow_reference` (the full node-type/edge/validation reference the model reads before building), `trillet_list_node_flows`, `trillet_get_node_flow`, `trillet_create_node_flow`, `trillet_list_node_flow_templates`, `trillet_update_node_graph`, `trillet_validate_node_graph`, `trillet_publish_node_graph`, `trillet_simulate_node_graph`, `trillet_list_node_flow_runs`
+
+**Phone numbers** — `trillet_list_phone_numbers`, `trillet_search_available_numbers`, `trillet_purchase_phone_number` (requires `confirm: true`; bills the workspace), `trillet_bind_phone_number` (office hours, metadata tags, secret bindings), `trillet_release_phone_number` (unbind from agent), `trillet_get_phone_number_config`, `trillet_update_phone_number_config`, `trillet_register_external_number` (BYO Twilio / SIP trunks, requires `confirm: true`)
+
+**Knowledge bases** — `trillet_list_knowledge_bases`, `trillet_get_knowledge_base` (with flow usage), `trillet_create_knowledge_base`, `trillet_add_kb_text`, `trillet_upload_kb_file`, `trillet_attach_knowledge_bases`, `trillet_delete_knowledge_base` (whole KB or one file; requires `confirm: true`)
+
+**Workflows** — `trillet_workflow_reference` (the full trigger/step/template reference the model reads before building: 7 triggers, 15 step types), `trillet_list_workflows`, `trillet_get_workflow`, `trillet_create_workflow`, `trillet_update_workflow`, `trillet_activate_workflow`, `trillet_pause_workflow`, `trillet_delete_workflow` (requires `confirm: true`), `trillet_test_workflow` (simulated side effects, works on drafts), `trillet_run_workflow` (real run, requires `confirm: true`), `trillet_list_workflow_runs`, `trillet_get_workflow_run` (per-step logs)
+
+**Secrets** — `trillet_list_secrets` (always masked), `trillet_set_secret`, `trillet_delete_secret`
+
+**Calls** — `trillet_list_calls` (filters + per-call cost/warm-transfer billing fields), `trillet_get_call_metrics` (aggregates), `trillet_get_call` (transcript, analysis, billing breakdown, optional functionCalls), `trillet_start_outbound_call` (requires explicit `confirm: true`; places a real phone call)
+
+**Account** — `trillet_get_usage` (wallet balance, optional 3-month minutes breakdown), `trillet_list_transactions` (charge ledger, month x type summaries)
+
+## Design notes
+
+The tool descriptions encode hard-won platform behavior so the model does the right thing first time:
+
+- **Editor drafts override production** for dashboard test calls; `trillet_get_call_flow` reports `has_active_draft` and `trillet_deactivate_drafts` returns a flow to production. This is the most common cause of "my changes aren't taking effect".
+- **Update merge semantics**: objects deep-merge, arrays replace wholesale, nulls are ignored. The dedicated setters (`trillet_set_incall_api_tools`, `trillet_set_post_call_analysis`, `trillet_attach_knowledge_bases`) always send complete arrays.
+- **In-call API tools**: the runtime appends call metadata to requests unless `callSetting.disableMetadata` is set; strict APIs (e.g. Airtable) reject unknown keys, so the setter defaults it on. Prompts should reference tools as `{{realtime_api "name" "vars"}}`.
+- **Workflows**: `maxRunsPerContact` defaults to 1/24h platform-side (silently skips repeat callers); the create tool defaults it to 500. Web test calls fire the *outbound* call-completed trigger.
+- **Prompts**: never script a greeting line in the prompt; the platform welcome message already plays it, and a scripted opening makes the agent greet twice.
+
+## Roadmap to the Anthropic directory
+
+- [x] Official SDK, stdio transport, tool annotations (`readOnlyHint`/`destructiveHint`), narrow tool descriptions, no dynamic code execution, secrets via env only
+- [ ] Public privacy policy page (required for directory review)
+- [ ] Remote server (Streamable HTTP + OAuth) for the Claude.ai connector directory (submission requires a Team/Enterprise org)
+- [x] `.mcpb` Desktop Extension bundle for one-click local install (`trillet.mcpb` in the plugin repo)
+- [ ] npm publish as `@trillet-ai/mcp` for `npx` usage (commands in [PUBLISH.md](./PUBLISH.md); not published yet)
+
+## Security
+
+- The API key and workspace id are read from environment variables and never logged.
+- All output goes to stdout as MCP protocol messages; diagnostics go to stderr.
+- Tools with real-world side effects or destructive outcomes (`trillet_start_outbound_call`, `trillet_run_workflow`, `trillet_purchase_phone_number`, `trillet_register_external_number`, and every delete tool) are annotated destructive and refuse to run without `confirm: true`.

package/dist/client.js

@@ -0,0 +1,116 @@
+/**
+ * Thin HTTP client for the Trillet public API.
+ *
+ * Auth model (verified against production):
+ * - `x-api-key`: a Trillet user API key. User keys are cross-workspace.
+ * - `x-workspace-id`: REQUIRED on every request. The key's user must be a
+ *   member of the workspace or the API returns 401.
+ */
+import { VERSION } from "./version.js";
+const DEFAULT_BASE_URL = "https://api.trillet.ai";
+export const SETUP_HINT = "Trillet credentials are not configured. Run the /trillet:setup command (it asks for a Trillet API key and workspace id and saves them), then restart Claude Code. Keys are created in the Trillet dashboard under Settings > API Keys.";
+/**
+ * Never throws: a server with missing credentials must still start so tools
+ * can return an actionable setup message instead of the whole server dying.
+ */
+export function loadConfig() {
+    return {
+        apiKey: (process.env.TRILLET_API_KEY || "").trim(),
+        workspaceId: (process.env.TRILLET_WORKSPACE_ID || "").trim(),
+        baseUrl: process.env.TRILLET_API_URL || DEFAULT_BASE_URL,
+    };
+}
+export class TrilletError extends Error {
+    status;
+    body;
+    constructor(status, body, method, path) {
+        // A flow/agent/call id from another workspace comes back as 404 or even a
+        // bare 500 ("Error fetching flow"), which reads like an outage. Say so.
+        const wrongWorkspaceHint = method === "GET" && (status === 404 || status === 500) && /\/[0-9a-f]{24}(\/|\?|$)/i.test(path)
+            ? " (If this id belongs to a client or sub-workspace, retry with that workspace_id: ids from another workspace fail this way.)"
+            : "";
+        super(`Trillet API ${method} ${path} failed with HTTP ${status}: ${body}${wrongWorkspaceHint}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+export class TrilletClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Base API URL (text-call tools map it to the environment's LiveKit host). */
+    get baseUrl() {
+        return this.cfg.baseUrl;
+    }
+    /** Default workspace id (text-call caps are scoped per workspace). */
+    get workspaceId() {
+        return this.cfg.workspaceId;
+    }
+    /** Where writes land: "production" unless the embedder asked for "draft". */
+    get writeTarget() {
+        return this.cfg.writeTarget === "draft" ? "draft" : "production";
+    }
+    /**
+     * Perform a request. `workspaceId` overrides the default workspace for this
+     * call only (agency accounts manage several workspaces with one key).
+     */
+    async request(method, path, opts = {}) {
+        if (!this.cfg.apiKey || !(opts.workspaceId || this.cfg.workspaceId)) {
+            throw new Error(SETUP_HINT);
+        }
+        const url = new URL(path, this.cfg.baseUrl);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            "x-api-key": this.cfg.apiKey,
+            "x-workspace-id": opts.workspaceId || this.cfg.workspaceId,
+            "content-type": "application/json",
+            "user-agent": `trillet-mcp/${VERSION}`,
+        };
+        const isRead = method === "GET" || method === "DELETE";
+        if (!isRead && this.writeTarget === "draft") {
+            headers["x-trillet-write-target"] = "draft";
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            // Several Trillet POST endpoints reject an empty body when
+            // content-type is application/json, so default to {}.
+            body: isRead ? undefined : JSON.stringify(opts.body ?? {}),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new TrilletError(res.status, text.slice(0, 1000), method, path);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    /** Multipart upload (knowledge base files). */
+    async upload(path, fieldName, filename, data, mimetype, workspaceId) {
+        if (!this.cfg.apiKey || !(workspaceId || this.cfg.workspaceId)) {
+            throw new Error(SETUP_HINT);
+        }
+        const form = new FormData();
+        form.append(fieldName, new Blob([data], { type: mimetype }), filename);
+        const res = await fetch(new URL(path, this.cfg.baseUrl), {
+            method: "POST",
+            headers: {
+                "x-api-key": this.cfg.apiKey,
+                "x-workspace-id": workspaceId || this.cfg.workspaceId,
+            },
+            body: form,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new TrilletError(res.status, text.slice(0, 1000), "POST", path);
+        }
+        return JSON.parse(text);
+    }
+}

package/dist/helpers.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { TrilletError } from "./client.js";
+/** Standard success payload: pretty JSON in a text block. */
+export function ok(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+/** Standard error payload with actionable messages for common failures. */
+export function fail(err) {
+    let msg = err instanceof Error ? err.message : String(err);
+    if (err instanceof TrilletError) {
+        if (err.status === 401) {
+            msg +=
+                "\nHint: the API key's user is not a member of this workspace. Check TRILLET_WORKSPACE_ID or the workspace_id argument.";
+        }
+        else if (err.status === 400 && err.body.includes("Workspace ID")) {
+            msg += "\nHint: x-workspace-id header missing; set TRILLET_WORKSPACE_ID.";
+        }
+    }
+    return {
+        content: [{ type: "text", text: `Error: ${msg}` }],
+        isError: true,
+    };
+}
+/** Wrap a handler so thrown errors become MCP error results, never crashes. */
+export function guard(fn) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    };
+}
+/** Optional per-call workspace override, shared by every tool. */
+export const workspaceParam = {
+    workspace_id: z
+        .string()
+        .optional()
+        .describe("Override the default workspace for this call (24-char hex id). Omit to use TRILLET_WORKSPACE_ID. Useful for agency accounts managing client workspaces."),
+};

package/dist/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Trillet AI MCP server.
+ *
+ * Exposes the Trillet public API as MCP tools for building and operating
+ * voice agents: agents, call flows (prompts, in-call API tools, post-call
+ * analysis, drafts), knowledge bases, workflows, and call history.
+ *
+ * Configuration (environment variables):
+ *   TRILLET_API_KEY       required, a Trillet user API key
+ *   TRILLET_WORKSPACE_ID  required, default workspace id
+ *   TRILLET_API_URL       optional, defaults to https://api.trillet.ai
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig, TrilletClient } from "./client.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerCallFlowTools } from "./tools/callFlows.js";
+import { registerKnowledgeBaseTools } from "./tools/knowledgeBases.js";
+import { registerWorkflowTools } from "./tools/workflows.js";
+import { registerCallTools } from "./tools/calls.js";
+import { registerNodeFlowTools } from "./tools/nodeFlows.js";
+import { registerPhoneNumberTools } from "./tools/phoneNumbers.js";
+import { registerFlowSettingTools } from "./tools/flowSettings.js";
+import { registerSecretTools } from "./tools/secrets.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerTextCallTools } from "./tools/textCalls.js";
+import { runTextCallWorker } from "./textcall/worker.js";
+import { VERSION } from "./version.js";
+async function main() {
+    const config = loadConfig();
+    const client = new TrilletClient(config);
+    const server = new McpServer({
+        name: "trillet",
+        version: VERSION,
+    });
+    registerAgentTools(server, client);
+    registerCallFlowTools(server, client);
+    registerFlowSettingTools(server, client);
+    registerNodeFlowTools(server, client);
+    registerPhoneNumberTools(server, client);
+    registerKnowledgeBaseTools(server, client);
+    registerWorkflowTools(server, client);
+    registerSecretTools(server, client);
+    registerCallTools(server, client);
+    registerTextCallTools(server, client);
+    registerAccountTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP transport; all logging must go to stderr.
+    console.error(`trillet-mcp v${VERSION} ready (workspace ${config.workspaceId}, api ${config.baseUrl})`);
+}
+// Text-call worker mode: this same file is forked as the LiveKit room
+// participant for text test calls (see textcall/worker.ts for why it must be
+// a separate process). Everything else — including the MCP server — stays off.
+if (process.env.TRILLET_MCP_TEXTCALL_WORKER === "1") {
+    runTextCallWorker();
+}
+else {
+    main().catch((err) => {
+        console.error("trillet-mcp fatal:", err?.message ?? err);
+        process.exit(1);
+    });
+}

package/dist/registry.js

@@ -0,0 +1,106 @@
+/**
+ * Transport-agnostic tool registry.
+ *
+ * The same 76 tools power three surfaces: the stdio MCP server (Claude Code
+ * plugin + Desktop .mcpb), a future remote MCP, and the in-dashboard AI
+ * assistant (trillet-backend embeds the bundled build of this module and runs
+ * the tools inside its own Anthropic loop).
+ *
+ * Collection works by passing a fake McpServer into the existing
+ * register*Tools() functions, so the tool files stay exactly as written for
+ * the MCP SDK — no churn, no drift between surfaces. Handlers close over the
+ * TrilletClient passed to buildRegistry(), so embedders build one registry
+ * per authenticated session (cheap: 76 object literals).
+ */
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { TrilletClient } from "./client.js";
+import { VERSION } from "./version.js";
+import { registerAgentTools } from "./tools/agents.js";
+import { registerCallFlowTools } from "./tools/callFlows.js";
+import { registerKnowledgeBaseTools } from "./tools/knowledgeBases.js";
+import { registerWorkflowTools } from "./tools/workflows.js";
+import { registerCallTools } from "./tools/calls.js";
+import { registerNodeFlowTools } from "./tools/nodeFlows.js";
+import { registerPhoneNumberTools } from "./tools/phoneNumbers.js";
+import { registerFlowSettingTools } from "./tools/flowSettings.js";
+import { registerSecretTools } from "./tools/secrets.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerTextCallTools } from "./tools/textCalls.js";
+const REGISTER_FNS = [
+    registerAgentTools,
+    registerCallFlowTools,
+    registerFlowSettingTools,
+    registerNodeFlowTools,
+    registerPhoneNumberTools,
+    registerKnowledgeBaseTools,
+    registerWorkflowTools,
+    registerSecretTools,
+    registerCallTools,
+    registerTextCallTools,
+    registerAccountTools,
+];
+/** Collect every tool, with handlers bound to the given client. */
+export function buildRegistry(client) {
+    const defs = [];
+    const collector = {
+        registerTool(name, config, handler) {
+            defs.push({
+                name,
+                title: config.title ?? name,
+                description: config.description ?? "",
+                inputSchema: config.inputSchema ?? {},
+                annotations: config.annotations ?? {},
+                handler,
+            });
+        },
+    };
+    for (const fn of REGISTER_FNS)
+        fn(collector, client);
+    return defs;
+}
+/** One tool's JSON-schema form, e.g. for the Anthropic Messages API tools[]. */
+export function toJsonSchemaTool(def, opts = {}) {
+    const shape = { ...def.inputSchema };
+    for (const key of opts.stripArgs ?? [])
+        delete shape[key];
+    const schema = zodToJsonSchema(z.object(shape), { target: "jsonSchema7" });
+    delete schema.$schema;
+    const text = opts.transformText ?? ((t) => t);
+    return {
+        name: def.name,
+        description: text(def.description),
+        input_schema: schema,
+    };
+}
+/**
+ * Execute a tool by def, honoring the same stripArgs contract as
+ * toJsonSchemaTool. Returns { text, isError } — the text is the JSON (or
+ * error message) the tool produced, ready to use as a tool_result body.
+ */
+export async function executeTool(def, args, opts = {}) {
+    const cleaned = { ...args };
+    for (const key of opts.stripArgs ?? [])
+        delete cleaned[key];
+    // Mirror the MCP SDK: zod-parse before the handler runs, so defaults apply
+    // (e.g. stub_incall_apis=true) and bad arg types come back as a retryable
+    // error message instead of a handler crash. Unknown keys are stripped.
+    let parsed;
+    try {
+        parsed = z.object(def.inputSchema).parse(cleaned);
+    }
+    catch (e) {
+        const detail = e?.errors?.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+        return { text: `Invalid arguments for ${def.name}: ${detail || e?.message || e}`, isError: true };
+    }
+    const res = await def.handler(parsed);
+    return {
+        text: res.content?.map((c) => c.text).join("\n") ?? "",
+        isError: res.isError === true,
+    };
+}
+// Embedders fork text-call workers from their own entry script (see
+// TRILLET_MCP_TEXTCALL_WORKER_PATH in tools/textCalls.ts); that script just
+// calls this.
+export { runTextCallWorker } from "./textcall/worker.js";
+export { TrilletClient, VERSION };

package/dist/textcall/deps.js

@@ -0,0 +1,80 @@
+/**
+ * Lazy installer for @livekit/rtc-node.
+ *
+ * Text test calls need a real LiveKit room participant (agent turns arrive as
+ * text streams over the WebRTC data channel — there is no HTTP ingress for
+ * them). @livekit/rtc-node carries a ~16MB native FFI binary per platform, and
+ * neither distribution of this server runs `npm install` at install time (the
+ * Claude Code plugin is a git clone with node_modules gitignored; the Desktop
+ * .mcpb is a static pack). So the dependency is installed on first use into a
+ * cache directory under the user's home, and only text-call users pay for it.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+/** Pinned: the version every live verification ran against. */
+export const RTC_NODE_VERSION = "0.13.34";
+export function depsDir() {
+    return (process.env.TRILLET_MCP_DEPS_DIR ||
+        join(os.homedir(), ".trillet-mcp", "textcall-deps"));
+}
+/**
+ * The package blocks subpath exports (requiring
+ * '@livekit/rtc-node/package.json' throws ERR_PACKAGE_PATH_NOT_EXPORTED), so
+ * the installed check reads the manifest straight off disk.
+ */
+export function rtcNodeInstalled() {
+    try {
+        const manifest = join(depsDir(), "node_modules", "@livekit", "rtc-node", "package.json");
+        if (!existsSync(manifest))
+            return false;
+        const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+        return pkg.version === RTC_NODE_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+/** Install (or upgrade to) the pinned rtc-node into the cache dir via npm. */
+export async function ensureRtcNode() {
+    if (rtcNodeInstalled())
+        return;
+    const dir = depsDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({
+        name: "trillet-mcp-textcall-deps",
+        private: true,
+        description: "Native LiveKit client used by trillet-mcp text test calls. Safe to delete; reinstalled on next use.",
+        dependencies: { "@livekit/rtc-node": RTC_NODE_VERSION },
+    }, null, 2));
+    await new Promise((resolve, reject) => {
+        const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+        const child = spawn(npm, ["install", "--no-audit", "--no-fund", "--loglevel=error"], {
+            cwd: dir,
+            stdio: ["ignore", "ignore", "pipe"],
+            shell: process.platform === "win32",
+        });
+        let stderr = "";
+        child.stderr?.on("data", (d) => {
+            stderr += String(d);
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error("npm install of @livekit/rtc-node timed out after 240s"));
+        }, 240_000);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(new Error(`Could not run npm to install the text-call dependency (@livekit/rtc-node): ${err.message}. ` +
+                `Install Node.js with npm, or manually run: cd ${dir} && npm install`));
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            if (code === 0 && rtcNodeInstalled())
+                resolve();
+            else
+                reject(new Error(`npm install of @livekit/rtc-node failed (exit ${code}). ${stderr.slice(0, 500)}\n` +
+                    `Manual fix: cd ${dir} && npm install`));
+        });
+    });
+}