@nwire/mcp 0.9.2 → 0.10.0

package/src/index.ts

@@ -1,348 +0,0 @@
-/**
- * `@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";
-import { inspectTools, findInspectTool } from "./inspect.js";
-import { writeTools, findWriteTool } from "./write-tools.js";
-
-// ─── 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_NOT_FOUND = -32601;
-const ERR_INVALID_PARAMS = -32602;
-const ERR_INTERNAL = -32603;
-
-// ─── 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;
-  /**
-   * 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;
-}
-
-/**
- * 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";
-  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(stdin, 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, send });
-  });
-
-  log("stdin closed — server exiting");
-}
-
-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> {
-  // 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) {
-      case "initialize":
-        ctx.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":
-        ctx.send({
-          jsonrpc: "2.0",
-          id,
-          result: {
-            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;
-
-      case "tools/call":
-        await callTool(req, id, ctx);
-        return;
-
-      default:
-        ctx.send({
-          jsonrpc: "2.0",
-          id,
-          error: { code: ERR_NOT_FOUND, message: `unknown method "${req.method}"` },
-        });
-    }
-  } catch (err) {
-    ctx.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) {
-    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)) {
-    ctx.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") {
-      ctx.send({
-        jsonrpc: "2.0",
-        method: "notifications/progress",
-        params: {
-          progressToken: handle.commandId,
-          message: event.line,
-          stream: event.stream,
-        },
-      });
-    } else if (event.kind === "command.progress") {
-      ctx.send({
-        jsonrpc: "2.0",
-        method: "notifications/progress",
-        params: {
-          progressToken: handle.commandId,
-          message: event.message,
-          pct: event.pct,
-        },
-      });
-    }
-  });
-
-  try {
-    const result = await handle.promise;
-    ctx.send({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        content: [{ type: "text", text: JSON.stringify(result) }],
-        isError: false,
-      },
-    });
-  } catch (err) {
-    ctx.send({
-      jsonrpc: "2.0",
-      id,
-      result: {
-        content: [{ type: "text", text: (err as Error).message }],
-        isError: true,
-      },
-    });
-  } finally {
-    unsubscribe();
-  }
-}
-
-/**
- * Read newline-delimited messages from a stream. Resolves when the
- * stream ends. Tolerates partial chunks (buffers + splits on \n).
- */
-function readLines(
-  stream: NodeJS.ReadableStream,
-  onLine: (line: string) => Promise<void>,
-): Promise<void> {
-  return new Promise((resolve) => {
-    let buffer = "";
-    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) {
-          process.stderr.write(`[nwire-mcp] onLine threw: ${(err as Error).message}\n`);
-        }
-      }
-    });
-    stream.on("end", () => resolve());
-    stream.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 };
-
-export { inspectTools, findInspectTool, resetInspectDiscoveryCache } from "./inspect.js";
-export type { InspectToolDef } from "./inspect.js";
-export { writeTools, findWriteTool } from "./write-tools.js";

package/src/inspect.ts

@@ -1,329 +0,0 @@
-/**
- * Inspect tools — proxy a running wire's `/_nwire/*` introspection
- * endpoints (or fall back to the on-disk `.nwire/` cache) as MCP tools.
- *
- * Today's `@nwire/mcp` only exposed the kernel's CLI commands. The
- * running wire mounts a rich read-only surface (manifest, recent events,
- * recent telemetry, dispatch…) at `/_nwire/*`. We adapt that surface
- * into MCP tools so an AI client can ask "what actions does this app
- * expose?" or "show me the last 100 events" without booting anything.
- *
- * Discovery follows the same pattern Studio uses (see
- * `packages/nwire-studio/vite.config.ts`):
- *
- *   1. If `NWIRE_INSPECT_URL` is set, trust it.
- *   2. Otherwise, probe a small fixed list of ports for a wire that
- *      answers `GET /_nwire/events/recent?limit=1` with a JSON array.
- *   3. Cache the result for 5s so a burst of tool calls is cheap.
- *
- * For tools that have a disk equivalent (`manifest`, `hooks`,
- * `plugins`), we fall through to `${cwd}/.nwire/<file>.json` when no
- * live wire answers. That makes the inspect tools usable in a cold
- * project too — just run `nwire cache` once.
- */
-
-import { request as httpRequest } from "node:http";
-import { createConnection } from "node:net";
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-
-// ─── Port discovery ────────────────────────────────────────────────
-
-const DEFAULT_PROBE_PORTS: readonly number[] = [
-  3000, 3001, 3002, 3003, 3004, 3005, 3006, 3007, 3008, 3009, 3010, 3030, 3040, 3050, 4000, 8080,
-];
-
-const PROBE_TIMEOUT_MS = 150;
-const CACHE_TTL_MS = 5_000;
-const NEGATIVE_CACHE_TTL_MS = 1_500;
-
-interface DiscoveredUrl {
-  readonly url: string | undefined;
-  readonly expires: number;
-}
-
-let discovered: DiscoveredUrl = { url: undefined, expires: 0 };
-
-/** Reset the URL cache. Tests use this to flush between cases. */
-export function resetInspectDiscoveryCache(): void {
-  discovered = { url: undefined, expires: 0 };
-}
-
-/**
- * Discover the base URL of a running wire. Honours `NWIRE_INSPECT_URL`
- * first (and does NOT validate it — callers asked for it explicitly),
- * then probes a fixed list of ports.
- */
-export async function discoverInspectUrl(): Promise<string | undefined> {
-  if (process.env.NWIRE_INSPECT_URL) {
-    return process.env.NWIRE_INSPECT_URL.replace(/\/$/, "");
-  }
-  if (Date.now() < discovered.expires) return discovered.url;
-  const ports = parsePorts(process.env.NWIRE_PROBE_PORTS) ?? DEFAULT_PROBE_PORTS;
-  for (const port of ports) {
-    if (await isNwireWire(port, PROBE_TIMEOUT_MS)) {
-      const url = `http://127.0.0.1:${port}`;
-      discovered = { url, expires: Date.now() + CACHE_TTL_MS };
-      return url;
-    }
-  }
-  discovered = { url: undefined, expires: Date.now() + NEGATIVE_CACHE_TTL_MS };
-  return undefined;
-}
-
-function parsePorts(raw: string | undefined): readonly number[] | undefined {
-  if (!raw) return undefined;
-  const ports = raw
-    .split(",")
-    .map((s) => Number(s.trim()))
-    .filter((n) => n > 0);
-  return ports.length > 0 ? ports : undefined;
-}
-
-/**
- * Probe one port: open a socket, then GET `/_nwire/events/recent?limit=1`
- * and require a JSON-array body. This rejects unrelated services on the
- * same port (TCP-only probes were too permissive).
- */
-function isNwireWire(port: number, timeoutMs: number): Promise<boolean> {
-  return new Promise((resolveProbe) => {
-    const sock = createConnection({ host: "127.0.0.1", port });
-    sock.setTimeout(timeoutMs, () => {
-      sock.destroy();
-      resolveProbe(false);
-    });
-    sock.once("error", () => resolveProbe(false));
-    sock.once("connect", () => {
-      sock.destroy();
-      const req = httpRequest(
-        { host: "127.0.0.1", port, path: "/_nwire/events/recent?limit=1", method: "GET" },
-        (res) => {
-          if (res.statusCode !== 200) {
-            res.resume();
-            return resolveProbe(false);
-          }
-          let buf = "";
-          res.setEncoding("utf8");
-          res.on("data", (c: string) => {
-            buf += c;
-            if (buf.length > 1024) res.destroy();
-          });
-          res.on("end", () => resolveProbe(buf.trimStart().startsWith("[")));
-        },
-      );
-      req.setTimeout(timeoutMs, () => {
-        req.destroy();
-        resolveProbe(false);
-      });
-      req.once("error", () => resolveProbe(false));
-      req.end();
-    });
-  });
-}
-
-// ─── HTTP helpers ──────────────────────────────────────────────────
-
-async function httpGetJson(url: string): Promise<unknown> {
-  return new Promise((resolveGet, rejectGet) => {
-    const u = new URL(url);
-    const req = httpRequest(
-      { host: u.hostname, port: u.port || 80, path: u.pathname + u.search, method: "GET" },
-      (res) => {
-        let buf = "";
-        res.setEncoding("utf8");
-        res.on("data", (c: string) => {
-          buf += c;
-        });
-        res.on("end", () => {
-          if ((res.statusCode ?? 0) >= 400) {
-            return rejectGet(new Error(`GET ${url} → ${res.statusCode}`));
-          }
-          try {
-            resolveGet(buf.length === 0 ? undefined : JSON.parse(buf));
-          } catch (err) {
-            rejectGet(new Error(`GET ${url} returned non-JSON: ${(err as Error).message}`));
-          }
-        });
-      },
-    );
-    req.setTimeout(5_000, () => {
-      req.destroy();
-      rejectGet(new Error(`GET ${url} timed out`));
-    });
-    req.once("error", rejectGet);
-    req.end();
-  });
-}
-
-// ─── Disk fallback ─────────────────────────────────────────────────
-
-function readDiskCache(file: string): unknown | undefined {
-  const path = resolve(process.cwd(), ".nwire", file);
-  if (!existsSync(path)) return undefined;
-  try {
-    return JSON.parse(readFileSync(path, "utf8"));
-  } catch {
-    return undefined;
-  }
-}
-
-// ─── Tool registry ─────────────────────────────────────────────────
-
-export interface InspectToolDef {
-  readonly name: string;
-  readonly description: string;
-  readonly inputSchema: Record<string, unknown>;
-  readonly run: (args: Record<string, unknown>) => Promise<unknown>;
-}
-
-/**
- * Resolve the full manifest. Live wire wins; otherwise disk cache.
- * Throws a helpful error if neither is available.
- */
-async function getManifest(): Promise<Record<string, unknown>> {
-  const url = await discoverInspectUrl();
-  if (url) {
-    try {
-      return (await httpGetJson(`${url}/_nwire/manifest`)) as Record<string, unknown>;
-    } catch {
-      // fall through to disk
-    }
-  }
-  const disk = readDiskCache("manifest.json");
-  if (disk) return disk as Record<string, unknown>;
-  throw new Error(
-    "no running wire and no .nwire/manifest.json on disk. Start a wire or run `nwire cache`.",
-  );
-}
-
-function filterByModule<T extends { module?: string }>(
-  items: readonly T[],
-  module: unknown,
-): readonly T[] {
-  if (typeof module !== "string" || module.length === 0) return items;
-  return items.filter((it) => it.module === module);
-}
-
-export const inspectTools: readonly InspectToolDef[] = [
-  {
-    name: "manifest",
-    description:
-      "Return the full .nwire manifest of the running wire (live HTTP) or the on-disk cache.",
-    inputSchema: { type: "object", additionalProperties: false, properties: {} },
-    async run() {
-      return getManifest();
-    },
-  },
-  {
-    name: "list_actions",
-    description: 'List actions exposed by the wire. Optional `module` filter (e.g. "submissions").',
-    inputSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: { module: { type: "string" } },
-    },
-    async run(args) {
-      const manifest = await getManifest();
-      const actions = (manifest.actions ?? readDiskCache("actions.json") ?? []) as Array<{
-        module?: string;
-      }>;
-      return filterByModule(actions, args.module);
-    },
-  },
-  {
-    name: "list_events",
-    description: "List events declared by the wire. Optional `module` filter.",
-    inputSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: { module: { type: "string" } },
-    },
-    async run(args) {
-      const manifest = await getManifest();
-      const events = (manifest.events ?? readDiskCache("events.json") ?? []) as Array<{
-        module?: string;
-      }>;
-      return filterByModule(events, args.module);
-    },
-  },
-  {
-    name: "list_hooks",
-    description: "List runtime hooks (reads .nwire/hooks.json from disk).",
-    inputSchema: { type: "object", additionalProperties: false, properties: {} },
-    async run() {
-      // hooks.json lives on disk; the running wire does not currently
-      // expose it via /_nwire (it's scanner output, not runtime state).
-      const disk = readDiskCache("hooks.json");
-      if (disk) return disk;
-      // Try the manifest as a last resort — some scans embed hooks there.
-      try {
-        const manifest = await getManifest();
-        return manifest.hooks ?? [];
-      } catch {
-        throw new Error(".nwire/hooks.json not found. Run `nwire cache`.");
-      }
-    },
-  },
-  {
-    name: "list_plugins",
-    description:
-      'List discovered plugins (reads .nwire/plugins.json). Optional `kind` filter: "plugin" | "module".',
-    inputSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: { kind: { type: "string", enum: ["plugin", "module"] } },
-    },
-    async run(args) {
-      let plugins = readDiskCache("plugins.json") as Array<{ kind?: string }> | undefined;
-      if (!plugins) {
-        try {
-          const manifest = await getManifest();
-          plugins = (manifest.plugins ?? []) as Array<{ kind?: string }>;
-        } catch {
-          throw new Error(".nwire/plugins.json not found. Run `nwire cache`.");
-        }
-      }
-      if (typeof args.kind === "string" && args.kind.length > 0) {
-        return plugins.filter((p) => p.kind === args.kind);
-      }
-      return plugins;
-    },
-  },
-  {
-    name: "recent_events",
-    description: "GET /_nwire/events/recent?limit=N from the running wire. Requires a live wire.",
-    inputSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: { limit: { type: "number", minimum: 1, maximum: 10_000 } },
-    },
-    async run(args) {
-      const url = await discoverInspectUrl();
-      if (!url) throw new Error("no running wire detected; recent_events requires a live wire.");
-      const limit = typeof args.limit === "number" ? args.limit : 100;
-      return httpGetJson(`${url}/_nwire/events/recent?limit=${limit}`);
-    },
-  },
-  {
-    name: "recent_telemetry",
-    description:
-      "GET /_nwire/telemetry/recent?limit=N from the running wire. Requires a live wire.",
-    inputSchema: {
-      type: "object",
-      additionalProperties: false,
-      properties: { limit: { type: "number", minimum: 1, maximum: 10_000 } },
-    },
-    async run(args) {
-      const url = await discoverInspectUrl();
-      if (!url) {
-        throw new Error("no running wire detected; recent_telemetry requires a live wire.");
-      }
-      const limit = typeof args.limit === "number" ? args.limit : 100;
-      return httpGetJson(`${url}/_nwire/telemetry/recent?limit=${limit}`);
-    },
-  },
-];
-
-export function findInspectTool(name: string): InspectToolDef | undefined {
-  return inspectTools.find((t) => t.name === name);
-}