@goke/mcp 0.0.9 → 0.0.10

package/src/__test__/http-multi-tenant.test.ts

@@ -0,0 +1,383 @@
+/**
+ * Multi-tenant remote-MCP test.
+ *
+ * Proves that one goke cli exposed over the MCP streamable-HTTP
+ * transport can serve multiple concurrent users with fully isolated
+ * state (in-memory fs + cwd + env) — no shared host process stdio,
+ * no cross-tenant leaks.
+ *
+ * Wiring choices worth calling out:
+ *
+ *   - `WebStandardStreamableHTTPServerTransport` from the MCP SDK
+ *     accepts a Web-Standard `Request` and returns a `Response`.
+ *     That means we can drive it **in-process** through the client
+ *     transport's `fetch` hook without ever binding a TCP socket
+ *     or spinning up `node:http` / Express. Same wire protocol,
+ *     zero sockets.
+ *   - `enableJsonResponse: true` switches the transport off SSE and
+ *     into pure request/response JSON. GET SSE opens are answered
+ *     with `405`, which the client treats as "server does not offer
+ *     SSE" and moves on (see `_startOrAuthSse` in the SDK client).
+ *   - Each session gets its own cli **clone** via
+ *     `baseCli.clone({ cwd, env, fs })`. The clone inherits the
+ *     command tree but owns its own `{ cwd, env, fs }`, which is
+ *     what `runCliTool` forwards into every action through
+ *     `ctx.process.*` / `ctx.fs`.
+ */
+
+import { randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
+import path from "node:path";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server as McpLowLevelServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { goke, type Goke, type GokeFs } from "goke";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { addCliToolsToMcp } from "../cli-to-mcp.js";
+
+// ─── Minimal in-memory fs ─────────────────────────────────────────
+
+/**
+ * Dead-simple `GokeFs` backed by a `Map<string, string>`.
+ *
+ * Implements only the methods the cli commands in this test
+ * actually call (`writeFile`, `readFile`, `mkdir`). Every other
+ * method throws so accidental real-fs usage would fail loudly.
+ */
+const notImplemented = (name: string) => () => {
+  throw new Error(`InMemoryFs.${name} not implemented for this test`);
+};
+
+class InMemoryFs implements GokeFs {
+  readonly files = new Map<string, string>();
+
+  writeFile: GokeFs["writeFile"] = async (filePath, data) => {
+    const key = String(filePath);
+    const text = typeof data === "string"
+      ? data
+      : new TextDecoder("utf-8").decode(data);
+    this.files.set(key, text);
+  };
+
+  readFile: GokeFs["readFile"] = async (filePath) => {
+    const key = String(filePath);
+    const content = this.files.get(key);
+    if (content === undefined) {
+      throw new Error(`ENOENT: ${key}`);
+    }
+    return content;
+  };
+
+  mkdir: GokeFs["mkdir"] = async () => undefined;
+
+  appendFile: GokeFs["appendFile"] = notImplemented("appendFile");
+  chmod: GokeFs["chmod"] = notImplemented("chmod");
+  copyFile: GokeFs["copyFile"] = notImplemented("copyFile");
+  link: GokeFs["link"] = notImplemented("link");
+  readlink: GokeFs["readlink"] = notImplemented("readlink");
+  realpath: GokeFs["realpath"] = notImplemented("realpath");
+  rename: GokeFs["rename"] = notImplemented("rename");
+  rm: GokeFs["rm"] = notImplemented("rm");
+  symlink: GokeFs["symlink"] = notImplemented("symlink");
+  utimes: GokeFs["utimes"] = notImplemented("utimes");
+}
+
+// ─── Shared cli definition ────────────────────────────────────────
+
+/**
+ * One cli definition, reused across tenants. Commands read / write
+ * through `ctx.fs` and resolve paths against `ctx.process.cwd`, so
+ * the *same* code runs per tenant but talks to a tenant-specific
+ * filesystem when invoked via the session-scoped clone below.
+ */
+function buildBaseCli(): Goke {
+  const cli = goke("notes-app");
+
+  cli
+    .command("save <filename>", "Save content to a file in the tenant workspace")
+    .option("--content <content>", z.string().describe("File content"))
+    .action(async (filename: string, options: { content: string }, ctx) => {
+      const full = path.posix.join(ctx.process.cwd, filename);
+      await ctx.fs.writeFile(full, options.content);
+      return { saved: full, tenant: ctx.process.env.TENANT_ID };
+    });
+
+  cli
+    .command("load <filename>", "Read a file from the tenant workspace")
+    .action(async (filename: string, _options, ctx) => {
+      const full = path.posix.join(ctx.process.cwd, filename);
+      const text = await ctx.fs.readFile(full, "utf8");
+      return { path: full, text, tenant: ctx.process.env.TENANT_ID };
+    });
+
+  return cli;
+}
+
+// ─── In-process multi-tenant fetch ────────────────────────────────
+
+/**
+ * Per-tenant state resolved from the `x-tenant-id` header on a
+ * session-initialization request. Each tenant gets its own cwd,
+ * env, and in-memory fs.
+ */
+interface TenantState {
+  cwd: string;
+  env: Record<string, string>;
+  fs: InMemoryFs;
+}
+
+/**
+ * Build a `FetchLike` that routes MCP streamable-HTTP traffic into
+ * in-process session-scoped `WebStandardStreamableHTTPServerTransport`
+ * instances. One transport + one cli clone per session. Each session
+ * is keyed by `mcp-session-id`; initialization requests pick a tenant
+ * via the `x-tenant-id` header.
+ *
+ * Returns both the custom fetch and the transports map so tests can
+ * inspect session state if needed.
+ */
+function createMultiTenantFetch(options: {
+  baseCli: Goke;
+  resolveTenant: (tenantId: string) => TenantState;
+}): {
+  fetch: FetchLike;
+  transports: Map<string, WebStandardStreamableHTTPServerTransport>;
+} {
+  const { baseCli, resolveTenant } = options;
+  const transports = new Map<string, WebStandardStreamableHTTPServerTransport>();
+
+  const customFetch: FetchLike = async (url, init) => {
+    const method = (init?.method ?? "GET").toUpperCase();
+    const headers = new Headers(init?.headers);
+
+    // Pure request/response mode: tell the client there's no SSE
+    // available on GET. `_startOrAuthSse` in the SDK client treats
+    // 405 as "server does not offer SSE" and moves on gracefully.
+    if (method === "GET") {
+      return new Response(null, { status: 405 });
+    }
+
+    // Parse POST body once and hand it to the transport via
+    // `parsedBody` in `HandleRequestOptions` so we don't have to
+    // worry about Request body streams being single-use.
+    let parsedBody: unknown = undefined;
+    if (method === "POST" && init?.body != null) {
+      const rawBody = init.body;
+      const bodyText = typeof rawBody === "string"
+        ? rawBody
+        : await new Response(rawBody).text();
+      if (bodyText) {
+        parsedBody = JSON.parse(bodyText);
+      }
+    }
+
+    // Rebuild a plain Request with the same method + headers. The
+    // transport reads accept/content-type from here and uses
+    // `parsedBody` for the actual JSON-RPC payload.
+    const request = new Request(url.toString(), {
+      method,
+      headers,
+    });
+
+    const sessionId = headers.get("mcp-session-id");
+
+    // Existing session: route to its transport.
+    if (sessionId && transports.has(sessionId)) {
+      return transports.get(sessionId)!.handleRequest(request, { parsedBody });
+    }
+
+    // New session: must be an initialize POST.
+    if (method !== "POST" || !isInitializeRequest(parsedBody)) {
+      return new Response(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+          id: null,
+        }),
+        { status: 400, headers: { "content-type": "application/json" } },
+      );
+    }
+
+    // Resolve the tenant from the custom header, build a cli clone
+    // with its cwd/env/fs, and spin up a session-scoped MCP server.
+    const tenantId = headers.get("x-tenant-id");
+    if (!tenantId) {
+      return new Response("missing x-tenant-id header", { status: 401 });
+    }
+    const tenant = resolveTenant(tenantId);
+
+    const tenantCli = baseCli.clone({
+      cwd: tenant.cwd,
+      env: { ...tenant.env, TENANT_ID: tenantId },
+      fs: tenant.fs,
+    });
+
+    const mcpServer = new McpLowLevelServer(
+      { name: "notes-app-mcp", version: "1.0.0" },
+      { capabilities: {} },
+    );
+    addCliToolsToMcp({ cli: tenantCli, server: mcpServer });
+
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      // Pure request/response — no SSE streaming to clean up.
+      enableJsonResponse: true,
+      onsessioninitialized: (sid) => {
+        transports.set(sid, transport);
+      },
+      onsessionclosed: (sid) => {
+        transports.delete(sid);
+      },
+    });
+
+    transport.onclose = () => {
+      const sid = transport.sessionId;
+      if (sid) {
+        transports.delete(sid);
+      }
+    };
+
+    await mcpServer.connect(transport);
+    return transport.handleRequest(request, { parsedBody });
+  };
+
+  return { fetch: customFetch, transports };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────
+
+describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () => {
+  function setupScenario() {
+    const baseCli = buildBaseCli();
+    const tenants = new Map<string, TenantState>();
+    tenants.set("tenant-a", {
+      cwd: "/workspace-a",
+      env: { ROLE: "writer" },
+      fs: new InMemoryFs(),
+    });
+    tenants.set("tenant-b", {
+      cwd: "/workspace-b",
+      env: { ROLE: "reader" },
+      fs: new InMemoryFs(),
+    });
+
+    const { fetch: tenantFetch } = createMultiTenantFetch({
+      baseCli,
+      resolveTenant: (id) => {
+        const tenant = tenants.get(id);
+        if (!tenant) throw new Error(`unknown tenant ${id}`);
+        return tenant;
+      },
+    });
+
+    // The URL is a placeholder — the in-process fetch never looks
+    // at the host, just the method/headers/body.
+    const endpoint = new URL("http://in-memory-mcp.test/mcp");
+
+    async function connectTenant(tenantId: string): Promise<Client> {
+      const transport = new StreamableHTTPClientTransport(endpoint, {
+        fetch: tenantFetch,
+        requestInit: {
+          headers: {
+            "x-tenant-id": tenantId,
+          },
+        },
+      });
+      const client = new Client(
+        { name: `${tenantId}-client`, version: "1.0.0" },
+        { capabilities: {} },
+      );
+      await client.connect(transport);
+      return client;
+    }
+
+    return { tenants, connectTenant };
+  }
+
+  function firstTextBlock(result: Awaited<ReturnType<Client["callTool"]>>): string {
+    const content = (result as { content?: Array<{ type: string; text?: string }> }).content ?? [];
+    return content.find((block) => block.type === "text")?.text ?? "";
+  }
+
+  it("routes each session to its own cli clone with tenant-specific cwd/env/fs", async () => {
+    const { tenants, connectTenant } = setupScenario();
+
+    const aliceClient = await connectTenant("tenant-a");
+    const bobClient = await connectTenant("tenant-b");
+
+    try {
+      // Each client sees the same tool catalog — it comes from the
+      // shared cli definition.
+      const aliceTools = (await aliceClient.listTools()).tools.map((t) => t.name).sort();
+      const bobTools = (await bobClient.listTools()).tools.map((t) => t.name).sort();
+      expect(aliceTools).toEqual(["load", "save"]);
+      expect(bobTools).toEqual(["load", "save"]);
+
+      // Both tenants write a file called `notes.txt` with different
+      // content. Since each session uses its own cli clone (with
+      // its own cwd + fs), the writes land in separate Maps.
+      const aliceSave = await aliceClient.callTool({
+        name: "save",
+        arguments: { filename: "notes.txt", content: "alice-secret" },
+      });
+      const bobSave = await bobClient.callTool({
+        name: "save",
+        arguments: { filename: "notes.txt", content: "bob-secret" },
+      });
+
+      expect(firstTextBlock(aliceSave)).toContain("/workspace-a/notes.txt");
+      expect(firstTextBlock(aliceSave)).toContain("tenant-a");
+      expect(firstTextBlock(bobSave)).toContain("/workspace-b/notes.txt");
+      expect(firstTextBlock(bobSave)).toContain("tenant-b");
+
+      // Each tenant reads back what it wrote.
+      const aliceLoad = await aliceClient.callTool({
+        name: "load",
+        arguments: { filename: "notes.txt" },
+      });
+      const bobLoad = await bobClient.callTool({
+        name: "load",
+        arguments: { filename: "notes.txt" },
+      });
+
+      expect(firstTextBlock(aliceLoad)).toContain("alice-secret");
+      expect(firstTextBlock(aliceLoad)).not.toContain("bob-secret");
+      expect(firstTextBlock(bobLoad)).toContain("bob-secret");
+      expect(firstTextBlock(bobLoad)).not.toContain("alice-secret");
+
+      // Sanity check: the underlying in-memory maps really are
+      // disjoint. Tenant A's fs only has tenant A's file.
+      const tenantAFs = tenants.get("tenant-a")!.fs;
+      const tenantBFs = tenants.get("tenant-b")!.fs;
+      expect([...tenantAFs.files.keys()]).toEqual(["/workspace-a/notes.txt"]);
+      expect([...tenantBFs.files.keys()]).toEqual(["/workspace-b/notes.txt"]);
+      expect(tenantAFs.files.get("/workspace-a/notes.txt")).toBe("alice-secret");
+      expect(tenantBFs.files.get("/workspace-b/notes.txt")).toBe("bob-secret");
+    } finally {
+      await aliceClient.close();
+      await bobClient.close();
+    }
+  });
+
+  it("raises a tool error when a tenant reads a file it never wrote", async () => {
+    const { connectTenant } = setupScenario();
+
+    const bobClient = await connectTenant("tenant-b");
+    try {
+      const result = await bobClient.callTool({
+        name: "load",
+        arguments: { filename: "does-not-exist.txt" },
+      });
+      expect(result.isError).toBe(true);
+      expect(firstTextBlock(result)).toMatch(/ENOENT/);
+    } finally {
+      await bobClient.close();
+    }
+  });
+});

package/src/cli-to-mcp.ts

@@ -16,7 +16,16 @@ import {
   type CallToolResult,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
-import { coerceBySchema, extractJsonSchema, type Command, type Goke, type StandardJSONSchemaV1 } from "goke";
+import {
+  coerceBySchema,
+  extractJsonSchema,
+  GokeProcessExit,
+  type Command,
+  type Goke,
+  type GokeExecutionContext,
+  type GokeOutputStream,
+  type StandardJSONSchemaV1,
+} from "goke";
 
 const CLI_TO_MCP_STATE = Symbol.for("@goke/mcp/cli-to-mcp-state");
 
@@ -44,11 +53,43 @@ interface OptionBinding {
 interface CliToolBinding {
   tool: Tool;
   command: Command;
+  /**
+   * The goke cli that owns this command. Used at tool-call time to
+   * build a `GokeExecutionContext` (console/fs/process) via
+   * `cli.createExecutionContext(override)` so actions receive the same
+   * injected context they would when invoked from the command line.
+   */
+  cli: Goke;
   positionalArgs: CommandArgLike[];
   options: OptionBinding[];
   requiredNames: string[];
 }
 
+/**
+ * A `GokeOutputStream` that accumulates writes into a string.
+ *
+ * Used to capture what an action writes through `ctx.console.log` /
+ * `ctx.console.error` / `ctx.process.stdout` / `ctx.process.stderr`
+ * so it can be surfaced in the MCP `CallToolResult.content` instead of
+ * leaking into the host process stdout (which, for the stdio MCP
+ * transport, is the JSON-RPC channel itself).
+ */
+interface TextCaptureStream extends GokeOutputStream {
+  readonly text: string;
+}
+
+function createTextCaptureStream(): TextCaptureStream {
+  const chunks: string[] = [];
+  return {
+    get text() {
+      return chunks.join("");
+    },
+    write(data: string) {
+      chunks.push(data);
+    },
+  };
+}
+
 interface CliToMcpState {
   toolsByName: Map<string, CliToolBinding>;
   commandToToolName: Map<string, string>;
@@ -254,6 +295,107 @@ function isToolNotFoundResult(result: unknown, toolName: string): boolean {
   return text.includes("tool") && text.includes("not found") && text.includes(toolName.toLowerCase());
 }
 
+/**
+ * Build the same `GokeExecutionContext` an action would receive from
+ * `cli.parse()`, but with capture streams for stdout/stderr and an
+ * `exit` that throws `GokeProcessExit` instead of killing the host
+ * process.
+ *
+ * Capturing is required for the stdio MCP transport because the host
+ * `process.stdout` is the JSON-RPC channel — any write to it would
+ * corrupt the protocol. Capturing is also what lets us surface
+ * `ctx.console.log` output in the `CallToolResult.content`.
+ */
+function createCallToolExecutionContext(cli: Goke): {
+  ctx: GokeExecutionContext;
+  stdout: TextCaptureStream;
+  stderr: TextCaptureStream;
+} {
+  const stdout = createTextCaptureStream();
+  const stderr = createTextCaptureStream();
+  const ctx = cli.createExecutionContext({
+    stdout,
+    stderr,
+    // Swallow the user-level exit: the outer createExecutionContext
+    // wrapper will still throw `GokeProcessExit` after this returns,
+    // which `runCliTool` catches and turns into a `CallToolResult`.
+    exit: () => {},
+  });
+  return { ctx, stdout, stderr };
+}
+
+/**
+ * Build a `CallToolResult` from an action's return value plus any
+ * text that was captured from the injected `ctx.console` /
+ * `ctx.process.stdout` / `ctx.process.stderr` streams.
+ *
+ * Precedence rules:
+ *   1. If the action returned a ready-made `CallToolResult` (object
+ *      with a `content` key), honor it as-is. Captured output is
+ *      ignored to give authors a fully manual escape hatch.
+ *   2. If anything was captured on stdout or stderr, emit one text
+ *      block per non-empty stream (stdout first, then stderr) and
+ *      append the stringified return value as a trailing block when
+ *      it is non-empty. This keeps warnings written via
+ *      `ctx.console.error` / `ctx.process.stderr.write` from being
+ *      silently dropped when the action also returns a value.
+ *   3. Otherwise fall back to the legacy behavior (stringify the
+ *      return value, empty string when `undefined`).
+ */
+function buildCallToolResult(
+  returnValue: unknown,
+  capturedStdout: string,
+  capturedStderr: string,
+): CallToolResult {
+  if (returnValue && typeof returnValue === "object" && "content" in returnValue) {
+    return returnValue as CallToolResult;
+  }
+
+  if (capturedStdout || capturedStderr) {
+    const blocks: Array<{ type: "text"; text: string }> = [];
+    if (capturedStdout) {
+      blocks.push({ type: "text", text: capturedStdout });
+    }
+    if (capturedStderr) {
+      blocks.push({ type: "text", text: capturedStderr });
+    }
+    const valueText = formatTextResult(returnValue);
+    if (valueText) {
+      blocks.push({ type: "text", text: valueText });
+    }
+    return { content: blocks };
+  }
+
+  return toCallToolResult(returnValue);
+}
+
+/**
+ * Build an error `CallToolResult` from captured output + the process
+ * exit code thrown by `ctx.process.exit(code)`. Mirrors the
+ * `{ stdout, stderr, exitCode }` shape just-bash produces, but in the
+ * MCP content-block format.
+ */
+function buildProcessExitResult(
+  exitCode: number,
+  capturedStdout: string,
+  capturedStderr: string,
+): CallToolResult {
+  const content: Array<{ type: "text"; text: string }> = [];
+  if (capturedStdout) {
+    content.push({ type: "text", text: capturedStdout });
+  }
+  if (capturedStderr) {
+    content.push({ type: "text", text: capturedStderr });
+  }
+  if (content.length === 0) {
+    content.push({ type: "text", text: `Process exited with code ${exitCode}` });
+  }
+  return {
+    isError: exitCode !== 0,
+    content,
+  };
+}
+
 async function runCliTool(binding: CliToolBinding, argumentsObject: Record<string, unknown>): Promise<CallToolResult> {
   for (const requiredName of binding.requiredNames) {
     if (getToolCallArguments(argumentsObject, requiredName) === undefined) {
@@ -303,19 +445,38 @@ async function runCliTool(binding: CliToolBinding, argumentsObject: Record<strin
     throw new McpError(ErrorCode.InvalidParams, `Command ${binding.command.name} has no action`);
   }
 
+  // Build the same execution context an action would see when invoked
+  // from the command line, but with capture streams + a no-op `exit`
+  // so tool calls can't corrupt the MCP transport or kill the host.
+  const { ctx, stdout, stderr } = createCallToolExecutionContext(binding.cli);
+
   try {
-    const result = await Promise.resolve(action(...positionalValues, optionsObject));
-    return toCallToolResult(result);
+    // Match `Goke#runMatchedCommand` by calling the action with the
+    // owning cli as `this`. Keeps behavior parity for JS authors who
+    // reference `this.name` / `this.options` from inside an action.
+    const result = await Promise.resolve(
+      action.apply(binding.cli, [...positionalValues, optionsObject, ctx]),
+    );
+    return buildCallToolResult(result, stdout.text, stderr.text);
   } catch (error) {
+    if (error instanceof GokeProcessExit) {
+      return buildProcessExitResult(error.code, stdout.text, stderr.text);
+    }
     const message = error instanceof Error ? error.message : String(error);
+    const content: Array<{ type: "text"; text: string }> = [
+      { type: "text", text: message },
+    ];
+    if (stderr.text) {
+      content.push({ type: "text", text: stderr.text });
+    }
     return {
       isError: true,
-      content: [{ type: "text", text: message }],
+      content,
     };
   }
 }
 
-function createBinding(command: Command, toolName: string): CliToolBinding {
+function createBinding(cli: Goke, command: Command, toolName: string): CliToolBinding {
   const positionalArgs = command.args as unknown as CommandArgLike[];
   const options = command.options as unknown as OptionLike[];
 
@@ -370,6 +531,7 @@ function createBinding(command: Command, toolName: string): CliToolBinding {
       inputSchema,
     },
     command,
+    cli,
     positionalArgs,
     options: optionBindings,
     requiredNames: Array.from(new Set(requiredNames)),
@@ -561,7 +723,7 @@ export function addCliToolsToMcp(options: AddCliToolsToMcpOptions): void {
     const toolName = uniqueToolName(baseToolName, usedNames);
     usedNames.add(toolName);
 
-    const binding = createBinding(command, toolName);
+    const binding = createBinding(cli, command, toolName);
     state.toolsByName.set(toolName, binding);
     state.commandToToolName.set(command.name, toolName);
   }