call-me-cloud-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rivers Cornelson
+
+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,93 @@
+# call-me-cloud-mcp
+
+MCP (Model Context Protocol) client that enables Claude to make phone calls via [Call-Me Cloud](https://github.com/riverscornelson/call-me-cloud).
+
+## What is this?
+
+This package lets Claude Code call you on the phone. It connects to a Call-Me Cloud server (which you deploy) and provides MCP tools for initiating and managing voice calls.
+
+## Installation
+
+Used automatically via npx in Claude Code configurations. Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "call-me-cloud": {
+      "command": "npx",
+      "args": ["-y", "call-me-cloud-mcp"],
+      "env": {
+        "CALLME_CLOUD_URL": "https://your-server.railway.app",
+        "CALLME_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CALLME_CLOUD_URL` | Yes | Your Call-Me Cloud server URL |
+| `CALLME_API_KEY` | Yes | API key for authentication |
+
+## Available Tools
+
+### `initiate_call`
+Start a phone call with the user.
+
+```
+initiate_call({ message: "Hey, I finished the refactor. Want me to walk through it?" })
+```
+
+Returns: `{ callId, response }` - The call ID and the user's spoken response.
+
+### `continue_call`
+Send a follow-up message and wait for response.
+
+```
+continue_call({ call_id: "call-1", message: "Should I also update the tests?" })
+```
+
+### `speak_to_user`
+Speak a message without waiting for a response.
+
+```
+speak_to_user({ call_id: "call-1", message: "Give me a moment to check that..." })
+```
+
+### `end_call`
+End the call with a closing message.
+
+```
+end_call({ call_id: "call-1", message: "Sounds good, I'll get started. Talk soon!" })
+```
+
+## Requirements
+
+- Node.js 18+
+- A deployed [Call-Me Cloud](https://github.com/riverscornelson/call-me-cloud) server
+- Twilio or Telnyx account for phone calls
+- OpenAI API key (for speech-to-text and text-to-speech)
+
+## How It Works
+
+```
+Claude Code  -->  This MCP Client  -->  Your Cloud Server  -->  Phone Call
+   (stdio)          (REST API)           (Twilio/Telnyx)        (to you)
+```
+
+1. Claude decides to call you using one of the MCP tools
+2. This client forwards the request to your cloud server
+3. The server initiates a phone call via Twilio/Telnyx
+4. Audio is processed through OpenAI's real-time API
+5. Your response is transcribed and returned to Claude
+
+## Server Setup
+
+See the main [Call-Me Cloud repository](https://github.com/riverscornelson/call-me-cloud) for server deployment instructions.
+
+## License
+
+MIT

package/bin/run.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const indexPath = join(__dirname, '..', 'index.ts');
+
+// Spawn node with tsx loader using --import flag (Node 20.6+/18.19+ compatible)
+const child = spawn(
+  process.execPath,
+  ['--import', 'tsx', indexPath],
+  {
+    stdio: 'inherit',
+    env: process.env,
+  }
+);
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+/**
+ * CallMe MCP Client
+ *
+ * A local MCP server that forwards tool calls to the cloud-hosted call-me server.
+ * This allows Claude Code to use call-me even when behind a VPN that blocks tunneling.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const CLOUD_URL = process.env.CALLME_CLOUD_URL;
+const API_KEY = process.env.CALLME_API_KEY;
+
+if (!CLOUD_URL) {
+  console.error('Error: CALLME_CLOUD_URL is required');
+  console.error('Set it to your Railway/Render deployment URL');
+  process.exit(1);
+}
+
+if (!API_KEY) {
+  console.error('Error: CALLME_API_KEY is required');
+  process.exit(1);
+}
+
+async function apiCall(path: string, body: unknown): Promise<unknown> {
+  const response = await fetch(`${CLOUD_URL}${path}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${API_KEY}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: response.statusText }));
+    throw new Error(error.error || `API error: ${response.status}`);
+  }
+
+  return response.json();
+}
+
+async function main() {
+  // Verify cloud server is reachable (uses unauthenticated /health endpoint)
+  try {
+    const healthResponse = await fetch(`${CLOUD_URL}/health`);
+    if (!healthResponse.ok) {
+      throw new Error(`Health check failed: ${healthResponse.status}`);
+    }
+    const health = await healthResponse.json() as { status: string; publicUrl?: string };
+    console.error(`Connected to cloud server: ${health.publicUrl || CLOUD_URL}`);
+  } catch (error) {
+    console.error('Warning: Could not reach cloud server:', error instanceof Error ? error.message : error);
+    console.error('Calls may fail until the server is available.');
+  }
+
+  const mcpServer = new Server(
+    { name: 'callme-client', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  // List available tools (same as original call-me)
+  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: 'initiate_call',
+          description: 'Start a phone call with the user. Use when you need voice input, want to report completed work, or need real-time discussion.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              message: {
+                type: 'string',
+                description: 'What you want to say to the user. Be natural and conversational.',
+              },
+            },
+            required: ['message'],
+          },
+        },
+        {
+          name: 'continue_call',
+          description: 'Continue an active call with a follow-up message.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              call_id: { type: 'string', description: 'The call ID from initiate_call' },
+              message: { type: 'string', description: 'Your follow-up message' },
+            },
+            required: ['call_id', 'message'],
+          },
+        },
+        {
+          name: 'speak_to_user',
+          description: 'Speak a message on an active call without waiting for a response.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              call_id: { type: 'string', description: 'The call ID from initiate_call' },
+              message: { type: 'string', description: 'What to say to the user' },
+            },
+            required: ['call_id', 'message'],
+          },
+        },
+        {
+          name: 'end_call',
+          description: 'End an active call with a closing message.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              call_id: { type: 'string', description: 'The call ID from initiate_call' },
+              message: { type: 'string', description: 'Your closing message (say goodbye!)' },
+            },
+            required: ['call_id', 'message'],
+          },
+        },
+      ],
+    };
+  });
+
+  // Handle tool calls by forwarding to cloud server
+  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+      if (request.params.name === 'initiate_call') {
+        const { message } = request.params.arguments as { message: string };
+        const result = await apiCall('/api/call', { message }) as { callId: string; response: string };
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Call initiated successfully.\n\nCall ID: ${result.callId}\n\nUser's response:\n${result.response}\n\nUse continue_call to ask follow-ups or end_call to hang up.`,
+          }],
+        };
+      }
+
+      if (request.params.name === 'continue_call') {
+        const { call_id, message } = request.params.arguments as { call_id: string; message: string };
+        const result = await apiCall(`/api/call/${call_id}/continue`, { message }) as { response: string };
+
+        return {
+          content: [{ type: 'text', text: `User's response:\n${result.response}` }],
+        };
+      }
+
+      if (request.params.name === 'speak_to_user') {
+        const { call_id, message } = request.params.arguments as { call_id: string; message: string };
+        await apiCall(`/api/call/${call_id}/speak`, { message });
+
+        return {
+          content: [{ type: 'text', text: `Message spoken: "${message}"` }],
+        };
+      }
+
+      if (request.params.name === 'end_call') {
+        const { call_id, message } = request.params.arguments as { call_id: string; message: string };
+        const result = await apiCall(`/api/call/${call_id}/end`, { message }) as { durationSeconds: number };
+
+        return {
+          content: [{ type: 'text', text: `Call ended. Duration: ${result.durationSeconds}s` }],
+        };
+      }
+
+      throw new Error(`Unknown tool: ${request.params.name}`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      return {
+        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Connect via stdio
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+
+  console.error('');
+  console.error('CallMe MCP Client ready');
+  console.error(`Cloud server: ${CLOUD_URL}`);
+  console.error('');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "call-me-cloud-mcp",
+  "version": "1.0.0",
+  "description": "MCP client for Call-Me Cloud - lets Claude call you via phone",
+  "type": "module",
+  "bin": {
+    "call-me-cloud-mcp": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node --import tsx index.ts",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "tsx": "^4.19.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "anthropic",
+    "ai",
+    "llm",
+    "phone",
+    "call",
+    "voice",
+    "telephony"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riverscornelson/call-me-cloud.git"
+  },
+  "homepage": "https://github.com/riverscornelson/call-me-cloud#readme",
+  "bugs": {
+    "url": "https://github.com/riverscornelson/call-me-cloud/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Rivers Cornelson",
+  "license": "MIT"
+}