@goke/mcp 0.0.9 → 0.0.11

package/README.md

@@ -51,6 +51,7 @@ await addMcpCommands({
 })
 
 cli.help()
+cli.completions()
 cli.parse()
 ```
 
@@ -93,6 +94,7 @@ cli.command("mcp", "Start MCP server over stdio")
   .action(createMcpAction({ cli }))
 
 cli.help()
+cli.completions()
 cli.parse()
 ```
 
@@ -172,6 +174,217 @@ mcp.tool("custom-tool", "A tool defined directly", async () => ({ ... }))
 addCliToolsToMcp({ cli, server: mcp })
 ```
 
+## Multi-tenant remote MCP over HTTP
+
+When you expose a cli as a **remote** MCP (over `StreamableHTTPServerTransport`, SSE, or any other network transport), one server process handles many concurrent users. Each tool call must run against that user's own filesystem, working directory, environment, and stdin — otherwise tenants see each other's state and stdio writes trample the JSON-RPC channel.
+
+The recipe is:
+
+1. Define the cli **once**.
+2. On every new MCP session, **clone** the cli with per-tenant `{ cwd, env, fs, stdin }` and mount it on a fresh session-scoped `Server` via `addCliToolsToMcp({ cli: tenantClone, server })`.
+3. Inside command actions, always use the **injected** `ctx` — `ctx.fs`, `ctx.process.cwd`, `ctx.process.env`, `ctx.console.log` — instead of the Node globals. `@goke/mcp` wires each tool call into the tenant's cloned context, but only code that goes through `ctx` participates in that isolation.
+
+### Write commands against `ctx`
+
+```ts
+import { goke } from "goke"
+import { z } from "zod"
+import path from "node:path"
+
+const cli = goke("notes-app")
+
+cli
+  .command("save <filename>", "Save content into the user's workspace")
+  .option("--content <content>", z.string().describe("File content"))
+  .action(async (filename, options, 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>", "Load a file from the user's workspace")
+  .action(async (filename, _options, ctx) => {
+    const full = path.posix.join(ctx.process.cwd, filename)
+    const text = await ctx.fs.readFile(full, "utf8")
+    return { path: full, text }
+  })
+```
+
+`ctx.fs` satisfies the `GokeFs` interface — a Node-compatible async filesystem API. You can point it at a real directory, a virtual in-memory store, an S3 bucket adapter, a `memfs`, or anything else you can wrap behind that interface.
+
+### Clone the cli per session
+
+The MCP SDK ships `WebStandardStreamableHTTPServerTransport`, which accepts a Web-Standard `Request` and returns a `Response`. That one shape plugs directly into **any** web framework that speaks web-standard: [Spiceflow](https://github.com/remorses/spiceflow), Cloudflare Workers, Deno, Bun, Next.js route handlers, SvelteKit endpoints, or a raw `fetch`-based handler. No Express, no `node:http` wiring, no framework lock-in.
+
+You build one `handleMcpRequest(request: Request): Promise<Response>` function and mount it wherever you route HTTP:
+
+```ts
+import { randomUUID } from "node:crypto"
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js"
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"
+import { addCliToolsToMcp } from "@goke/mcp"
+import type { GokeFs } from "goke"
+
+// Wherever you store per-user state — DB, Redis, config files, etc.
+declare function resolveTenant(tenantId: string): {
+  cwd: string
+  env: Record<string, string>
+  fs: GokeFs   // your filesystem adapter
+}
+
+const transports = new Map<string, WebStandardStreamableHTTPServerTransport>()
+
+export async function handleMcpRequest(request: Request): Promise<Response> {
+  // Pre-parse the body so we can use it for both routing decisions
+  // (is this an `initialize` request?) and as the pre-parsed body
+  // forwarded to the transport via `HandleRequestOptions.parsedBody`.
+  let parsedBody: unknown
+  if (request.method === "POST") {
+    parsedBody = await request.clone().json().catch(() => undefined)
+  }
+
+  const sessionId = request.headers.get("mcp-session-id")
+
+  // Existing session — route to its transport.
+  if (sessionId && transports.has(sessionId)) {
+    return transports.get(sessionId)!.handleRequest(request, { parsedBody })
+  }
+
+  // No session yet — must be an `initialize` request.
+  if (!isInitializeRequest(parsedBody)) {
+    return Response.json(
+      {
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Bad Request: No valid session ID provided" },
+        id: null,
+      },
+      { status: 400 },
+    )
+  }
+
+  // Derive the tenant from whatever header/cookie/JWT you use.
+  const tenantId = request.headers.get("x-tenant-id")
+  if (!tenantId) return new Response("missing x-tenant-id", { status: 401 })
+  const tenant = resolveTenant(tenantId)
+
+  // Clone the base cli with tenant-specific cwd/env/fs. Every tool
+  // call on this session now sees the tenant's state via `ctx`.
+  const tenantCli = baseCli.clone({
+    cwd: tenant.cwd,
+    env: { ...tenant.env, TENANT_ID: tenantId },
+    fs: tenant.fs,
+  })
+
+  const mcpServer = new McpServer(
+    { name: "notes-app-mcp", version: "1.0.0" },
+    { capabilities: {} },
+  )
+  addCliToolsToMcp({ cli: tenantCli, server: mcpServer })
+
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+    enableJsonResponse: true, // pure request/response; no SSE to manage
+    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 })
+}
+```
+
+Now plug `handleMcpRequest` into whichever web runtime you use:
+
+```ts
+// Spiceflow — runs on Node, Bun, and Cloudflare Workers with the same code
+import { Spiceflow } from "spiceflow"
+
+export const app = new Spiceflow()
+  .route({
+    method: "*",
+    path: "/mcp",
+    handler: ({ request }) => handleMcpRequest(request),
+  })
+
+app.listen(3000)
+
+// Cloudflare Workers / Deno / Bun
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname === "/mcp") return handleMcpRequest(request)
+    return new Response("not found", { status: 404 })
+  },
+}
+
+// Next.js app router
+export async function POST(request: Request) {
+  return handleMcpRequest(request)
+}
+```
+
+**Key guarantees**
+
+- Every tool call inside a session runs against `tenantCli`'s `cwd` / `env` / `fs` — not the base cli's and not another tenant's.
+- `ctx.console.log` / `ctx.console.error` / `ctx.process.stdout.write` / `ctx.process.stderr.write` are captured into the `CallToolResult.content`. They never reach the host process stdio, so they can't corrupt the JSON-RPC channel or leak between users.
+- `ctx.process.exit(code)` throws `GokeProcessExit` instead of killing the server. The tool call resolves as `{ isError: code !== 0, content: [captured output] }` and the next request keeps running.
+- Actions that `throw` are caught and returned as `{ isError: true, content: [message, stderr] }`.
+
+**Bypass hazards**
+
+Only code that flows through `ctx` participates in the isolation. The following **bypass** it and will leak across tenants or kill the host process:
+
+- `import fs from "node:fs"` inside a command action — reads/writes the real disk.
+- `console.log(...)` / `console.error(...)` — writes to the real server stdio.
+- `process.exit(1)` — terminates the entire host process.
+- `process.cwd()` / `process.env.X` at module load time — snapshots the server's values, not the tenant's.
+
+Port those to `ctx.fs`, `ctx.console`, `ctx.process.*` and you're multi-tenant-safe.
+
+For a runnable end-to-end example (including two concurrent in-memory-fs tenants writing separate files), see [`src/__test__/http-multi-tenant.test.ts`](./src/__test__/http-multi-tenant.test.ts).
+
+### Lower-level primitive: `cli.createExecutionContext(override)`
+
+If you're building a custom transport or a non-HTTP multi-tenant adapter, the underlying goke primitive is:
+
+```ts
+import { GokeProcessExit, type GokeExecutionContextOverride } from "goke"
+
+const override: GokeExecutionContextOverride = {
+  cwd: tenant.cwd,
+  env: tenant.env,
+  fs: tenant.fs,
+  stdin: tenant.stdin,
+  stdout: captureStdoutStream,
+  stderr: captureStderrStream,
+  exit: () => {}, // throw-only: the wrapper still throws GokeProcessExit
+}
+
+const ctx = cli.createExecutionContext(override)
+
+try {
+  await action(...positionalArgs, options, ctx)
+} catch (err) {
+  if (err instanceof GokeProcessExit) {
+    // handle the exit code — the host process is untouched
+  } else {
+    throw err
+  }
+}
+```
+
+`addCliToolsToMcp` builds this context for you on every tool call. Call it yourself if you need finer control (e.g. per-request capture streams for custom routing, synthetic `argv`, or serving MCP from a non-Node runtime that implements `GokeFs` differently).
+
 ## Full example (with config persistence)
 
 This is the pattern used by [notion-mcp-cli](../notion-mcp-cli):
@@ -241,6 +454,7 @@ cli.command('logout', 'Clear tokens').action(() => {
 })
 
 cli.help()
+cli.completions()
 cli.parse()
 ```
 

package/dist/__test__/add-cli-tools-to-mcp.test.js

@@ -20,6 +20,8 @@ function createCli() {
         const message = `Hello ${options.name}!`;
         return options.caps ? message.toUpperCase() : message;
     });
+    // sum-values uses wrapJsonSchema whose output is `unknown`, so values are
+    // cast with Number() inside the action.
     cli
         .command("sum-values", "Add two numbers")
         .option("--left <left>", wrapJsonSchema({
@@ -31,7 +33,7 @@ function createCli() {
         description: "Right operand",
     }))
         .action((options) => ({
-        sum: options.left + options.right,
+        sum: Number(options.left) + Number(options.right),
     }));
     cli
         .command("echo <message>", "Echo positional message")
@@ -41,7 +43,7 @@ function createCli() {
         description: "Repeat count",
     }))
         .action((message, options) => {
-        return message.repeat(options.repeat);
+        return message.repeat(Number(options.repeat));
     });
     cli
         .command("string-options", "Infer option types from plain string descriptions")
@@ -397,3 +399,222 @@ describe("addCliToolsToMcp", () => {
         }
     });
 });
+/**
+ * Spin up a live MCP client/server pair wired to a single cli.
+ *
+ * Used by the execution-context tests below to keep the boilerplate
+ * out of each test body.
+ */
+async function withMcpClient(cli, fn) {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const server = new Server({ name: "test-server", version: "1.0.0" }, { capabilities: {} });
+    addCliToolsToMcp({ cli, server });
+    const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+    try {
+        await server.connect(serverTransport);
+        await client.connect(clientTransport);
+        return await fn(client);
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+function textBlocks(result) {
+    const content = "content" in result ? result.content : [];
+    return content.filter((entry) => entry.type === "text").map((entry) => entry.text ?? "");
+}
+describe("addCliToolsToMcp execution context", () => {
+    it("passes an execution context as the third argument to the action", async () => {
+        const cli = goke("ctx-cli", {
+            cwd: "/workspace",
+            env: { TOKEN: "abc", USER: "tommy" },
+            stdin: "hello from stdin",
+        });
+        cli.command("inspect-ctx", "Return the injected execution context").action((_options, ctx) => {
+            return {
+                hasCtx: ctx != null,
+                hasConsole: typeof ctx?.console?.log === "function",
+                hasFs: typeof ctx?.fs?.readFile === "function",
+                cwd: ctx?.process?.cwd,
+                token: ctx?.process?.env?.TOKEN,
+                user: ctx?.process?.env?.USER,
+                stdin: ctx?.process?.stdin,
+            };
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "inspect-ctx", arguments: {} }));
+        expect(firstTextContent(result)).toMatchInlineSnapshot(`
+      "{
+        "hasCtx": true,
+        "hasConsole": true,
+        "hasFs": true,
+        "cwd": "/workspace",
+        "token": "abc",
+        "user": "tommy",
+        "stdin": "hello from stdin"
+      }"
+    `);
+    });
+    it("captures ctx.console.log output into the tool result content", async () => {
+        const cli = goke("logs-cli");
+        cli.command("noisy", "Write to ctx.console and return nothing").action((_options, ctx) => {
+            ctx.console.log("line one");
+            ctx.console.log("line", "two");
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "noisy", arguments: {} }));
+        expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "line one
+      line two
+      ",
+      ]
+    `);
+    });
+    it("captures ctx.console.log output and still uses the action's return value", async () => {
+        const cli = goke("logs-plus-return-cli");
+        cli.command("both", "Log and return").action((_options, ctx) => {
+            ctx.console.log("before");
+            return "the-return-value";
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "both", arguments: {} }));
+        // Captured stdout first, then the stringified return value, as
+        // separate content blocks. Authors who want a single block can
+        // return a `{ content }` object to bypass this merging.
+        expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "before
+      ",
+        "the-return-value",
+      ]
+    `);
+    });
+    it("treats ctx.process.exit(0) as a success result with captured content", async () => {
+        const cli = goke("exit-ok-cli");
+        cli.command("exit-ok", "Exit cleanly").action((_options, ctx) => {
+            ctx.console.log("all good");
+            ctx.process.exit(0);
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "exit-ok", arguments: {} }));
+        expect(result.isError).toBeFalsy();
+        expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "all good
+      ",
+      ]
+    `);
+    });
+    it("treats ctx.process.exit(1) as an isError result with captured stderr", async () => {
+        const cli = goke("exit-fail-cli");
+        cli.command("exit-fail", "Exit with error").action((_options, ctx) => {
+            ctx.console.error("boom");
+            ctx.process.exit(1);
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "exit-fail", arguments: {} }));
+        expect(result.isError).toBe(true);
+        expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "boom
+      ",
+      ]
+    `);
+    });
+    it("does not corrupt the MCP transport when the action writes to ctx.process.stdout directly", async () => {
+        const cli = goke("stdout-cli");
+        cli.command("write-stdout", "Write through ctx.process.stdout").action((_options, ctx) => {
+            ctx.process.stdout.write("from-process-stdout\n");
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "write-stdout", arguments: {} }));
+        expect(firstTextContent(result)).toBe("from-process-stdout\n");
+    });
+    it("keeps the server alive after a tool action calls ctx.process.exit", async () => {
+        const cli = goke("survive-cli");
+        cli.command("boom", "Exit with non-zero code").action((_options, ctx) => {
+            ctx.process.exit(2);
+        });
+        cli.command("ping", "Return a value").action(() => "pong");
+        await withMcpClient(cli, async (client) => {
+            const boomResult = await client.callTool({ name: "boom", arguments: {} });
+            expect(boomResult.isError).toBe(true);
+            // Server must still be able to serve subsequent tool calls.
+            const pingResult = await client.callTool({ name: "ping", arguments: {} });
+            expect(firstTextContent(pingResult)).toBe("pong");
+        });
+    });
+    it("does not include captured content when the action returns a ready-made CallToolResult", async () => {
+        const cli = goke("raw-cli");
+        cli.command("raw", "Return a raw CallToolResult").action((_options, ctx) => {
+            // This write should be ignored — returning a {content} object is
+            // the explicit escape hatch for authors who want full control.
+            ctx.console.log("ignored-capture");
+            return {
+                content: [
+                    { type: "text", text: "authoritative" },
+                ],
+            };
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "raw", arguments: {} }));
+        expect(textBlocks(result)).toEqual(["authoritative"]);
+    });
+    it("captures ctx.console.error output on the success path", async () => {
+        const cli = goke("success-stderr-cli");
+        cli.command("warn-and-return", "Emit a warning and return a value").action((_options, ctx) => {
+            ctx.console.error("something suspicious");
+            return { ok: true };
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "warn-and-return", arguments: {} }));
+        // Captured stderr lands in its own text block so authors can spot
+        // the warning even though the action returned successfully. The
+        // stringified return value is appended after it.
+        expect(result.isError).toBeFalsy();
+        expect(textBlocks(result)).toMatchInlineSnapshot(`
+      [
+        "something suspicious
+      ",
+        "{
+        "ok": true
+      }",
+      ]
+    `);
+    });
+    it("captures ctx.process.stderr.write output on the success path", async () => {
+        const cli = goke("success-stderr-write-cli");
+        cli.command("warn-only", "Write to stderr and return undefined").action((_options, ctx) => {
+            ctx.process.stderr.write("low-level-warning\n");
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "warn-only", arguments: {} }));
+        expect(result.isError).toBeFalsy();
+        expect(textBlocks(result)).toEqual(["low-level-warning\n"]);
+    });
+    it("does not leak tool output into the cli's configured stdout/stderr", async () => {
+        const sentinelStdout = [];
+        const sentinelStderr = [];
+        const cli = goke("sentinel-cli", {
+            stdout: { write: (data) => { sentinelStdout.push(data); } },
+            stderr: { write: (data) => { sentinelStderr.push(data); } },
+        });
+        cli.command("noisy", "Write to both streams").action((_options, ctx) => {
+            ctx.console.log("stdout-chatter");
+            ctx.console.error("stderr-chatter");
+            ctx.process.stdout.write("direct-stdout\n");
+            ctx.process.stderr.write("direct-stderr\n");
+            return "value";
+        });
+        const result = await withMcpClient(cli, (client) => client.callTool({ name: "noisy", arguments: {} }));
+        // Everything lands in the CallToolResult — the cli's configured
+        // host streams must not receive a single byte during a tool call.
+        expect(sentinelStdout.join("")).toBe("");
+        expect(sentinelStderr.join("")).toBe("");
+        expect(textBlocks(result).join("|")).toBe("stdout-chatter\ndirect-stdout\n|stderr-chatter\ndirect-stderr\n|value");
+    });
+    it("invokes command actions with the owning cli as `this`", async () => {
+        const cli = goke("this-binding-cli");
+        let seenThis;
+        cli.command("whoami", "Report this-binding").action(function (_options, _ctx) {
+            seenThis = this;
+            return "ok";
+        });
+        await withMcpClient(cli, (client) => client.callTool({ name: "whoami", arguments: {} }));
+        // Same binding Goke#runMatchedCommand uses for parse-path actions.
+        expect(seenThis).toBe(cli);
+    });
+});

package/dist/__test__/create-mcp-action.test.js

@@ -148,13 +148,15 @@ describe("createMcpAction", () => {
             .action(() => {
             throw new Error("something went wrong");
         });
-        // Wrapped JSON schema command
+        // Wrapped JSON schema command.
+        // wrapJsonSchema produces a StandardJSONSchemaV1 with `unknown` output, so
+        // values are cast explicitly inside the action.
         cli
             .command("config set", "Set a config value")
             .option("--key <key>", wrapJsonSchema({ type: "string", description: "Config key" }))
             .option("--value <value>", wrapJsonSchema({ type: "string", description: "Config value" }))
             .action((options) => {
-            return `set ${options.key} = ${options.value}`;
+            return `set ${String(options.key)} = ${String(options.value)}`;
         });
         // Commands without actions (should NOT appear as tools)
         cli.command("no-action", "This has no action handler");

package/dist/__test__/http-multi-tenant.test.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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`.
+ */
+export {};
+//# sourceMappingURL=http-multi-tenant.test.d.ts.map

package/dist/__test__/http-multi-tenant.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-multi-tenant.test.d.ts","sourceRoot":"","sources":["../../src/__test__/http-multi-tenant.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}