@rynger/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rynger
+
+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,159 @@
+# @rynger/mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **Rynger**, your personal AI
+outbound-call agent. It lets any MCP host (Claude Desktop, Claude Code, Cursor,
+Codex, …) place and schedule one-off phone calls, read their transcripts and
+outcomes, manage your phone numbers, and handle billing.
+
+This server is a **thin client over Rynger's HTTP API**. It shapes inputs,
+applies a few client-side guards that mirror the Rynger web portal, and forwards
+to the API. It deliberately contains **no business logic** — credits, AI judging
+of whether the goal was met, number provisioning, and caller-ID selection all
+live server-side.
+
+## Guardrails
+
+- **Personal one-off calls only.** No marketing, mass, sequential, list-based, or
+  robocalling (TCPA). There is **no bulk / auto-loop / "call this list"**
+  capability, and the tools must not be looped to simulate one.
+- **The AI self-discloses that it is an AI** on every call.
+- **1 credit per call** (your first call is free). Each call is **hard-capped at
+  10 minutes**.
+- **`callee` must be E.164** (e.g. `+14155550123`). A number bought for a country
+  can only dial that country; with the shared US number, non-US destinations show
+  a US caller ID (the tool says so in its result).
+- **Pay actions return a URL** the human must open — `rynger_buy_number`,
+  `rynger_checkout`, and `rynger_billing_portal` never charge money directly.
+- Your API key (`rk_...`) is **redacted** from all logs and error messages.
+
+## Get your API key
+
+Open Rynger → **Power Users** tab and create an API key. It looks like
+`rk_live_...`. Set it as `RYNGER_API_KEY` (see configs below).
+
+## Configuration (environment)
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `RYNGER_API_KEY` | **yes** | — | Bearer token. The server exits on startup if unset. |
+| `RYNGER_API_BASE` | no | `https://rynger-func-g4d4caf7c0c9c0ak.eastus-01.azurewebsites.net/api` | Override the API base URL. |
+| `RYNGER_REQUEST_TIMEOUT_MS` | no | `30000` | Per-request timeout in milliseconds. |
+
+Runs with no install via `npx -y @rynger/mcp`. Requires **Node 18+** (uses the
+built-in `fetch`).
+
+## Install per client
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "rynger": {
+      "command": "npx",
+      "args": ["-y", "@rynger/mcp"],
+      "env": {
+        "RYNGER_API_KEY": "rk_live_xxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+To point at a non-default API base, add it to `env`:
+
+```json
+"env": {
+  "RYNGER_API_KEY": "rk_live_xxxxxxxxxxxxxxxx",
+  "RYNGER_API_BASE": "https://your-host/api"
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add rynger --env RYNGER_API_KEY=rk_live_xxxxxxxxxxxxxxxx -- npx -y @rynger/mcp
+```
+
+### Cursor
+
+Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "rynger": {
+      "command": "npx",
+      "args": ["-y", "@rynger/mcp"],
+      "env": {
+        "RYNGER_API_KEY": "rk_live_xxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to your Codex MCP config (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.rynger]
+command = "npx"
+args = ["-y", "@rynger/mcp"]
+env = { RYNGER_API_KEY = "rk_live_xxxxxxxxxxxxxxxx" }
+```
+
+## Tools
+
+All tools are prefixed `rynger_` and map 1:1 to the Rynger HTTP API.
+
+| Tool | What it does |
+|---|---|
+| `rynger_place_call` | Place a single outbound AI call now toward one person to accomplish a goal. |
+| `rynger_get_call` | Fetch one call's full record, including transcript and the goal-met verdict. |
+| `rynger_list_calls` | List recent calls with status, goal, callee, and outcome. |
+| `rynger_wait_for_call` | Poll a call until it leaves `pending` (or a timeout, max 7 min); return the final record. |
+| `rynger_refine_goal` | Tighten a call goal and list any missing details before you place the call. |
+| `rynger_schedule_call` | Schedule a single call for a future time, optionally recurring. |
+| `rynger_list_schedules` | List scheduled/recurring calls with next run time and repeat rule. |
+| `rynger_cancel_schedule` | Cancel a scheduled call by id. |
+| `rynger_list_numbers` | List the shared number, your owned numbers, inbound config, and buyable countries. |
+| `rynger_quote_number` | Get the price and regulatory fields needed to buy a number in a country. |
+| `rynger_buy_number` | Start buying a number — returns a Stripe Checkout URL for the human to open. |
+| `rynger_release_number` | Permanently release one of your owned numbers (destructive). |
+| `rynger_set_inbound` | Configure how the AI answers inbound calls to one of your numbers. |
+| `rynger_whoami` | Your account identity plus current credit balance and plan. |
+| `rynger_get_balance` | Your current credit balance and plan. |
+| `rynger_checkout` | Start a plan checkout (`starter`/`plus`/`pro`) — returns a URL to open. |
+| `rynger_billing_portal` | Get a Stripe billing-portal URL the human can open. |
+| `rynger_redeem` | Redeem a promo/credit code. |
+
+Read-only tools (`get_call`, `list_calls`, `wait_for_call`, `refine_goal`,
+`list_schedules`, `list_numbers`, `quote_number`, `whoami`, `get_balance`) are
+marked `readOnlyHint`. Mutating, money/call-spending, or irreversible tools
+(`place_call`, `schedule_call`, `buy_number`, `release_number`) are marked
+`destructiveHint` so hosts can prompt for confirmation.
+
+## Languages
+
+`en, es, de, fr, it, pt, nl, pl, uk`. Languages other than `en`/`pl` may not yet
+have a base assistant configured server-side; if so, the backend's error is
+surfaced verbatim.
+
+## Development
+
+```bash
+npm install
+npm run build          # tsc -> dist/
+npm test               # builds, runs guard tests, runs --list-tools smoke
+node dist/index.js --list-tools   # prints tools, no API key or network needed
+```
+
+## License
+
+MIT

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * Environment / configuration handling for the Rynger MCP server.
+ *
+ * Reads RYNGER_API_KEY (required), RYNGER_API_BASE (optional) and
+ * RYNGER_REQUEST_TIMEOUT_MS (optional). Kept separate from the server so the
+ * --list-tools smoke path can avoid touching it entirely.
+ */
+export const DEFAULT_API_BASE = "https://rynger-func-g4d4caf7c0c9c0ak.eastus-01.azurewebsites.net/api";
+export const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Build config from process.env, or exit the process with a clear stderr message
+ * when RYNGER_API_KEY is missing. Only call this on a code path that actually
+ * needs to talk to the API (never on --list-tools).
+ */
+export function loadConfigOrExit() {
+    const apiKey = process.env.RYNGER_API_KEY?.trim();
+    if (!apiKey) {
+        process.stderr.write("Set RYNGER_API_KEY — create one in Rynger → Power Users\n");
+        process.exit(1);
+    }
+    const apiBase = (process.env.RYNGER_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/+$/, "");
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    const rawTimeout = process.env.RYNGER_REQUEST_TIMEOUT_MS?.trim();
+    if (rawTimeout) {
+        const parsed = Number(rawTimeout);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            timeoutMs = Math.floor(parsed);
+        }
+    }
+    return { apiKey, apiBase, timeoutMs };
+}

package/dist/guards.js

@@ -0,0 +1,101 @@
+/**
+ * Pure, side-effect-free client-side guards for the Rynger MCP server.
+ *
+ * These mirror the guardrails the Rynger web portal applies before it calls the
+ * HTTP API. They do NOT re-implement any server-side business logic (credits,
+ * judging, provisioning, caller-ID selection all stay on the backend). They only
+ * shape/validate input so obviously-bad requests fail fast with a clear message.
+ *
+ * Exported separately so tests can import them without booting the MCP server.
+ */
+/** E.164 phone numbers: leading +, first digit 1-9, total 7-15 digits. */
+export const E164_REGEX = /^\+[1-9]\d{6,14}$/;
+/**
+ * Validate a phone number against E.164.
+ * @returns true if the string is a syntactically valid E.164 number.
+ */
+export function validateE164(value) {
+    return typeof value === "string" && E164_REGEX.test(value);
+}
+/**
+ * Map of owned-number country code -> allowed callee dial prefixes (the digits
+ * that follow the leading "+"). US and CA share the "NA" group (+1).
+ *
+ * This mirrors the portal's caller/destination matching: a number bought for a
+ * given country may only dial destinations in that country.
+ */
+export const DIAL_CODE_MAP = {
+    NA: ["1"],
+    GB: ["44"],
+    PL: ["48"],
+    DE: ["49"],
+    FR: ["33"],
+    ES: ["34"],
+    NL: ["31"],
+    IT: ["39"],
+    IE: ["353"],
+};
+/** Country codes that the backend reports but that all belong to the "NA" group. */
+const NA_ALIASES = new Set(["NA", "US", "CA"]);
+/** Normalize a backend-reported country code to the key used in DIAL_CODE_MAP. */
+function normalizeCountry(country) {
+    const upper = (country || "").toUpperCase();
+    return NA_ALIASES.has(upper) ? "NA" : upper;
+}
+/**
+ * Decide whether a call from a given owned number may dial a given destination,
+ * and surface the shared-number caller-ID note when no owned number is used.
+ *
+ * @param callee       destination number in E.164 (already validated upstream).
+ * @param fromCountry  the `country` of the chosen owned number, or null/undefined
+ *                     when the caller did not pass `from_number_id` (i.e. the
+ *                     shared US number will be used).
+ *
+ * Behaviour (mirrors the portal):
+ *  - No owned number (fromCountry null) + callee not +1  -> allowed, but attach a
+ *    note that caller ID will display as a US number.
+ *  - No owned number + callee +1                         -> allowed, no note.
+ *  - Owned number whose country we don't recognize       -> allowed (let the
+ *    backend be the source of truth), no note.
+ *  - Owned number + callee dial code matches its country -> allowed.
+ *  - Owned number + callee dial code does NOT match      -> blocked with a clear
+ *    error.
+ */
+export function callerDestCheck(callee, fromCountry) {
+    // Shared US number path: caller did not select an owned number.
+    if (fromCountry === null || fromCountry === undefined || fromCountry === "") {
+        if (!callee.startsWith("+1")) {
+            return {
+                ok: true,
+                note: "caller ID will display as a US number",
+            };
+        }
+        return { ok: true };
+    }
+    const country = normalizeCountry(fromCountry);
+    const allowedPrefixes = DIAL_CODE_MAP[country];
+    // Unknown country: defer to the backend rather than blocking incorrectly.
+    if (!allowedPrefixes) {
+        return { ok: true };
+    }
+    const digits = callee.replace(/^\+/, "");
+    const matches = allowedPrefixes.some((prefix) => digits.startsWith(prefix));
+    if (!matches) {
+        return {
+            ok: false,
+            error: `Caller/destination mismatch: your ${country} number can only call ${country} ` +
+                `destinations (dial code +${allowedPrefixes.join("/+")}), but ${callee} is not in that range. ` +
+                `Use a matching owned number, or omit from_number_id to call from the shared US number.`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Redact any Rynger API-key-shaped substring (rk_...) from arbitrary text so the
+ * key never leaks into logs or error messages.
+ */
+export function redact(text) {
+    if (typeof text !== "string")
+        return text;
+    return text.replace(/rk_[A-Za-z0-9_\-]+/g, "rk_***");
+}

package/dist/http.js

@@ -0,0 +1,95 @@
+/**
+ * Thin HTTP client over the Rynger API.
+ *
+ * This is the ONLY place that performs network I/O. Every tool calls one of the
+ * endpoints in the documented contract via this client. No business logic lives
+ * here — it just attaches auth, enforces a timeout, and normalizes errors into a
+ * shape the tool layer can turn into an MCP result.
+ */
+import { redact } from "./guards.js";
+/** Error thrown for non-2xx responses or transport failures, carrying status + body. */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(redact(message));
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class RyngerHttpClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** GET helper. */
+    get(path) {
+        return this.request("GET", path);
+    }
+    /** POST helper. Body is JSON-encoded; omit for empty-body POSTs. */
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async request(method, path, body) {
+        const url = `${this.config.apiBase}${path.startsWith("/") ? path : `/${path}`}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            Accept: "application/json",
+        };
+        let payload;
+        if (body !== undefined && method !== "GET") {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(body);
+        }
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: payload,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new ApiError(`Request timed out after ${this.config.timeoutMs}ms (${method} ${path}).`, 0, null);
+            }
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new ApiError(`Network error calling Rynger API (${method} ${path}): ${detail}`, 0, null);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const parsed = await parseBody(res);
+        if (!res.ok) {
+            throw new ApiError(`Rynger API returned HTTP ${res.status}`, res.status, parsed);
+        }
+        return { ok: true, status: res.status, body: parsed };
+    }
+}
+/** Parse a Response body as JSON when possible, falling back to text. */
+async function parseBody(res) {
+    const text = await res.text();
+    if (!text)
+        return null;
+    const contentType = res.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    // Some backends omit the header; attempt JSON anyway, fall back to raw text.
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Rynger MCP server — entry point.
+ *
+ * Rynger is a personal AI outbound-call agent. This server is a THIN client over
+ * Rynger's existing HTTP API: it shapes inputs, applies a few client-side guards
+ * that mirror the web portal, and forwards to the API. It does NOT implement any
+ * business logic (credits, judging, provisioning, caller-ID all stay server-side).
+ *
+ * Transport: stdio.
+ *
+ * The --list-tools path is handled before any env read or transport setup, so it
+ * works without RYNGER_API_KEY and performs no network calls.
+ */
+import { listToolSummaries, buildTools } from "./tools.js";
+const SERVER_NAME = "rynger";
+const SERVER_VERSION = "0.1.0";
+const SERVER_INSTRUCTIONS = [
+    "Rynger is your personal AI outbound-call agent. These tools let you place and schedule one-off phone calls, " +
+        "check their transcripts and outcomes, manage your phone numbers, and handle billing.",
+    "",
+    "Guardrails (enforced or required):",
+    "- Personal one-off calls only. Never use this for marketing, mass, sequential, list-based, or robocalling (TCPA). " +
+        "There is no bulk / auto-loop / 'call this list' capability and you must not simulate one by calling tools in a loop.",
+    "- The AI self-discloses that it is an AI on every call.",
+    "- Calls cost 1 credit each (the first call is free) and are hard-capped at 10 minutes.",
+    "- callee numbers must be E.164 (e.g. +14155550123). A number bought for one country can only dial that country; " +
+        "with the shared US number, non-US destinations will show a US caller ID.",
+    "- Pay actions (rynger_buy_number, rynger_checkout, rynger_billing_portal) return a URL that the human must open — " +
+        "agents cannot complete payment.",
+].join("\n");
+/** Print tool names + one-line descriptions and exit. No env, no network. */
+function printToolList() {
+    const tools = listToolSummaries();
+    for (const t of tools) {
+        process.stdout.write(`${t.name} — ${t.description}\n`);
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--list-tools")) {
+        printToolList();
+        process.exit(0);
+    }
+    // Defer all env + SDK + network setup until we know we are actually serving.
+    const { loadConfigOrExit } = await import("./config.js");
+    const { RyngerHttpClient } = await import("./http.js");
+    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const config = loadConfigOrExit();
+    const client = new RyngerHttpClient(config);
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: SERVER_INSTRUCTIONS,
+        capabilities: { tools: {} },
+    });
+    for (const tool of buildTools(client)) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        }, 
+        // The SDK passes validated args (and an extra) — we only use args.
+        async (args) => {
+            const result = await tool.handler(args ?? {});
+            return result;
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stay alive; the transport keeps the process running on stdin.
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Redact any key-shaped substring defensively (avoid importing for one call).
+    const safe = msg.replace(/rk_[A-Za-z0-9_\-]+/g, "rk_***");
+    process.stderr.write(`rynger-mcp fatal: ${safe}\n`);
+    process.exit(1);
+});

package/dist/result.js

@@ -0,0 +1,84 @@
+/**
+ * Helpers for turning API results / errors into MCP tool results.
+ *
+ * Centralizes the HTTP-status -> actionable-message mapping and the redaction of
+ * the API key from every outgoing string.
+ */
+import { redact } from "./guards.js";
+import { ApiError } from "./http.js";
+/** Wrap arbitrary JSON-able data as a successful text tool result. */
+export function ok(data) {
+    return {
+        content: [{ type: "text", text: redact(pretty(data)) }],
+        isError: false,
+    };
+}
+/** Wrap a successful API result's body as a text tool result. */
+export function okBody(res) {
+    return ok(res.body);
+}
+/** Build an error tool result with a redacted, actionable message. */
+export function fail(message) {
+    return {
+        content: [{ type: "text", text: redact(message) }],
+        isError: true,
+    };
+}
+/** Pretty-print JSON; fall back to String() for non-serializable input. */
+function pretty(data) {
+    if (typeof data === "string")
+        return data;
+    try {
+        return JSON.stringify(data, null, 2);
+    }
+    catch {
+        return String(data);
+    }
+}
+/** Extract the backend `error` field from a parsed body, if present. */
+function backendError(body) {
+    if (body && typeof body === "object" && "error" in body) {
+        const e = body.error;
+        if (typeof e === "string")
+            return e;
+        if (e != null)
+            return JSON.stringify(e);
+    }
+    if (typeof body === "string" && body.trim())
+        return body.trim();
+    return undefined;
+}
+/**
+ * Map any thrown error (ApiError or otherwise) to an actionable MCP error result.
+ * Always includes the HTTP status. Mirrors the contract's error mapping:
+ *   401 -> revoked key, 402 -> out of calls, 404 -> not found,
+ *   400/403/409/503 -> pass through backend `error` verbatim.
+ */
+export function mapError(err) {
+    if (err instanceof ApiError) {
+        const status = err.status;
+        const beError = backendError(err.body);
+        switch (status) {
+            case 401:
+                return fail("HTTP 401: Invalid or revoked API key — create a new one in Rynger → Power Users.");
+            case 402:
+                return fail("HTTP 402: Out of calls — top up with rynger_checkout or redeem a code with rynger_redeem." +
+                    (beError ? ` (${beError})` : ""));
+            case 404:
+                return fail("HTTP 404: Not found." + (beError ? ` ${beError}` : ""));
+            case 400:
+            case 403:
+            case 409:
+            case 503:
+                return fail(`HTTP ${status}: ${beError ?? err.message}`);
+            default:
+                if (status === 0) {
+                    // Transport-level failure (timeout / DNS / network).
+                    return fail(err.message);
+                }
+                return fail(`HTTP ${status}: ${beError ?? err.message}`);
+        }
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return fail(detail);
+}

package/dist/tools.js

@@ -0,0 +1,595 @@
+/**
+ * Tool definitions for the Rynger MCP server.
+ *
+ * Every tool is a thin shim over exactly one documented HTTP endpoint (plus the
+ * client-side guards that mirror the portal). No business logic — credits,
+ * judging, provisioning, caller-ID selection all stay server-side.
+ *
+ * `buildTools(client)` returns the full list. `listToolSummaries()` returns just
+ * names + descriptions and constructs NO client, so it is safe for the
+ * --list-tools smoke path (no env, no network).
+ */
+import { z } from "zod";
+import { callerDestCheck, validateE164, } from "./guards.js";
+import { mapError, ok, okBody, fail } from "./result.js";
+// ---------------------------------------------------------------------------
+// Shared enums / field schemas (mirror the contract)
+// ---------------------------------------------------------------------------
+const LANGUAGES = ["en", "es", "de", "fr", "it", "pt", "nl", "pl", "uk"];
+const REPEATS = ["none", "daily", "weekdays", "weekly", "monthly"];
+const PLANS = ["starter", "plus", "pro"];
+const languageField = z
+    .enum(LANGUAGES)
+    .describe("Language the AI speaks on the call. One of en,es,de,fr,it,pt,nl,pl,uk. " +
+    "Non-en/pl may fail server-side until a base assistant is configured; the server error is surfaced verbatim.");
+const calleeField = z
+    .string()
+    .describe("Destination phone number in E.164 format, e.g. +14155550123.");
+const contextField = z
+    .object({
+    name: z.string().describe("Who the AI should say it is calling on behalf of (the user's name)."),
+    reason: z.string().describe("Short reason/background for the call the AI can reference."),
+})
+    .describe("Context the AI uses to introduce itself and frame the call.");
+const fromNumberIdField = z
+    .string()
+    .optional()
+    .describe("Optional id of one of your owned numbers to call from (see rynger_list_numbers). " +
+    "Omit to use the shared US number. Must match the destination country.");
+// ---------------------------------------------------------------------------
+// Guard helpers shared by place_call / schedule_call
+// ---------------------------------------------------------------------------
+/**
+ * Run the E.164 + caller/destination guards for an outbound request.
+ * Returns either a blocking ToolResult (caller should return it directly) or an
+ * optional advisory note to append after a successful API call.
+ */
+async function runOutboundGuards(client, callee, fromNumberId) {
+    if (!validateE164(callee)) {
+        return {
+            block: fail(`Invalid callee "${callee}": must be E.164, e.g. +14155550123 (leading +, 7–15 digits).`),
+        };
+    }
+    // No owned number selected -> shared US number path; only need the note check.
+    if (!fromNumberId) {
+        const check = callerDestCheck(callee, null);
+        return { note: check.note };
+    }
+    // Owned number selected -> look up its country to enforce the match.
+    let fromCountry = null;
+    try {
+        const res = await client.get("/numbers");
+        const owned = extractOwned(res.body);
+        const match = owned.find((n) => n.id === fromNumberId);
+        if (!match) {
+            return {
+                block: fail(`from_number_id "${fromNumberId}" is not one of your owned numbers. ` +
+                    `Call rynger_list_numbers to see available ids.`),
+            };
+        }
+        fromCountry = match.country ?? null;
+    }
+    catch (err) {
+        // If we cannot verify, fail closed with an actionable message rather than
+        // silently calling from the wrong country.
+        return { block: mapError(err) };
+    }
+    const check = callerDestCheck(callee, fromCountry);
+    if (!check.ok) {
+        return { block: fail(check.error ?? "Caller/destination mismatch.") };
+    }
+    return { note: check.note };
+}
+/** Pull the owned[] array out of a /numbers response defensively. */
+function extractOwned(body) {
+    if (body && typeof body === "object" && "owned" in body) {
+        const owned = body.owned;
+        if (Array.isArray(owned)) {
+            return owned.filter((n) => !!n && typeof n === "object" && typeof n.id === "string");
+        }
+    }
+    return [];
+}
+/** Append an advisory note to a successful tool result's text. */
+function withNote(result, note) {
+    if (!note)
+        return result;
+    return {
+        ...result,
+        content: [
+            ...result.content,
+            { type: "text", text: `Note: ${note}.` },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool builder
+// ---------------------------------------------------------------------------
+const PERSONAL_USE_NOTE = "Personal one-off calls only — no marketing, mass, sequential, list-based, or robocalling (TCPA). " +
+    "The AI self-discloses that it is an AI on every call. Costs 1 credit per call (first call free). " +
+    "Each call is capped at 10 minutes.";
+export function buildTools(client) {
+    return [
+        // ----------------------------------------------------------------- Calls
+        {
+            name: "rynger_place_call",
+            title: "Place a call",
+            description: "Place a single outbound AI phone call now toward one person to accomplish a goal. " +
+                PERSONAL_USE_NOTE,
+            inputSchema: {
+                goal: z
+                    .string()
+                    .describe("What the call should accomplish, e.g. 'Book a table for 2 at 7pm tonight'."),
+                callee: calleeField,
+                language: languageField,
+                context: contextField,
+                from_number_id: fromNumberIdField,
+            },
+            annotations: {
+                title: "Place a call",
+                readOnlyHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            },
+            handler: async (args) => {
+                const callee = String(args.callee ?? "");
+                const fromNumberId = args.from_number_id;
+                const guard = await runOutboundGuards(client, callee, fromNumberId);
+                if (guard.block)
+                    return guard.block;
+                try {
+                    const res = await client.post("/start_call", {
+                        goal: args.goal,
+                        callee,
+                        language: args.language,
+                        context: args.context,
+                        ...(fromNumberId ? { from_number_id: fromNumberId } : {}),
+                    });
+                    return withNote(okBody(res), guard.note);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_get_call",
+            title: "Get call detail",
+            description: "Fetch the full record for one call by id, including transcript and the verdict on whether the goal was met.",
+            inputSchema: {
+                call_id: z.string().describe("The call_id returned by rynger_place_call or rynger_list_calls."),
+            },
+            annotations: { title: "Get call detail", readOnlyHint: true },
+            handler: async (args) => {
+                try {
+                    const res = await client.get(`/calls/${encodeURIComponent(String(args.call_id))}`);
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_list_calls",
+            title: "List calls",
+            description: "List your recent calls with their status, goal, callee, and whether the goal was met.",
+            inputSchema: {},
+            annotations: { title: "List calls", readOnlyHint: true },
+            handler: async () => {
+                try {
+                    return okBody(await client.get("/calls"));
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_wait_for_call",
+            title: "Wait for a call to finish",
+            description: "Poll a call until it is no longer pending (completed/failed) or a timeout is reached, then return the final record. " +
+                "Use after rynger_place_call to wait for the outcome. Default and maximum wait is 7 minutes.",
+            inputSchema: {
+                call_id: z.string().describe("The call_id to wait on."),
+                timeout_seconds: z
+                    .number()
+                    .int()
+                    .positive()
+                    .max(420)
+                    .optional()
+                    .describe("Max seconds to wait (default 420 = 7 min, capped at 420)."),
+            },
+            annotations: { title: "Wait for a call to finish", readOnlyHint: true },
+            handler: async (args) => {
+                const callId = String(args.call_id);
+                const requested = typeof args.timeout_seconds === "number" ? args.timeout_seconds : 420;
+                const timeoutSec = Math.min(Math.max(1, Math.floor(requested)), 420);
+                const deadline = Date.now() + timeoutSec * 1000;
+                const intervalMs = 5000;
+                let last = null;
+                try {
+                    // First immediate check, then poll every ~5s.
+                    // eslint-disable-next-line no-constant-condition
+                    while (true) {
+                        const res = await client.get(`/calls/${encodeURIComponent(callId)}`);
+                        last = res.body;
+                        const status = readStatus(res.body);
+                        if (status !== "pending") {
+                            return okBody(res);
+                        }
+                        if (Date.now() + intervalMs >= deadline) {
+                            return ok({
+                                timed_out: true,
+                                waited_seconds: timeoutSec,
+                                message: `Call ${callId} is still pending after ${timeoutSec}s; returning latest snapshot.`,
+                                latest: last,
+                            });
+                        }
+                        await sleep(intervalMs);
+                    }
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        // -------------------------------------------------------------- Optimize
+        {
+            name: "rynger_refine_goal",
+            title: "Refine a call goal",
+            description: "Improve a call goal before placing the call: returns a tightened goal and a list of any missing details to ask the user for.",
+            inputSchema: {
+                goal: z.string().describe("The draft goal to improve."),
+                context: contextField.optional().describe("Optional context (name, reason) to ground the rewrite."),
+                language: languageField.optional(),
+            },
+            annotations: { title: "Refine a call goal", readOnlyHint: true },
+            handler: async (args) => {
+                try {
+                    const res = await client.post("/refine_goal", {
+                        goal: args.goal,
+                        ...(args.context ? { context: args.context } : {}),
+                        ...(args.language ? { language: args.language } : {}),
+                    });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        // ------------------------------------------------------------ Scheduling
+        {
+            name: "rynger_schedule_call",
+            title: "Schedule a call",
+            description: "Schedule a single outbound AI call for a future time (optionally recurring). " +
+                PERSONAL_USE_NOTE,
+            inputSchema: {
+                goal: z.string().describe("What the call should accomplish."),
+                callee: calleeField,
+                language: languageField,
+                context: contextField,
+                from_number_id: fromNumberIdField,
+                scheduled_for: z
+                    .string()
+                    .describe("When to place the call, as an ISO 8601 timestamp, e.g. 2026-07-01T15:00:00Z."),
+                timezone: z
+                    .string()
+                    .optional()
+                    .describe("Optional IANA timezone for the schedule, e.g. America/New_York."),
+                repeat: z
+                    .enum(REPEATS)
+                    .optional()
+                    .describe("Optional recurrence: none, daily, weekdays, weekly, or monthly."),
+                repeat_until: z
+                    .string()
+                    .optional()
+                    .describe("Optional ISO 8601 date/time after which recurrence stops."),
+            },
+            annotations: {
+                title: "Schedule a call",
+                readOnlyHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            },
+            handler: async (args) => {
+                const callee = String(args.callee ?? "");
+                const fromNumberId = args.from_number_id;
+                const guard = await runOutboundGuards(client, callee, fromNumberId);
+                if (guard.block)
+                    return guard.block;
+                try {
+                    const res = await client.post("/schedule_call", {
+                        goal: args.goal,
+                        callee,
+                        language: args.language,
+                        context: args.context,
+                        scheduled_for: args.scheduled_for,
+                        ...(fromNumberId ? { from_number_id: fromNumberId } : {}),
+                        ...(args.timezone ? { timezone: args.timezone } : {}),
+                        ...(args.repeat ? { repeat: args.repeat } : {}),
+                        ...(args.repeat_until ? { repeat_until: args.repeat_until } : {}),
+                    });
+                    return withNote(okBody(res), guard.note);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_list_schedules",
+            title: "List scheduled calls",
+            description: "List your scheduled (upcoming/recurring) calls with their next run time, repeat rule, goal, and callee.",
+            inputSchema: {},
+            annotations: { title: "List scheduled calls", readOnlyHint: true },
+            handler: async () => {
+                try {
+                    return okBody(await client.get("/schedules"));
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_cancel_schedule",
+            title: "Cancel a scheduled call",
+            description: "Cancel a scheduled call by its schedule id.",
+            inputSchema: {
+                schedule_id: z.string().describe("The schedule id (from rynger_list_schedules) to cancel."),
+            },
+            annotations: { title: "Cancel a scheduled call", readOnlyHint: false },
+            handler: async (args) => {
+                try {
+                    const res = await client.post(`/schedules/${encodeURIComponent(String(args.schedule_id))}/cancel`);
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        // --------------------------------------------------------------- Numbers
+        {
+            name: "rynger_list_numbers",
+            title: "List phone numbers",
+            description: "List the shared number, your owned numbers (with country/status), inbound config, and which countries are available to buy.",
+            inputSchema: {},
+            annotations: { title: "List phone numbers", readOnlyHint: true },
+            handler: async () => {
+                try {
+                    return okBody(await client.get("/numbers"));
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_quote_number",
+            title: "Quote a phone number",
+            description: "Get the price and the regulatory fields needed to buy a number in a given country before purchasing.",
+            inputSchema: {
+                country: z.string().describe("ISO country code to quote, e.g. US, GB, DE."),
+            },
+            annotations: { title: "Quote a phone number", readOnlyHint: true },
+            handler: async (args) => {
+                try {
+                    const res = await client.post("/numbers/quote", { country: args.country });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_buy_number",
+            title: "Buy a phone number",
+            description: "Start buying a phone number for a country. Returns a Stripe Checkout URL the human must open to pay — " +
+                "agents cannot complete payment. Use rynger_quote_number first to learn the required regulatory fields.",
+            inputSchema: {
+                country: z.string().describe("ISO country code to buy in, e.g. US, GB, DE."),
+                area_code: z.string().optional().describe("Optional preferred area code."),
+                language: languageField.optional().describe("Optional default language for the number."),
+                regulatory: z
+                    .record(z.string(), z.unknown())
+                    .optional()
+                    .describe("Regulatory bundle fields required for the country (see rynger_quote_number fields_needed). " +
+                    "Shape varies by country (none/address/address_id)."),
+            },
+            annotations: {
+                title: "Buy a phone number",
+                readOnlyHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            },
+            handler: async (args) => {
+                try {
+                    const res = await client.post("/numbers/buy", {
+                        country: args.country,
+                        ...(args.area_code ? { area_code: args.area_code } : {}),
+                        ...(args.language ? { language: args.language } : {}),
+                        ...(args.regulatory ? { regulatory: args.regulatory } : {}),
+                    });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_release_number",
+            title: "Release a phone number",
+            description: "Permanently release (give up) one of your owned numbers by id. This is destructive and cannot be undone.",
+            inputSchema: {
+                number_id: z.string().describe("The owned number id (from rynger_list_numbers) to release."),
+            },
+            annotations: {
+                title: "Release a phone number",
+                readOnlyHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            },
+            handler: async (args) => {
+                try {
+                    const res = await client.post(`/numbers/${encodeURIComponent(String(args.number_id))}/release`);
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_set_inbound",
+            title: "Configure inbound for a number",
+            description: "Configure how the AI answers inbound calls to one of your owned numbers: owner name, greeting, instructions, questions to ask, and language.",
+            inputSchema: {
+                number_id: z.string().describe("The owned number id to configure."),
+                owner_name: z.string().describe("Name the AI uses to identify whose line this is."),
+                greeting: z.string().describe("Opening line the AI says when answering."),
+                instructions: z.string().describe("How the AI should handle inbound callers."),
+                questions: z
+                    .array(z.string())
+                    .describe("Questions the AI should ask inbound callers (may be empty)."),
+                language: languageField,
+            },
+            annotations: { title: "Configure inbound for a number", readOnlyHint: false },
+            handler: async (args) => {
+                try {
+                    const res = await client.post(`/numbers/${encodeURIComponent(String(args.number_id))}/inbound`, {
+                        owner_name: args.owner_name,
+                        greeting: args.greeting,
+                        instructions: args.instructions,
+                        questions: args.questions,
+                        language: args.language,
+                    });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        // ------------------------------------------------------- Billing/Account
+        {
+            name: "rynger_whoami",
+            title: "Who am I + balance",
+            description: "Return your account identity together with your current call-credit balance and plan (combines /me and /credits).",
+            inputSchema: {},
+            annotations: { title: "Who am I + balance", readOnlyHint: true },
+            handler: async () => {
+                try {
+                    const [meRes, creditsRes] = await Promise.all([
+                        client.get("/me"),
+                        client.get("/credits"),
+                    ]);
+                    return ok({ me: meRes.body, credits: creditsRes.body });
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_get_balance",
+            title: "Get credit balance",
+            description: "Return your current call-credit balance and plan.",
+            inputSchema: {},
+            annotations: { title: "Get credit balance", readOnlyHint: true },
+            handler: async () => {
+                try {
+                    return okBody(await client.get("/credits"));
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_checkout",
+            title: "Start a credit/plan checkout",
+            description: "Start a checkout for a plan (starter, plus, or pro) to add call credits. Returns a URL the human must open to pay.",
+            inputSchema: {
+                plan: z.enum(PLANS).describe("Which plan to buy: starter, plus, or pro."),
+            },
+            annotations: { title: "Start a credit/plan checkout", readOnlyHint: false },
+            handler: async (args) => {
+                try {
+                    const res = await client.post("/checkout", { plan: args.plan });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_billing_portal",
+            title: "Open billing portal",
+            description: "Get a Stripe billing-portal URL the human can open to manage their subscription, payment method, and invoices.",
+            inputSchema: {},
+            annotations: { title: "Open billing portal", readOnlyHint: false },
+            handler: async () => {
+                try {
+                    return okBody(await client.post("/portal"));
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+        {
+            name: "rynger_redeem",
+            title: "Redeem a code",
+            description: "Redeem a promo/credit code and return the granted status and updated balance.",
+            inputSchema: {
+                code: z.string().describe("The code to redeem."),
+            },
+            annotations: { title: "Redeem a code", readOnlyHint: false },
+            handler: async (args) => {
+                try {
+                    const res = await client.post("/redeem", { code: args.code });
+                    return okBody(res);
+                }
+                catch (err) {
+                    return mapError(err);
+                }
+            },
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// --list-tools support (no client, no env, no network)
+// ---------------------------------------------------------------------------
+/** Names + one-line descriptions for the --list-tools smoke path. */
+export function listToolSummaries() {
+    // Build against a throwaway client stub; handlers are never invoked here.
+    const stub = {};
+    return buildTools(stub).map((t) => ({
+        name: t.name,
+        description: firstSentence(t.description),
+    }));
+}
+function firstSentence(text) {
+    const idx = text.indexOf(". ");
+    return idx === -1 ? text : text.slice(0, idx + 1);
+}
+// ---------------------------------------------------------------------------
+// small utils
+// ---------------------------------------------------------------------------
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function readStatus(body) {
+    if (body && typeof body === "object" && "status" in body) {
+        const s = body.status;
+        if (typeof s === "string")
+            return s;
+    }
+    return "pending";
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rynger/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Rynger — your personal AI outbound-call agent. A thin client over Rynger's HTTP API: place one-off calls, schedule them, manage phone numbers, and handle billing from any MCP host.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "rynger-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node test/guards.test.js && node dist/index.js --list-tools"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "rynger",
+    "ai-calls",
+    "outbound",
+    "voice-agent"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.5.0"
+  }
+}