@nwire/mcp 0.9.1 → 0.10.0

package/README.md

@@ -1,36 +1,65 @@
 # @nwire/mcp
 
-> Model Context Protocol server — exposes the kernel's CommandRouter + read-only inspect tools + mutating write tools as MCP tools over stdio.
+> Model Context Protocol — Nwire wires as MCP tools.
 
-Wraps the Nwire kernel 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 `tools/list` and `tools/call` to:
+```bash
+pnpm add @nwire/mcp @nwire/app @nwire/endpoint @nwire/wires
+```
 
-1. **Kernel CommandRouter** — same commands the CLI and Studio drive.
-2. **Inspect tools** — read-only introspection over `/__nwire/*` (falls back to `.nwire/` cache).
-3. **Write tools** — mutating actions that POST to `/__nwire/*` on a live wire.
+## As an adopter
 
-One transport, three surfaces (CLI, Studio, MCP).
+The 0.10 adopter consumes wires whose `binding.$adapter === "mcp"` and
+exposes them as MCP tools — same wire, same handler, served alongside
+HTTP and queue under one endpoint:
 
-```bash
-pnpm add @nwire/mcp
+```ts
+import { createApp } from "@nwire/app";
+import { endpoint } from "@nwire/endpoint";
+import { tool } from "@nwire/wires/mcp";
+import { httpKoa } from "@nwire/koa";
+import { mcpAdapter } from "@nwire/mcp";
+import { z } from "zod";
+
+const app = createApp({ appName: "tasks" });
+
+app.wire(
+  tool("create-task", {
+    description: "Create a task",
+    input: z.object({ title: z.string() }),
+  }),
+  async (input) => ({ id: createId(), title: input.title }),
+);
+
+const mcp = mcpAdapter();
+await endpoint("tasks", { port: 3000 })
+  .use(httpKoa({ prefix: "/api" }))
+  .use(mcp)
+  .mount(app)
+  .run();
+
+// In-process introspection — no stdio server required:
+mcp.list();                                  // [{ name, description, inputSchema }]
+await mcp.call("create-task", { title: "x" });
 ```
 
-## Quick example
+## Stdio server (legacy serveMcp)
+
+The original `serveMcp()` entry — JSON-RPC 2.0 over stdin/stdout, suitable
+for direct Claude Desktop / Cursor / IDE plugin integration — stays
+available:
 
 ```ts
 import { serveMcp } from "@nwire/mcp";
-import { createKernel } from "@nwire/kernel";
+import { createKernel } from "./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.
+// Process speaks MCP over stdin/stdout; stderr is for logs.
 ```
 
-Then point Claude Desktop at the binary in `claude_desktop_config.json`:
+Claude Desktop config:
 
 ```json
 { "mcpServers": { "my-app": { "command": "node", "args": ["./mcp.js"] } } }
@@ -38,52 +67,14 @@ Then point Claude Desktop at the binary in `claude_desktop_config.json`:
 
 ## Surface
 
-| Export                                                                | Role                                                                         |
-| --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `serveMcp({ kernel?, serverName?, serverVersion?, stdin?, stdout? })` | Boot the server on stdio; resolves when stdin closes.                        |
-| `JsonRpcRequest` / `JsonRpcResponse` / `JsonRpcNotification`          | JSON-RPC types for callers writing alternative transports (WebSocket, etc.). |
-
-### Built-in tools
-
-Beyond the kernel's CommandRouter, the server exposes these tools:
-
-**Inspect (read-only)** — proxy `/__nwire/*` on a running wire, fall back to `.nwire/*.json` on disk:
-
-| Tool               | Reads                            |
-| ------------------ | -------------------------------- |
-| `manifest`         | `.nwire/manifest.json`           |
-| `list_actions`     | `.nwire/actions.json`            |
-| `list_events`      | `.nwire/events.json`             |
-| `list_hooks`       | `.nwire/hooks.json`              |
-| `list_plugins`     | `.nwire/plugins.json`            |
-| `recent_events`    | Live `/__nwire/events/recent`    |
-| `recent_telemetry` | Live `/__nwire/telemetry/recent` |
-
-**Write (mutating)** — POST to a live wire:
-
-| Tool              | Posts to                                                 |
-| ----------------- | -------------------------------------------------------- |
-| `dispatch_action` | `/__nwire/dispatch` — fire any registered action.        |
-| `run_command`     | `/__nwire/commands/run` — invoke a `defineCommand`.      |
-| `replay_trace`    | `/__nwire/replay` — replay a recording against the wire. |
-
-Write tools gracefully gap-flag when the target endpoint isn't mounted
-(e.g., MCP running standalone with no wire up).
-
-### Progress notifications
-
-For kernel router commands, the server forwards `command.log` and
-`command.progress` events as MCP `notifications/progress` so the AI
-client streams output as the command runs. Inspect + write tools are
-synchronous and don't notify.
+- `mcpAdapter(config?)` — 0.10 adopter
+- `serveMcp(options)` — stdio JSON-RPC server (legacy)
+- `inspectTools`, `findInspectTool` — read-only introspection tools
+- `writeTools`, `findWriteTool` — mutating tools that drive `/__nwire/*`
 
 ## Related
 
-- `@nwire/kernel` — supplies the `CommandRouter` + `CommandHandle` lifecycle.
-- `@nwire/cli` — same kernel router exposed as a terminal CLI.
-- `@nwire/studio` — same `/__nwire/*` middleware that write/inspect tools target.
-- `@nwire/scan` — produces the `.nwire/*.json` files inspect tools fall back to.
-
-## Status
-
-v0.x — `initialize`, `tools/list`, `tools/call` work end-to-end. Resources, prompts, and sampling are sketched but not implemented yet.
+- [`@nwire/wires`](../core-wires) — `tool()` binding helper
+- [`@nwire/endpoint`](../core-endpoint) — adopter lifecycle host
+- [`examples/multi-transport`](../../examples/multi-transport) — MCP alongside
+  HTTP + queue

package/dist/index.d.ts

@@ -23,7 +23,7 @@
  * `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";
+import { type Kernel } from "./internal/index.js";
 interface JsonRpcRequest {
     readonly jsonrpc: "2.0";
     readonly id?: string | number | null;
@@ -79,4 +79,4 @@ export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification };
 export { inspectTools, findInspectTool, resetInspectDiscoveryCache } from "./inspect.js";
 export type { InspectToolDef } from "./inspect.js";
 export { writeTools, findWriteTool } from "./write-tools.js";
-//# sourceMappingURL=index.d.ts.map
+export { mcpAdapter, type McpAdapter, type McpAdapterConfig, type McpToolDescriptor } from "./mcp-adapter.js";

package/dist/index.js

@@ -23,7 +23,7 @@
  * `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";
+import { createKernel } from "./internal/index.js";
 import { inspectTools, findInspectTool } from "./inspect.js";
 import { writeTools, findWriteTool } from "./write-tools.js";
 const ERR_PARSE = -32700;
@@ -72,6 +72,15 @@ export async function serveMcp(options = {}) {
     log("stdin closed — server exiting");
 }
 async function handle(req, ctx) {
+    // JSON-RPC 2.0: a request with no `id` is a notification. Per the spec
+    // we must not respond to it. The MCP lifecycle uses
+    // `notifications/initialized` (and other `notifications/*` methods)
+    // for client-driven signals — these are silently accepted, never
+    // answered. Strict MCP clients hang otherwise.
+    const isNotification = req.id === undefined || req.method.startsWith("notifications/");
+    if (isNotification) {
+        return;
+    }
     const id = req.id ?? null;
     try {
         switch (req.method) {
@@ -263,4 +272,5 @@ function readLines(stream, onLine) {
 }
 export { inspectTools, findInspectTool, resetInspectDiscoveryCache } from "./inspect.js";
 export { writeTools, findWriteTool } from "./write-tools.js";
-//# sourceMappingURL=index.js.map
+// 0.10 adopter shape — consumed by endpoint().use(mcpAdapter()).mount(app).
+export { mcpAdapter } from "./mcp-adapter.js";

package/dist/inspect.d.ts

@@ -37,4 +37,3 @@ export interface InspectToolDef {
 }
 export declare const inspectTools: readonly InspectToolDef[];
 export declare function findInspectTool(name: string): InspectToolDef | undefined;
-//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -291,4 +291,3 @@ export const inspectTools = [
 export function findInspectTool(name) {
     return inspectTools.find((t) => t.name === name);
 }
-//# sourceMappingURL=inspect.js.map

package/dist/internal/command-router.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CommandRouter — one dispatch table for every named kernel command.
+ *
+ * The CLI registers handlers ("dev", "test", "build", ...). The CLI, Studio,
+ * and MCP all *invoke* them via `kernel.run(name, args)`. Every handler
+ * receives a CommandContext with helpers that publish through the same
+ * EventBus, so the live UI feels identical regardless of which surface
+ * fired the command.
+ */
+import type { EventBus, KernelEvent } from "./event-bus.js";
+export interface CommandContext {
+    readonly commandId: string;
+    readonly bus: EventBus;
+    readonly signal: AbortSignal;
+    log(line: string, stream?: "stdout" | "stderr"): void;
+    progress(message: string, pct?: number): void;
+}
+export type CommandHandler<TArgs = unknown, TResult = unknown> = (ctx: CommandContext, args: TArgs) => Promise<TResult>;
+export interface CommandHandle<TResult = unknown> {
+    readonly commandId: string;
+    readonly name: string;
+    readonly promise: Promise<TResult>;
+    abort(reason?: string): void;
+    on(handler: (event: KernelEvent) => void): () => void;
+}
+/**
+ * Holds the named-handler table + creates handles when commands run.
+ * Pure routing — execution is the handler's job; this class only wires up
+ * the context, lifecycle events, and abort plumbing.
+ */
+export declare class CommandRouter {
+    private readonly bus;
+    private readonly handlers;
+    constructor(bus: EventBus);
+    register<TArgs, TResult>(name: string, handler: CommandHandler<TArgs, TResult>): void;
+    has(name: string): boolean;
+    list(): string[];
+    run<TArgs = unknown, TResult = unknown>(name: string, args: TArgs): CommandHandle<TResult>;
+}

package/dist/internal/command-router.js

@@ -0,0 +1,112 @@
+/**
+ * CommandRouter — one dispatch table for every named kernel command.
+ *
+ * The CLI registers handlers ("dev", "test", "build", ...). The CLI, Studio,
+ * and MCP all *invoke* them via `kernel.run(name, args)`. Every handler
+ * receives a CommandContext with helpers that publish through the same
+ * EventBus, so the live UI feels identical regardless of which surface
+ * fired the command.
+ */
+import { randomUUID } from "node:crypto";
+/**
+ * Holds the named-handler table + creates handles when commands run.
+ * Pure routing — execution is the handler's job; this class only wires up
+ * the context, lifecycle events, and abort plumbing.
+ */
+export class CommandRouter {
+    bus;
+    handlers = new Map();
+    constructor(bus) {
+        this.bus = bus;
+    }
+    register(name, handler) {
+        if (this.handlers.has(name)) {
+            throw new Error(`command "${name}" is already registered`);
+        }
+        this.handlers.set(name, handler);
+    }
+    has(name) {
+        return this.handlers.has(name);
+    }
+    list() {
+        return [...this.handlers.keys()].sort();
+    }
+    run(name, args) {
+        const handler = this.handlers.get(name);
+        if (!handler) {
+            throw new Error(`unknown command "${name}"`);
+        }
+        const commandId = randomUUID();
+        const controller = new AbortController();
+        const startedAt = Date.now();
+        const ctx = {
+            commandId,
+            bus: this.bus,
+            signal: controller.signal,
+            log: (line, stream = "stdout") => {
+                this.bus.emit({
+                    kind: "command.log",
+                    commandId,
+                    stream,
+                    line,
+                    at: new Date().toISOString(),
+                });
+            },
+            progress: (message, pct) => {
+                this.bus.emit({
+                    kind: "command.progress",
+                    commandId,
+                    message,
+                    pct,
+                    at: new Date().toISOString(),
+                });
+            },
+        };
+        this.bus.emit({
+            kind: "command.started",
+            commandId,
+            name,
+            args,
+            at: new Date(startedAt).toISOString(),
+        });
+        // Defer the handler so subscribers can attach via `handle.on(...)`
+        // before any `ctx.log` / `ctx.progress` fires. Without this, every
+        // sync log call inside the handler races the caller's subscription.
+        const promise = Promise.resolve()
+            .then(() => handler(ctx, args))
+            .then((result) => {
+            this.bus.emit({
+                kind: "command.done",
+                commandId,
+                result,
+                durationMs: Date.now() - startedAt,
+                at: new Date().toISOString(),
+            });
+            return result;
+        })
+            .catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            this.bus.emit({
+                kind: "command.error",
+                commandId,
+                message,
+                durationMs: Date.now() - startedAt,
+                at: new Date().toISOString(),
+            });
+            throw err;
+        });
+        return {
+            commandId,
+            name,
+            promise,
+            abort: (reason) => controller.abort(reason),
+            on: (handler) => {
+                return this.bus.onAny((event) => {
+                    if ("commandId" in event && event.commandId === commandId) {
+                        handler(event);
+                    }
+                });
+            },
+        };
+    }
+}

package/dist/internal/event-bus.d.ts

@@ -0,0 +1,72 @@
+/**
+ * EventBus — typed pub/sub for kernel-level events.
+ *
+ * Every command and every supervised process emits events here. The CLI
+ * renders them in ink, Studio mirrors them over SSE, MCP forwards them to
+ * the model. One emitter, many subscribers — that's the whole point.
+ */
+import type { LogLine } from "@nwire/supervisor";
+export type KernelEvent = {
+    kind: "command.started";
+    commandId: string;
+    name: string;
+    args: unknown;
+    at: string;
+} | {
+    kind: "command.log";
+    commandId: string;
+    stream: "stdout" | "stderr";
+    line: string;
+    at: string;
+} | {
+    kind: "command.progress";
+    commandId: string;
+    message: string;
+    pct?: number;
+    at: string;
+} | {
+    kind: "command.done";
+    commandId: string;
+    result: unknown;
+    durationMs: number;
+    at: string;
+} | {
+    kind: "command.error";
+    commandId: string;
+    message: string;
+    durationMs: number;
+    at: string;
+} | {
+    kind: "process.started";
+    processId: string;
+    topology: string;
+    port?: number;
+    at: string;
+} | {
+    kind: "process.log";
+    processId: string;
+    line: LogLine;
+} | {
+    kind: "process.exited";
+    processId: string;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    at: string;
+};
+export type KernelEventKind = KernelEvent["kind"];
+type EventByKind<K extends KernelEventKind> = Extract<KernelEvent, {
+    kind: K;
+}>;
+/**
+ * Tiny in-process bus. EventEmitter under the hood; the typed wrappers
+ * are the only public surface so consumers can't subscribe to unknown
+ * event names.
+ */
+export declare class EventBus {
+    private readonly emitter;
+    constructor();
+    emit(event: KernelEvent): void;
+    on<K extends KernelEventKind>(kind: K, handler: (event: EventByKind<K>) => void): () => void;
+    onAny(handler: (event: KernelEvent) => void): () => void;
+}
+export {};

package/dist/internal/event-bus.js

@@ -0,0 +1,34 @@
+/**
+ * EventBus — typed pub/sub for kernel-level events.
+ *
+ * Every command and every supervised process emits events here. The CLI
+ * renders them in ink, Studio mirrors them over SSE, MCP forwards them to
+ * the model. One emitter, many subscribers — that's the whole point.
+ */
+import { EventEmitter } from "node:events";
+const WILDCARD = "__any__";
+/**
+ * Tiny in-process bus. EventEmitter under the hood; the typed wrappers
+ * are the only public surface so consumers can't subscribe to unknown
+ * event names.
+ */
+export class EventBus {
+    emitter = new EventEmitter();
+    constructor() {
+        // Plenty of headroom — Studio + ink + MCP can each add several listeners.
+        this.emitter.setMaxListeners(100);
+    }
+    emit(event) {
+        this.emitter.emit(event.kind, event);
+        this.emitter.emit(WILDCARD, event);
+    }
+    on(kind, handler) {
+        const listener = handler;
+        this.emitter.on(kind, listener);
+        return () => this.emitter.off(kind, listener);
+    }
+    onAny(handler) {
+        this.emitter.on(WILDCARD, handler);
+        return () => this.emitter.off(WILDCARD, handler);
+    }
+}

package/dist/internal/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal command-routing substrate for the MCP server.
+ *
+ * Was `@nwire/app` in 0.9.x — moved in-tree as the kernel package was
+ * repurposed for the runtime substrate. MCP keeps its own dispatch table
+ * + event bus until the MCP server itself becomes a wire adapter.
+ */
+export { createKernel, type Kernel } from "./kernel.js";
+export { CommandRouter, type CommandHandler, type CommandContext, type CommandHandle, } from "./command-router.js";
+export { EventBus, type KernelEvent, type KernelEventKind } from "./event-bus.js";

package/dist/internal/index.js

@@ -0,0 +1,10 @@
+/**
+ * Internal command-routing substrate for the MCP server.
+ *
+ * Was `@nwire/app` in 0.9.x — moved in-tree as the kernel package was
+ * repurposed for the runtime substrate. MCP keeps its own dispatch table
+ * + event bus until the MCP server itself becomes a wire adapter.
+ */
+export { createKernel } from "./kernel.js";
+export { CommandRouter, } from "./command-router.js";
+export { EventBus } from "./event-bus.js";

package/dist/internal/kernel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Kernel — composes the three primitives into the one object the CLI,
+ * Studio, and MCP all hold.
+ *
+ *   const kernel = createKernel();
+ *   kernel.router.register("dev", devHandler);
+ *   kernel.run("dev", { wire: "main" });   // delegates to router
+ *   kernel.bus.on("command.log", ...);     // anyone can listen
+ *   kernel.supervisor.start(...);          // long-lived processes
+ *
+ * That's the whole surface. New commands plug into the router; new live
+ * surfaces plug into the bus; new long-running processes plug into the
+ * supervisor.
+ */
+import { RunnerSupervisor } from "@nwire/supervisor";
+import { CommandRouter, type CommandHandle } from "./command-router.js";
+import { EventBus } from "./event-bus.js";
+export interface Kernel {
+    readonly bus: EventBus;
+    readonly router: CommandRouter;
+    readonly supervisor: RunnerSupervisor;
+    run<TArgs = unknown, TResult = unknown>(name: string, args: TArgs): CommandHandle<TResult>;
+}
+export declare function createKernel(): Kernel;

package/dist/internal/kernel.js

@@ -0,0 +1,53 @@
+/**
+ * Kernel — composes the three primitives into the one object the CLI,
+ * Studio, and MCP all hold.
+ *
+ *   const kernel = createKernel();
+ *   kernel.router.register("dev", devHandler);
+ *   kernel.run("dev", { wire: "main" });   // delegates to router
+ *   kernel.bus.on("command.log", ...);     // anyone can listen
+ *   kernel.supervisor.start(...);          // long-lived processes
+ *
+ * That's the whole surface. New commands plug into the router; new live
+ * surfaces plug into the bus; new long-running processes plug into the
+ * supervisor.
+ */
+import { RunnerSupervisor } from "@nwire/supervisor";
+import { CommandRouter } from "./command-router.js";
+import { EventBus } from "./event-bus.js";
+export function createKernel() {
+    const bus = new EventBus();
+    const router = new CommandRouter(bus);
+    const supervisor = new RunnerSupervisor();
+    // Re-publish supervisor events on the kernel bus so a single subscriber
+    // sees the whole picture without listening on two emitters.
+    supervisor.on("log", (processId, line) => {
+        bus.emit({ kind: "process.log", processId, line });
+    });
+    supervisor.on("status", (processId, status, proc) => {
+        if (status === "running") {
+            bus.emit({
+                kind: "process.started",
+                processId,
+                topology: proc.topology,
+                port: proc.port,
+                at: new Date().toISOString(),
+            });
+        }
+        else if (status === "exited" || status === "crashed") {
+            bus.emit({
+                kind: "process.exited",
+                processId,
+                code: proc.exitCode ?? null,
+                signal: (proc.signal ?? null),
+                at: new Date().toISOString(),
+            });
+        }
+    });
+    return {
+        bus,
+        router,
+        supervisor,
+        run: (name, args) => router.run(name, args),
+    };
+}

package/dist/mcp-adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@nwire/mcp` — Adapter shape for 0.10.
+ *
+ *   import { mcpAdapter } from "@nwire/mcp";
+ *
+ *   const mcp = mcpAdapter();
+ *   await endpoint("svc", { port: 3000 })
+ *     .use(httpKoa({ prefix: "/api" }))
+ *     .use(mcp)
+ *     .mount(app)
+ *     .run();
+ *
+ *   const tools = mcp.list();           // [{ name, description, input }]
+ *   const result = await mcp.call("create-task", { title: "x" });
+ *
+ * Consumes wires whose `binding.$adapter === "mcp"` + `binding.kind === "tool"`.
+ * In-process introspection (`list`, `call`) makes the adapter testable without
+ * spinning up an MCP stdio server. The legacy `serveMcp(...)` stdio entry
+ * stays available via the package's main export.
+ */
+import type { Adapter } from "@nwire/endpoint";
+import { type Logger } from "@nwire/logger";
+export interface McpAdapterConfig {
+    readonly logger?: Logger;
+}
+export interface McpToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema?: unknown;
+}
+export interface McpAdapter extends Adapter {
+    list(): readonly McpToolDescriptor[];
+    call(toolName: string, input: unknown): Promise<unknown>;
+}
+export declare function mcpAdapter(config?: McpAdapterConfig): McpAdapter;