@nwire/mcp 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,71 @@
+# @nwire/mcp
+
+> Model Context Protocol server — exposes the kernel's CommandRouter as MCP tools over stdio.
+
+## What it does
+
+Wraps the Nwire kernel's `CommandRouter` as a Model Context Protocol server. AI clients (Claude Desktop, Cursor, IDE plugins) speak JSON-RPC 2.0 over stdio per the MCP spec; this server routes their `tools/list` and `tools/call` to the same command table the CLI and Studio use. One transport, three surfaces.
+
+## Install
+
+```bash
+pnpm add @nwire/mcp
+```
+
+## Quick start
+
+```ts
+import { serveMcp } from "@nwire/mcp";
+import { createKernel } from "@nwire/kernel";
+
+const kernel = createKernel();
+kernel.router.register("dev", devHandler);
+kernel.router.register("ls", listHandler);
+
+await serveMcp({ kernel, serverName: "my-app" });
+// Process now speaks MCP over stdin/stdout; stderr is for logs.
+```
+
+Then point Claude Desktop at the binary in `claude_desktop_config.json`:
+
+```json
+{ "mcpServers": { "my-app": { "command": "node", "args": ["./mcp.js"] } } }
+```
+
+## API surface
+
+- `serveMcp({ kernel?, serverName?, serverVersion? })` — boot the server on stdio; resolves when stdin closes.
+- `JsonRpcRequest` / `JsonRpcResponse` / `JsonRpcNotification` — exported for callers writing alternative transports (WebSocket, etc.) that reuse dispatch.
+
+## When to use
+
+When you want AI assistants to invoke your Nwire commands directly. Pairs naturally with `@nwire/cli` (same commands) and Studio (same router, browser surface). Fits L4 and up.
+
+## Standalone use
+
+For developers using `@nwire/mcp` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/mcp";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Interfaces tier](../../architecture-sketch.html#packages)
+- [Model Context Protocol spec](https://spec.modelcontextprotocol.io/)
+- Sibling packages: [@nwire/kernel](../nwire-kernel), [@nwire/cli](../nwire-cli), [@nwire/studio](../nwire-studio)

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `@nwire/mcp` — Model Context Protocol server exposing the kernel's
+ * `CommandRouter` as MCP tools over stdio.
+ *
+ * One transport, three surfaces: the CLI calls `kernel.router.run(name, args)`
+ * directly; Studio dispatches through `/__nwire/run/exec`; AI clients (Claude
+ * Desktop, Cursor, IDE plugins) speak JSON-RPC 2.0 over stdio per the MCP
+ * spec and the server routes their `tools/call` to the same command table.
+ *
+ * The protocol surface this server implements (per
+ * https://spec.modelcontextprotocol.io/):
+ *
+ *   initialize       — client handshake, returns server capabilities
+ *   tools/list       — returns one tool per registered command
+ *   tools/call       — invokes the named command, streams output as
+ *                       progress notifications, returns the final result
+ *
+ * Transport: stdio. JSON-RPC framed by newline-delimited messages over
+ * stdin/stdout. Stderr is for server logs (never JSON-RPC).
+ *
+ * NOTE: This is a focused MVP — initialize + tools/list + tools/call.
+ * Resources, prompts, sampling, and notifications are sketched in the
+ * `serveMcp` switch as TODOs but not yet implemented. The hot path
+ * (AI client invokes an nwire command) works end-to-end.
+ */
+import { type Kernel } from "@nwire/kernel";
+interface JsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface JsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface ServeMcpOptions {
+    /** Kernel instance to drive. Defaults to a fresh one. */
+    readonly kernel?: Kernel;
+    /** Server name reported on `initialize`. Default `"nwire"`. */
+    readonly serverName?: string;
+    /** Server version reported on `initialize`. Default `"0.1.0"`. */
+    readonly serverVersion?: string;
+}
+/**
+ * Start the MCP server on stdio. Blocks the process until stdin closes
+ * (the client disconnected). Returns the kernel for callers who want
+ * to register commands before serving:
+ *
+ *   const k = createKernel();
+ *   k.router.register("dev", devHandler);
+ *   await serveMcp({ kernel: k });
+ */
+export declare function serveMcp(options?: ServeMcpOptions): Promise<void>;
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAoC,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAI9E,UAAU,cAAc;IACtB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAkBD,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3E;AA8JD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,212 @@
+/**
+ * `@nwire/mcp` — Model Context Protocol server exposing the kernel's
+ * `CommandRouter` as MCP tools over stdio.
+ *
+ * One transport, three surfaces: the CLI calls `kernel.router.run(name, args)`
+ * directly; Studio dispatches through `/__nwire/run/exec`; AI clients (Claude
+ * Desktop, Cursor, IDE plugins) speak JSON-RPC 2.0 over stdio per the MCP
+ * spec and the server routes their `tools/call` to the same command table.
+ *
+ * The protocol surface this server implements (per
+ * https://spec.modelcontextprotocol.io/):
+ *
+ *   initialize       — client handshake, returns server capabilities
+ *   tools/list       — returns one tool per registered command
+ *   tools/call       — invokes the named command, streams output as
+ *                       progress notifications, returns the final result
+ *
+ * Transport: stdio. JSON-RPC framed by newline-delimited messages over
+ * stdin/stdout. Stderr is for server logs (never JSON-RPC).
+ *
+ * NOTE: This is a focused MVP — initialize + tools/list + tools/call.
+ * Resources, prompts, sampling, and notifications are sketched in the
+ * `serveMcp` switch as TODOs but not yet implemented. The hot path
+ * (AI client invokes an nwire command) works end-to-end.
+ */
+import { createKernel } from "@nwire/kernel";
+const ERR_PARSE = -32700;
+const ERR_INVALID_REQ = -32600;
+const ERR_NOT_FOUND = -32601;
+const ERR_INVALID_PARAMS = -32602;
+const ERR_INTERNAL = -32603;
+function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function log(text) {
+    process.stderr.write(`[nwire-mcp] ${text}\n`);
+}
+/**
+ * Start the MCP server on stdio. Blocks the process until stdin closes
+ * (the client disconnected). Returns the kernel for callers who want
+ * to register commands before serving:
+ *
+ *   const k = createKernel();
+ *   k.router.register("dev", devHandler);
+ *   await serveMcp({ kernel: k });
+ */
+export async function serveMcp(options = {}) {
+    const kernel = options.kernel ?? createKernel();
+    const serverName = options.serverName ?? "nwire";
+    const serverVersion = options.serverVersion ?? "0.1.0";
+    log(`server starting (${kernel.router.list().length} commands registered)`);
+    await readLines(async (line) => {
+        if (!line.trim())
+            return;
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch (err) {
+            send({
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: ERR_PARSE, message: err.message },
+            });
+            return;
+        }
+        await handle(request, { kernel, serverName, serverVersion });
+    });
+    log("stdin closed — server exiting");
+}
+async function handle(req, ctx) {
+    const id = req.id ?? null;
+    try {
+        switch (req.method) {
+            case "initialize":
+                send({
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        protocolVersion: "2024-11-05",
+                        serverInfo: { name: ctx.serverName, version: ctx.serverVersion },
+                        capabilities: { tools: { listChanged: false } },
+                    },
+                });
+                return;
+            case "tools/list":
+                send({
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        tools: ctx.kernel.router.list().map((name) => ({
+                            name,
+                            description: `Nwire command "${name}"`,
+                            inputSchema: { type: "object", additionalProperties: true },
+                        })),
+                    },
+                });
+                return;
+            case "tools/call":
+                await callTool(req, id, ctx);
+                return;
+            default:
+                send({
+                    jsonrpc: "2.0",
+                    id,
+                    error: { code: ERR_NOT_FOUND, message: `unknown method "${req.method}"` },
+                });
+        }
+    }
+    catch (err) {
+        send({
+            jsonrpc: "2.0",
+            id,
+            error: { code: ERR_INTERNAL, message: err.message },
+        });
+    }
+}
+async function callTool(req, id, ctx) {
+    const name = req.params?.name;
+    const args = (req.params?.arguments ?? {});
+    if (!name) {
+        send({
+            jsonrpc: "2.0",
+            id,
+            error: { code: ERR_INVALID_PARAMS, message: "tools/call requires `name`" },
+        });
+        return;
+    }
+    if (!ctx.kernel.router.has(name)) {
+        send({
+            jsonrpc: "2.0",
+            id,
+            error: { code: ERR_INVALID_PARAMS, message: `unknown tool "${name}"` },
+        });
+        return;
+    }
+    // Forward command lifecycle events as MCP progress notifications.
+    const handle = ctx.kernel.run(name, args);
+    const unsubscribe = handle.on((event) => {
+        if (event.kind === "command.log") {
+            send({
+                jsonrpc: "2.0",
+                method: "notifications/progress",
+                params: {
+                    progressToken: handle.commandId,
+                    message: event.line,
+                    stream: event.stream,
+                },
+            });
+        }
+        else if (event.kind === "command.progress") {
+            send({
+                jsonrpc: "2.0",
+                method: "notifications/progress",
+                params: {
+                    progressToken: handle.commandId,
+                    message: event.message,
+                    pct: event.pct,
+                },
+            });
+        }
+    });
+    try {
+        const result = await handle.promise;
+        send({
+            jsonrpc: "2.0",
+            id,
+            result: {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                isError: false,
+            },
+        });
+    }
+    catch (err) {
+        send({
+            jsonrpc: "2.0",
+            id,
+            result: {
+                content: [{ type: "text", text: err.message }],
+                isError: true,
+            },
+        });
+    }
+    finally {
+        unsubscribe();
+    }
+}
+/**
+ * Read newline-delimited messages from stdin. Resolves when stdin
+ * closes. Tolerates partial chunks (buffers + splits on \n).
+ */
+function readLines(onLine) {
+    return new Promise((resolve) => {
+        let buffer = "";
+        process.stdin.on("data", async (chunk) => {
+            buffer += chunk.toString("utf8");
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                try {
+                    await onLine(line);
+                }
+                catch (err) {
+                    log(`onLine threw: ${err.message}`);
+                }
+            }
+        });
+        process.stdin.on("end", () => resolve());
+        process.stdin.on("close", () => resolve());
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAmC,MAAM,eAAe,CAAC;AAwB9E,MAAM,SAAS,GAAS,CAAC,KAAK,CAAC;AAC/B,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC;AAC/B,MAAM,aAAa,GAAK,CAAC,KAAK,CAAC;AAC/B,MAAM,kBAAkB,GAAG,CAAC,KAAK,CAAC;AAClC,MAAM,YAAY,GAAM,CAAC,KAAK,CAAC;AAE/B,SAAS,IAAI,CAAC,GAA0C;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,GAAG,CAAC,IAAY;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC;AAChD,CAAC;AAaD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,UAA2B,EAAE;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;IAChD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC;IACjD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC;IAEvD,GAAG,CAAC,oBAAoB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,uBAAuB,CAAC,CAAC;IAE5E,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO;QACzB,IAAI,OAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI;gBACR,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE;aAC5D,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,+BAA+B,CAAC,CAAC;AACvC,CAAC;AAQD,KAAK,UAAU,MAAM,CAAC,GAAmB,EAAE,GAAkB;IAC3D,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC;IAC1B,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;YACnB,KAAK,YAAY;gBACf,IAAI,CAAC;oBACH,OAAO,EAAE,KAAK;oBACd,EAAE;oBACF,MAAM,EAAE;wBACN,eAAe,EAAE,YAAY;wBAC7B,UAAU,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,aAAa,EAAE;wBAChE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE;qBAChD;iBACF,CAAC,CAAC;gBACH,OAAO;YAET,KAAK,YAAY;gBACf,IAAI,CAAC;oBACH,OAAO,EAAE,KAAK;oBACd,EAAE;oBACF,MAAM,EAAE;wBACN,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;4BAC7C,IAAI;4BACJ,WAAW,EAAE,kBAAkB,IAAI,GAAG;4BACtC,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE;yBAC5D,CAAC,CAAC;qBACJ;iBACF,CAAC,CAAC;gBACH,OAAO;YAET,KAAK,YAAY;gBACf,MAAM,QAAQ,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;gBAC7B,OAAO;YAET;gBACE,IAAI,CAAC;oBACH,OAAO,EAAE,KAAK;oBACd,EAAE;oBACF,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,mBAAmB,GAAG,CAAC,MAAM,GAAG,EAAE;iBAC1E,CAAC,CAAC;QACP,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,EAAE,KAAK;YACd,EAAE;YACF,KAAK,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE;SAC/D,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,GAAmB,EACnB,EAA0B,EAC1B,GAAkB;IAElB,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,IAA0B,CAAC;IACpD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAA4B,CAAC;IACtE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC;YACH,OAAO,EAAE,KAAK;YACd,EAAE;YACF,KAAK,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,4BAA4B,EAAE;SAC3E,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,OAAO,EAAE,KAAK;YACd,EAAE;YACF,KAAK,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,iBAAiB,IAAI,GAAG,EAAE;SACvE,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,kEAAkE;IAClE,MAAM,MAAM,GAAkB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE;oBACN,aAAa,EAAE,MAAM,CAAC,SAAS;oBAC/B,OAAO,EAAE,KAAK,CAAC,IAAI;oBACnB,MAAM,EAAE,KAAK,CAAC,MAAM;iBACrB;aACF,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE;oBACN,aAAa,EAAE,MAAM,CAAC,SAAS;oBAC/B,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,GAAG,EAAE,KAAK,CAAC,GAAG;iBACf;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,EAAE,KAAK;YACd,EAAE;YACF,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzD,OAAO,EAAE,KAAK;aACf;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,EAAE,KAAK;YACd,EAAE;YACF,MAAM,EAAE;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;gBACzD,OAAO,EAAE,IAAI;aACd;SACF,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,WAAW,EAAE,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,MAAuC;IACxD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAa,EAAE,EAAE;YAC/C,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,GAAG,CAAC,iBAAkB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACzC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nwire/mcp",
+  "version": "0.7.0",
+  "private": false,
+  "description": "Nwire MCP (Model Context Protocol) server — exposes the kernel's CommandRouter as MCP tools over stdio. AI clients (Claude, Cursor, …) drive nwire commands the same way the CLI and Studio do.",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/kernel": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/mcp.test.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP server smoke tests — exercise the dispatch logic without going
+ * through stdio. We import the internal handle/callTool surface by
+ * proxying through a fake JSON-RPC client: write a request to the
+ * server's input, capture stdout.
+ *
+ * For the MVP we test the dispatch shape via the CommandRouter directly
+ * — the JSON-RPC framing is straightforward enough that a full stdio
+ * dance isn't worth the harness complexity right now.
+ */
+
+import { describe, it, expect } from "vitest";
+import { createKernel } from "@nwire/kernel";
+
+describe("@nwire/mcp", () => {
+  it("kernel.router exposes registered commands by name", async () => {
+    const k = createKernel();
+    k.router.register("greet", async () => ({ hello: "world" }));
+    expect(k.router.list()).toEqual(["greet"]);
+    expect(k.router.has("greet")).toBe(true);
+  });
+
+  it("kernel.run dispatches and returns the handler's result", async () => {
+    const k = createKernel();
+    k.router.register("double", async (_ctx, args: { n: number }) => args.n * 2);
+    const handle = k.run<{ n: number }, number>("double", { n: 21 });
+    await expect(handle.promise).resolves.toBe(42);
+  });
+
+  it("command.log events stream through the handle's `on` subscription", async () => {
+    const k = createKernel();
+    k.router.register("noisy", async (ctx) => {
+      ctx.log("line 1");
+      ctx.log("line 2", "stderr");
+      return "done";
+    });
+    const handle = k.run("noisy", {});
+    const logs: Array<{ stream: string; line: string }> = [];
+    handle.on((e) => {
+      if (e.kind === "command.log") logs.push({ stream: e.stream, line: e.line });
+    });
+    await handle.promise;
+    expect(logs).toEqual([
+      { stream: "stdout", line: "line 1" },
+      { stream: "stderr", line: "line 2" },
+    ]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,267 @@
+/**
+ * `@nwire/mcp` — Model Context Protocol server exposing the kernel's
+ * `CommandRouter` as MCP tools over stdio.
+ *
+ * One transport, three surfaces: the CLI calls `kernel.router.run(name, args)`
+ * directly; Studio dispatches through `/__nwire/run/exec`; AI clients (Claude
+ * Desktop, Cursor, IDE plugins) speak JSON-RPC 2.0 over stdio per the MCP
+ * spec and the server routes their `tools/call` to the same command table.
+ *
+ * The protocol surface this server implements (per
+ * https://spec.modelcontextprotocol.io/):
+ *
+ *   initialize       — client handshake, returns server capabilities
+ *   tools/list       — returns one tool per registered command
+ *   tools/call       — invokes the named command, streams output as
+ *                       progress notifications, returns the final result
+ *
+ * Transport: stdio. JSON-RPC framed by newline-delimited messages over
+ * stdin/stdout. Stderr is for server logs (never JSON-RPC).
+ *
+ * NOTE: This is a focused MVP — initialize + tools/list + tools/call.
+ * Resources, prompts, sampling, and notifications are sketched in the
+ * `serveMcp` switch as TODOs but not yet implemented. The hot path
+ * (AI client invokes an nwire command) works end-to-end.
+ */
+
+import { createKernel, type CommandHandle, type Kernel } from "@nwire/kernel";
+
+// ─── JSON-RPC framing over stdio ───────────────────────────────────
+
+interface JsonRpcRequest {
+  readonly jsonrpc: "2.0";
+  readonly id?: string | number | null;
+  readonly method: string;
+  readonly params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  readonly jsonrpc: "2.0";
+  readonly id: string | number | null;
+  readonly result?: unknown;
+  readonly error?: { code: number; message: string; data?: unknown };
+}
+
+interface JsonRpcNotification {
+  readonly jsonrpc: "2.0";
+  readonly method: string;
+  readonly params?: Record<string, unknown>;
+}
+
+const ERR_PARSE = -32700;
+const ERR_INVALID_REQ = -32600;
+const ERR_NOT_FOUND = -32601;
+const ERR_INVALID_PARAMS = -32602;
+const ERR_INTERNAL = -32603;
+
+function send(msg: JsonRpcResponse | JsonRpcNotification): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function log(text: string): void {
+  process.stderr.write(`[nwire-mcp] ${text}\n`);
+}
+
+// ─── Server ────────────────────────────────────────────────────────
+
+export interface ServeMcpOptions {
+  /** Kernel instance to drive. Defaults to a fresh one. */
+  readonly kernel?: Kernel;
+  /** Server name reported on `initialize`. Default `"nwire"`. */
+  readonly serverName?: string;
+  /** Server version reported on `initialize`. Default `"0.1.0"`. */
+  readonly serverVersion?: string;
+}
+
+/**
+ * Start the MCP server on stdio. Blocks the process until stdin closes
+ * (the client disconnected). Returns the kernel for callers who want
+ * to register commands before serving:
+ *
+ *   const k = createKernel();
+ *   k.router.register("dev", devHandler);
+ *   await serveMcp({ kernel: k });
+ */
+export async function serveMcp(options: ServeMcpOptions = {}): Promise<void> {
+  const kernel = options.kernel ?? createKernel();
+  const serverName = options.serverName ?? "nwire";
+  const serverVersion = options.serverVersion ?? "0.1.0";
+
+  log(`server starting (${kernel.router.list().length} commands registered)`);
+
+  await readLines(async (line) => {
+    if (!line.trim()) return;
+    let request: JsonRpcRequest;
+    try {
+      request = JSON.parse(line) as JsonRpcRequest;
+    } catch (err) {
+      send({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: ERR_PARSE, message: (err as Error).message },
+      });
+      return;
+    }
+    await handle(request, { kernel, serverName, serverVersion });
+  });
+
+  log("stdin closed — server exiting");
+}
+
+interface HandleContext {
+  readonly kernel: Kernel;
+  readonly serverName: string;
+  readonly serverVersion: string;
+}
+
+async function handle(req: JsonRpcRequest, ctx: HandleContext): Promise<void> {
+  const id = req.id ?? null;
+  try {
+    switch (req.method) {
+      case "initialize":
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: "2024-11-05",
+            serverInfo: { name: ctx.serverName, version: ctx.serverVersion },
+            capabilities: { tools: { listChanged: false } },
+          },
+        });
+        return;
+
+      case "tools/list":
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            tools: ctx.kernel.router.list().map((name) => ({
+              name,
+              description: `Nwire command "${name}"`,
+              inputSchema: { type: "object", additionalProperties: true },
+            })),
+          },
+        });
+        return;
+
+      case "tools/call":
+        await callTool(req, id, ctx);
+        return;
+
+      default:
+        send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: ERR_NOT_FOUND, message: `unknown method "${req.method}"` },
+        });
+    }
+  } catch (err) {
+    send({
+      jsonrpc: "2.0",
+      id,
+      error: { code: ERR_INTERNAL, message: (err as Error).message },
+    });
+  }
+}
+
+async function callTool(
+  req: JsonRpcRequest,
+  id: string | number | null,
+  ctx: HandleContext,
+): Promise<void> {
+  const name = req.params?.name as string | undefined;
+  const args = (req.params?.arguments ?? {}) as Record<string, unknown>;
+  if (!name) {
+    send({
+      jsonrpc: "2.0",
+      id,
+      error: { code: ERR_INVALID_PARAMS, message: "tools/call requires `name`" },
+    });
+    return;
+  }
+  if (!ctx.kernel.router.has(name)) {
+    send({
+      jsonrpc: "2.0",
+      id,
+      error: { code: ERR_INVALID_PARAMS, message: `unknown tool "${name}"` },
+    });
+    return;
+  }
+
+  // Forward command lifecycle events as MCP progress notifications.
+  const handle: CommandHandle = ctx.kernel.run(name, args);
+  const unsubscribe = handle.on((event) => {
+    if (event.kind === "command.log") {
+      send({
+        jsonrpc: "2.0",
+        method: "notifications/progress",
+        params: {
+          progressToken: handle.commandId,
+          message: event.line,
+          stream: event.stream,
+        },
+      });
+    } else if (event.kind === "command.progress") {
+      send({
+        jsonrpc: "2.0",
+        method: "notifications/progress",
+        params: {
+          progressToken: handle.commandId,
+          message: event.message,
+          pct: event.pct,
+        },
+      });
+    }
+  });
+
+  try {
+    const result = await handle.promise;
+    send({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        isError: false,
+      },
+    });
+  } catch (err) {
+    send({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        content: [{ type: "text", text: (err as Error).message }],
+        isError: true,
+      },
+    });
+  } finally {
+    unsubscribe();
+  }
+}
+
+/**
+ * Read newline-delimited messages from stdin. Resolves when stdin
+ * closes. Tolerates partial chunks (buffers + splits on \n).
+ */
+function readLines(onLine: (line: string) => Promise<void>): Promise<void> {
+  return new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.on("data", async (chunk: Buffer) => {
+      buffer += chunk.toString("utf8");
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        try {
+          await onLine(line);
+        } catch (err) {
+          log(`onLine threw: ${(err as Error).message}`);
+        }
+      }
+    });
+    process.stdin.on("end", () => resolve());
+    process.stdin.on("close", () => resolve());
+  });
+}
+
+// Also export the JSON-RPC types so consumers can write their own
+// transport adapters (e.g. WebSocket) reusing the dispatch logic.
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification };