@nwire/mcp 0.7.1 → 0.8.0

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

@@ -0,0 +1,332 @@
+/**
+ * Inspect-tools tests — exercise the read-only MCP tools that proxy
+ * `/_nwire/*` (or fall back to the on-disk `.nwire/` cache). We stand
+ * up a tiny stub HTTP server on a free port, point the discovery layer
+ * at it via `NWIRE_INSPECT_URL`, and drive the tools through the same
+ * stdio harness the existing `mcp-io.test.ts` uses.
+ *
+ * For disk-fallback tools (`list_hooks`, `list_plugins` happy paths),
+ * we mkdtemp a directory, write fixture JSON into `<tmp>/.nwire/`, and
+ * chdir into it. The kernel and `serveMcp` see nothing different —
+ * the inspect module reads `process.cwd()`.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { PassThrough } from "node:stream";
+import { createServer, type Server } from "node:http";
+import { AddressInfo } from "node:net";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+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 StubWire {
+  readonly url:    string;
+  readonly server: Server;
+  manifest:        Record<string, unknown>;
+  events:          unknown[];
+  telemetry:       unknown[];
+  requests:        Array<{ method: string; url: string }>;
+}
+
+async function startStubWire(): Promise<StubWire> {
+  const stub: StubWire = {
+    url:       "",
+    server:    null as unknown as Server,
+    manifest:  {},
+    events:    [],
+    telemetry: [],
+    requests:  [],
+  };
+  const server = createServer((req, res) => {
+    stub.requests.push({ method: req.method ?? "?", url: req.url ?? "" });
+    const send = (body: unknown) => {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(body));
+    };
+    const url = req.url ?? "";
+    if (url === "/_nwire/manifest") return send(stub.manifest);
+    if (url.startsWith("/_nwire/events/recent")) return send(stub.events);
+    if (url.startsWith("/_nwire/telemetry/recent")) return send(stub.telemetry);
+    res.statusCode = 404;
+    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 — inspect tools", () => {
+  let kernel:  Kernel;
+  let harness: StdioHarness;
+  let stub:    StubWire | undefined;
+  let tmpDir:  string | undefined;
+  let prevCwd: string | undefined;
+  let prevInspectUrl: string | undefined;
+
+  beforeEach(() => {
+    kernel = createKernel();
+    prevInspectUrl = process.env.NWIRE_INSPECT_URL;
+    resetInspectDiscoveryCache();
+  });
+
+  afterEach(async () => {
+    if (harness) await harness.close();
+    if (stub) await stopStubWire(stub);
+    stub = undefined;
+    if (prevCwd) {
+      process.chdir(prevCwd);
+      prevCwd = undefined;
+    }
+    if (tmpDir) {
+      rmSync(tmpDir, { recursive: true, force: true });
+      tmpDir = undefined;
+    }
+    if (prevInspectUrl === undefined) delete process.env.NWIRE_INSPECT_URL;
+    else process.env.NWIRE_INSPECT_URL = prevInspectUrl;
+    resetInspectDiscoveryCache();
+  });
+
+  it("tools/list appends inspect tools to the kernel commands", async () => {
+    kernel.router.register("dev", async () => "ok");
+    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("dev");
+    expect(names).toContain("manifest");
+    expect(names).toContain("list_actions");
+    expect(names).toContain("list_events");
+    expect(names).toContain("list_hooks");
+    expect(names).toContain("list_plugins");
+    expect(names).toContain("recent_events");
+    expect(names).toContain("recent_telemetry");
+  });
+
+  it("manifest returns the live wire's manifest body", async () => {
+    stub = await startStubWire();
+    stub.manifest = { actions: [{ name: "a.do", module: "alpha" }], events: [], generatedAt: "now" };
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", { name: "manifest", arguments: {} });
+    expect(res.result.isError).toBe(false);
+    expect(parseToolResult(res)).toEqual(stub.manifest);
+    expect(stub.requests.some((r) => r.url === "/_nwire/manifest")).toBe(true);
+  });
+
+  it("list_actions filters by module", async () => {
+    stub = await startStubWire();
+    stub.manifest = {
+      actions: [
+        { name: "submit", module: "submissions" },
+        { name: "grade",  module: "submissions" },
+        { name: "enrol",  module: "roster" },
+      ],
+    };
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const unfiltered = await harness.request("tools/call", {
+      name:      "list_actions",
+      arguments: {},
+    });
+    expect((parseToolResult(unfiltered) as unknown[]).length).toBe(3);
+
+    const filtered = await harness.request("tools/call", {
+      name:      "list_actions",
+      arguments: { module: "submissions" },
+    });
+    const actions = parseToolResult(filtered) as Array<{ name: string }>;
+    expect(actions.map((a) => a.name)).toEqual(["submit", "grade"]);
+  });
+
+  it("list_events filters by module", async () => {
+    stub = await startStubWire();
+    stub.manifest = {
+      events: [
+        { name: "Submitted", module: "submissions" },
+        { name: "Graded",    module: "submissions" },
+        { name: "Enrolled",  module: "roster" },
+      ],
+    };
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "list_events",
+      arguments: { module: "roster" },
+    });
+    const events = parseToolResult(res) as Array<{ name: string }>;
+    expect(events).toHaveLength(1);
+    expect(events[0]!.name).toBe("Enrolled");
+  });
+
+  it("list_hooks reads .nwire/hooks.json from disk", async () => {
+    tmpDir  = mkdtempSync(join(tmpdir(), "nwire-mcp-hooks-"));
+    prevCwd = process.cwd();
+    mkdirSync(join(tmpDir, ".nwire"), { recursive: true });
+    const hooks = [{ name: "tracing", phase: "before" }];
+    writeFileSync(join(tmpDir, ".nwire", "hooks.json"), JSON.stringify(hooks));
+    process.chdir(tmpDir);
+    // No live wire — clear inspect URL so discovery falls through.
+    delete process.env.NWIRE_INSPECT_URL;
+    resetInspectDiscoveryCache();
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", { name: "list_hooks", arguments: {} });
+    expect(res.result.isError).toBe(false);
+    expect(parseToolResult(res)).toEqual(hooks);
+  });
+
+  it("list_plugins reads .nwire/plugins.json from disk and supports kind filter", async () => {
+    tmpDir  = mkdtempSync(join(tmpdir(), "nwire-mcp-plugins-"));
+    prevCwd = process.cwd();
+    mkdirSync(join(tmpDir, ".nwire"), { recursive: true });
+    const plugins = [
+      { name: "rbac",       kind: "plugin" },
+      { name: "identity",   kind: "plugin" },
+      { name: "submissions", kind: "module" },
+    ];
+    writeFileSync(join(tmpDir, ".nwire", "plugins.json"), JSON.stringify(plugins));
+    process.chdir(tmpDir);
+    delete process.env.NWIRE_INSPECT_URL;
+    resetInspectDiscoveryCache();
+    harness = new StdioHarness(kernel);
+
+    const all = await harness.request("tools/call", {
+      name:      "list_plugins",
+      arguments: {},
+    });
+    expect((parseToolResult(all) as unknown[]).length).toBe(3);
+
+    const onlyPlugins = await harness.request("tools/call", {
+      name:      "list_plugins",
+      arguments: { kind: "plugin" },
+    });
+    expect((parseToolResult(onlyPlugins) as Array<{ name: string }>).map((p) => p.name)).toEqual([
+      "rbac",
+      "identity",
+    ]);
+  });
+
+  it("recent_events passes the limit param through to the wire", async () => {
+    stub = await startStubWire();
+    stub.events = [{ name: "Submitted", t: 1 }, { name: "Graded", t: 2 }];
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "recent_events",
+      arguments: { limit: 42 },
+    });
+    expect(res.result.isError).toBe(false);
+    expect(parseToolResult(res)).toEqual(stub.events);
+    const eventsHit = stub.requests.find((r) => r.url.startsWith("/_nwire/events/recent"));
+    expect(eventsHit?.url).toContain("limit=42");
+  });
+
+  it("recent_telemetry defaults to limit=100 when omitted", async () => {
+    stub = await startStubWire();
+    stub.telemetry = [{ kind: "event", at: "now" }];
+    process.env.NWIRE_INSPECT_URL = stub.url;
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "recent_telemetry",
+      arguments: {},
+    });
+    expect(res.result.isError).toBe(false);
+    expect(parseToolResult(res)).toEqual(stub.telemetry);
+    const hit = stub.requests.find((r) => r.url.startsWith("/_nwire/telemetry/recent"));
+    expect(hit?.url).toContain("limit=100");
+  });
+
+  it("manifest gracefully fails when no wire and no cache are available", async () => {
+    // Point at an empty tmp dir with no .nwire/ AND no live wire URL.
+    tmpDir  = mkdtempSync(join(tmpdir(), "nwire-mcp-empty-"));
+    prevCwd = process.cwd();
+    process.chdir(tmpDir);
+    // Force discovery to find nothing: set a deliberately-empty probe list
+    // AND clear the inspect URL.
+    delete process.env.NWIRE_INSPECT_URL;
+    const prevProbe = process.env.NWIRE_PROBE_PORTS;
+    process.env.NWIRE_PROBE_PORTS = "1"; // port 1 is reliably closed
+    resetInspectDiscoveryCache();
+    try {
+      harness = new StdioHarness(kernel);
+      const res = await harness.request("tools/call", { name: "manifest", arguments: {} });
+      expect(res.result.isError).toBe(true);
+      expect(res.result.content[0].text).toMatch(/no running wire/);
+    } finally {
+      if (prevProbe === undefined) delete process.env.NWIRE_PROBE_PORTS;
+      else process.env.NWIRE_PROBE_PORTS = prevProbe;
+    }
+  });
+});

package/src/__tests__/mcp-io.test.ts

@@ -0,0 +1,180 @@
+/**
+ * MCP I/O tests — drive `serveMcp` over real PassThrough streams the
+ * same way Claude / Cursor will over stdio. We submit newline-framed
+ * JSON-RPC requests on the input stream and parse responses off the
+ * output stream. The kernel underneath is the real CommandRouter — no
+ * mocks. If this passes, an AI client can actually drive nwire.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { PassThrough } from "node:stream";
+import { createKernel, type Kernel } from "@nwire/kernel";
+import { serveMcp } from "../index";
+
+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;
+  }
+}
+
+describe("@nwire/mcp — JSON-RPC over stdio", () => {
+  let kernel:  Kernel;
+  let harness: StdioHarness;
+
+  beforeEach(() => {
+    kernel = createKernel();
+  });
+
+  afterEach(async () => {
+    if (harness) await harness.close();
+  });
+
+  it("handshakes via initialize", async () => {
+    harness = new StdioHarness(kernel);
+    const res = await harness.request("initialize", {});
+    expect(res.result.protocolVersion).toBe("2024-11-05");
+    expect(res.result.serverInfo).toEqual({ name: "nwire-test", version: "0.0.0-test" });
+    expect(res.result.capabilities.tools).toBeDefined();
+  });
+
+  it("tools/list returns every registered command", async () => {
+    kernel.router.register("greet",  async () => "hi");
+    kernel.router.register("double", async (_ctx, a: { n: number }) => a.n * 2);
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/list", {});
+    const tools = res.result.tools as Array<{
+      name:        string;
+      description: string;
+      inputSchema: { type: string };
+    }>;
+    const names = tools.map((t) => t.name);
+    // Kernel commands come first; inspect tools are appended after.
+    expect(names).toContain("double");
+    expect(names).toContain("greet");
+    const kernelTools = tools.filter((t) => t.name === "double" || t.name === "greet");
+    for (const tool of kernelTools) {
+      expect(tool.description).toContain(tool.name);
+      expect(tool.inputSchema.type).toBe("object");
+    }
+  });
+
+  it("tools/call invokes a command and returns the wrapped result", async () => {
+    kernel.router.register("double", async (_ctx, a: { n: number }) => ({ doubled: a.n * 2 }));
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", {
+      name:      "double",
+      arguments: { n: 21 },
+    });
+    expect(res.result.isError).toBe(false);
+    expect(res.result.content).toHaveLength(1);
+    expect(res.result.content[0].type).toBe("text");
+    expect(JSON.parse(res.result.content[0].text)).toEqual({ doubled: 42 });
+  });
+
+  it("tools/call streams command.log lines as progress notifications", async () => {
+    kernel.router.register("noisy", async (ctx) => {
+      ctx.log("step 1");
+      ctx.log("step 2", "stderr");
+      return "done";
+    });
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", { name: "noisy", arguments: {} });
+    expect(res.result.isError).toBe(false);
+
+    const progress = harness.notifications.filter((n) => n.method === "notifications/progress");
+    expect(progress.length).toBeGreaterThanOrEqual(2);
+    expect(progress.map((n) => n.params.message)).toContain("step 1");
+    expect(progress.map((n) => n.params.message)).toContain("step 2");
+    const stderrFrame = progress.find((n) => n.params.stream === "stderr");
+    expect(stderrFrame?.params.message).toBe("step 2");
+  });
+
+  it("tools/call surfaces handler throws as isError content (not JSON-RPC error)", async () => {
+    kernel.router.register("explode", async () => {
+      throw new Error("boom");
+    });
+    harness = new StdioHarness(kernel);
+
+    const res = await harness.request("tools/call", { name: "explode", arguments: {} });
+    expect(res.error).toBeUndefined();
+    expect(res.result.isError).toBe(true);
+    expect(res.result.content[0].text).toBe("boom");
+  });
+
+  it("unknown tool returns -32602 invalid params", async () => {
+    harness = new StdioHarness(kernel);
+    const res = await harness.request("tools/call", { name: "nope", arguments: {} });
+    expect(res.error?.code).toBe(-32602);
+    expect(res.error?.message).toMatch(/unknown tool/);
+  });
+
+  it("unknown method returns -32601 method not found", async () => {
+    harness = new StdioHarness(kernel);
+    const res = await harness.request("resources/list", {});
+    expect(res.error?.code).toBe(-32601);
+  });
+
+  it("malformed JSON line returns -32700 with null id", async () => {
+    harness = new StdioHarness(kernel);
+    const buf: any[] = [];
+    harness.stdout.on("data", (chunk: string) => {
+      for (const line of chunk.split("\n")) {
+        if (line.trim()) buf.push(JSON.parse(line));
+      }
+    });
+    harness.stdin.write("this is not json\n");
+    // Give the parser a tick to emit.
+    await new Promise((r) => setTimeout(r, 30));
+    const parseError = buf.find((m) => m.error?.code === -32700);
+    expect(parseError).toBeDefined();
+    expect(parseError.id).toBeNull();
+  });
+});