clawdcall-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawdCall
+
+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 @@
+# ClawdCall MCP Server
+
+Give AI agents access to ClawdCall's agent-facing phone execution API through the Model Context Protocol.
+
+`clawdcall-mcp` exposes the confirmed ClawdCall workflow:
+
+- send signup OTP
+- verify signup OTP
+- place outbound calls
+- fetch call transcripts
+
+The API base URL defaults to `https://api.clawdcall.com`.
+
+## Quick Start
+
+### 1. Add ClawdCall to your MCP client
+
+```json
+{
+  "mcpServers": {
+    "clawdcall": {
+      "command": "npx",
+      "args": ["-y", "clawdcall-mcp"],
+      "env": {
+        "CLAWDCALL_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+`CLAWDCALL_API_KEY` is required for outbound calls and transcript retrieval. Signup OTP tools do not require an existing key.
+
+For staging or self-hosted API routing:
+
+```json
+{
+  "mcpServers": {
+    "clawdcall": {
+      "command": "npx",
+      "args": ["-y", "clawdcall-mcp"],
+      "env": {
+        "CLAWDCALL_API_KEY": "sk_live_your_key_here",
+        "CLAWDCALL_BASE_URL": "https://api.clawdcall.com"
+      }
+    }
+  }
+}
+```
+
+## Example Prompts
+
+- "Sign me up for ClawdCall and send a verification code."
+- "Verify this ClawdCall OTP and tell me what credential I need to store securely."
+- "Call this restaurant and ask if they have a table for two tonight."
+- "Fetch the transcript for this ClawdCall call ID."
+
+## Tools
+
+| Tool | Confirmed endpoint | Description |
+| --- | --- | --- |
+| `send_signup_otp` | `POST /cc/signup/send-otp` | Send a phone verification OTP for signup. |
+| `verify_signup_otp` | `POST /cc/signup/verify-otp` | Verify the OTP and receive account/API-key details. |
+| `place_outbound_call` | `POST /external/v1/agent/outbound?conversionFlag=1` | Place an outbound voice-agent call. |
+| `get_call_transcript` | `GET /cc/v1/calls/{id}/transcript` | Fetch a transcript by call ID or campaign ID. |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `CLAWDCALL_API_KEY` | For call/transcript tools | | ClawdCall API key. |
+| `CLAWDCALL_BASE_URL` | No | `https://api.clawdcall.com` | API base URL. |
+
+## Development
+
+```bash
+git clone https://github.com/dialgoodian/clawdcall-mcp.git
+cd clawdcall-mcp
+npm install
+npm run dev
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Run the built server:
+
+```bash
+CLAWDCALL_API_KEY=sk_live_your_key_here npm start
+```
+
+## API Contract
+
+This server tracks the ClawdCall agent-facing OpenAPI contract currently published by the ClawdCall UI repo:
+
+- `POST /cc/signup/send-otp`
+- `POST /cc/signup/verify-otp`
+- `POST /external/v1/agent/outbound?conversionFlag=1`
+- `GET /cc/v1/calls/{id}/transcript`
+
+Do not add MCP tools for agents, number purchase, SMS, conversations, voices, or general webhooks until those routes exist in ClawdCall's API contract.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue | undefined;
+};
+export declare class ClawdCallApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export interface ClawdCallClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export declare class ClawdCallClient {
+    private readonly apiKey?;
+    private readonly baseUrl;
+    constructor(options: ClawdCallClientOptions);
+    get(path: string, query?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<JsonValue>;
+    post(path: string, body?: JsonObject, options?: RequestOptions): Promise<JsonValue>;
+    patch(path: string, body?: JsonObject, options?: RequestOptions): Promise<JsonValue>;
+    delete(path: string, options?: RequestOptions): Promise<JsonValue>;
+    private request;
+}
+interface RequestOptions {
+    authenticated?: boolean;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,64 @@
+export class ClawdCallApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`ClawdCall API request failed with status ${status}: ${body}`);
+        this.name = "ClawdCallApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class ClawdCallClient {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://api.clawdcall.com");
+    }
+    async get(path, query, options) {
+        return this.request("GET", path, undefined, query, options);
+    }
+    async post(path, body, options) {
+        return this.request("POST", path, body, undefined, options);
+    }
+    async patch(path, body, options) {
+        return this.request("PATCH", path, body, undefined, options);
+    }
+    async delete(path, options) {
+        return this.request("DELETE", path, undefined, undefined, options);
+    }
+    async request(method, path, body, query, options) {
+        const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+        const authenticated = options?.authenticated ?? true;
+        if (authenticated && !this.apiKey) {
+            throw new Error("CLAWDCALL_API_KEY is required for this tool");
+        }
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const response = await fetch(url, {
+            method,
+            headers: {
+                ...(authenticated ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+                "Content-Type": "application/json",
+                "User-Agent": "clawdcall-mcp/0.1.0",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new ClawdCallApiError(response.status, text);
+        }
+        if (!text) {
+            return null;
+        }
+        return JSON.parse(text);
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface Config {
+    apiKey?: string;
+    baseUrl: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,6 @@
+export function loadConfig(env = process.env) {
+    return {
+        apiKey: env.CLAWDCALL_API_KEY,
+        baseUrl: env.CLAWDCALL_BASE_URL ?? "https://api.clawdcall.com",
+    };
+}

package/dist/format.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from "./client.js";
+export declare function jsonResponse(value: JsonValue): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/format.js

@@ -0,0 +1,10 @@
+export function jsonResponse(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ClawdCallClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        printHelp();
+        return;
+    }
+    const config = loadConfig();
+    const client = new ClawdCallClient(config);
+    const server = new McpServer({
+        name: "clawdcall",
+        version: "0.1.0",
+    });
+    registerTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function printHelp() {
+    process.stdout.write(`clawdcall-mcp
+
+Run a ClawdCall MCP server over stdio.
+
+Environment:
+  CLAWDCALL_API_KEY    API key required for call and transcript tools.
+  CLAWDCALL_BASE_URL   Optional API base URL. Defaults to https://api.clawdcall.com.
+
+Usage:
+  CLAWDCALL_API_KEY=sk_live_xxx npx clawdcall-mcp
+`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClawdCallClient } from "./client.js";
+export declare function registerTools(server: McpServer, client: ClawdCallClient): void;

package/dist/tools.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { jsonResponse } from "./format.js";
+const optionalString = z.string().min(1).optional();
+export function registerTools(server, client) {
+    server.tool("send_signup_otp", "Send a ClawdCall signup phone verification OTP. Does not require an API key.", {
+        email: z.string().email(),
+        phone_number: z.string().min(1).describe("Human phone number to verify."),
+    }, async ({ email, phone_number }) => {
+        return jsonResponse(await client.post("/cc/signup/send-otp", {
+            email,
+            phoneNumber: phone_number,
+        }, { authenticated: false }));
+    });
+    server.tool("verify_signup_otp", "Verify a ClawdCall signup OTP and receive account/API-key details. Does not require an existing API key.", {
+        email: z.string().email(),
+        phone_number: z.string().min(1).describe("Human phone number used for signup."),
+        otp: z.string().min(1).describe("OTP code received by the human."),
+    }, async ({ email, phone_number, otp }) => {
+        return jsonResponse(await client.post("/cc/signup/verify-otp", {
+            email,
+            phoneNumber: phone_number,
+            otp,
+        }, { authenticated: false }));
+    });
+    server.tool("place_outbound_call", "Place an outbound ClawdCall agent call. Requires CLAWDCALL_API_KEY.", {
+        target: z.string().min(1).describe("E.164 phone number to call."),
+        tasks: z.string().min(1).describe("Full voice-agent instruction set for the call."),
+        intro_message: optionalString.describe("Optional opening line for the voice agent."),
+        openclaw_webhook_url: optionalString.describe("Optional OpenClaw /agent/run webhook URL for completion events."),
+        openclaw_webhook_authorization: optionalString.describe("Optional Authorization header value for the OpenClaw webhook."),
+        conversation_id: optionalString.describe("Optional OpenClaw conversation ID for event correlation."),
+        user_id: optionalString.describe("Optional user ID for webhook correlation."),
+        context: optionalString.describe("Optional extra context to include in the webhook payload."),
+    }, async (args) => {
+        return jsonResponse(await client.post("/external/v1/agent/outbound?conversionFlag=1", compact({
+            target: args.target,
+            tasks: args.tasks,
+            raw: args.intro_message ? { introMessage: args.intro_message } : undefined,
+            openclaw: buildOpenClawPayload(args),
+        })));
+    });
+    server.tool("get_call_transcript", "Fetch a ClawdCall transcript by call ID or campaign ID. Requires CLAWDCALL_API_KEY.", {
+        id: z.string().min(1).describe("Call ID or campaign ID returned by ClawdCall."),
+    }, async ({ id }) => {
+        return jsonResponse(await client.get(`/cc/v1/calls/${encodeURIComponent(id)}/transcript`));
+    });
+}
+function buildOpenClawPayload(args) {
+    if (!args.openclaw_webhook_url &&
+        !args.openclaw_webhook_authorization &&
+        !args.conversation_id &&
+        !args.user_id &&
+        !args.context) {
+        return undefined;
+    }
+    return compact({
+        webhook: args.openclaw_webhook_url
+            ? compact({
+                url: args.openclaw_webhook_url,
+                method: "POST",
+                headers: args.openclaw_webhook_authorization
+                    ? {
+                        Authorization: args.openclaw_webhook_authorization,
+                    }
+                    : undefined,
+            })
+            : undefined,
+        webhookPayload: compact({
+            conversation_id: args.conversation_id,
+            user_id: args.user_id,
+            context: args.context,
+        }),
+    });
+}
+function compact(values) {
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "clawdcall-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ClawdCall's agent-facing phone execution API.",
+  "type": "module",
+  "bin": {
+    "clawdcall-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "clawdcall",
+    "mcp",
+    "model-context-protocol",
+    "telephony",
+    "phone",
+    "voice",
+    "ai-agents",
+    "openclaw",
+    "claude-code"
+  ],
+  "author": "ClawdCall",
+  "license": "MIT",
+  "homepage": "https://github.com/dialgoodian/clawdcall-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dialgoodian/clawdcall-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dialgoodian/clawdcall-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}