@goke/mcp

中文文档
0.1.2发布于 2026/09/16MITTypeScriptES Module近 30 天下载 6.5万

Dynamically generate CLI commands from MCP server tools

原始使用文档
文档目录18 节
  1. Install
  2. How it works
  3. Quick start
  4. Expose a CLI as an MCP server
  5. Installing the MCP server in clients
  6. Advanced: addCliToolsToMcp
  7. Multi-tenant remote MCP over HTTP
  8. Write commands against ctx
  9. Clone the cli per request
  10. Lower-level primitive: cli.createExecutionContext(override)
  11. Full example (with config persistence)
  12. API
  13. addMcpCommands(options)
  14. McpOAuthConfig
  15. Exports
  16. OAuth flow
  17. Caching
  18. License

@goke/mcp

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

Install

npm install @goke/mcp goke

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

How it works

MCP server                        Your CLI
┌──────────────────┐              ┌──────────────────────────┐
│  tools/list      │──discover──▸ │  mycli notion-search     │
│  - notion-search │              │  mycli notion-get-page   │
│  - notion-get-…  │              │  mycli notion-create-…   │
│  (JSON Schema)   │──coerce───▸ │  --query <string>        │
│                  │              │  --pageId <string>       │
└──────────────────┘              └──────────────────────────┘
  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

import { goke } from 'goke'
import { addMcpCommands } from '@goke/mcp'
import type { McpOAuthState, CachedMcpTools } from '@goke/mcp'

const cli = goke('notion-mcp-cli')

await addMcpCommands({
  cli,
  getMcpUrl: () => 'https://mcp.notion.com/mcp',
  oauth: {
    clientName: 'Notion CLI',
    load: () => loadConfig().oauthState,
    save: (state) => saveConfig({ oauthState: state }),
  },
  loadCache: () => loadConfig().cache,
  saveCache: (cache) => saveConfig({ cache }),
})

cli.help()
cli.completions()
cli.parse()

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:

await addMcpCommands({
  cli,
  getMcpUrl: () => 'https://api.example.com/mcp',
  getHeaders: () => {
    const token = process.env.EXAMPLE_TOKEN || loadConfig().token
    if (!token) return
    return { Authorization: `Bearer ${token}` }
  },
  loadCache: () => loadConfig().cache,
  saveCache: (cache) => saveConfig({ cache }),
})

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

notion-mcp-cli notion-search --query "meeting notes"
notion-mcp-cli notion-retrieve-page --page_id "abc123"
notion-mcp-cli notion-list-users

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.

import { goke } from "goke"
import { z } from "zod"
import { createMcpAction } from "@goke/mcp"

const cli = goke("my-cli")

cli
  .command("search", "Search pages")
  .option("--query <query>", z.string().describe("Search query"))
  .required()
  .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.completions()
cli.parse()

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

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

inputSchema.required is not the CLI <value> syntax. --query <query> means the flag needs a value if it is present. The flag itself is still optional unless you chain .required(). Required positionals like <env> 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:

# 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. If the command needs custom arguments, pass the full command string:

npx @playwriter/install-mcp 'npx my-cli mcp' --client cursor

createMcpAction accepts the same filtering options as addCliToolsToMcp:

OptionTypeDefaultDescription
cliGokerequiredThe CLI instance to expose
commandFilter(name) => boolean—Additional filter (MCP command is always excluded)
sanitizeToolName(name) => string—Custom tool name sanitizer
serverNamestringCLI nameMCP server name
serverVersionstring'1.0.0'MCP server version
createTransport() => TransportstdioCustom transport factory

Advanced: addCliToolsToMcp

For more control (composing with existing MCP tools, using a custom server), use addCliToolsToMcp() directly:

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)

Also works with the high-level McpServer:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"

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

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

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

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:

import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js"
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
import { addCliToolsToMcp } from "@goke/mcp"
import type { GokeFs } from "goke"

declare function resolveTenant(tenantId: string): {
  cwd: string
  env: Record<string, string>
  fs: GokeFs
}

declare function isAllowedOrigin(origin: string): boolean

export async function handleMcpRequest(request: Request): Promise<Response> {
  const origin = request.headers.get("origin")
  if (origin && !isAllowedOrigin(origin)) {
    return new Response(null, { status: 403 })
  }

  if (request.method !== "POST") {
    return new Response(null, { status: 405, headers: { Allow: "POST" } })
  }

  const parsedBody = await request.clone().json().catch(() => undefined)

  const tenantId = request.headers.get("x-tenant-id")
  if (!tenantId) return new Response("missing x-tenant-id", { 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 McpServer(
    { name: "notes-app-mcp", version: "1.0.0" },
    { capabilities: {} },
  )
  addCliToolsToMcp({ cli: tenantCli, server: mcpServer })

  const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  })
  await mcpServer.connect(transport)
  try {
    return await transport.handleRequest(request, { parsedBody })
  } finally {
    await transport.close()
    await mcpServer.close()
  }
}

Now plug handleMcpRequest into whichever web runtime you use:

// 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 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] }.

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, with a new server per POST), see 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:

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:

import { goke } from 'goke'
import { addMcpCommands } from '@goke/mcp'
import type { McpOAuthState, CachedMcpTools } from '@goke/mcp'
import fs from 'node:fs'
import path from 'node:path'
import os from 'node:os'

// --- Config persistence (JSON file in ~/.myapp/) ---

const CONFIG_DIR = path.join(os.homedir(), '.myapp')
const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')

interface AppConfig {
  mcpUrl: string
  oauthState?: McpOAuthState
  cache?: CachedMcpTools
}

function loadConfig(): AppConfig {
  try {
    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'))
  } catch {
    return { mcpUrl: 'https://mcp.notion.com/mcp' }
  }
}

function saveConfig(partial: Partial<AppConfig>): void {
  const merged = { ...loadConfig(), ...partial }
  fs.mkdirSync(CONFIG_DIR, { recursive: true })
  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2))
}

// --- CLI setup ---

const cli = goke('myapp')

await addMcpCommands({
  cli,
  clientName: 'myapp',
  getMcpUrl: () => loadConfig().mcpUrl,
  oauth: {
    clientName: 'My App',
    load: () => loadConfig().oauthState,
    save: (state) => saveConfig({ oauthState: state }),
  },
  loadCache: () => loadConfig().cache,
  saveCache: (cache) => saveConfig({ cache }),
})

// Custom commands alongside auto-generated MCP commands
cli
  .command('login', 'Save MCP URL')
  .option('--url <url>', 'MCP server URL')
  .action((options) => {
    saveConfig({ mcpUrl: options.url })
    console.log(`Saved: ${options.url}`)
  })

cli.command('logout', 'Clear tokens').action(() => {
  saveConfig({ oauthState: undefined, cache: undefined })
  console.log('Logged out')
})

cli.help()
cli.completions()
cli.parse()

API

addMcpCommands(options)

Registers MCP tool commands on a goke CLI instance.

OptionTypeDefaultDescription
cliGokerequiredThe 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() => 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
argvstring[]process.argv.slice(2)Args used to skip live discovery on help and already registered commands
commandPrefixstring''Prefix for commands (e.g. 'mcp' makes mcp notion-search)
clientNamestring'mcp-cli-client'Name sent to the MCP server during connection
oauthMcpOAuthConfig—OAuth config for servers that require authentication
loadCache() => CachedMcpTools | undefinedrequiredLoad cached tools from storage
saveCache(cache) => voidrequiredSave cached tools to storage

McpOAuthConfig

FieldTypeDescription
clientNamestringName shown on the OAuth consent screen
load() => McpOAuthState | undefinedLoad persisted OAuth state
save(state) => voidSave OAuth state after auth or token refresh
onAuthUrl(url: string) => voidCustom handler for auth URL (default: opens browser)
onAuthSuccess() => voidCalled after successful authentication
onAuthError(error: string) => voidCalled on authentication failure

Exports

// MCP server → CLI (consume MCP tools as CLI commands)
export { addMcpCommands } 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

OAuth is lazy — no auth check happens on startup. The flow is:

User runs command
       │
       ▼
  Call MCP tool ───── success ──▸ Print result
       │
    401 error
       │
       ▼
  Start local server (random port)
       │
       ▼
  Open browser ──▸ User authorizes
       │
       ▼
  Receive callback with auth code
       │
       ▼
  Exchange code for tokens
       │
       ▼
  Save tokens via oauth.save()
       │
       ▼
  Retry the original tool call

Tokens are persisted via the oauth.save() callback you provide, so subsequent runs skip auth entirely.

Caching

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.

If a live tools/list cannot run (no transport, 401 during --help), addMcpCommands still registers tools from an expired cache so help stays useful.

License

MIT

版本与发布记录

@goke/mcp 共发布 13 个版本,首次发布于 2026/02/09;过去 12 个月发布了 13 个版本。

版本发布日期距今
0.1.2latest2026/09/162 个月前
0.1.12026/09/162 个月前
0.1.02026/09/162 个月前
0.0.132026/08/153 个月前
0.0.122026/08/153 个月前
0.0.112026/06/274 个月前

关于 @goke/mcp 的常见问题

@goke/mcp 是什么?

Dynamically generate CLI commands from MCP server tools

如何安装 @goke/mcp?

在项目目录运行 npm install @goke/mcp,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:goke(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@goke/mcp 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@goke/mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@goke/mcp 可以商用吗?

@goke/mcp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@goke/mcp 的下载量有多少?

根据 npm 官方下载统计,@goke/mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 65,139 次,日均约 2,171 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@goke/mcp 还在维护吗?

最新版本 0.1.2 发布于 2026/09/16(2 个月前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/02/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。