@goke/mcp 0.0.8 → 0.0.10

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

@@ -0,0 +1,276 @@
+/**
+ * Tests for createMcpAction — turning a CLI into a stdio MCP server.
+ *
+ * Uses InMemoryTransport (via createTransport option) to avoid actual stdio.
+ * Simulates the goke runtime by setting matchedCommandName before calling the action.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { goke, wrapJsonSchema } from "goke";
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+import { createMcpAction } from "../cli-to-mcp.js";
+function firstTextContent(result) {
+    const content = "content" in result ? result.content : [];
+    return content.find((entry) => entry.type === "text")?.text ?? "";
+}
+describe("createMcpAction", () => {
+    it("returns an action function", () => {
+        const cli = goke("test");
+        const action = createMcpAction({ cli });
+        expect(typeof action).toBe("function");
+    });
+    it("starts an MCP server exposing CLI commands, excluding the mcp command", async () => {
+        const cli = goke("test");
+        cli
+            .command("greet", "Say hello")
+            .option("--name <name>", z.string().describe("Person to greet"))
+            .action((options) => `Hello ${options.name}!`);
+        cli
+            .command("add", "Add numbers")
+            .option("--a <a>", z.number().describe("First"))
+            .option("--b <b>", z.number().describe("Second"))
+            .action((options) => ({ sum: options.a + options.b }));
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        // Simulate goke matching the "mcp" command (normally set by cli.parse())
+        cli.matchedCommandName = "mcp";
+        // Fire the action — starts the MCP server on the in-memory transport
+        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 toolNames = tools.tools.map((t) => t.name).sort();
+            expect(toolNames).toEqual(["add", "greet"]);
+            const greetResult = await client.callTool({
+                name: "greet",
+                arguments: { name: "World" },
+            });
+            expect(firstTextContent(greetResult)).toBe("Hello World!");
+            const addResult = await client.callTool({
+                name: "add",
+                arguments: { a: 3, b: 7 },
+            });
+            expect(firstTextContent(addResult)).toBe('{\n  "sum": 10\n}');
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("composes user commandFilter with auto-exclusion", async () => {
+        const cli = goke("test");
+        cli.command("public-cmd", "Public command").action(() => "public");
+        cli.command("secret-cmd", "Secret command").action(() => "secret");
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            commandFilter: (name) => name !== "secret-cmd",
+            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 toolNames = tools.tools.map((t) => t.name).sort();
+            // Both "mcp" (auto-excluded) and "secret-cmd" (user filter) excluded
+            expect(toolNames).toEqual(["public-cmd"]);
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("works with multi-word command names", async () => {
+        const cli = goke("test");
+        cli
+            .command("db migrate", "Run migrations")
+            .action(() => "migrated");
+        cli
+            .command("db seed", "Seed database")
+            .action(() => "seeded");
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("serve mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        cli.matchedCommandName = "serve mcp";
+        const mcpCommand = cli.commands.find((c) => c.name === "serve 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 toolNames = tools.tools.map((t) => t.name).sort();
+            expect(toolNames).toEqual(["db_migrate", "db_seed"]);
+            const migrateResult = await client.callTool({
+                name: "db_migrate",
+                arguments: {},
+            });
+            expect(firstTextContent(migrateResult)).toBe("migrated");
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("end-to-end: MCP client connects, discovers tools with schemas, calls tools, handles errors", async () => {
+        const cli = goke("my-app");
+        // String option command
+        cli
+            .command("search", "Search for items")
+            .option("--query <query>", z.string().describe("Search query"))
+            .option("--limit [limit]", z.number().default(10).describe("Max results"))
+            .action((options) => {
+            return { results: [`result for "${options.query}"`], limit: options.limit };
+        });
+        // Boolean flag + positional arg command
+        cli
+            .command("deploy <env>", "Deploy to environment")
+            .option("--dry-run", z.boolean().default(false).describe("Simulate deployment"))
+            .action((env, options) => {
+            return options.dryRun ? `dry-run deploy to ${env}` : `deployed to ${env}`;
+        });
+        // Command that returns a CallToolResult directly
+        cli
+            .command("status", "Get system status")
+            .action(() => ({
+            content: [{ type: "text", text: "all systems operational" }],
+        }));
+        // Command that throws an error (should be caught and returned as isError)
+        cli
+            .command("fail", "Always fails")
+            .action(() => {
+            throw new Error("something went wrong");
+        });
+        // 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 ${String(options.key)} = ${String(options.value)}`;
+        });
+        // Commands without actions (should NOT appear as tools)
+        cli.command("no-action", "This has no action handler");
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            serverName: "my-app-mcp",
+            serverVersion: "2.5.0",
+            createTransport: () => serverTransport,
+        }));
+        cli.matchedCommandName = "mcp";
+        const mcpCommand = cli.commands.find((c) => c.name === "mcp");
+        await mcpCommand.commandAction({});
+        const client = new Client({ name: "e2e-test-client", version: "1.0.0" }, { capabilities: {} });
+        await client.connect(clientTransport);
+        try {
+            // ── Server info ──
+            const serverInfo = client.getServerVersion();
+            expect(serverInfo).toMatchObject({ name: "my-app-mcp", version: "2.5.0" });
+            // ── Tool discovery ──
+            const tools = await client.listTools();
+            const toolNames = tools.tools.map((t) => t.name).sort();
+            // "mcp" auto-excluded, "no-action" has no handler → not mounted
+            expect(toolNames).toEqual(["config_set", "deploy", "fail", "search", "status"]);
+            // ── Verify schemas are propagated ──
+            const searchTool = tools.tools.find((t) => t.name === "search");
+            expect(searchTool.description).toBe("Search for items");
+            expect(searchTool.inputSchema.properties).toHaveProperty("query");
+            expect(searchTool.inputSchema.properties).toHaveProperty("limit");
+            expect(searchTool.inputSchema.required).toEqual(["query"]);
+            const deployTool = tools.tools.find((t) => t.name === "deploy");
+            expect(deployTool.inputSchema.properties).toHaveProperty("env");
+            expect(deployTool.inputSchema.properties).toHaveProperty("dryRun");
+            expect(deployTool.inputSchema.required).toEqual(["env"]);
+            // ── Call tool with schema-based options ──
+            const searchResult = await client.callTool({
+                name: "search",
+                arguments: { query: "hello", limit: 5 },
+            });
+            expect(firstTextContent(searchResult)).toBe('{\n  "results": [\n    "result for \\"hello\\""\n  ],\n  "limit": 5\n}');
+            // ── Call tool with positional args ──
+            const deployResult = await client.callTool({
+                name: "deploy",
+                arguments: { env: "production", dryRun: true },
+            });
+            expect(firstTextContent(deployResult)).toBe("dry-run deploy to production");
+            // ── Call tool that returns a raw CallToolResult ──
+            const statusResult = await client.callTool({
+                name: "status",
+                arguments: {},
+            });
+            expect(firstTextContent(statusResult)).toBe("all systems operational");
+            // ── Call tool that throws → error is caught and returned as isError ──
+            const failResult = await client.callTool({
+                name: "fail",
+                arguments: {},
+            });
+            expect(failResult.isError).toBe(true);
+            expect(firstTextContent(failResult)).toBe("something went wrong");
+            // ── Call tool with multi-word command name ──
+            const configResult = await client.callTool({
+                name: "config_set",
+                arguments: { key: "theme", value: "dark" },
+            });
+            expect(firstTextContent(configResult)).toBe("set theme = dark");
+            // ── Call nonexistent tool → MCP error ──
+            await expect(client.callTool({ name: "nonexistent", arguments: {} })).rejects.toThrow(/not found/i);
+        }
+        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();
+        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();
+            expect(tools.tools).toEqual([]);
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it("exposes all commands when matchedCommandName is not set", async () => {
+        const cli = goke("test");
+        cli.command("ping", "Ping").action(() => "pong");
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        cli.command("mcp", "Start MCP server").action(createMcpAction({
+            cli,
+            createTransport: () => serverTransport,
+        }));
+        // Do NOT set matchedCommandName — simulates programmatic invocation
+        // without cli.parse(). All commands including "mcp" should be exposed.
+        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 toolNames = tools.tools.map((t) => t.name).sort();
+            // Without matchedCommandName, auto-exclusion can't kick in
+            expect(toolNames).toEqual(["mcp", "ping"]);
+        }
+        finally {
+            await client.close();
+        }
+    });
+});

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"}

package/dist/__test__/http-multi-tenant.test.js

@@ -0,0 +1,309 @@
+/**
+ * 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 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 { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { goke } 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) => () => {
+    throw new Error(`InMemoryFs.${name} not implemented for this test`);
+};
+class InMemoryFs {
+    files = new Map();
+    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 = async (filePath) => {
+        const key = String(filePath);
+        const content = this.files.get(key);
+        if (content === undefined) {
+            throw new Error(`ENOENT: ${key}`);
+        }
+        return content;
+    };
+    mkdir = async () => undefined;
+    appendFile = notImplemented("appendFile");
+    chmod = notImplemented("chmod");
+    copyFile = notImplemented("copyFile");
+    link = notImplemented("link");
+    readlink = notImplemented("readlink");
+    realpath = notImplemented("realpath");
+    rename = notImplemented("rename");
+    rm = notImplemented("rm");
+    symlink = notImplemented("symlink");
+    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() {
+    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, 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>", "Read a file from the tenant 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, tenant: ctx.process.env.TENANT_ID };
+    });
+    return cli;
+}
+/**
+ * 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) {
+    const { baseCli, resolveTenant } = options;
+    const transports = new Map();
+    const customFetch = 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 = 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();
+        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) {
+            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) {
+        const content = result.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/dist/cli-to-mcp.d.ts

@@ -6,6 +6,7 @@
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { type Goke } from "goke";
 export interface AddCliToolsToMcpOptions {
     cli: Goke;
@@ -13,5 +14,32 @@ export interface AddCliToolsToMcpOptions {
     commandFilter?: (commandName: string) => boolean;
     sanitizeToolName?: (commandName: string) => string;
 }
+export interface CreateMcpActionOptions {
+    /** The CLI instance whose commands will be exposed as MCP tools */
+    cli: Goke;
+    /** Additional filter for which commands to expose. The MCP command itself is always excluded. */
+    commandFilter?: (commandName: string) => boolean;
+    /** Custom tool name sanitizer */
+    sanitizeToolName?: (commandName: string) => string;
+    /** MCP server name. Defaults to the CLI name or 'cli-mcp-server' */
+    serverName?: string;
+    /** MCP server version. Defaults to '1.0.0' */
+    serverVersion?: string;
+    /** Custom transport factory. Defaults to StdioServerTransport (stdin/stdout). */
+    createTransport?: () => Transport | Promise<Transport>;
+}
+/**
+ * Create a goke action callback that starts an MCP server over stdio.
+ *
+ * Exposes all CLI commands as MCP tools, automatically excluding the
+ * command this action is attached to.
+ *
+ * @example
+ * ```ts
+ * cli.command('mcp', 'Start MCP server over stdio')
+ *   .action(createMcpAction({ cli }))
+ * ```
+ */
+export declare function createMcpAction(options: CreateMcpActionOptions): (...args: any[]) => Promise<void>;
 export declare function addCliToolsToMcp(options: AddCliToolsToMcpOptions): void;
 //# sourceMappingURL=cli-to-mcp.d.ts.map

package/dist/cli-to-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-to-mcp.d.ts","sourceRoot":"","sources":["../src/cli-to-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AASxE,OAAO,EAAmD,KAAK,IAAI,EAA6B,MAAM,MAAM,CAAC;AAwD7G,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,gBAAgB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;CACpD;AA4XD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAyCvE"}
+{"version":3,"file":"cli-to-mcp.d.ts","sourceRoot":"","sources":["../src/cli-to-mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAS/E,OAAO,EAKL,KAAK,IAAI,EAIV,MAAM,MAAM,CAAC;AAwFd,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,gBAAgB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;CACpD;AAqfD,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,GAAG,EAAE,IAAI,CAAC;IACV,iGAAiG;IACjG,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,iCAAiC;IACjC,gBAAgB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;IACnD,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAsClG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAyCvE"}