reasonix 0.3.0-alpha.1 → 0.3.0-alpha.3

package/README.md

@@ -94,22 +94,43 @@ with your own API key: `npx tsx benchmarks/tau-bench/runner.ts --repeats 3`.
 ### Extends to MCP (v0.3-alpha)
 
 Any [MCP](https://spec.modelcontextprotocol.io/) server's tools inherit
-the same Cache-First benefits. Live run with an MCP tool call in the
-middle of a conversation:
+the same Cache-First benefits. Two live runs, two data points:
 
-| turn | what happened | cache hit |
-|---|---|---:|
-| 1 | user asks, model decides to call `add` tool via MCP stdio | 0.0% (first-ever prefix) |
-| 1 (continued) | model receives tool result (42), writes final answer | **96.6%** |
+| server | turns | tool calls | cache hit | cost | vs Claude |
+|---|---:|---:|---:|---:|---:|
+| bundled demo (`add` / `echo` / `get_time`) | 2 | 1 | **96.6%** (turn 2) | $0.000254 | −94.0% |
+| official `@modelcontextprotocol/server-filesystem` | 5 | 4 | **96.7%** overall | $0.001235 | −97.0% |
+| **both concurrently** (`demo_add` + `fs_write_file`) | 5 | 4 | **81.1%** | $0.001852 | −95.9% |
 
-The MCP round-trip did not disturb the byte-stable prefix — server-side
-prompt cache kicked in on turn 2. Cost $0.000254 total, **94% cheaper
-than Claude** at equivalent token counts. Reference transcript:
-[`mcp-demo.add.jsonl`][mcp]. Reproduce:
+The third row is the ecosystem proof: two MCP servers running as
+separate subprocesses, tools from both exercised in one conversation
+(compute `17+25` with the demo server, write the result to a real file
+via the filesystem server). **One single prefix hash across all 5
+turns** — byte-stability survives concurrent MCP subprocesses.
+
+**Reproduce without an API key** (replay the committed transcripts):
+
+```bash
+npx reasonix replay benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl
+npx reasonix replay benchmarks/tau-bench/transcripts/mcp-filesystem.jsonl
+```
+
+**Reproduce with your own key** (live, ~$0.002):
 
 ```bash
-reasonix chat --mcp "node --import tsx examples/mcp-server-demo.ts"
-# ask "use add to compute 17 + 25" — model calls the MCP tool, cache holds
+# Don't know what MCP servers exist? Start here:
+reasonix mcp list
+# Prints a curated catalog (filesystem, fetch, github, sqlite, …) with
+# ready-to-paste --mcp commands.
+
+# One server:
+reasonix chat --mcp "filesystem=npx -y @modelcontextprotocol/server-filesystem /tmp/safe"
+
+# Multiple servers at once — each gets its own namespace prefix:
+reasonix chat \
+  --mcp "fs=npx -y @modelcontextprotocol/server-filesystem /tmp/safe" \
+  --mcp "mem=npx -y @modelcontextprotocol/server-memory"
+# Tools land in a shared registry as fs_read_file, mem_set, etc.
 ```
 
 [mcp]: ./benchmarks/tau-bench/transcripts/mcp-demo.add.jsonl

package/dist/cli/index.js

@@ -2004,11 +2004,25 @@ var StdioTransport = class {
   stdoutBuffer = "";
   constructor(opts) {
     const env = opts.replaceEnv ? { ...opts.env ?? {} } : { ...process.env, ...opts.env ?? {} };
-    this.child = spawn(opts.command, opts.args ?? [], {
-      env,
-      cwd: opts.cwd,
-      stdio: ["pipe", "pipe", "inherit"]
-    });
+    const shell = opts.shell ?? process.platform === "win32";
+    if (shell) {
+      const line = [
+        opts.command,
+        ...(opts.args ?? []).map((a) => quoteArg(a, process.platform === "win32"))
+      ].join(" ");
+      this.child = spawn(line, [], {
+        env,
+        cwd: opts.cwd,
+        stdio: ["pipe", "pipe", "inherit"],
+        shell: true
+      });
+    } else {
+      this.child = spawn(opts.command, opts.args ?? [], {
+        env,
+        cwd: opts.cwd,
+        stdio: ["pipe", "pipe", "inherit"]
+      });
+    }
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onStdout(chunk));
     this.child.on("close", () => this.onClose());
@@ -2082,6 +2096,12 @@ var StdioTransport = class {
     else this.queue.push(msg);
   }
 };
+function quoteArg(s, windows) {
+  if (!windows) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+  }
+  return `"${s.replace(/"/g, '""')}"`;
+}
 
 // src/mcp/registry.ts
 async function bridgeMcpTools(client, opts = {}) {
@@ -2166,7 +2186,7 @@ function redactKey(key) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0-alpha.1";
+var VERSION = "0.3.0-alpha.3";
 
 // src/cli/commands/chat.tsx
 import { render } from "ink";
@@ -2201,11 +2221,6 @@ function shellSplit(input) {
       i++;
       continue;
     }
-    if (ch === "\\" && i + 1 < s.length) {
-      cur += s[i + 1];
-      i += 2;
-      continue;
-    }
     if (ch === " " || ch === "	") {
       if (cur.length > 0) {
         tokens.push(cur);
@@ -2226,6 +2241,24 @@ function shellSplit(input) {
   return tokens;
 }
 
+// src/mcp/spec.ts
+var NAME_PREFIX = /^([a-zA-Z_][a-zA-Z0-9_]*)=(.*)$/;
+function parseMcpSpec(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("empty MCP spec");
+  }
+  const nameMatch = NAME_PREFIX.exec(trimmed);
+  const name = nameMatch ? nameMatch[1] : null;
+  const body = nameMatch ? nameMatch[2] : trimmed;
+  const argv = shellSplit(body);
+  if (argv.length === 0) {
+    throw new Error(`MCP spec has name but no command: ${input}`);
+  }
+  const [command, ...args] = argv;
+  return { name, command, args };
+}
+
 // src/cli/ui/App.tsx
 import { Box as Box6, Static, Text as Text6, useApp } from "ink";
 import React6, { useCallback, useEffect as useEffect2, useMemo, useRef, useState as useState2 } from "react";
@@ -2974,34 +3007,31 @@ function Root({ initialKey, tools, ...appProps }) {
 async function chatCommand(opts) {
   loadDotenv();
   const initialKey = loadApiKey();
-  let mcp;
+  const mcpSpecs = opts.mcp ?? [];
+  const clients = [];
   let tools;
-  if (opts.mcp) {
-    const argv = shellSplit(opts.mcp);
-    if (argv.length === 0) {
-      process.stderr.write("error: --mcp requires a command\n");
-      process.exit(2);
-    }
-    const [command, ...args] = argv;
-    if (!command) {
-      process.stderr.write("error: --mcp command is empty\n");
-      process.exit(2);
-    }
-    const transport = new StdioTransport({ command, args });
-    mcp = new McpClient({ transport });
-    try {
-      await mcp.initialize();
-      const bridge = await bridgeMcpTools(mcp, { namePrefix: opts.mcpPrefix });
-      tools = bridge.registry;
-      process.stderr.write(
-        `\u25B8 MCP: ${bridge.registeredNames.length} tool(s) from ${argv.join(" ")}
+  if (mcpSpecs.length > 0) {
+    tools = new ToolRegistry();
+    for (const raw of mcpSpecs) {
+      try {
+        const spec = parseMcpSpec(raw);
+        const prefix = spec.name ? `${spec.name}_` : mcpSpecs.length === 1 && opts.mcpPrefix ? opts.mcpPrefix : "";
+        const transport = new StdioTransport({ command: spec.command, args: spec.args });
+        const mcp2 = new McpClient({ transport });
+        await mcp2.initialize();
+        const bridge = await bridgeMcpTools(mcp2, { registry: tools, namePrefix: prefix });
+        const label = spec.name ?? "anon";
+        process.stderr.write(
+          `\u25B8 MCP[${label}]: ${bridge.registeredNames.length} tool(s) from ${spec.command} ${spec.args.join(" ")}
 `
-      );
-    } catch (err) {
-      process.stderr.write(`MCP setup failed: ${err.message}
+        );
+        clients.push(mcp2);
+      } catch (err) {
+        process.stderr.write(`MCP setup failed for "${raw}": ${err.message}
 `);
-      await mcp.close();
-      process.exit(1);
+        for (const c of clients) await c.close();
+        process.exit(1);
+      }
     }
   }
   const { waitUntilExit } = render(/* @__PURE__ */ React8.createElement(Root, { initialKey, tools, ...opts }), {
@@ -3010,7 +3040,7 @@ async function chatCommand(opts) {
   try {
     await waitUntilExit();
   } finally {
-    await mcp?.close();
+    for (const c of clients) await c.close();
   }
 }
 
@@ -3176,6 +3206,82 @@ markdown report written to ${opts.mdPath}`);
   console.log(renderSummaryTable(report));
 }
 
+// src/mcp/catalog.ts
+var MCP_CATALOG = [
+  {
+    name: "filesystem",
+    summary: "read/write/search files inside a sandboxed directory",
+    package: "@modelcontextprotocol/server-filesystem",
+    userArgs: "<dir>",
+    note: "the directory is a hard sandbox \u2014 the server refuses access outside it"
+  },
+  {
+    name: "fetch",
+    summary: "fetch URLs (markdown-friendly extraction, not a full browser)",
+    package: "@modelcontextprotocol/server-fetch"
+  },
+  {
+    name: "memory",
+    summary: "persistent key-value memory across sessions",
+    package: "@modelcontextprotocol/server-memory"
+  },
+  {
+    name: "github",
+    summary: "read issues, PRs, code search (needs GITHUB_PERSONAL_ACCESS_TOKEN)",
+    package: "@modelcontextprotocol/server-github",
+    note: "set GITHUB_PERSONAL_ACCESS_TOKEN in your env before spawning"
+  },
+  {
+    name: "sqlite",
+    summary: "read/write a sqlite database file",
+    package: "@modelcontextprotocol/server-sqlite",
+    userArgs: "<db.sqlite>"
+  },
+  {
+    name: "puppeteer",
+    summary: "browser automation \u2014 take screenshots, click, type",
+    package: "@modelcontextprotocol/server-puppeteer",
+    note: "downloads Chromium on first run (~200 MB)"
+  },
+  {
+    name: "everything",
+    summary: "official test server \u2014 exercises every MCP feature",
+    package: "@modelcontextprotocol/server-everything",
+    note: "useful for debugging your Reasonix setup"
+  }
+];
+function mcpCommandFor(entry) {
+  const pkg = entry.package;
+  const tail = entry.userArgs ? ` ${entry.userArgs}` : "";
+  return `--mcp "${entry.name}=npx -y ${pkg}${tail}"`;
+}
+
+// src/cli/commands/mcp.ts
+function mcpListCommand(opts) {
+  if (opts.json) {
+    console.log(JSON.stringify(MCP_CATALOG, null, 2));
+    return;
+  }
+  console.log("Popular MCP servers you can bridge into Reasonix:");
+  console.log("");
+  for (const entry of MCP_CATALOG) {
+    console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
+    console.log(`               ${mcpCommandFor(entry)}`);
+    if (entry.note) console.log(`               \xB7 ${entry.note}`);
+    console.log("");
+  }
+  console.log("Usage:  reasonix chat <one-of-the---mcp-lines-above>");
+  console.log(
+    "Docs:   https://github.com/modelcontextprotocol/servers  \u2014  Anthropic's official server repo"
+  );
+  console.log(
+    "        https://mcp.so                                   \u2014  community-maintained catalog"
+  );
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
 // src/cli/commands/replay.ts
 import { render as render3 } from "ink";
 import React13 from "react";
@@ -3366,29 +3472,31 @@ async function runCommand(opts) {
   loadDotenv();
   const apiKey = await ensureApiKey();
   process.env.DEEPSEEK_API_KEY = apiKey;
-  let mcp;
+  const mcpSpecs = opts.mcp ?? [];
+  const clients = [];
   let tools;
-  if (opts.mcp) {
-    const argv = shellSplit(opts.mcp);
-    const [command, ...args] = argv;
-    if (!command) {
-      process.stderr.write("error: --mcp command is empty\n");
-      process.exit(2);
-    }
-    mcp = new McpClient({ transport: new StdioTransport({ command, args }) });
-    try {
-      await mcp.initialize();
-      const bridge = await bridgeMcpTools(mcp, { namePrefix: opts.mcpPrefix });
-      tools = bridge.registry;
-      process.stderr.write(
-        `\u25B8 MCP: ${bridge.registeredNames.length} tool(s) from ${argv.join(" ")}
+  if (mcpSpecs.length > 0) {
+    tools = new ToolRegistry();
+    for (const raw of mcpSpecs) {
+      try {
+        const spec = parseMcpSpec(raw);
+        const prefix2 = spec.name ? `${spec.name}_` : mcpSpecs.length === 1 && opts.mcpPrefix ? opts.mcpPrefix : "";
+        const mcp2 = new McpClient({
+          transport: new StdioTransport({ command: spec.command, args: spec.args })
+        });
+        await mcp2.initialize();
+        const bridge = await bridgeMcpTools(mcp2, { registry: tools, namePrefix: prefix2 });
+        process.stderr.write(
+          `\u25B8 MCP[${spec.name ?? "anon"}]: ${bridge.registeredNames.length} tool(s) from ${spec.command} ${spec.args.join(" ")}
 `
-      );
-    } catch (err) {
-      process.stderr.write(`MCP setup failed: ${err.message}
+        );
+        clients.push(mcp2);
+      } catch (err) {
+        process.stderr.write(`MCP setup failed for "${raw}": ${err.message}
 `);
-      await mcp.close();
-      process.exit(1);
+        for (const c of clients) await c.close();
+        process.exit(1);
+      }
     }
   }
   const client = new DeepSeekClient();
@@ -3450,7 +3558,7 @@ transcript: ${opts.transcript}
     process.stdout.write(`  \u2192 npx reasonix replay ${opts.transcript}
 `);
   }
-  await mcp?.close();
+  for (const c of clients) await c.close();
 }
 
 // src/cli/commands/sessions.ts
@@ -3575,9 +3683,14 @@ program.command("chat").description("Interactive Ink TUI with live cache/cost pa
   "--session <name>",
   "Use a named session (default: 'default'). Resume the same session next time."
 ).option("--no-session", "Disable session persistence for this run (ephemeral chat)").option(
-  "--mcp <command>",
-  'Spawn an MCP server and bridge its tools. Shell-quoted: --mcp "npx -y @scope/server-x /path"'
-).option("--mcp-prefix <str>", "Prefix prepended to every MCP tool name (avoid collisions)").action(async (opts) => {
+  "--mcp <spec>",
+  'MCP server spec; repeatable. Forms: "name=cmd args..." (namespaced, tools get `name_` prefix) or "cmd args..." (anonymous). Example: --mcp "fs=npx -y @scope/fs /tmp" --mcp "gh=npx -y @scope/gh"',
+  (value, previous = []) => [...previous, value],
+  []
+).option(
+  "--mcp-prefix <str>",
+  "Global prefix applied to every MCP tool (only honored when no per-spec name is set; avoids collisions with a single anonymous server)"
+).action(async (opts) => {
   let session;
   if (opts.session === false) {
     session = void 0;
@@ -3605,9 +3718,14 @@ program.command("run <task>").description("Run a single task non-interactively,
   "Self-consistency: run N parallel samples per turn and pick the most confident",
   (v) => Number.parseInt(v, 10)
 ).option("--transcript <path>", "Write a JSONL transcript to this path for replay/diff").option(
-  "--mcp <command>",
-  'Spawn an MCP server and bridge its tools. Shell-quoted: --mcp "npx -y @scope/server-x /path"'
-).option("--mcp-prefix <str>", "Prefix prepended to every MCP tool name (avoid collisions)").action(async (task, opts) => {
+  "--mcp <spec>",
+  'MCP server spec; repeatable. "name=cmd args..." or "cmd args...".',
+  (value, previous = []) => [...previous, value],
+  []
+).option(
+  "--mcp-prefix <str>",
+  "Global prefix (only honored when no per-spec name is set; for a single anonymous server)"
+).action(async (task, opts) => {
   await runCommand({
     task,
     model: opts.model,
@@ -3648,6 +3766,10 @@ program.command("diff <a> <b>").description(
     tui: !!opts.tui
   });
 });
+var mcp = program.command("mcp").description("Model Context Protocol helpers \u2014 discover servers, test your setup.");
+mcp.command("list").description("Show a curated catalog of popular MCP servers with ready-to-use --mcp commands.").option("--json", "Emit the catalog as JSON instead of the human-readable table").action((opts) => {
+  mcpListCommand({ json: !!opts.json });
+});
 program.command("version").description("Print Reasonix version.").action(versionCommand);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err);