byourside-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 By Your Side
+
+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,151 @@
+# byourside-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 By Your Side Agent API.
+
+## Prerequisites
+
+- Node 18 or newer
+- A By Your Side agent API key (starts with `bys_ak_`)
+
+## Quick start
+
+```bash
+cd mcp
+npm install
+BYOURSIDE_API_KEY=bys_ak_your_key_here npm start
+```
+
+## MCP client configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS:
+
+```json
+{
+  "mcpServers": {
+    "byourside": {
+      "command": "node",
+      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
+      "env": { "BYOURSIDE_API_KEY": "bys_ak_your_key_here" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "byourside": {
+      "command": "node",
+      "args": ["/absolute/path/to/voip-agent/mcp/src/server.js"],
+      "env": { "BYOURSIDE_API_KEY": "bys_ak_your_key_here" }
+    }
+  }
+}
+```
+
+To point at a staging or self-hosted instance, add `"BYOURSIDE_API_BASE": "https://staging.example.com"` to the `env` block.
+
+## Tools
+
+### `place_call`
+
+Places an outbound AI phone call toward an objective. Returns a `callId` immediately; the call runs asynchronously. Poll `get_call` with that `callId` until status is terminal.
+
+**Inputs:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `to` | string | yes | Destination number in E.164 (e.g. `+14155550123`) |
+| `objective` | string | yes | What the call should accomplish |
+| `context` | string | no | Background context for the assistant |
+| `fields` | array | no | Structured fields to extract (up to 20 items: `{ name, type?, description? }`) |
+| `webhookUrl` | string | no | HTTPS URL to receive the signed result when the call ends |
+| `callerId` | string | no | Caller ID override; must be a number on your account |
+
+**Returns:** `{ callId, status }` where `status` is `queued` on success.
+
+### `get_call`
+
+Fetches the current status and result of a call.
+
+**Inputs:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `callId` | string | yes | The `callId` from `place_call` |
+
+**Returns:** `{ id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }`
+
+### `list_calls`
+
+Lists recent calls placed by your account (most recent first).
+
+**Inputs:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `limit` | number | no | Max calls to return (default 20, max 100) |
+
+**Returns:** `{ calls: [ { id, to, objective, status, summary, createdAt, startedAt, endedAt, durationSec, error? } ] }`
+
+## Call statuses
+
+| Status | Terminal? | Meaning |
+|---|---|---|
+| `queued` | no | Call accepted, not yet dialing |
+| `ringing` | no | Dialing the destination |
+| `in_progress` | no | Call is live |
+| `completed` | yes | Call finished normally |
+| `no_answer` | yes | Destination did not pick up |
+| `voicemail` | yes | Reached voicemail |
+| `declined` | yes | Call was rejected |
+| `failed` | yes | Technical failure |
+
+## Place your first call
+
+1. Configure your MCP client as above.
+2. Ask your assistant: "Place a call to +14155550123 with the objective: confirm the meeting time for tomorrow at 2pm."
+3. The assistant calls `place_call` and gets back a `callId`.
+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
+
+1. Set `BYOURSIDE_API_KEY` and optionally `BYOURSIDE_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.
+
+## Development
+
+Run tests:
+
+```bash
+cd mcp && node --test
+```
+
+Check server parses:
+
+```bash
+node --check mcp/src/server.js
+```
+
+Smoke test (missing key, should exit 1):
+
+```bash
+node mcp/src/server.js
+```
+
+Smoke test (with dummy key, should print "ready on stdio" to stderr):
+
+```bash
+BYOURSIDE_API_KEY=bys_ak_test node mcp/src/server.js
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "byourside-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server giving AI agents a phone via By Your Side outbound AI calls.",
+  "license": "MIT",
+  "author": "By Your Side",
+  "homepage": "https://byourside.ai/docs/agent-api",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allexp1/voip-agent.git",
+    "directory": "mcp"
+  },
+  "keywords": ["voice", "ai", "phone", "outbound", "agent", "mcp", "voip", "calls"],
+  "files": ["src", "README.md", "LICENSE"],
+  "bin": { "byourside-mcp": "src/server.js" },
+  "scripts": { "test": "node --test", "start": "node src/server.js" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.0"
+  },
+  "engines": { "node": ">=18" }
+}

package/src/client.js

@@ -0,0 +1,30 @@
+// Tiny authed REST client for the By Your Side Agent API. Never throws on HTTP or
+// network errors; returns a structured result so tool handlers can surface a clean
+// message. fetchImpl is injectable for tests (defaults to global fetch on Node 18+).
+import { mapApiError } from './errors.js';
+
+export function createClient({ apiKey, baseUrl, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('no fetch available (Node 18+ required)');
+  async function request(method, path, body) {
+    const url = `${baseUrl}${path}`;
+    const opts = { method, headers: { Authorization: `Bearer ${apiKey}` } };
+    if (body !== undefined && method !== 'GET') {
+      opts.headers['content-type'] = 'application/json';
+      opts.body = JSON.stringify(body);
+    }
+    let res;
+    try {
+      res = await fetchImpl(url, opts);
+    } catch (e) {
+      return { ok: false, status: 0, error: 'network_error', message: mapApiError(0, null) };
+    }
+    let data = null;
+    try { data = await res.json(); } catch { data = null; }
+    if (res.ok) {
+      if (data == null) return { ok: false, status: res.status, error: 'empty_response', message: 'Server returned an empty or non-JSON response. Please retry shortly.' };
+      return { ok: true, status: res.status, data };
+    }
+    return { ok: false, status: res.status, error: (data && data.error) || 'error', message: mapApiError(res.status, data) };
+  }
+  return { request };
+}

package/src/config.js

@@ -0,0 +1,12 @@
+// Reads + validates the MCP server's runtime config from an env object.
+// Pure (takes env in) so it is unit-testable without touching process.env.
+const DEFAULT_BASE = 'https://api.byourside.ai';
+
+export function loadConfig(env = process.env) {
+  const apiKey = String(env.BYOURSIDE_API_KEY || '').trim();
+  if (!apiKey) {
+    throw new Error('BYOURSIDE_API_KEY is required (your bys_ak_ agent key). Set it in your MCP client config.');
+  }
+  const baseUrl = String(env.BYOURSIDE_API_BASE || DEFAULT_BASE).trim().replace(/\/+$/, '');
+  return { apiKey, baseUrl };
+}

package/src/errors.js

@@ -0,0 +1,28 @@
+// Map a By Your Side Agent API error (status + body token) to a clear, actionable
+// message for the calling LLM/user. Never includes secrets. Pure.
+const TOKEN_MESSAGES = {
+  destination_blocked: "That destination is not allowed (premium, IRSF, or unsupported country).",
+  invalid_number: 'The destination number is invalid (use full E.164, e.g. +14155550123).',
+  to_required: 'A destination number ("to") is required.',
+  objective_required: 'An "objective" for the call is required.',
+  invalid_context: 'The "context" value is invalid.',
+  invalid_fields: 'The "fields" value is invalid (use up to 20 items of { name, type?, description? }).',
+  invalid_webhook_url: 'The "webhookUrl" must be an https URL.',
+  invalid_caller_id: 'The "callerId" value is invalid.',
+  caller_id_not_owned: "That caller ID is not a number on your account.",
+  rate_limited: 'Rate limit reached. Try again shortly.',
+  over_minute_cap: 'Outbound usage limit reached for now.',
+  unauthorized: 'Invalid or missing API key (BYOURSIDE_API_KEY).',
+  not_found: 'No call found with that id (or it does not belong to your account).',
+  placement_failed: 'The call could not be placed (carrier/trunk issue). Try again shortly.',
+  store_error: 'Temporary service error. Please retry shortly.',
+};
+
+export function mapApiError(status, body) {
+  if (!status) return 'Temporary service error. Please retry shortly.';
+  const token = body && typeof body === 'object' ? String(body.error || '') : '';
+  if (token && TOKEN_MESSAGES[token]) return TOKEN_MESSAGES[token];
+  if (status >= 500) return 'Temporary service error. Please retry shortly.';
+  if (token) return `Request failed (${token}).`;
+  return `Request failed with status ${status}.`;
+}

package/src/server.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// By Your Side MCP server (stdio). Registers place_call / get_call / list_calls on an
+// McpServer and serves over stdin/stdout. Config comes from env (BYOURSIDE_API_KEY,
+// BYOURSIDE_API_BASE). Exits with a clear message if the key is missing.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { createClient } from './client.js';
+import { buildTools } from './tools.js';
+
+async function main() {
+  let cfg;
+  try { cfg = loadConfig(process.env); }
+  catch (e) { console.error(`[byourside-mcp] ${e.message}`); process.exit(1); }
+
+  const client = createClient({ apiKey: cfg.apiKey, baseUrl: cfg.baseUrl });
+  const server = new McpServer({ name: 'byourside-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);
+  }
+
+  await server.connect(new StdioServerTransport());
+  console.error('[byourside-mcp] ready on stdio');
+}
+
+main().catch((e) => { console.error('[byourside-mcp] fatal:', e?.message || e); process.exit(1); });

package/src/tools.js

@@ -0,0 +1,55 @@
+// 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).
+import { z } from 'zod';
+
+const okText = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+const errText = (msg) => ({ isError: true, content: [{ type: 'text', text: msg }] });
+const result = (r) => (r.ok ? okText(r.data) : errText(r.message || `Request failed (${r.error || r.status}).`));
+
+export function buildTools(client) {
+  return [
+    {
+      name: 'place_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).',
+      inputShape: {
+        to: z.string().describe('Destination phone number in E.164, e.g. +14155550123.'),
+        objective: z.string().describe('What the call should accomplish.'),
+        context: z.string().optional().describe('Background context for the assistant.'),
+        fields: z.array(z.object({
+          name: z.string(),
+          type: z.enum(['string', 'boolean', 'number']).optional(),
+          description: z.string().optional(),
+        })).optional().describe('Structured fields to extract from the call.'),
+        webhookUrl: z.string().optional().describe('Optional https URL to receive the signed result.'),
+        callerId: z.string().optional().describe('Optional caller ID; must be a number on your account.'),
+      },
+      handler: async (args) => result(await client.request('POST', '/v1/agent/calls', {
+        to: args.to, objective: args.objective, context: args.context,
+        fields: args.fields, webhookUrl: args.webhookUrl, callerId: args.callerId,
+      })),
+    },
+    {
+      name: 'get_call',
+      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.',
+      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',
+      description: 'List recent calls placed by your account (most recent first).',
+      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
+        return result(await client.request('GET', `/v1/agent/calls?limit=${limit}`));
+      },
+    },
+  ];
+}