@goke/mcp 0.0.13 → 0.1.1

package/README.md

@@ -25,7 +25,7 @@ MCP server                        Your CLI
 
 1. **Discover** — calls `tools/list` on the MCP server to get every tool + its JSON Schema
 2. **Register** — creates a CLI command per tool with `--options` derived from the schema
-3. **Cache** — tools and session ID are cached for 1 hour (no network on subsequent runs). Expired cache is still used when a live fetch is impossible (no token, 401 on `--help`)
+3. **Cache** — tool schemas are cached for 1 hour (no network on subsequent runs). Expired cache is still used when a live fetch is impossible (no token, 401 on `--help`)
 4. **Execute** — on invocation, connects to the server and calls the tool with coerced arguments
 5. **OAuth** — if the server returns 401, automatically opens the browser for OAuth, then retries. `--help`, `--version`, `completions`, and no-args never start OAuth
 
@@ -129,6 +129,8 @@ my-cli mcp
 
 When running as MCP, the server exposes `search` and `deploy` as tools. The `mcp` command itself is excluded. Options with Zod schemas (or any Standard Schema) become typed `inputSchema` properties in the MCP tool definition.
 
+**`inputSchema.required` is not the CLI `<value>` syntax.** `--query <query>` means the flag needs a value if it is present. The flag is still optional unless the schema rejects omit (`z.string()`, not `z.string().optional()`). Required **positionals** like `<env>` always go in `required`. Schema-required flags go in `required` too. Untyped flags and `wrapJsonSchema()` flags stay optional.
+
 ### Installing the MCP server in clients
 
 Users can install your CLI as an MCP server in any client using [`@playwriter/install-mcp`](https://github.com/nicepkg/install-mcp) — a cross-platform tool that handles config file locations for every major MCP client:
@@ -194,12 +196,14 @@ 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.
+When you expose a cli as a **remote** MCP over HTTP, one process handles many concurrent users. Each request 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.
+
+Do **not** keep MCP session IDs. Streamable HTTP can run **stateless**: `sessionIdGenerator: undefined`. Each POST builds a fresh `Server` and transport, then closes them. That works on Cloudflare Workers and any other isolate that does not keep process memory.
 
 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 })`.
+2. On **every POST**, resolve the tenant from the request (JWT, cookie, header), **clone** the cli with `{ cwd, env, fs }`, and mount it on a fresh `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`
@@ -231,64 +235,68 @@ cli
 
 `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
+### Clone the cli per request
 
 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.
 
+Pass `sessionIdGenerator: undefined` so the transport does not emit or expect `mcp-session-id`. Do not store transports in a `Map`. JSON-RPC `initialize`, `tools/list`, and `tools/call` are separate POSTs. Each one clones the cli from the request's tenant identity.
+
+This is MCP SDK v1 Streamable HTTP **without optional transport sessions** (protocol revisions through `2025-11-25`). It is not the later `2026-07-28` protocol, which drops `initialize`. Session IDs are optional in `2025-11-25`. Stateless servers omit them.
+
+The Streamable HTTP spec requires **Origin** checks on every request (DNS rebinding). Reject a present, disallowed `Origin` with **403**. Missing `Origin` is normal for non-browser MCP clients.
+
+```
+POST /mcp  (JWT / x-tenant-id)
+        │
+        v
+resolveTenant(id) ──> baseCli.clone({ cwd, env, fs })
+                           │
+                           v
+                    fresh Server + transport
+                    sessionIdGenerator: undefined
+                           │
+                           v
+addCliToolsToMcp ──> handleRequest
+                           │
+                           v
+                        Response
+                           │
+                           v
+             close transport + server ──> nothing stored
+```
+
 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
+  fs: GokeFs
 }
 
-const transports = new Map<string, WebStandardStreamableHTTPServerTransport>()
+declare function isAllowedOrigin(origin: string): boolean
 
 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 origin = request.headers.get("origin")
+  if (origin && !isAllowedOrigin(origin)) {
+    return new Response(null, { status: 403 })
   }
 
-  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 })
+  if (request.method !== "POST") {
+    return new Response(null, { status: 405, headers: { Allow: "POST" } })
   }
 
-  // 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 },
-    )
-  }
+  const parsedBody = await request.clone().json().catch(() => undefined)
 
-  // 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 },
@@ -302,22 +310,16 @@ export async function handleMcpRequest(request: Request): Promise<Response> {
   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)
-    },
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
   })
-  transport.onclose = () => {
-    const sid = transport.sessionId
-    if (sid) transports.delete(sid)
-  }
-
   await mcpServer.connect(transport)
-  return transport.handleRequest(request, { parsedBody })
+  try {
+    return await transport.handleRequest(request, { parsedBody })
+  } finally {
+    await transport.close()
+    await mcpServer.close()
+  }
 }
 ```
 
@@ -353,7 +355,7 @@ export async function POST(request: 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.
+- Every request 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] }`.
@@ -369,7 +371,7 @@ Only code that flows through `ctx` participates in the isolation. The following
 
 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).
+For a runnable end-to-end example (including two concurrent in-memory-fs tenants writing separate files, with a new server per POST), see [`src/__test__/http-multi-tenant.test.ts`](./src/__test__/http-multi-tenant.test.ts).
 
 ### Lower-level primitive: `cli.createExecutionContext(override)`
 
@@ -486,7 +488,7 @@ Registers MCP tool commands on a goke CLI instance.
 |--------|------|---------|-------------|
 | `cli` | `Goke` | **required** | The goke CLI instance to add commands to |
 | `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL. Return the URL even when the user is not logged in so `--help` still works |
-| `getMcpTransport` | `(sessionId?) => Transport \| null` | — | Custom transport. Use for stdio or anything `getMcpUrl` cannot express |
+| `getMcpTransport` | `() => Transport \| null` | — | Custom transport. Use for stdio or anything `getMcpUrl` cannot express |
 | `getHeaders` | `() => Record<string, string> \| undefined` | — | Extra HTTP headers (for example `Authorization`). Used with `getMcpUrl` |
 | `argv` | `string[]` | `process.argv.slice(2)` | Args used to skip live discovery on help and already registered commands |
 | `commandPrefix` | `string` | `''` | Prefix for commands (e.g. `'mcp'` makes `mcp notion-search`) |
@@ -554,7 +556,7 @@ Tokens are persisted via the `oauth.save()` callback you provide, so subsequent
 
 ## Caching
 
-Tools and the MCP session ID are cached for **1 hour** to avoid connecting on every invocation. The cache is managed through the `loadCache`/`saveCache` callbacks — you control where it's stored (file, database, env, etc.).
+Tool schemas are cached for **1 hour** so `--help` and command registration do not hit the network on every invocation. The cache is managed through the `loadCache`/`saveCache` callbacks. You control where it is stored (file, database, env, etc.). Each tool call still opens a new MCP connection. There is no `Mcp-Session-Id` reuse.
 
 When the cache expires or a tool call fails, the cache is cleared and tools are re-fetched on the next run.
 

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

@@ -178,11 +178,7 @@ describe("addCliToolsToMcp", () => {
                 "type": "number",
                 "description": "Right operand"
               }
-            },
-            "required": [
-              "left",
-              "right"
-            ]
+            }
           }
         },
         {
@@ -224,10 +220,7 @@ describe("addCliToolsToMcp", () => {
                 "type": "boolean",
                 "description": "Dry run flag"
               }
-            },
-            "required": [
-              "title"
-            ]
+            }
           }
         }
       ]"
@@ -280,11 +273,7 @@ describe("addCliToolsToMcp", () => {
                 "type": "number",
                 "description": "Right operand"
               }
-            },
-            "required": [
-              "left",
-              "right"
-            ]
+            }
           }
         },
         {
@@ -326,10 +315,7 @@ describe("addCliToolsToMcp", () => {
                 "type": "boolean",
                 "description": "Dry run flag"
               }
-            },
-            "required": [
-              "title"
-            ]
+            }
           }
         }
       ]"

package/dist/__test__/add-mcp-commands-help.test.js

@@ -1,7 +1,10 @@
 // First-run help and stale-cache behavior for addMcpCommands.
 import http from 'node:http';
 import { describe, expect, it } from 'vitest';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { goke } from 'goke';
+import { addCliToolsToMcp } from '../cli-to-mcp.js';
 import { addMcpCommands } from '../index.js';
 const staleCache = (over = {}) => ({
     tools: [
@@ -12,7 +15,6 @@ const staleCache = (over = {}) => ({
         },
     ],
     timestamp: Date.now() - 2 * 60 * 60 * 1000,
-    sessionId: 'stale-session',
     ...over,
 });
 function captureErrors() {
@@ -124,4 +126,64 @@ describe('addMcpCommands first-run help', () => {
         });
         expect(transportCalls).toBe(0);
     });
+    it('does not pass a session id into getMcpTransport', async () => {
+        const sessionIds = [];
+        const cli = goke('testcli');
+        await addMcpCommands({
+            cli,
+            argv: ['find_bookmarks'],
+            getMcpTransport: (sessionId) => {
+                sessionIds.push(sessionId);
+                return null;
+            },
+            loadCache: () => ({
+                tools: [
+                    {
+                        name: 'find_bookmarks',
+                        description: 'Find bookmarks',
+                        inputSchema: { type: 'object', properties: {} },
+                    },
+                ],
+                timestamp: Date.now(),
+                sessionId: 'should-not-be-reused',
+            }),
+            saveCache: () => { },
+        });
+        const command = cli.commands.find((entry) => entry.name === 'find_bookmarks');
+        try {
+            await command?.commandAction?.({});
+        }
+        catch {
+            // transport is null, so the action exits
+        }
+        expect(sessionIds).toEqual([undefined]);
+    });
+    it('caches tools without a session id', async () => {
+        const saved = [];
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const serverCli = goke('server-cli');
+        serverCli.command('ping', 'Ping').action(() => 'pong');
+        const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: {} });
+        addCliToolsToMcp({ cli: serverCli, server });
+        await server.connect(serverTransport);
+        const cli = goke('testcli');
+        try {
+            await addMcpCommands({
+                cli,
+                argv: ['ping'],
+                getMcpTransport: () => clientTransport,
+                loadCache: () => undefined,
+                saveCache: (cache) => {
+                    if (cache)
+                        saved.push(cache);
+                },
+            });
+        }
+        finally {
+            await server.close();
+        }
+        expect(saved).toHaveLength(1);
+        expect(saved[0]?.tools.map((tool) => tool.name)).toEqual(['ping']);
+        expect(saved[0]).not.toHaveProperty('sessionId');
+    });
 });

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

@@ -229,6 +229,120 @@ describe("createMcpAction", () => {
             await client.close();
         }
     });
+    it("keeps --flag <value> in properties but not in required", async () => {
+        const cli = goke("strada");
+        cli
+            .command("projects create <slug>", "Create a project")
+            .option("--traces-days <days>", z.string().optional().describe("Traces retention days"))
+            .option("--logs-days <days>", z.string().optional().describe("Logs retention days"))
+            .option("--errors-days <days>", z.string().optional().describe("Errors retention days"))
+            .option("--metrics-days <days>", z.string().optional().describe("Metrics retention days"))
+            .option("--all-days <days>", z.string().optional().describe("Retention for all signals"))
+            .action((slug, options) => ({ slug, ...options }));
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        cli.matchedCommandName = "mcp";
+        const mcpCommand = cli.commands.find((c) => c.name === "mcp");
+        await mcpCommand.commandAction({});
+        const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(clientTransport);
+        try {
+            const tools = await client.listTools();
+            const createTool = tools.tools.find((t) => t.name === "projects_create");
+            expect(createTool.inputSchema.properties).toHaveProperty("slug");
+            expect(createTool.inputSchema.properties).toHaveProperty("tracesDays");
+            expect(createTool.inputSchema.properties).toHaveProperty("logsDays");
+            expect(createTool.inputSchema.properties).toHaveProperty("allDays");
+            expect(createTool.inputSchema.required).toEqual(["slug"]);
+            const result = await client.callTool({
+                name: "projects_create",
+                arguments: { slug: "my-app" },
+            });
+            expect(firstTextContent(result)).toBe('{\n  "slug": "my-app"\n}');
+            await expect(client.callTool({
+                name: "projects_create",
+                arguments: {},
+            })).rejects.toThrow("Missing required argument: slug");
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("puts schema-required --flag <value> in inputSchema.required", async () => {
+        const cli = goke("checks");
+        cli
+            .command("checks create", "Create a check")
+            .option("--url <url>", z.string().describe("URL to check"))
+            .option("--name <name>", z.string().describe("Check name"))
+            .option("--timeout [ms]", z.number().optional().describe("Timeout"))
+            .action((options) => options);
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        cli.matchedCommandName = "mcp";
+        const mcpCommand = cli.commands.find((c) => c.name === "mcp");
+        await mcpCommand.commandAction({});
+        const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(clientTransport);
+        try {
+            const tools = await client.listTools();
+            const createTool = tools.tools.find((t) => t.name === "checks_create");
+            expect(createTool.inputSchema.properties).toHaveProperty("url");
+            expect(createTool.inputSchema.properties).toHaveProperty("name");
+            expect(createTool.inputSchema.properties).toHaveProperty("timeout");
+            expect(createTool.inputSchema.required).toEqual(["url", "name"]);
+            const result = await client.callTool({
+                name: "checks_create",
+                arguments: { url: "https://example.com", name: "home" },
+            });
+            expect(firstTextContent(result)).toContain("https://example.com");
+            await expect(client.callTool({
+                name: "checks_create",
+                arguments: { name: "home" },
+            })).rejects.toThrow("Missing required argument: url");
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("does not put wrapJsonSchema flags in required", async () => {
+        const cli = goke("wrapped");
+        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) => options);
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        cli.matchedCommandName = "mcp";
+        const mcpCommand = cli.commands.find((c) => c.name === "mcp");
+        await mcpCommand.commandAction({});
+        const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(clientTransport);
+        try {
+            const tools = await client.listTools();
+            const setTool = tools.tools.find((t) => t.name === "config_set");
+            expect(setTool.inputSchema.properties).toHaveProperty("key");
+            expect(setTool.inputSchema.properties).toHaveProperty("value");
+            expect(setTool.inputSchema.required).toBeUndefined();
+            const result = await client.callTool({
+                name: "config_set",
+                arguments: {},
+            });
+            expect(firstTextContent(result)).toBe("{}");
+        }
+        finally {
+            await client.close();
+        }
+    });
     it("returns empty tool list when only the mcp command exists", async () => {
         const cli = goke("empty-app");
         const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

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

@@ -1,10 +1,11 @@
 /**
  * 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.
+ * Proves that one goke cli exposed over stateless MCP streamable HTTP
+ * can serve multiple concurrent users with fully isolated state
+ * (in-memory fs + cwd + env) — no shared host process stdio, no
+ * cross-tenant leaks, no mcp-session-id map. Isolation comes from
+ * the `x-tenant-id` header on each POST, not from `Mcp-Session-Id`.
  *
  * Wiring choices worth calling out:
  *
@@ -14,11 +15,15 @@
  *     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
+ *   - `sessionIdGenerator: undefined` is stateless mode. The
+ *     transport does not emit or expect `mcp-session-id`. Each
+ *     POST builds a fresh Server + transport, then closes them.
+ *   - `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 request 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

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

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