@goke/mcp weekly downloads statistics

@goke/mcp

Turn any MCP server into a CLI. Connects to the server, discovers tools, and generates CLI commands with typed arguments — automatically.

Install

goke is a peer dependency (the CLI framework that commands are registered on).

How it works

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 — 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

Quick start

If the MCP server is HTTP, pass getMcpUrl even when the user has no token. --help and no-args must still run so the CLI can show config / login instructions. Use getMcpTransport when you need stdio or a custom transport.

For an HTTP Bearer token, pass getHeaders:

That's it. Every tool the MCP server exposes becomes a CLI command:

Expose a CLI as an MCP 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.

Now users can use your CLI directly or connect it as an MCP server:

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 syntax. --query means the flag needs a value if it is present. The flag itself is still optional unless you chain .required(). Required positionals like always go in required. .required() flags go in required too.

Installing the MCP server in clients

Users can install your CLI as an MCP server in any client using @playwriter/install-mcp — a cross-platform tool that handles config file locations for every major MCP client:

This works with any client: claude-desktop, cursor, vscode, windsurf, claude-code, opencode, zed, goose, cline, codex, gemini-cli, and more. If the command needs custom arguments, pass the full command string:

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:

Also works with the high-level McpServer:

Multi-tenant remote MCP over HTTP

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

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 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, 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.

You build one handleMcpRequest(request: Request): Promise function and mount it wherever you route HTTP:

Now plug handleMcpRequest into whichever web runtime you use:

Key guarantees…

Description from the npm listing.