twelveai 0.2.0 → 0.3.0

package/README.md

@@ -177,6 +177,28 @@ Approve a `pendingConfirmation` (resends the turn with `confirmed: true`).
 | `escalated` / `policy` | The turn was routed for human review, and by which rule. |
 | `usage` / `billing` | Token usage and billing for the turn. |
 
+## MCP server (for AI coding agents)
+
+The package ships an MCP server, so the agent writing your integration can read
+the docs, inspect your workspace's exact tool-call contract, classify messages,
+and test sandbox chats while it codes:
+
+```json
+{
+  "mcpServers": {
+    "twelveai": {
+      "command": "npx",
+      "args": ["-y", "twelveai-mcp"],
+      "env": { "TWELVE_API_KEY": "sk_live_..." }
+    }
+  }
+}
+```
+
+Tools: `twelveai_docs`, `twelveai_manifest` (per-active-agent tool-call
+contract), `twelveai_classify`, `twelveai_sandbox_chat`. Only `twelveai_docs`
+works without an API key.
+
 ## Docs
 
 Full platform documentation - agents, policies, customer tiers, WhatsApp channel, endpoint auth options, streaming: **https://console.twelveai.app/docs**

package/dist/mcp.cjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/mcp.ts
+var mcp_exports = {};
+__export(mcp_exports, {
+  createServer: () => createServer
+});
+module.exports = __toCommonJS(mcp_exports);
+var import_node_readline = require("readline");
+var PROTOCOL_VERSION = "2024-11-05";
+var SERVER_INFO = { name: "twelveai", version: "0.3.0" };
+var TOOLS = [
+  {
+    name: "twelveai_docs",
+    description: "The TwelveAI integration guide (llms.txt): auth, the classify level, the chat protocol, client-fetch hand-offs, endpoint auth options, and every endpoint. Read this first.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "twelveai_manifest",
+    description: "The workspace's tool-call contract, per ACTIVE agent: every tool call the integration might receive, with parameter schemas, side effects, execution mode (hosted vs client), and endpoint bindings. Code against this.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "twelveai_classify",
+    description: "Classify one customer message: returns intent, a confidence score, and extracted entities (amount / account number / phone). Free; nothing stored.",
+    inputSchema: {
+      type: "object",
+      properties: { message: { type: "string", description: "The customer message to classify." } },
+      required: ["message"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "twelveai_sandbox_chat",
+    description: "Run one chat turn in SANDBOX mode (tools return sample data; nothing real is called or moved). Use it to see real response shapes - including pendingToolCalls hand-offs - while building.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string" },
+        customerId: { type: "string", description: 'Your id for the test end-user (default "mcp-test").' },
+        continuation: { type: "string", description: "Previous turn continuation, to test multi-turn." }
+      },
+      required: ["message"],
+      additionalProperties: false
+    }
+  }
+];
+function createServer(deps = {}) {
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  const env = deps.env ?? process.env;
+  const baseUrl = (env.TWELVE_BASE_URL || "https://ai.twelveai.app").replace(/\/+$/, "");
+  function apiKey() {
+    return env.TWELVE_API_KEY || null;
+  }
+  async function api(path, body) {
+    const key = apiKey();
+    if (!key) return "Error: set the TWELVE_API_KEY environment variable (your workspace API key from https://console.twelveai.app) to use this tool.";
+    const res = await fetchImpl(`${baseUrl}${path}`, {
+      method: body ? "POST" : "GET",
+      headers: { "content-type": "application/json", "x-api-key": key },
+      ...body ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await res.text();
+    if (!res.ok) return `Error ${res.status}: ${text.slice(0, 500)}`;
+    try {
+      return JSON.stringify(JSON.parse(text), null, 2);
+    } catch {
+      return text;
+    }
+  }
+  async function runTool(name, args) {
+    switch (name) {
+      case "twelveai_docs": {
+        const res = await fetchImpl(`${baseUrl}/llms.txt`);
+        return res.ok ? await res.text() : `Error ${res.status}: could not fetch the docs.`;
+      }
+      case "twelveai_manifest":
+        return api("/v1/manifest");
+      case "twelveai_classify":
+        return api("/v1/classify", { message: String(args?.message ?? "") });
+      case "twelveai_sandbox_chat":
+        return api("/v1/chat", {
+          message: String(args?.message ?? ""),
+          customerId: args?.customerId ? String(args.customerId) : "mcp-test",
+          ...args?.continuation ? { continuation: String(args.continuation) } : {},
+          sandbox: true
+        });
+      default:
+        throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32602 });
+    }
+  }
+  async function handle(msg) {
+    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) return null;
+    const id = msg.id;
+    const reply = (result) => ({ jsonrpc: "2.0", id: id ?? null, result });
+    try {
+      switch (msg.method) {
+        case "initialize":
+          return reply({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
+        case "ping":
+          return reply({});
+        case "tools/list":
+          return reply({ tools: TOOLS });
+        case "tools/call": {
+          const text = await runTool(String(msg.params?.name), msg.params?.arguments ?? {});
+          return reply({ content: [{ type: "text", text }], isError: text.startsWith("Error") });
+        }
+        default:
+          if (id === void 0) return null;
+          return { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
+      }
+    } catch (error) {
+      if (id === void 0) return null;
+      const e = error;
+      return { jsonrpc: "2.0", id, error: { code: e.code ?? -32603, message: e.message || "Internal error" } };
+    }
+  }
+  return { handle, tools: TOOLS };
+}
+var isMain = process.argv[1] && /mcp\.(js|cjs|ts)$/.test(process.argv[1]);
+if (isMain) {
+  const server = createServer();
+  const rl = (0, import_node_readline.createInterface)({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    const res = await server.handle(msg);
+    if (res) process.stdout.write(JSON.stringify(res) + "\n");
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServer
+});

package/dist/mcp.d.cts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * The TwelveAI MCP server - plug TwelveAI into any MCP-capable coding agent
+ * (Claude Code, Cursor, etc.) so it can read the docs, inspect your workspace's
+ * tool-call contract, classify messages, and test chats in the sandbox while it
+ * writes your integration.
+ *
+ *   npx twelveai-mcp            # stdio transport
+ *
+ * Config (env):
+ *   TWELVE_API_KEY   your workspace key - required for manifest/classify/chat
+ *   TWELVE_BASE_URL  engine base (default https://ai.twelveai.app)
+ *
+ * Zero dependencies: a minimal JSON-RPC 2.0 loop over stdio implementing the
+ * MCP handshake, tools/list, and tools/call.
+ */
+interface Deps {
+    fetch?: typeof globalThis.fetch;
+    env?: Record<string, string | undefined>;
+}
+interface RpcMessage {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: any;
+}
+/** Build the message handler; injectable deps keep it unit-testable. */
+declare function createServer(deps?: Deps): {
+    handle: (msg: RpcMessage) => Promise<RpcMessage | null>;
+    tools: ({
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message?: undefined;
+                customerId?: undefined;
+                continuation?: undefined;
+            };
+            additionalProperties: boolean;
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message: {
+                    type: string;
+                    description: string;
+                };
+                customerId?: undefined;
+                continuation?: undefined;
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message: {
+                    type: string;
+                    description?: undefined;
+                };
+                customerId: {
+                    type: string;
+                    description: string;
+                };
+                continuation: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+    })[];
+};
+
+export { createServer };

package/dist/mcp.d.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * The TwelveAI MCP server - plug TwelveAI into any MCP-capable coding agent
+ * (Claude Code, Cursor, etc.) so it can read the docs, inspect your workspace's
+ * tool-call contract, classify messages, and test chats in the sandbox while it
+ * writes your integration.
+ *
+ *   npx twelveai-mcp            # stdio transport
+ *
+ * Config (env):
+ *   TWELVE_API_KEY   your workspace key - required for manifest/classify/chat
+ *   TWELVE_BASE_URL  engine base (default https://ai.twelveai.app)
+ *
+ * Zero dependencies: a minimal JSON-RPC 2.0 loop over stdio implementing the
+ * MCP handshake, tools/list, and tools/call.
+ */
+interface Deps {
+    fetch?: typeof globalThis.fetch;
+    env?: Record<string, string | undefined>;
+}
+interface RpcMessage {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method?: string;
+    params?: any;
+    result?: any;
+    error?: any;
+}
+/** Build the message handler; injectable deps keep it unit-testable. */
+declare function createServer(deps?: Deps): {
+    handle: (msg: RpcMessage) => Promise<RpcMessage | null>;
+    tools: ({
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message?: undefined;
+                customerId?: undefined;
+                continuation?: undefined;
+            };
+            additionalProperties: boolean;
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message: {
+                    type: string;
+                    description: string;
+                };
+                customerId?: undefined;
+                continuation?: undefined;
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                message: {
+                    type: string;
+                    description?: undefined;
+                };
+                customerId: {
+                    type: string;
+                    description: string;
+                };
+                continuation: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
+    })[];
+};
+
+export { createServer };

package/dist/mcp.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+// src/mcp.ts
+import { createInterface } from "readline";
+var PROTOCOL_VERSION = "2024-11-05";
+var SERVER_INFO = { name: "twelveai", version: "0.3.0" };
+var TOOLS = [
+  {
+    name: "twelveai_docs",
+    description: "The TwelveAI integration guide (llms.txt): auth, the classify level, the chat protocol, client-fetch hand-offs, endpoint auth options, and every endpoint. Read this first.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "twelveai_manifest",
+    description: "The workspace's tool-call contract, per ACTIVE agent: every tool call the integration might receive, with parameter schemas, side effects, execution mode (hosted vs client), and endpoint bindings. Code against this.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "twelveai_classify",
+    description: "Classify one customer message: returns intent, a confidence score, and extracted entities (amount / account number / phone). Free; nothing stored.",
+    inputSchema: {
+      type: "object",
+      properties: { message: { type: "string", description: "The customer message to classify." } },
+      required: ["message"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "twelveai_sandbox_chat",
+    description: "Run one chat turn in SANDBOX mode (tools return sample data; nothing real is called or moved). Use it to see real response shapes - including pendingToolCalls hand-offs - while building.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string" },
+        customerId: { type: "string", description: 'Your id for the test end-user (default "mcp-test").' },
+        continuation: { type: "string", description: "Previous turn continuation, to test multi-turn." }
+      },
+      required: ["message"],
+      additionalProperties: false
+    }
+  }
+];
+function createServer(deps = {}) {
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  const env = deps.env ?? process.env;
+  const baseUrl = (env.TWELVE_BASE_URL || "https://ai.twelveai.app").replace(/\/+$/, "");
+  function apiKey() {
+    return env.TWELVE_API_KEY || null;
+  }
+  async function api(path, body) {
+    const key = apiKey();
+    if (!key) return "Error: set the TWELVE_API_KEY environment variable (your workspace API key from https://console.twelveai.app) to use this tool.";
+    const res = await fetchImpl(`${baseUrl}${path}`, {
+      method: body ? "POST" : "GET",
+      headers: { "content-type": "application/json", "x-api-key": key },
+      ...body ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await res.text();
+    if (!res.ok) return `Error ${res.status}: ${text.slice(0, 500)}`;
+    try {
+      return JSON.stringify(JSON.parse(text), null, 2);
+    } catch {
+      return text;
+    }
+  }
+  async function runTool(name, args) {
+    switch (name) {
+      case "twelveai_docs": {
+        const res = await fetchImpl(`${baseUrl}/llms.txt`);
+        return res.ok ? await res.text() : `Error ${res.status}: could not fetch the docs.`;
+      }
+      case "twelveai_manifest":
+        return api("/v1/manifest");
+      case "twelveai_classify":
+        return api("/v1/classify", { message: String(args?.message ?? "") });
+      case "twelveai_sandbox_chat":
+        return api("/v1/chat", {
+          message: String(args?.message ?? ""),
+          customerId: args?.customerId ? String(args.customerId) : "mcp-test",
+          ...args?.continuation ? { continuation: String(args.continuation) } : {},
+          sandbox: true
+        });
+      default:
+        throw Object.assign(new Error(`Unknown tool: ${name}`), { code: -32602 });
+    }
+  }
+  async function handle(msg) {
+    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) return null;
+    const id = msg.id;
+    const reply = (result) => ({ jsonrpc: "2.0", id: id ?? null, result });
+    try {
+      switch (msg.method) {
+        case "initialize":
+          return reply({ protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
+        case "ping":
+          return reply({});
+        case "tools/list":
+          return reply({ tools: TOOLS });
+        case "tools/call": {
+          const text = await runTool(String(msg.params?.name), msg.params?.arguments ?? {});
+          return reply({ content: [{ type: "text", text }], isError: text.startsWith("Error") });
+        }
+        default:
+          if (id === void 0) return null;
+          return { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
+      }
+    } catch (error) {
+      if (id === void 0) return null;
+      const e = error;
+      return { jsonrpc: "2.0", id, error: { code: e.code ?? -32603, message: e.message || "Internal error" } };
+    }
+  }
+  return { handle, tools: TOOLS };
+}
+var isMain = process.argv[1] && /mcp\.(js|cjs|ts)$/.test(process.argv[1]);
+if (isMain) {
+  const server = createServer();
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    const res = await server.handle(msg);
+    if (res) process.stdout.write(JSON.stringify(res) + "\n");
+  });
+}
+export {
+  createServer
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twelveai",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official SDK for TwelveAI - AI infrastructure for conversational banking. One call runs the whole chat protocol: routing, grounded tool calls, client-fetch hand-offs, confirmations, and request verification.",
   "license": "MIT",
   "author": "TwelveAI",
@@ -38,7 +38,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/mcp.ts --format esm,cjs --dts --clean",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
@@ -54,5 +54,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "twelveai-mcp": "./dist/mcp.js"
   }
 }