@nwire/mcp 0.7.1 → 0.8.0

package/src/__tests__/write-tools.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Write-tools tests — mutating counterpart to `inspect-tools.test.ts`.
+ *
+ * Pattern: stand up a stub HTTP server, point discovery at it via
+ * `NWIRE_INSPECT_URL`, drive the tools through the same stdio harness.
+ * Each tool gets a happy path (or, for tools whose endpoint isn't yet
+ * mounted, a gap-flag assertion) and a "no wire running" graceful
+ * failure.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { PassThrough } from "node:stream";
+import { createServer, type Server, type IncomingMessage } from "node:http";
+import { AddressInfo } from "node:net";
+import { createKernel, type Kernel } from "@nwire/kernel";
+import { serveMcp } from "../index";
+import { resetInspectDiscoveryCache } from "../inspect";
+
+interface PendingResponse { resolve: (value: any) => void }
+
+class StdioHarness {
+  readonly stdin  = new PassThrough();
+  readonly stdout = new PassThrough();
+  private buffer  = "";
+  private pending = new Map<string | number, PendingResponse>();
+  readonly notifications: Array<{ method: string; params?: any }> = [];
+  readonly served:        Promise<void>;
+  private id = 0;
+
+  constructor(kernel: Kernel) {
+    this.served = serveMcp({
+      kernel,
+      stdin:  this.stdin,
+      stdout: this.stdout,
+      serverName:    "nwire-test",
+      serverVersion: "0.0.0-test",
+    });
+    this.stdout.setEncoding("utf8");
+    this.stdout.on("data", (chunk: string) => {
+      this.buffer += chunk;
+      const lines = this.buffer.split("\n");
+      this.buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        const msg = JSON.parse(line) as { id?: string | number; method?: string };
+        if (msg.id != null && this.pending.has(msg.id)) {
+          this.pending.get(msg.id)!.resolve(msg);
+          this.pending.delete(msg.id);
+        } else if (msg.method) {
+          this.notifications.push(msg as any);
+        }
+      }
+    });
+  }
+
+  request(method: string, params?: Record<string, unknown>): Promise<any> {
+    const id = ++this.id;
+    const promise = new Promise<any>((resolve) => {
+      this.pending.set(id, { resolve });
+    });
+    this.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    return promise;
+  }
+
+  async close(): Promise<void> {
+    this.stdin.end();
+    await this.served;
+  }
+}
+
+interface CapturedRequest {
+  readonly method: string;
+  readonly url:    string;
+  readonly body:   unknown;
+}
+
+interface StubWire {
+  readonly url:    string;
+  readonly server: Server;
+  readonly requests: CapturedRequest[];
+  /** Override per-path responses. Default → 404 so gap-flag tests fire. */
+  routes: Map<string, (body: unknown) => { status: number; body: unknown }>;
+}
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolveBody) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (c: string) => { raw += c; });
+    req.on("end",  () => {
+      if (raw.length === 0) return resolveBody(undefined);
+      try {
+        resolveBody(JSON.parse(raw));
+      } catch {
+        resolveBody(raw);
+      }
+    });
+  });
+}
+
+async function startStubWire(): Promise<StubWire> {
+  const stub: StubWire = {
+    url:      "",
+    server:   null as unknown as Server,
+    requests: [],
+    routes:   new Map(),
+  };
+  const server = createServer(async (req, res) => {
+    const url    = req.url ?? "";
+    const method = req.method ?? "?";
+    const body   = method === "POST" ? await readBody(req) : undefined;
+    stub.requests.push({ method, url, body });
+
+    // The discovery probe hits GET /_nwire/events/recent — always 200 [].
+    if (method === "GET" && url.startsWith("/_nwire/events/recent")) {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "application/json");
+      res.end("[]");
+      return;
+    }
+
+    const handler = stub.routes.get(`${method} ${url.split("?")[0]}`);
+    if (handler) {
+      const { status, body: out } = handler(body);
+      res.statusCode = status;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(out));
+      return;
+    }
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "not found" }));
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+  const port = (server.address() as AddressInfo).port;
+  stub.server = server;
+  (stub as { url: string }).url = `http://127.0.0.1:${port}`;
+  return stub;
+}
+
+async function stopStubWire(stub: StubWire): Promise<void> {
+  await new Promise<void>((r) => stub.server.close(() => r()));
+}
+
+function parseToolResult(res: any): unknown {
+  expect(res.result.content).toHaveLength(1);
+  expect(res.result.content[0].type).toBe("text");
+  return JSON.parse(res.result.content[0].text);
+}
+
+describe("@nwire/mcp — write tools", () => {
+  let kernel:  Kernel;
+  let harness: StdioHarness;
+  let stub:    StubWire | undefined;
+  let prevInspectUrl: string | undefined;
+  let prevProbePorts: string | undefined;
+
+  beforeEach(() => {
+    kernel = createKernel();
+    prevInspectUrl = process.env.NWIRE_INSPECT_URL;
+    prevProbePorts = process.env.NWIRE_PROBE_PORTS;
+    resetInspectDiscoveryCache();
+  });
+
+  afterEach(async () => {
+    if (harness) await harness.close();
+    if (stub) await stopStubWire(stub);
+    stub = undefined;
+    if (prevInspectUrl === undefined) delete process.env.NWIRE_INSPECT_URL;
+    else process.env.NWIRE_INSPECT_URL = prevInspectUrl;
+    if (prevProbePorts === undefined) delete process.env.NWIRE_PROBE_PORTS;
+    else process.env.NWIRE_PROBE_PORTS = prevProbePorts;
+    resetInspectDiscoveryCache();
+  });
+
+  it("tools/list includes the three write tools", async () => {
+    harness = new StdioHarness(kernel);
+    const res = await harness.request("tools/list", {});
+    const names = (res.result.tools as Array<{ name: string }>).map((t) => t.name);
+    expect(names).toContain("dispatch_action");
+    expect(names).toContain("run_command");
+    expect(names).toContain("replay_trace");
+  });
+
+  // ─── dispatch_action ─────────────────────────────────────────────
+
+  it("dispatch_action POSTs to /_nwire/dispatch and returns the wire body", async () => {
+    stub = await startStubWire();
+    stub.routes.set("POST /_nwire/dispatch", (body) => {
+      expect(body).toEqual({
+        action: "submissions.submit",
+        input:  { studentId: "alice", answer: "42" },
+        userId: "u-1",
+      });
+      return {
+        status: 200,
+        body:   {
+          ok:       true,
+          result:   { events: [{ name: "Submitted" }] },
+          envelope: { messageId: "m-1", correlationId: "c-1" },
+        },
+      };
+    });
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "dispatch_action",
+      arguments: {
+        action: "submissions.submit",
+        input:  { studentId: "alice", answer: "42" },
+        user:   { id: "u-1", roles: ["student"] },
+      },
+    });
+    expect(res.result.isError).toBe(false);
+    const parsed = parseToolResult(res) as { ok: boolean; envelope: { correlationId: string } };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.envelope.correlationId).toBe("c-1");
+    const hit = stub.requests.find((r) => r.url === "/_nwire/dispatch");
+    expect(hit?.method).toBe("POST");
+  });
+
+  it("dispatch_action gracefully fails when no wire is running", async () => {
+    delete process.env.NWIRE_INSPECT_URL;
+    process.env.NWIRE_PROBE_PORTS = "1";
+    resetInspectDiscoveryCache();
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "dispatch_action",
+      arguments: { action: "x", input: {} },
+    });
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toMatch(/no running wire/);
+  });
+
+  // ─── run_command ─────────────────────────────────────────────────
+
+  it("run_command gap-flags when the wire returns 404 (endpoint not mounted)", async () => {
+    stub = await startStubWire();
+    // No route registered for POST /_nwire/command → stub returns 404.
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "run_command",
+      arguments: { name: "dev", args: {} },
+    });
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toMatch(
+      /endpoint not implemented yet on wire side: POST \/_nwire\/command/,
+    );
+    // Sanity: the tool DID POST against the wire (so the gap is detected
+    // by the wire's 404 rather than synthesized client-side).
+    const hit = stub.requests.find((r) => r.url === "/_nwire/command");
+    expect(hit?.method).toBe("POST");
+  });
+
+  it("run_command happy path returns the wire body if the endpoint is mounted", async () => {
+    // Belt-and-braces: if/when /_nwire/command lands on the wire, the
+    // existing tool already speaks the right contract.
+    stub = await startStubWire();
+    stub.routes.set("POST /_nwire/command", (body) => {
+      expect(body).toEqual({ name: "dev", args: { wire: "main" } });
+      return { status: 200, body: { ok: true, exitCode: 0, stdout: "started\n" } };
+    });
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "run_command",
+      arguments: { name: "dev", args: { wire: "main" } },
+    });
+    expect(res.result.isError).toBe(false);
+    const parsed = parseToolResult(res) as { ok: boolean; exitCode: number };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.exitCode).toBe(0);
+  });
+
+  it("run_command gracefully fails when no wire is running", async () => {
+    delete process.env.NWIRE_INSPECT_URL;
+    process.env.NWIRE_PROBE_PORTS = "1";
+    resetInspectDiscoveryCache();
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "run_command",
+      arguments: { name: "dev", args: {} },
+    });
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toMatch(/no running wire/);
+  });
+
+  // ─── replay_trace ────────────────────────────────────────────────
+
+  it("replay_trace gap-flags when the wire returns 404 (endpoint not mounted)", async () => {
+    stub = await startStubWire();
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const recording = {
+      ctxIn:   {},
+      outcome: "ok",
+      steps:   [{ stepKind: "branch", stepName: "guard", phase: "enter" }],
+    };
+    const res = await harness.request("tools/call", {
+      name:      "replay_trace",
+      arguments: { recording },
+    });
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toMatch(
+      /endpoint not implemented yet on wire side: POST \/_nwire\/replay/,
+    );
+    const hit = stub.requests.find((r) => r.url === "/_nwire/replay");
+    expect(hit?.method).toBe("POST");
+    expect((hit?.body as { recording: unknown }).recording).toEqual(recording);
+  });
+
+  it("replay_trace happy path returns drift report if the endpoint is mounted", async () => {
+    stub = await startStubWire();
+    stub.routes.set("POST /_nwire/replay", () => ({
+      status: 200,
+      body:   { ok: true, drift: [], stepsCompared: 1 },
+    }));
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "replay_trace",
+      arguments: { recording: { ctxIn: {}, outcome: "ok", steps: [] } },
+    });
+    expect(res.result.isError).toBe(false);
+    const parsed = parseToolResult(res) as { ok: boolean; drift: unknown[] };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.drift).toEqual([]);
+  });
+
+  it("replay_trace gracefully fails when no wire is running", async () => {
+    delete process.env.NWIRE_INSPECT_URL;
+    process.env.NWIRE_PROBE_PORTS = "1";
+    resetInspectDiscoveryCache();
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "replay_trace",
+      arguments: { recording: { ctxIn: {}, outcome: "ok", steps: [] } },
+    });
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toMatch(/no running wire/);
+  });
+});

package/src/index.ts

@@ -25,6 +25,8 @@
  */
 
 import { createKernel, type CommandHandle, type Kernel } from "@nwire/kernel";
+import { inspectTools, findInspectTool } from "./inspect.js";
+import { writeTools, findWriteTool } from "./write-tools.js";
 
 // ─── JSON-RPC framing over stdio ───────────────────────────────────
 
@@ -48,19 +50,10 @@ interface JsonRpcNotification {
   readonly params?: Record<string, unknown>;
 }
 
-const ERR_PARSE = -32700;
-const ERR_INVALID_REQ = -32600;
-const ERR_NOT_FOUND = -32601;
+const ERR_PARSE          = -32700;
+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`);
-}
+const ERR_INTERNAL       = -32603;
 
 // ─── Server ────────────────────────────────────────────────────────
 
@@ -71,6 +64,18 @@ export interface ServeMcpOptions {
   readonly serverName?: string;
   /** Server version reported on `initialize`. Default `"0.1.0"`. */
   readonly serverVersion?: string;
+  /**
+   * Input stream the server reads newline-delimited JSON-RPC from.
+   * Defaults to `process.stdin`. Tests supply a PassThrough; foreign
+   * transports (websocket, http) can adapt to this same shape.
+   */
+  readonly stdin?:  NodeJS.ReadableStream;
+  /**
+   * Output stream the server writes responses + notifications to.
+   * Defaults to `process.stdout`. Stderr is always used for server
+   * logs and is never overridden.
+   */
+  readonly stdout?: NodeJS.WritableStream;
 }
 
 /**
@@ -86,10 +91,19 @@ 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";
+  const stdin  = options.stdin  ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+
+  const send = (msg: JsonRpcResponse | JsonRpcNotification): void => {
+    stdout.write(JSON.stringify(msg) + "\n");
+  };
+  const log = (text: string): void => {
+    process.stderr.write(`[nwire-mcp] ${text}\n`);
+  };
 
   log(`server starting (${kernel.router.list().length} commands registered)`);
 
-  await readLines(async (line) => {
+  await readLines(stdin, async (line) => {
     if (!line.trim()) return;
     let request: JsonRpcRequest;
     try {
@@ -102,7 +116,7 @@ export async function serveMcp(options: ServeMcpOptions = {}): Promise<void> {
       });
       return;
     }
-    await handle(request, { kernel, serverName, serverVersion });
+    await handle(request, { kernel, serverName, serverVersion, send });
   });
 
   log("stdin closed — server exiting");
@@ -112,6 +126,7 @@ interface HandleContext {
   readonly kernel: Kernel;
   readonly serverName: string;
   readonly serverVersion: string;
+  readonly send: (msg: JsonRpcResponse | JsonRpcNotification) => void;
 }
 
 async function handle(req: JsonRpcRequest, ctx: HandleContext): Promise<void> {
@@ -119,7 +134,7 @@ async function handle(req: JsonRpcRequest, ctx: HandleContext): Promise<void> {
   try {
     switch (req.method) {
       case "initialize":
-        send({
+        ctx.send({
           jsonrpc: "2.0",
           id,
           result: {
@@ -131,15 +146,32 @@ async function handle(req: JsonRpcRequest, ctx: HandleContext): Promise<void> {
         return;
 
       case "tools/list":
-        send({
+        ctx.send({
           jsonrpc: "2.0",
           id,
           result: {
-            tools: ctx.kernel.router.list().map((name) => ({
-              name,
-              description: `Nwire command "${name}"`,
-              inputSchema: { type: "object", additionalProperties: true },
-            })),
+            tools: [
+              ...ctx.kernel.router.list().map((name) => ({
+                name,
+                description: `Nwire command "${name}"`,
+                inputSchema: { type: "object", additionalProperties: true },
+              })),
+              // Read-only introspection tools that proxy /_nwire/* (or
+              // fall back to the .nwire/ disk cache).
+              ...inspectTools.map((t) => ({
+                name:        t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+              })),
+              // Mutating tools that drive the wire via POST /_nwire/*.
+              // Some target endpoints aren't mounted yet — those tools
+              // gracefully gap-flag (see write-tools.ts).
+              ...writeTools.map((t) => ({
+                name:        t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+              })),
+            ],
           },
         });
         return;
@@ -149,14 +181,14 @@ async function handle(req: JsonRpcRequest, ctx: HandleContext): Promise<void> {
         return;
 
       default:
-        send({
+        ctx.send({
           jsonrpc: "2.0",
           id,
           error: { code: ERR_NOT_FOUND, message: `unknown method "${req.method}"` },
         });
     }
   } catch (err) {
-    send({
+    ctx.send({
       jsonrpc: "2.0",
       id,
       error: { code: ERR_INTERNAL, message: (err as Error).message },
@@ -172,15 +204,45 @@ async function callTool(
   const name = req.params?.name as string | undefined;
   const args = (req.params?.arguments ?? {}) as Record<string, unknown>;
   if (!name) {
-    send({
+    ctx.send({
       jsonrpc: "2.0",
       id,
       error: { code: ERR_INVALID_PARAMS, message: "tools/call requires `name`" },
     });
     return;
   }
+
+  // Inspect + write tools live alongside the kernel CommandRouter but
+  // don't emit progress notifications — they're synchronous HTTP/file
+  // reads (inspect) or single POSTs (write). Match these BEFORE the
+  // router-has check so they don't collide.
+  const httpTool = findInspectTool(name) ?? findWriteTool(name);
+  if (httpTool) {
+    try {
+      const out = await httpTool.run(args);
+      ctx.send({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: JSON.stringify(out) }],
+          isError: false,
+        },
+      });
+    } catch (err) {
+      ctx.send({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: (err as Error).message }],
+          isError: true,
+        },
+      });
+    }
+    return;
+  }
+
   if (!ctx.kernel.router.has(name)) {
-    send({
+    ctx.send({
       jsonrpc: "2.0",
       id,
       error: { code: ERR_INVALID_PARAMS, message: `unknown tool "${name}"` },
@@ -192,7 +254,7 @@ async function callTool(
   const handle: CommandHandle = ctx.kernel.run(name, args);
   const unsubscribe = handle.on((event) => {
     if (event.kind === "command.log") {
-      send({
+      ctx.send({
         jsonrpc: "2.0",
         method: "notifications/progress",
         params: {
@@ -202,7 +264,7 @@ async function callTool(
         },
       });
     } else if (event.kind === "command.progress") {
-      send({
+      ctx.send({
         jsonrpc: "2.0",
         method: "notifications/progress",
         params: {
@@ -216,7 +278,7 @@ async function callTool(
 
   try {
     const result = await handle.promise;
-    send({
+    ctx.send({
       jsonrpc: "2.0",
       id,
       result: {
@@ -225,7 +287,7 @@ async function callTool(
       },
     });
   } catch (err) {
-    send({
+    ctx.send({
       jsonrpc: "2.0",
       id,
       result: {
@@ -239,26 +301,32 @@ async function callTool(
 }
 
 /**
- * Read newline-delimited messages from stdin. Resolves when stdin
- * closes. Tolerates partial chunks (buffers + splits on \n).
+ * Read newline-delimited messages from a stream. Resolves when the
+ * stream ends. Tolerates partial chunks (buffers + splits on \n).
  */
-function readLines(onLine: (line: string) => Promise<void>): Promise<void> {
+function readLines(
+  stream: NodeJS.ReadableStream,
+  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");
+    stream.on("data", async (chunk: Buffer | string) => {
+      buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      // CRLF-safe: Windows MCP clients write `\r\n` terminated frames.
+      // Splitting on `\n` alone leaves a trailing `\r` on every line which
+      // breaks downstream JSON parsing of the next message.
+      const lines = buffer.split(/\r?\n/);
       buffer = lines.pop() ?? "";
       for (const line of lines) {
         try {
           await onLine(line);
         } catch (err) {
-          log(`onLine threw: ${(err as Error).message}`);
+          process.stderr.write(`[nwire-mcp] onLine threw: ${(err as Error).message}\n`);
         }
       }
     });
-    process.stdin.on("end", () => resolve());
-    process.stdin.on("close", () => resolve());
+    stream.on("end", () => resolve());
+    stream.on("close", () => resolve());
   });
 }