voxplo-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,21 +1,29 @@
 # voxplo-mcp
 
-MCP server that gives any MCP client (Claude Desktop, Cursor, etc.) a phone -- place outbound AI calls, poll for results, and list call history via the Voxplo Agent API.
+Give your AI agent a phone. This MCP server lets any MCP client (Claude, Cursor, ChatGPT developer mode, and others) place real outbound AI phone calls through [Voxplo](https://voxplo.ai): the AI calls a person, conducts the conversation toward an objective, and returns a summary, transcript, and structured extracted fields.
 
-## Prerequisites
+- **Hosted (remote) server:** `https://mcp.voxplo.ai/mcp` (Streamable HTTP + OAuth, no install)
+- **Local (stdio) server:** `npx voxplo-mcp` (this package)
+- **Docs:** https://voxplo.ai/docs/agent-api/mcp
+- **Tools:** `place_call`, `set_appointment`, `get_call`, `list_calls`
 
-- Node 18 or newer
-- A Voxplo agent API key (starts with `bys_ak_`)
+## Option A: hosted server (recommended)
 
-## Quick start
+No install. Add `https://mcp.voxplo.ai/mcp` as a remote MCP server in your client:
 
-```bash
-cd mcp
-npm install
-VOXPLO_API_KEY=bys_ak_your_key_here npm start
+```json
+{
+  "mcpServers": {
+    "voxplo": { "type": "streamable-http", "url": "https://mcp.voxplo.ai/mcp" }
+  }
+}
 ```
 
-## MCP client configuration
+In Claude: Settings, then Connectors, then "Add custom connector", paste `https://mcp.voxplo.ai/mcp`. Your browser opens Voxplo's consent screen; approve by pasting an Agent API key from your [Developers page](https://voxplo.ai/account/developers). The client never sees the key itself, only an OAuth token.
+
+## Option B: local server (this package)
+
+Prerequisites: Node 18+, a Voxplo Agent API key (starts with `bys_ak_`, from your [Developers page](https://voxplo.ai/account/developers)).
 
 ### Claude Desktop
 
@@ -25,8 +33,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 {
   "mcpServers": {
     "voxplo": {
-      "command": "node",
-      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
+      "command": "npx",
+      "args": ["-y", "voxplo-mcp"],
       "env": { "VOXPLO_API_KEY": "bys_ak_your_key_here" }
     }
   }
@@ -35,19 +43,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ### Cursor
 
-Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "voxplo": {
-      "command": "node",
-      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
-      "env": { "VOXPLO_API_KEY": "bys_ak_your_key_here" }
-    }
-  }
-}
-```
+Add the same block to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`).
 
 To point at a staging or self-hosted instance, add `"VOXPLO_API_BASE": "https://staging.example.com"` to the `env` block.
 
@@ -70,6 +66,24 @@ Places an outbound AI phone call toward an objective. Returns a `callId` immedia
 
 **Returns:** `{ callId, status }` where `status` is `queued` on success.
 
+### `set_appointment`
+
+Places an outbound AI phone call to set up a meeting. The assistant calls the person, agrees a time, and the result (poll `get_call`) carries an `outcome` (`appointment_set | callback_requested | declined | no_answer | failed`) and, when set, the appointment details (`startISO`, `timezone`, `durationMinutes`, `attendee`, `subject`). Returns a `callId` immediately.
+
+**Inputs:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `to` | string | yes | Who to call, in E.164 |
+| `subject` | string | yes | What the meeting is about |
+| `durationMinutes` | number | no | Meeting length in minutes (default 30) |
+| `timePreference` | string | no | Natural-language window, e.g. "weekday mornings next week" |
+| `slots` | array | no | Specific start times to offer: `[{ startISO }]`, ISO-8601 with offset |
+| `timezone` | string | no | IANA timezone for the appointment, e.g. `Asia/Jerusalem` |
+| `autoBook` | boolean | no | Also book the agreed time on your connected calendar |
+| `webhookUrl` | string | no | HTTPS URL to receive the signed result |
+| `callerId` | string | no | Caller ID override; must be a number on your account |
+
 ### `get_call`
 
 Fetches the current status and result of a call.
@@ -78,7 +92,7 @@ Fetches the current status and result of a call.
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `callId` | string | yes | The `callId` from `place_call` |
+| `callId` | string | yes | The `callId` from `place_call` or `set_appointment` |
 
 **Returns:** `{ id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }`
 
@@ -115,37 +129,28 @@ Lists recent calls placed by your account (most recent first).
 4. Ask: "Check on call `<callId>` -- did it complete?"
 5. The assistant calls `get_call` and returns the status, summary, and any extracted fields.
 
-## Manual end-to-end test
+## Safety
 
-1. Set `VOXPLO_API_KEY` and optionally `VOXPLO_API_BASE` in your MCP client config.
-2. Configure the client using the JSON above.
-3. Ask your agent to call a number you control with a specific objective and one extraction field (e.g. `{ name: "confirmed", type: "boolean" }`).
-4. Confirm `place_call` returns a `callId`.
-5. Call `get_call` repeatedly until `status` is terminal; verify `extracted.confirmed` is present.
-6. Try a blocked destination (e.g. a premium-rate number) and confirm the mapped error message is returned.
+Outbound destinations are screened server-side (premium-rate, satellite, and other high-risk routes are blocked), calls carry an AI disclosure when asked, and the call-placing tools are annotated `openWorldHint: true` so clients ask for confirmation before dialing. Details: https://voxplo.ai/security
 
 ## Development
 
 Run tests:
 
 ```bash
-cd mcp && node --test
+node --test
 ```
 
-Check server parses:
-
-```bash
-node --check mcp/src/server.js
-```
-
-Smoke test (missing key, should exit 1):
+Smoke test (with dummy key, should print "ready on stdio" to stderr):
 
 ```bash
-node mcp/src/server.js
+VOXPLO_API_KEY=bys_ak_test node src/server.js
 ```
 
-Smoke test (with dummy key, should print "ready on stdio" to stderr):
+## Links
 
-```bash
-VOXPLO_API_KEY=bys_ak_test node mcp/src/server.js
-```
+- Voxplo: https://voxplo.ai
+- Agent API reference: https://voxplo.ai/docs/agent-api
+- OpenAPI spec: https://www.voxplo.ai/openapi.json
+- Hosted MCP server card: https://mcp.voxplo.ai/.well-known/mcp/server-card.json
+- License: MIT

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "voxplo-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "mcpName": "ai.voxplo/voxplo",
   "type": "module",
   "description": "MCP server giving AI agents a phone via Voxplo outbound AI calls.",
   "license": "MIT",
@@ -8,8 +9,7 @@
   "homepage": "https://voxplo.ai/docs/agent-api",
   "repository": {
     "type": "git",
-    "url": "https://github.com/allexp1/voip-agent.git",
-    "directory": "mcp"
+    "url": "https://github.com/allexp1/voxplo-mcp.git"
   },
   "keywords": ["voice", "ai", "phone", "outbound", "agent", "mcp", "voip", "calls"],
   "files": ["src", "README.md", "LICENSE"],

package/src/server.js

@@ -17,9 +17,12 @@ async function main() {
   const server = new McpServer({ name: 'voxplo-mcp', version: '0.1.0' });
 
   for (const t of buildTools(client)) {
-    // SDK high-level registration: (name, description, zodRawShape, handler).
-    // SDK version 1.29.0 uses this variadic overload.
-    server.tool(t.name, t.description, t.inputShape, t.handler);
+    server.registerTool(t.name, {
+      title: t.title,
+      description: t.description,
+      inputSchema: t.inputShape,
+      annotations: t.annotations,
+    }, t.handler);
   }
 
   await server.connect(new StdioServerTransport());

package/src/tools.js

@@ -1,7 +1,9 @@
-// The three MCP tools, as plain definitions ({name, description, inputShape, handler})
-// so they are unit-testable without the MCP SDK. server.js registers them on an
-// McpServer. Handlers call the injected REST client and shape the MCP result; API
-// errors are surfaced as { isError: true } with the mapped message (never thrown).
+// The four MCP tools, as plain definitions ({name, title, description, inputShape,
+// annotations, handler}) so they are unit-testable without the MCP SDK. server.js
+// registers them on an McpServer. Handlers call the injected REST client and shape the
+// MCP result; API errors are surfaced as { isError: true } with the mapped message
+// (never thrown). Annotations follow the MCP tool-annotation hints: the two call-placing
+// tools reach a real person by phone (openWorldHint), the two read tools are readOnly.
 import { z } from 'zod';
 
 const okText = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
@@ -12,10 +14,12 @@ export function buildTools(client) {
   return [
     {
       name: 'place_call',
+      title: 'Place an AI phone call',
       description:
         'Place an outbound AI phone call toward an objective. Returns a callId immediately; ' +
         'the call is conducted asynchronously. Poll get_call with that callId until status is ' +
         'terminal (completed | no_answer | voicemail | declined | failed).',
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       inputShape: {
         to: z.string().describe('Destination phone number in E.164, e.g. +14155550123.'),
         objective: z.string().describe('What the call should accomplish.'),
@@ -35,11 +39,13 @@ export function buildTools(client) {
     },
     {
       name: 'set_appointment',
+      title: 'Set an appointment by phone',
       description:
         'Place an outbound AI phone call to set up a meeting. The assistant calls the person, ' +
         'agrees a time, and the result (poll get_call) carries outcome (appointment_set | ' +
         'callback_requested | declined | no_answer | failed) and, when set, the appointment ' +
         '(startISO, timezone, durationMinutes, attendee, subject). Returns a callId immediately.',
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
       inputShape: {
         to: z.string().describe('Who to call, in E.164, e.g. +14155550123.'),
         subject: z.string().describe('What the meeting is about.'),
@@ -59,16 +65,20 @@ export function buildTools(client) {
     },
     {
       name: 'get_call',
+      title: 'Get call status and result',
       description:
         'Get the status and result of a call by id. status is one of queued | ringing | ' +
         'in_progress (still running, poll again) or completed | no_answer | voicemail | ' +
         'declined | failed (terminal). Returns summary, transcript, and extracted fields.',
+      annotations: { readOnlyHint: true, openWorldHint: false },
       inputShape: { callId: z.string().describe('The callId returned by place_call.') },
       handler: async (args) => result(await client.request('GET', `/v1/agent/calls/${encodeURIComponent(args.callId)}`)),
     },
     {
       name: 'list_calls',
+      title: 'List recent calls',
       description: 'List recent calls placed by your account (most recent first).',
+      annotations: { readOnlyHint: true, openWorldHint: false },
       inputShape: { limit: z.number().int().positive().max(100).optional().describe('Max calls to return (default 20, max 100).') },
       handler: async (args) => {
         const limit = Math.min(Math.max(1, Number(args.limit) || 20), 100); // backstop for direct callers bypassing zod