@goke/mcp 0.0.7 → 0.0.9

package/README.md

@@ -62,60 +62,114 @@ notion-mcp-cli notion-retrieve-page --page_id "abc123"
 notion-mcp-cli notion-list-users
 ```
 
-## Turn a goke CLI into an MCP server
+## Expose a CLI as an MCP server
 
-`addCliToolsToMcp()` does the inverse mapping: every CLI command becomes an MCP tool.
-
-- Command description → MCP tool description
-- Option schema (Zod or any Standard Schema library) → MCP `inputSchema` JSON Schema
-- Command names are sanitized into valid MCP tool names (invalid characters become `_`)
-- Composable with existing MCP tools already registered on the same server
-
-### With low-level `Server`
+`createMcpAction()` turns your entire CLI into a stdio MCP server with one line. Every CLI command becomes an MCP tool automatically. The command you attach it to is excluded from the tool list.
 
 ```ts
 import { goke } from "goke"
 import { z } from "zod"
-import { Server } from "@modelcontextprotocol/sdk/server/index.js"
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
-import { addCliToolsToMcp } from "@goke/mcp"
+import { createMcpAction } from "@goke/mcp"
 
 const cli = goke("my-cli")
 
 cli
-  .command("notion search", "Search Notion pages")
+  .command("search", "Search pages")
   .option("--query <query>", z.string().describe("Search query"))
-  .action((options) => ({ query: options.query }))
+  .option("--limit [limit]", z.number().default(10).describe("Max results"))
+  .action((options) => {
+    return { results: findPages(options.query, options.limit) }
+  })
+
+cli
+  .command("deploy <env>", "Deploy to environment")
+  .option("--dry-run", z.boolean().default(false).describe("Simulate"))
+  .action((env, options) => {
+    return options.dryRun ? `would deploy to ${env}` : deploy(env)
+  })
+
+// Add MCP support — runs a stdio MCP server when the user invokes `my-cli mcp`
+cli.command("mcp", "Start MCP server over stdio")
+  .action(createMcpAction({ cli }))
+
+cli.help()
+cli.parse()
+```
+
+Now users can use your CLI directly **or** connect it as an MCP server:
+
+```bash
+# Use as a normal CLI
+my-cli search --query "meeting notes"
+my-cli deploy staging --dry-run
+
+# Use as an MCP server (e.g. from Claude Desktop, Cursor, etc.)
+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.
+
+### 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:
+
+```bash
+# Install in Claude Desktop
+npx @playwriter/install-mcp my-cli --client claude-desktop
+
+# Install in Cursor
+npx @playwriter/install-mcp my-cli --client cursor
+
+# Install in VS Code
+npx @playwriter/install-mcp my-cli --client vscode
+```
+
+This works with any client: `claude-desktop`, `cursor`, `vscode`, `windsurf`, `claude-code`, `opencode`, `zed`, `goose`, `cline`, `codex`, `gemini-cli`, and [more](https://github.com/supermemoryai/install-mcp#supported-clients). If the command needs custom arguments, pass the full command string:
+
+```bash
+npx @playwriter/install-mcp 'npx my-cli mcp' --client cursor
+```
+
+`createMcpAction` accepts the same filtering options as `addCliToolsToMcp`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cli` | `Goke` | **required** | The CLI instance to expose |
+| `commandFilter` | `(name) => boolean` | — | Additional filter (MCP command is always excluded) |
+| `sanitizeToolName` | `(name) => string` | — | Custom tool name sanitizer |
+| `serverName` | `string` | CLI name | MCP server name |
+| `serverVersion` | `string` | `'1.0.0'` | MCP server version |
+| `createTransport` | `() => Transport` | stdio | Custom transport factory |
+
+### Advanced: `addCliToolsToMcp`
+
+For more control (composing with existing MCP tools, using a custom server), use `addCliToolsToMcp()` directly:
+
+```ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { addCliToolsToMcp } from "@goke/mcp"
 
 const server = new Server(
   { name: "my-cli-mcp", version: "1.0.0" },
   { capabilities: {} },
 )
 
+// Mount CLI commands as tools alongside your own
 addCliToolsToMcp({ cli, server })
 
 const transport = new StdioServerTransport()
 await server.connect(transport)
 ```
 
-Run it with Node:
-
-```bash
-node dist/server.js
-```
-
-### With high-level `McpServer`
+Also works with the high-level `McpServer`:
 
 ```ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
-import { addCliToolsToMcp } from "@goke/mcp"
 
 const mcp = new McpServer({ name: "my-cli-mcp", version: "1.0.0" })
+mcp.tool("custom-tool", "A tool defined directly", async () => ({ ... }))
 addCliToolsToMcp({ cli, server: mcp })
-
-const transport = new StdioServerTransport()
-await mcp.connect(transport)
 ```
 
 ## Full example (with config persistence)
@@ -220,13 +274,14 @@ Registers MCP tool commands on a goke CLI instance.
 ### Exports
 
 ```ts
-// Main function
+// MCP server → CLI (consume MCP tools as CLI commands)
 export { addMcpCommands } from '@goke/mcp'
-
-// Types
-export type { AddMcpCommandsOptions } from '@goke/mcp'
-export type { CachedMcpTools } from '@goke/mcp'
+export type { AddMcpCommandsOptions, CachedMcpTools } from '@goke/mcp'
 export type { McpOAuthConfig, McpOAuthState } from '@goke/mcp'
+
+// CLI → MCP server (expose CLI commands as MCP tools)
+export { createMcpAction, addCliToolsToMcp } from '@goke/mcp'
+export type { CreateMcpActionOptions, AddCliToolsToMcpOptions } from '@goke/mcp'
 ```
 
 ## OAuth flow

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

@@ -0,0 +1,5 @@
+/**
+ * End-to-end tests for exposing a goke CLI as MCP tools.
+ */
+export {};
+//# sourceMappingURL=add-cli-tools-to-mcp.test.d.ts.map

package/dist/__test__/add-cli-tools-to-mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-cli-tools-to-mcp.test.d.ts","sourceRoot":"","sources":["../../src/__test__/add-cli-tools-to-mcp.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

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

@@ -0,0 +1,399 @@
+/**
+ * End-to-end tests for exposing a goke CLI as MCP tools.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { goke, wrapJsonSchema } from "goke";
+import { z } from "zod";
+import { describe, expect, it } from "vitest";
+import { addCliToolsToMcp } from "../cli-to-mcp.js";
+function createCli() {
+    const cli = goke("test-cli");
+    cli
+        .command("say hi", "Say hello")
+        .option("--name <name>", z.string().describe("Person to greet"))
+        .option("--caps", z.boolean().default(false).describe("Uppercase output"))
+        .action((options) => {
+        const message = `Hello ${options.name}!`;
+        return options.caps ? message.toUpperCase() : message;
+    });
+    cli
+        .command("sum-values", "Add two numbers")
+        .option("--left <left>", wrapJsonSchema({
+        type: "number",
+        description: "Left operand",
+    }))
+        .option("--right <right>", wrapJsonSchema({
+        type: "number",
+        description: "Right operand",
+    }))
+        .action((options) => ({
+        sum: options.left + options.right,
+    }));
+    cli
+        .command("echo <message>", "Echo positional message")
+        .option("--repeat [repeat]", wrapJsonSchema({
+        type: "integer",
+        default: 2,
+        description: "Repeat count",
+    }))
+        .action((message, options) => {
+        return message.repeat(options.repeat);
+    });
+    cli
+        .command("string-options", "Infer option types from plain string descriptions")
+        .option("--title <title>", "Required title")
+        .option("--tag [tag]", "Optional tag")
+        .option("--dry-run", "Dry run flag")
+        .action((options) => {
+        return options;
+    });
+    return cli;
+}
+function firstTextContent(result) {
+    const content = "content" in result ? result.content : [];
+    return content.find((entry) => entry.type === "text")?.text ?? "";
+}
+function expectCommandDescriptions(tools) {
+    const descriptionByName = Object.fromEntries(tools.map((tool) => [tool.name, tool.description]));
+    expect(descriptionByName).toMatchObject({
+        say_hi: "Say hello",
+        "sum-values": "Add two numbers",
+        echo: "Echo positional message",
+        "string-options": "Infer option types from plain string descriptions",
+    });
+}
+function addUserLowLevelTools(server) {
+    server.registerCapabilities({ tools: { listChanged: true } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: [
+            {
+                name: "user_tool",
+                description: "Tool added directly by user",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (request.params.name !== "user_tool") {
+            throw new McpError(ErrorCode.InvalidParams, `Tool ${request.params.name} not found`);
+        }
+        return {
+            content: [{ type: "text", text: "from-user-low-level" }],
+        };
+    });
+}
+async function runScenario(mode) {
+    const cli = createCli();
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const server = mode === "low-level-server"
+        ? new Server({ name: "test-server", version: "1.0.0" }, { capabilities: {} })
+        : new McpServer({ name: "test-server", version: "1.0.0" });
+    addCliToolsToMcp({ cli, server });
+    const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+    try {
+        await server.connect(serverTransport);
+        await client.connect(clientTransport);
+        const toolsResult = await client.listTools();
+        const greetingResult = await client.callTool({
+            name: "say_hi",
+            arguments: { name: "Tommy" },
+        });
+        const sumResult = await client.callTool({
+            name: "sum-values",
+            arguments: { left: 2, right: 3 },
+        });
+        const echoResult = await client.callTool({
+            name: "echo",
+            arguments: { message: "ha" },
+        });
+        const stringOptionsResult = await client.callTool({
+            name: "string-options",
+            arguments: {
+                title: "Release notes",
+                dryRun: true,
+            },
+        });
+        return {
+            tools: toolsResult.tools,
+            greeting: firstTextContent(greetingResult),
+            sum: firstTextContent(sumResult),
+            echo: firstTextContent(echoResult),
+            stringOptions: firstTextContent(stringOptionsResult),
+        };
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+describe("addCliToolsToMcp", () => {
+    it("mounts CLI tools and executes calls with low-level Server", async () => {
+        const result = await runScenario("low-level-server");
+        expect("\n" + JSON.stringify(result.tools, null, 2)).toMatchInlineSnapshot(`
+      "
+      [
+        {
+          "name": "say_hi",
+          "description": "Say hello",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "type": "string",
+                "description": "Person to greet"
+              },
+              "caps": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "default": false,
+                "description": "Uppercase output",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name"
+            ]
+          }
+        },
+        {
+          "name": "sum-values",
+          "description": "Add two numbers",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "left": {
+                "type": "number",
+                "description": "Left operand"
+              },
+              "right": {
+                "type": "number",
+                "description": "Right operand"
+              }
+            },
+            "required": [
+              "left",
+              "right"
+            ]
+          }
+        },
+        {
+          "name": "echo",
+          "description": "Echo positional message",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "message": {
+                "type": "string",
+                "description": "Positional argument message"
+              },
+              "repeat": {
+                "type": "integer",
+                "default": 2,
+                "description": "Repeat count"
+              }
+            },
+            "required": [
+              "message"
+            ]
+          }
+        },
+        {
+          "name": "string-options",
+          "description": "Infer option types from plain string descriptions",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Required title"
+              },
+              "tag": {
+                "type": "string",
+                "description": "Optional tag"
+              },
+              "dryRun": {
+                "type": "boolean",
+                "description": "Dry run flag"
+              }
+            },
+            "required": [
+              "title"
+            ]
+          }
+        }
+      ]"
+    `);
+        expectCommandDescriptions(result.tools);
+        expect(result.greeting).toBe("Hello Tommy!");
+        expect(result.sum).toBe('{\n  "sum": 5\n}');
+        expect(result.echo).toBe("haha");
+        expect(result.stringOptions).toBe('{\n  "title": "Release notes",\n  "dryRun": true\n}');
+    });
+    it("mounts CLI tools and executes calls with high-level McpServer", async () => {
+        const result = await runScenario("mcp-server");
+        expect("\n" + JSON.stringify(result.tools, null, 2)).toMatchInlineSnapshot(`
+      "
+      [
+        {
+          "name": "say_hi",
+          "description": "Say hello",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "type": "string",
+                "description": "Person to greet"
+              },
+              "caps": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "default": false,
+                "description": "Uppercase output",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name"
+            ]
+          }
+        },
+        {
+          "name": "sum-values",
+          "description": "Add two numbers",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "left": {
+                "type": "number",
+                "description": "Left operand"
+              },
+              "right": {
+                "type": "number",
+                "description": "Right operand"
+              }
+            },
+            "required": [
+              "left",
+              "right"
+            ]
+          }
+        },
+        {
+          "name": "echo",
+          "description": "Echo positional message",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "message": {
+                "type": "string",
+                "description": "Positional argument message"
+              },
+              "repeat": {
+                "type": "integer",
+                "default": 2,
+                "description": "Repeat count"
+              }
+            },
+            "required": [
+              "message"
+            ]
+          }
+        },
+        {
+          "name": "string-options",
+          "description": "Infer option types from plain string descriptions",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Required title"
+              },
+              "tag": {
+                "type": "string",
+                "description": "Optional tag"
+              },
+              "dryRun": {
+                "type": "boolean",
+                "description": "Dry run flag"
+              }
+            },
+            "required": [
+              "title"
+            ]
+          }
+        }
+      ]"
+    `);
+        expectCommandDescriptions(result.tools);
+        expect(result.greeting).toBe("Hello Tommy!");
+        expect(result.sum).toBe('{\n  "sum": 5\n}');
+        expect(result.echo).toBe("haha");
+        expect(result.stringOptions).toBe('{\n  "title": "Release notes",\n  "dryRun": true\n}');
+    });
+    it("composes with user tools already mounted on low-level Server", async () => {
+        const cli = createCli();
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const server = new Server({ name: "test-server", version: "1.0.0" }, { capabilities: {} });
+        const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+        addUserLowLevelTools(server);
+        addCliToolsToMcp({ cli, server, commandFilter: (name) => name === "say hi" });
+        try {
+            await server.connect(serverTransport);
+            await client.connect(clientTransport);
+            const tools = await client.listTools();
+            expect(tools.tools.map((tool) => tool.name).sort()).toEqual(["say_hi", "user_tool"]);
+            const cliResult = await client.callTool({
+                name: "say_hi",
+                arguments: { name: "Tommy" },
+            });
+            const userResult = await client.callTool({
+                name: "user_tool",
+                arguments: {},
+            });
+            expect(firstTextContent(cliResult)).toBe("Hello Tommy!");
+            expect(firstTextContent(userResult)).toBe("from-user-low-level");
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    });
+    it("composes with user tools already mounted on high-level McpServer", async () => {
+        const cli = createCli();
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const server = new McpServer({ name: "test-server", version: "1.0.0" });
+        const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
+        server.tool("user_tool", "Tool added directly by user", async () => ({
+            content: [{ type: "text", text: "from-user-mcp-server" }],
+        }));
+        addCliToolsToMcp({ cli, server, commandFilter: (name) => name === "say hi" });
+        try {
+            await server.connect(serverTransport);
+            await client.connect(clientTransport);
+            const tools = await client.listTools();
+            expect(tools.tools.map((tool) => tool.name).sort()).toEqual(["say_hi", "user_tool"]);
+            const cliResult = await client.callTool({
+                name: "say_hi",
+                arguments: { name: "Tommy" },
+            });
+            const userResult = await client.callTool({
+                name: "user_tool",
+                arguments: {},
+            });
+            expect(firstTextContent(cliResult)).toBe("Hello Tommy!");
+            expect(firstTextContent(userResult)).toBe("from-user-mcp-server");
+        }
+        finally {
+            await client.close();
+            await server.close();
+        }
+    });
+});

package/dist/__test__/create-mcp-action.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=create-mcp-action.test.d.ts.map

package/dist/__test__/create-mcp-action.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-mcp-action.test.d.ts","sourceRoot":"","sources":["../../src/__test__/create-mcp-action.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}