nexting-cc-bridge 0.8.3

package/dist/mcp-device-proxy.js

@@ -0,0 +1,501 @@
+// Nexting device-tool MCP proxy — a standalone stdio MCP server spawned by
+// claude/codex (configured by the cc-bridge). It exposes the phone's device
+// tools (calendar / reminders / contacts / location / health / homekit) to the
+// agent and forwards each call to the cloud, which fans it out to the phone's
+// SSE stream for execution.
+//
+// IMPORTANT: stdout is the MCP JSON-RPC channel. Anything written to stdout that
+// is not a framed protocol message corrupts the session. ALL logging here goes
+// to stderr (see `log`).
+//
+// Env inputs (set by the bridge when writing the per-session MCP config):
+//   NEXTING_CLOUD_URL  — cloud API base, e.g. https://api.nexting.ai
+//   NEXTING_BUS_TOKEN  — device-tool-scoped bearer token
+//   NEXTING_ENGINE     — "cc" | "codex" (selects the /api/v1/{engine}/* route)
+//   NEXTING_SESSION_ID — the phone session this proxy is bound to
+//
+// Run: node dist/mcp-device-proxy.js
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+/** Build an inputSchema from a flat param list, mirroring the Swift defaults
+ *  (`required` defaults to true). */
+function schema(params) {
+    const properties = {};
+    const required = [];
+    for (const p of params) {
+        properties[p.name] = { type: p.type, description: p.description };
+        if (p.required !== false)
+            required.push(p.name);
+    }
+    return { type: "object", properties, required };
+}
+/** All device tools, 1:1 with iOS DeviceSkillManager.toolDefs(for:). The cloud
+ *  only stores which SKILLS are enabled; the schemas are fixed and live here. */
+export const DEVICE_TOOL_CATALOG = [
+    // --- calendar ---
+    {
+        name: "calendar_today",
+        description: "Get today's calendar events",
+        inputSchema: schema([]),
+    },
+    {
+        name: "calendar_upcoming",
+        description: "Get upcoming events for the next N days",
+        inputSchema: schema([
+            {
+                name: "days",
+                type: "number",
+                required: false,
+                description: "Number of days to look ahead (default 7)",
+            },
+        ]),
+    },
+    {
+        name: "calendar_add_event",
+        description: "Create a new calendar event",
+        inputSchema: schema([
+            { name: "title", type: "string", description: "Event title" },
+            {
+                name: "startDate",
+                type: "string",
+                description: "Start date in ISO 8601 format",
+            },
+            {
+                name: "endDate",
+                type: "string",
+                required: false,
+                description: "End date in ISO 8601 format (default: 1 hour after start)",
+            },
+        ]),
+    },
+    // --- reminders ---
+    {
+        name: "reminders_list",
+        description: "List incomplete reminders",
+        inputSchema: schema([]),
+    },
+    {
+        name: "reminders_add",
+        description: "Add a new reminder",
+        inputSchema: schema([
+            { name: "title", type: "string", description: "Reminder title" },
+            {
+                name: "dueDate",
+                type: "string",
+                required: false,
+                description: "Due date in ISO 8601 format",
+            },
+        ]),
+    },
+    {
+        name: "reminders_complete",
+        description: "Mark a reminder as completed",
+        inputSchema: schema([
+            {
+                name: "title",
+                type: "string",
+                description: "Title of the reminder to complete",
+            },
+        ]),
+    },
+    // --- contacts ---
+    {
+        name: "contacts_search",
+        description: "Search contacts by name",
+        inputSchema: schema([
+            { name: "query", type: "string", description: "Name to search for" },
+        ]),
+    },
+    {
+        name: "contacts_get_phone",
+        description: "Get a contact's phone number",
+        inputSchema: schema([
+            { name: "name", type: "string", description: "Contact name" },
+        ]),
+    },
+    // --- location ---
+    {
+        name: "location_current",
+        description: "Get the user's current GPS coordinates and reverse-geocoded address",
+        inputSchema: schema([]),
+    },
+    // --- health ---
+    {
+        name: "health_today_summary",
+        description: "Get today's health summary: steps, active calories, heart rate, walking distance",
+        inputSchema: schema([]),
+    },
+    {
+        name: "health_steps_history",
+        description: "Get daily step counts for the last N days",
+        inputSchema: schema([
+            {
+                name: "days",
+                type: "number",
+                required: false,
+                description: "Number of days (default 7, max 30)",
+            },
+        ]),
+    },
+    {
+        name: "health_sleep",
+        description: "Get last night's sleep data including duration and sleep stages",
+        inputSchema: schema([]),
+    },
+    // --- homekit ---
+    {
+        name: "homekit_list",
+        description: "List all HomeKit homes, rooms, accessories and their current state",
+        inputSchema: schema([]),
+    },
+    {
+        name: "homekit_control",
+        description: "Control a HomeKit accessory (turn on/off, set brightness, set temperature)",
+        inputSchema: schema([
+            {
+                name: "accessory",
+                type: "string",
+                description: "Name of the accessory to control",
+            },
+            {
+                name: "action",
+                type: "string",
+                description: "Action: on, off, brightness:N (0-100), temperature:N",
+            },
+        ]),
+    },
+    {
+        name: "homekit_scene",
+        description: "List available scenes, or trigger a scene by name",
+        inputSchema: schema([
+            {
+                name: "scene",
+                type: "string",
+                required: false,
+                description: "Scene name to trigger (omit to list all scenes)",
+            },
+        ]),
+    },
+];
+/** Read + validate the proxy config from the environment. Throws on missing
+ *  required vars (the proxy can't function without them). */
+export function readProxyConfig(env) {
+    const rawUrl = (env.NEXTING_CLOUD_URL ?? "").trim();
+    const busToken = (env.NEXTING_BUS_TOKEN ?? "").trim();
+    const rawEngine = (env.NEXTING_ENGINE ?? "").trim();
+    const sessionId = (env.NEXTING_SESSION_ID ?? "").trim();
+    const missing = [];
+    if (!rawUrl)
+        missing.push("NEXTING_CLOUD_URL");
+    if (!busToken)
+        missing.push("NEXTING_BUS_TOKEN");
+    if (!sessionId)
+        missing.push("NEXTING_SESSION_ID");
+    if (rawEngine !== "cc" && rawEngine !== "codex") {
+        missing.push("NEXTING_ENGINE(cc|codex)");
+    }
+    if (missing.length > 0) {
+        throw new Error(`missing/invalid env: ${missing.join(", ")}`);
+    }
+    return {
+        cloudUrl: rawUrl.replace(/\/+$/, ""),
+        busToken,
+        engine: rawEngine === "codex" ? "codex" : "cc",
+        sessionId,
+    };
+}
+export const ASK_USER_TOOL_NAME = "ask_user";
+export const ASK_USER_TOOL = {
+    name: ASK_USER_TOOL_NAME,
+    description: "Ask the user a multiple-choice question and BLOCK until they answer on " +
+        "their phone. Use this whenever you would otherwise stop to ask the user " +
+        "to choose between options or confirm a direction — the user has no " +
+        "terminal, only the Nexting phone app, so this is the ONLY way to get an " +
+        "interactive answer. Provide 1-4 questions; each needs a short `header` " +
+        "(<=12 chars), the `question` text, and 2-4 `options` each with a `label` " +
+        "and a `description`. Set `multiSelect: true` to let the user pick several. " +
+        "Returns the chosen option label(s) per question. If the user does not " +
+        "answer in time you are told so — then proceed with your best judgment.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            questions: {
+                type: "array",
+                description: "1-4 questions to ask the user.",
+                items: {
+                    type: "object",
+                    properties: {
+                        question: {
+                            type: "string",
+                            description: "The full question text.",
+                        },
+                        header: {
+                            type: "string",
+                            description: "A short label for the question (<=12 chars).",
+                        },
+                        multiSelect: {
+                            type: "boolean",
+                            description: "Allow picking more than one option (default false).",
+                        },
+                        options: {
+                            type: "array",
+                            description: "2-4 options the user can choose from.",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    label: {
+                                        type: "string",
+                                        description: "The option text the user picks.",
+                                    },
+                                    description: {
+                                        type: "string",
+                                        description: "A short explanation of this option.",
+                                    },
+                                },
+                                required: ["label"],
+                            },
+                        },
+                    },
+                    required: ["question", "header", "options"],
+                },
+            },
+        },
+        required: ["questions"],
+    },
+};
+// --- HTTP wiring -------------------------------------------------------------
+const CALL_TIMEOUT_MS = 30_000;
+// 11 min — just OVER the cloud's 10 min ask wait, so the cloud's own timeout
+// resolves the round-trip first (the proxy receives {ok:false,error:"timeout"})
+// instead of the proxy aborting the request mid-flight.
+const ASK_USER_TIMEOUT_MS = 11 * 60_000;
+/** POST {cloud}/api/v1/{engine}/ask-user — ask the phone user a structured
+ *  multiple-choice question and BLOCK for their answer. The agent's turn waits
+ *  on this tool result, which is exactly the "stop and ask the user" semantics
+ *  the native AskUserQuestion can't deliver headless. Returns the chosen labels
+ *  as JSON text; a no-answer resolves to a NON-error nudge so the agent proceeds
+ *  instead of retrying. */
+export async function callAskUser(cfg, questions, fetchImpl = fetch, timeoutMs = ASK_USER_TIMEOUT_MS) {
+    const url = `${cfg.cloudUrl}/api/v1/${cfg.engine}/ask-user`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${cfg.busToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ sessionId: cfg.sessionId, questions }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            return {
+                isError: true,
+                text: `ask_user failed (HTTP ${res.status})${body ? `: ${body}` : ""}`,
+            };
+        }
+        const json = (await res.json().catch(() => null));
+        if (json && json.ok === true && json.answers != null) {
+            return { isError: false, text: JSON.stringify(json.answers) };
+        }
+        // Not answered (timeout / dismissed / phone offline). NON-error so the agent
+        // continues with its own judgment instead of treating it as a tool failure.
+        const reason = json && typeof json.error === "string" ? json.error : "no_answer";
+        return {
+            isError: false,
+            text: `The user did not answer (${reason}). Proceed with your best judgment.`,
+        };
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            return {
+                isError: false,
+                text: "The user did not answer (timeout). Proceed with your best judgment.",
+            };
+        }
+        return { isError: true, text: `ask_user error: ${errText(err)}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** GET {cloud}/api/v1/{engine}/device-skills → list of enabled tool names.
+ *  On any failure returns [] (a failed fetch must never block the session). */
+export async function fetchEnabledToolNames(cfg, fetchImpl = fetch) {
+    const url = `${cfg.cloudUrl}/api/v1/${cfg.engine}/device-skills`;
+    try {
+        const res = await fetchImpl(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${cfg.busToken}` },
+        });
+        if (!res.ok) {
+            log(`device-skills GET failed (${res.status})`);
+            return [];
+        }
+        const json = await res.json();
+        return parseEnabledToolNames(json);
+    }
+    catch (err) {
+        log(`device-skills GET error: ${errText(err)}`);
+        return [];
+    }
+}
+/** Pull the enabled device-tool names out of the cloud response. We accept a
+ *  couple of shapes defensively (the cloud may key by tool or by skill). */
+export function parseEnabledToolNames(json) {
+    if (!json || typeof json !== "object")
+        return [];
+    const obj = json;
+    // Preferred: { tools: ["calendar_today", ...] }
+    if (Array.isArray(obj.tools)) {
+        return obj.tools.filter((t) => typeof t === "string");
+    }
+    // Alternate: { enabled: [...] }
+    if (Array.isArray(obj.enabled)) {
+        return obj.enabled.filter((t) => typeof t === "string");
+    }
+    return [];
+}
+/** POST {cloud}/api/v1/{engine}/device-tool — fan the call out to the phone.
+ *  30s timeout; success → result text, timeout/HTTP error → isError text. */
+export async function callDeviceTool(cfg, toolName, params, fetchImpl = fetch, timeoutMs = CALL_TIMEOUT_MS) {
+    const url = `${cfg.cloudUrl}/api/v1/${cfg.engine}/device-tool`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${cfg.busToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                sessionId: cfg.sessionId,
+                toolName,
+                params,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            return {
+                isError: true,
+                text: `device tool '${toolName}' failed (HTTP ${res.status})${body ? `: ${body}` : ""}`,
+            };
+        }
+        const json = await res.json().catch(() => null);
+        return interpretCallResponse(toolName, json);
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            return {
+                isError: true,
+                text: `device tool '${toolName}' timed out after ${timeoutMs / 1000}s (phone offline or not subscribed)`,
+            };
+        }
+        return {
+            isError: true,
+            text: `device tool '${toolName}' error: ${errText(err)}`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Map the cloud's { ok, result } / { ok:false, error } envelope to MCP text. */
+export function interpretCallResponse(toolName, json) {
+    if (!json || typeof json !== "object") {
+        return {
+            isError: true,
+            text: `device tool '${toolName}' returned no result`,
+        };
+    }
+    const obj = json;
+    const ok = obj.ok === true || obj.success === true;
+    if (!ok) {
+        const error = typeof obj.error === "string" && obj.error
+            ? obj.error
+            : "device tool execution failed";
+        return { isError: true, text: error };
+    }
+    const result = obj.result;
+    if (typeof result === "string") {
+        return { isError: false, text: result };
+    }
+    if (result == null) {
+        return { isError: false, text: "(no output)" };
+    }
+    return { isError: false, text: JSON.stringify(result) };
+}
+// --- logging (stderr only) ---------------------------------------------------
+function log(msg) {
+    process.stderr.write(`[pinclaw-device-proxy] ${msg}\n`);
+}
+function errText(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+// --- MCP server --------------------------------------------------------------
+/** Build the MCP server with ListTools / CallTool wired to the cloud. Exported
+ *  for tests (the entrypoint below just builds + connects stdio). */
+export function buildServer(cfg, fetchImpl = fetch) {
+    const server = new Server({ name: "pinclaw-device", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const enabled = await fetchEnabledToolNames(cfg, fetchImpl);
+        const enabledSet = new Set(enabled);
+        const tools = DEVICE_TOOL_CATALOG.filter((t) => enabledSet.has(t.name)).map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+        // ask_user — always available, every session, both engines.
+        tools.push(ASK_USER_TOOL);
+        log(`ListTools → ${tools.length} tools`);
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const args = (request.params.arguments ?? {});
+        log(`CallTool ${toolName}`);
+        // ask_user blocks for a phone answer; everything else is a device tool
+        // fanned out to the phone.
+        const result = toolName === ASK_USER_TOOL_NAME
+            ? await callAskUser(cfg, args.questions, fetchImpl)
+            : await callDeviceTool(cfg, toolName, args, fetchImpl);
+        return {
+            content: [{ type: "text", text: result.text }],
+            isError: result.isError,
+        };
+    });
+    return server;
+}
+async function main() {
+    let cfg;
+    try {
+        cfg = readProxyConfig(process.env);
+    }
+    catch (err) {
+        log(`startup failed: ${errText(err)}`);
+        process.exitCode = 1;
+        return;
+    }
+    log(`starting (engine=${cfg.engine} session=${cfg.sessionId})`);
+    const server = buildServer(cfg);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log("connected on stdio");
+}
+// Entrypoint guard: run only when invoked directly (not when imported in tests).
+const isDirectRun = process.argv[1] !== undefined &&
+    (process.argv[1].endsWith("mcp-device-proxy.js") ||
+        process.argv[1].endsWith("mcp-device-proxy.ts"));
+if (isDirectRun) {
+    main().catch((err) => {
+        log(`fatal: ${errText(err)}`);
+        process.exitCode = 1;
+    });
+}