@nudge-ui/mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createAgentCompanion, type AgentCompanion, type AgentCompanionOptions } from "./server.js";
+export { createLoopbackBridge, type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress, type BridgeClock, type CanvasCommandInput, } from "./bridge.js";
+export { openPairedPage, parseCliArguments, runCli, type CliOptions, type PageLaunchDependencies, } from "./cli.js";
+export * from "./protocol.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createAgentCompanion } from "./server.js";
+export { createLoopbackBridge, } from "./bridge.js";
+export { openPairedPage, parseCliArguments, runCli, } from "./cli.js";
+export * from "./protocol.js";

package/dist/protocol.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Companion-facing aliases and transport envelopes.
+ *
+ * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
+ * transport names discoverable for Node consumers while preserving a single
+ * protocol vocabulary for browser and agent adapters.
+ */
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
+export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, AgentRequestOutcome, AgentRequestStatus, AgentRoute, AgentStatusSnapshot, AgentStatusUpdate, BridgeCanvasCommandEvent, BridgeConnectedEvent, BridgeDisconnectedEvent, BridgeEnvelope, BridgeEvent, BridgeEventType, BridgeStatusEvent, CanvasCommand, CanvasCommandAcknowledgement, CanvasCommandError, CanvasCommandResult, CanvasGroup, CanvasGroupOwner, CanvasState, FitCanvasCommand, FocusCanvasGroupCommand, PairingRequest, PairingResponse, PresentRoutesCommand, PromptDispatchRequest, PromptDispatchResponse, ReadCanvasStateCommand, RemoveCanvasGroupCommand, StatusEventRequest, } from "@nudge-ui/agent-protocol";
+/** Stable endpoint names used by the loopback browser bridge. */
+export declare const BRIDGE_ENDPOINTS: {
+    readonly health: "/health";
+    readonly pair: "/pair";
+    readonly events: "/events";
+    readonly prompt: "/prompt";
+    readonly status: "/status";
+    readonly canvasAcknowledgement: "/canvas/ack";
+    readonly disconnect: "/disconnect";
+};
+export type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
+/** Error body returned by every rejected bridge request. */
+export interface BridgeHttpError {
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}

package/dist/protocol.js

@@ -0,0 +1,18 @@
+/**
+ * Companion-facing aliases and transport envelopes.
+ *
+ * The domain contracts live in `@nudge-ui/agent-protocol`; this module keeps
+ * transport names discoverable for Node consumers while preserving a single
+ * protocol vocabulary for browser and agent adapters.
+ */
+export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, canonicalOrigin, defaultBridgePort, isAgentPromptRequest, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isCanonicalOrigin, isProjectIdentity, isSameOriginRoute, protocolError, validateRoutes, } from "@nudge-ui/agent-protocol";
+/** Stable endpoint names used by the loopback browser bridge. */
+export const BRIDGE_ENDPOINTS = {
+    health: "/health",
+    pair: "/pair",
+    events: "/events",
+    prompt: "/prompt",
+    status: "/status",
+    canvasAcknowledgement: "/canvas/ack",
+    disconnect: "/disconnect",
+};

package/dist/server.d.ts

@@ -0,0 +1,28 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { AgentProjectIdentity } from "@nudge-ui/agent-protocol";
+import { type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress } from "./bridge.js";
+export declare const MCP_SERVER_NAME = "nudge-ui";
+export declare const MCP_SERVER_VERSION = "0.1.0";
+/** Instructions are sent through MCP initialization for every host. */
+export declare const MCP_SERVER_INSTRUCTIONS: string;
+export interface AgentCompanionOptions extends BrowserBridgeOptions {
+    readonly workspaceRoot?: string;
+    readonly serverName?: string;
+    readonly serverVersion?: string;
+}
+export interface AgentCompanionStartResult {
+    readonly address: BridgeAddress;
+}
+export interface AgentCompanion {
+    readonly bridge: BrowserBridge;
+    readonly mcpServer: McpServer;
+    readonly project: AgentProjectIdentity;
+    start(transport?: Transport): Promise<AgentCompanionStartResult>;
+    close(): Promise<void>;
+}
+/**
+ * Creates one project-scoped MCP companion and its loopback browser bridge.
+ * The returned companion is inert until `start` is called.
+ */
+export declare function createAgentCompanion(options: AgentCompanionOptions): AgentCompanion;

package/dist/server.js

@@ -0,0 +1,243 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { validateRoutes } from "@nudge-ui/agent-protocol";
+import { createLoopbackBridge, } from "./bridge.js";
+export const MCP_SERVER_NAME = "nudge-ui";
+export const MCP_SERVER_VERSION = "0.1.0";
+/** Instructions are sent through MCP initialization for every host. */
+export const MCP_SERVER_INSTRUCTIONS = [
+    "Nudge UI is a local browser companion for one project workspace.",
+    "Browser pairing requires the app origin to be configured explicitly with --origin or NUDGE_UI_ORIGIN; an unconfigured bridge accepts no HTTP pairing.",
+    "Call nudge_listen (or nudge_connect) immediately at task start and keep the call open while waiting for a browser request; the bridge may be running before a listener exists.",
+    "After a prompt is delivered, edit the project source using the host's normal approval flow.",
+    "Report completed, failed, or interrupted status with nudge_report_status before listening again.",
+    "Canvas tools operate only on same-origin routes from the paired project.",
+    "No request, prompt, or browser state is persisted by this companion.",
+].join(" ");
+function textResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value) }],
+    };
+}
+function errorResult(error) {
+    const message = error instanceof Error ? error.message : "The Nudge companion could not complete the operation.";
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    };
+}
+function promptResult(request) {
+    return textResult({
+        requestId: request.requestId,
+        projectId: request.projectId,
+        prompt: request.prompt,
+        ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
+    });
+}
+function commandResult(result) {
+    return {
+        ...(result.ok ? {} : { isError: true }),
+        ...textResult(result),
+    };
+}
+function boundedWorkspaceRoot(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.length === 0 || value.length > 4096)
+        throw new TypeError("workspaceRoot must be a bounded non-empty string");
+    return value;
+}
+function installTools(mcpServer, bridge) {
+    const listen = async (_args, extra) => {
+        try {
+            return promptResult(await bridge.waitForPrompt(extra.signal));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    };
+    const listenDescription = "Call this immediately at task start. Wait for one browser prompt. Keep this standard MCP call open, then call nudge_report_status and listen again after the request ends.";
+    const emptyInput = {};
+    mcpServer.registerTool("nudge_listen", {
+        title: "Listen for Nudge requests",
+        description: listenDescription,
+        inputSchema: emptyInput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, listen);
+    mcpServer.registerTool("nudge_connect", {
+        title: "Connect to Nudge",
+        description: "Open the long-lived Nudge browser connection and wait for one prompt.",
+        inputSchema: emptyInput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, listen);
+    mcpServer.registerTool("nudge_get_status", {
+        title: "Get Nudge status",
+        description: "Read the in-memory browser pairing and request status for this project.",
+        inputSchema: emptyInput,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => textResult(bridge.getStatus()));
+    mcpServer.registerTool("nudge_report_status", {
+        title: "Report Nudge request status",
+        description: "Report working, completed, failed, or interrupted status for the prompt currently being handled.",
+        inputSchema: {
+            requestId: z.string().min(1).max(256),
+            status: z.enum(["working", "completed", "failed", "interrupted"]),
+            summary: z.string().max(32_000).optional(),
+            error: z.string().max(32_000).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        const update = {
+            requestId: args.requestId,
+            status: args.status,
+            ...(args.summary === undefined ? {} : { summary: args.summary }),
+            ...(args.error === undefined ? {} : { error: args.error }),
+        };
+        try {
+            bridge.updateRequestStatus(update);
+            return textResult(bridge.getStatus());
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    mcpServer.registerTool("nudge_read_canvas", {
+        title: "Read Canvas state",
+        description: "Read the paired browser's current Canvas groups and focus.",
+        inputSchema: emptyInput,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return commandResult(await bridge.dispatchCanvasCommand({ type: "read-state" }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    mcpServer.registerTool("nudge_present_routes", {
+        title: "Present routes in Canvas",
+        description: "Append or focus an agent-owned, labeled comparison group of same-origin project routes in Canvas.",
+        inputSchema: {
+            label: z.string().min(1).max(160),
+            groupId: z.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/).optional(),
+            routes: z.array(z.object({
+                url: z.string().min(1).max(2048),
+                title: z.string().max(512).optional(),
+                label: z.string().max(160).optional(),
+            }).strict()).min(1).max(64),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (args) => {
+        try {
+            if (!bridge.effectiveOrigin)
+                throw new Error("Canvas routes require a paired or configured browser origin.");
+            const routes = validateRoutes(args.routes, bridge.effectiveOrigin);
+            return commandResult(await bridge.dispatchCanvasCommand({
+                type: "present-routes",
+                groupId: args.groupId ?? `agent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+                label: args.label,
+                routes,
+            }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    mcpServer.registerTool("nudge_focus_canvas_group", {
+        title: "Focus Canvas group",
+        description: "Focus an existing Canvas comparison group by its stable group ID.",
+        inputSchema: { groupId: z.string().min(1).max(256) },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            return commandResult(await bridge.dispatchCanvasCommand({ type: "focus-group", groupId: args.groupId }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    mcpServer.registerTool("nudge_fit_canvas", {
+        title: "Fit Canvas",
+        description: "Fit all current Canvas cards into the browser board.",
+        inputSchema: emptyInput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            return commandResult(await bridge.dispatchCanvasCommand({ type: "fit-all" }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    mcpServer.registerTool("nudge_remove_canvas_group", {
+        title: "Remove agent Canvas group",
+        description: "Remove an agent-owned Canvas comparison group. The browser refuses removal of user-owned groups.",
+        inputSchema: { groupId: z.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            return commandResult(await bridge.dispatchCanvasCommand({ type: "remove-group", groupId: args.groupId }));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}
+/**
+ * Creates one project-scoped MCP companion and its loopback browser bridge.
+ * The returned companion is inert until `start` is called.
+ */
+export function createAgentCompanion(options) {
+    const workspaceRoot = boundedWorkspaceRoot(options.workspaceRoot);
+    const bridge = createLoopbackBridge(options);
+    const mcpServer = new McpServer({
+        name: options.serverName ?? MCP_SERVER_NAME,
+        version: options.serverVersion ?? MCP_SERVER_VERSION,
+    }, { instructions: MCP_SERVER_INSTRUCTIONS });
+    installTools(mcpServer, bridge);
+    const project = {
+        projectId: options.projectId,
+        ...(bridge.origin === null ? {} : { origin: bridge.origin }),
+        ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+    };
+    let startPromise = null;
+    let closePromise = null;
+    let transport = null;
+    const start = (providedTransport) => {
+        if (closePromise)
+            return Promise.reject(new Error("The Nudge companion is closing."));
+        if (startPromise)
+            return startPromise;
+        startPromise = (async () => {
+            const address = await bridge.start();
+            transport = providedTransport ?? new StdioServerTransport();
+            await mcpServer.connect(transport);
+            return { address };
+        })();
+        return startPromise;
+    };
+    const close = () => {
+        if (closePromise)
+            return closePromise;
+        closePromise = (async () => {
+            if (transport) {
+                try {
+                    await mcpServer.close();
+                }
+                catch {
+                    // The SDK may already close a transport after a client disconnect.
+                }
+            }
+            await bridge.close();
+        })();
+        return closePromise;
+    };
+    return {
+        bridge,
+        mcpServer,
+        project,
+        start,
+        close,
+    };
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@nudge-ui/mcp",
+  "version": "0.1.0",
+  "description": "Optional local MCP companion for pairing Nudge UI with coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/charlessmart/nudge-ui.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/charlessmart/nudge-ui/issues"
+  },
+  "homepage": "https://github.com/charlessmart/nudge-ui#readme",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nudge-mcp": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "default": "./dist/protocol.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge.d.ts",
+      "import": "./dist/bridge.js",
+      "default": "./dist/bridge.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs && node scripts/build.mjs",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@nudge-ui/agent-protocol": "workspace:*",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.21.5",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}