ratel-local

<div align="center"> <h1>@ratel-ai/mcp-server</h1> <h4>通过 MCP 将 Ratel 目录暴露出来 - 从一个 CLI 管理你的 MCP 范围。</h4> <p> <a href="https://github.com/ratel-ai/ratel">Ratel 核心</a> • <a href="https://github.com/ratel-ai/ratel/blob/main/docs/roadmap.md">路线图</a> • <a href="https://discord.gg/hdKpx69NR">Discord</a> </p> <p> <a href="https://www.npmjs.com/package/@ratel-ai/mcp-server"><img src="https://img.shields.io/npm/v/@ratel-ai/mcp-server?label=npm&color=cb3837" alt="npm" /></a> <a href="https://github.com/ratel-ai/ratel-mcp/stargazers"><img src="https://img.shields.io/github/stars/ratel-ai/ratel-mcp?style=social" alt="GitHub stars" /></a> <a href="https://discord.gg/hdKpx69NR"><img src="https://img.shields.io/discord/1478702964003705015?logo=discord&logoColor=white&color=7289da&label=discord" alt="Discord" /></a> <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license" /></a> </p> </div> `@ratel-ai/mcp-server` 是一个包含两个功能的软件包： - 一个 **库**，它接受一个 Ratel [`ToolCatalog`](https://github.com/ratel-ai/ratel) 并将其暴露为一个 Model Context Protocol 服务器 - MCP 客户端（Claude Desktop，一个代理框架，一个 `@modelcontextprotocol/sdk` `Client`）看到的是 `search_capabilities` + `invoke_tool`（以及配置技能时的 `get_skill_content`），而不是每个上游的完整工具列表； - 一个 **CLI** (`ratel-mcp`)，它消除了 MCP 主机（Claude Code，Cursor，ChatGPT）和任意一组上游 MCP 服务器之间的网关 - 具有 Claude 兼容的配置 UX，三范围层次结构，HTTP + SSE 上游的 OAuth 2.1 / PKCE，以及用于迁移现有 Claude Code MCP 设置的一次性 `mcp import` 向导。 这是 `@ratel-ai/sdk` 的 [`registerMcpServer`](https://github.com/ratel-ai/ratel/blob/main/src/sdk/ts/README.md#registermcpserver--index-an-mcp-servers-tools-into-the-catalog) 的逆操作，它将上游 MCP 服务器的工具**摄入**到目录中。 `createMcpServer` 将目录**暴露为** MCP 服务器。 ## 安装 ```bash # CLI（全局安装） pnpm add -g @ratel-ai/mcp-server # 库（在 TS/Node 项目中） pnpm add @ratel-ai/mcp-server @ratel-ai/sdk @modelcontextprotocol/sdk ``` 或者跳过安装并直接运行 CLI： ```bash npx -y @ratel-ai/mcp-server --help ``` ### 代理插件市场 该存储库还附带了一个用于 Codex 和 Claude Code 的共享 Ratel MCP 插件。它 使用 `npx -y @ratel-ai/mcp-server@latest serve --auto-config` 启动 stdio 网关，并为设置，调试和工具使用审查捆绑了技能。 #### Codex 添加远程市场，然后从 **Ratel** 市场安装 **Ratel MCP**： ```bash codex plugin marketplace add ratel-ai/ratel-mcp ``` 对于 Codex 从检出进行本地开发，请从仓库根目录运行： ```bash codex plugin marketplace add . ``` #### Claude Code 添加远程市场并安装插件： ```bash claude plugin marketplace add ratel-ai/ratel-mcp claude plugin install ratel-mcp@ratel ``` 如果 Claude Code 已经在运行，请重新启动它或在会话中运行 `/reload-plugins`。 对于 Claude Code 从检出进行本地开发，请使用 `.` 作为市场： ```bash claude plugin marketplace add . claude plugin install ratel-mcp@ratel ``` Claude Code 插件目前无法设置顶级 `statusLine` 默认值，因此 `ratel-mcp mcp link` 和 `ratel-mcp mcp import` 自动安装 Ratel 状态行 在连接好 Claude Code 后（如果您已经配置了非 Ratel 状态行，则跳过此步骤）。手动安装或重新安装它使用 `ratel-mcp statusline install` 或从 Claude Code 代理页面在 `ratel-mcp ui` 中。参见 Claude 的 [状态行文档](https://code.claude.com/docs/en/statusline) 和 [插件参考](https://code.claude.com/docs/en/plugins-reference)。 ## CLI 快速入门 `ratel-mcp` 镜像 `claude mcp add` 的标志布局 - 任何适用于 Claude Code CLI 的调用在此处均不变。 ```bash # 添加上游（stdio） ratel-mcp mcp add --scope user airtable -e API_KEY=xyz -- npx -y airtable-mcp-server # 添加上游（HTTP，带 OAuth） ratel-mcp mcp add --scope user stripe https://mcp.stripe.com --transport http # 列出已配置的内容 ratel-mcp mcp list # 将现有的代理 MCP 设置导入到 ratel-mcp 的范围中 ratel-mcp mcp import ratel-mcp mcp import --agent codex # 将代理指向 Ratel 网关而不删除原生 MCP 条目 ratel-mcp mcp link ratel-mcp mcp link --agent claude-code # 安装 Claude Code 状态行 ratel-mcp statusline install # 通过 stdio 启动网关（这是链接的代理程序启动的内容） ratel-mcp serve --config ~/.ratel/config.json ``` 运行 `ratel-mcp <group>` 来获取组中的动词： | 组 | 动词 | |---|---| | `mcp` | `add`，`remove`，`list`，`get`，`edit`，`import`，`link`，`auth` | | `backup` | `list` | | `statusline` | 从 stdin 渲染，`install`，`uninstall` | | （顶级） | `serve`，`ui` | ### `ratel-mcp mcp add` - 与 Claude 兼容 ``` ratel-mcp mcp add [flags] <name> -- <command> [args...] # stdio ratel-mcp mcp add [flags] <name> <url> # http / sse ``` | 标志 | 含义 | |---|---| | `--transport stdio\|http\|sse` | 强制传输。否则推断（URL → http， `--` → stdio）。 | | `--scope user\|project\|local` | 要写入的范围。默认为 `user`。 | | `--env KEY=VALUE` / `-e KEY=VALUE` | stdio 条目的环境变量。重复。 | | `--header "Name: Value"` | HTTP 头部，用于 http/sse 条目。重复。 | | `--client-id <id>` / `--client-secret <s>` / `--callback-port <n>` / `--oauth-scope <s>` | http/sse 条目的 OAuth 客户端配置。DCR 是首选的 - 仅当上游不支持它时才传递 `--client-id`。 | | `--description <text>` | 服务器的人类描述。胜过自动获取的上游 `instructions`。 | | `--no-fetch-description` | 跳过自动探测 - 无连接，无描述获取，无 OAuth 流程。 | | `--force` | 覆盖所选范围内具有相同名称的现有条目。 | 默认情况下，`mcp add` 连接到上游并存储其服务器级 `instructions`（按 MCP 规范）作为条目的 `description`。对于 http/sse 上游，它驱动 OAuth 2.1 / PKCE 流内联（浏览器打开，令牌保存在 `~/.ratel/oauth/<name>.json` 中）。 ### 三范围层次结构 `ratel-mcp` 镜像 Claude Code 的 MCP 范围，具有三个逻辑配置： | 范围 | 路径 | 备注 | |---|---|---| | user | `~/.ratel/config.json` | 每用户，适用于所有地方。 | | project | `<root>/.ratel/config.json` | 与仓库一起提交。 | | local | `<root>/.ratel/config.local.json` | 每用户每项目；添加到项目的 `.gitignore` 中。 | 当您运行 `ratel-mcp serve --config a.json --config b.json --config c.json` 时，配置按顺序合并 - 最后一个在 `mcpServers` 键冲突时获胜。 `link` 命令在每个范围内将正确的 `--config` 链连接到 Claude Code。 `import` 向导将选定的原生 MCP 条目迁移到 Ratel，并可以在其第二阶段清理导入的条目。 ### Claude Code 状态行 `ratel-mcp statusline` 是一个 Claude Code 状态行命令。Claude 通过 stdin 传递 JSON 有效载荷；命令向 stdout 写入两行状态行内容 如果有效载荷或遥测缺失，则打开加载/无遥测行。 ```bash ratel-mcp statusline install # 写入 ~/.claude/settings.json ratel-mcp statusline install --force # 替换另一个配置的状态行 ratel-mcp statusline uninstall # 仅删除 Ratel 拥有的状态行 ``` 安装写入用户范围的 Claude Code 设置： ```json { "statusLine": { "type": "command", "command": "ratel-mcp statusline", "padding": 0, "refreshInterval": 30 } } ``` 状态行在 Ratel 通过链接的 MCP 条目或启用的 `ratel-mcp@...` 插件配置为启动 Ratel 时，将 Ratel 显示为启用状态。 它 不安装或启用插件本身。 ### OAuth 流 需要 OAuth 授权的 HTTP 和 SSE 上游通过 `ratel-mcp` 的循环回调流运行。从 CLI： 1. `ratel-mcp mcp add --scope user my-upstream https://mcp.example/mcp [--client-id <id>] [--callback-port <n>] [--oauth-scope "<s>"]` - 记录条目 **和** 驱动 OAuth 流内联。 2. `ratel-mcp mcp auth my-upstream` - 刷新优先。如果磁盘上有 `refresh_token`，则静默旋转（无浏览器）。如果刷新失败，则回退到仅 PKCE。 3. `ratel-mcp mcp auth --check` - 只读状态报告：令牌存在，刷新可用性，到期的时间。 4. `ratel-mcp mcp list` - 显示每条记录的单行身份验证列：`ok` / `expired` / `needs auth` / `n/a`。 当网关启动时，每个存储的令牌的 HTTP/SSE 上游都通过主动刷新运行。 `invoke_tool` 期间的 401 返回 `{ error: "needs_auth", upstream }`，因此代理可以分支并调用 `auth` MCP 工具来恢复。 ### 遥测 `ratel-mcp serve` 默认情况下将每个事件的 JSON 行写入 `~/.ratel/telemetry/<project-slug>/<ISO-ts>-<short>.jsonl` - 每个搜索，调用，网关调用，上游 MCP 调用，OAuth 事件和 Ratel 的上游工具负载估计令牌通过相同的 JSONL（[ADR 0009](https://github.com/ratel-ai/ratel/blob/main/docs/adr/0009-trace-events-core-owned-schema.md)）。尽力而为，可采样，在背压时丢失 - 查询日志形状，不是操作日志。 | 标志 | 环境变量 | 用途 | |---|---|---| | `--telemetry off` | `RATEL_TELEMETRY=off` | 禁止此运行的遥测。 | | `--telemetry-file <path>` | - | 覆盖 JSONL 路径（无斜线）。 | | - | `RATEL_TELEMETRY_DIR` | 覆盖默认的遥测根目录。 | 要汇总生成的 JSONL 流，请参阅 [`@ratel-ai/cli`](https://github.com/ratel-ai/ratel/tree/main/src/integrations/cli) 的 `ratel inspect` - 它共享磁盘格式。 ### 备份 每次 `import`，`link`，`add`，`edit` 和 `remove` 都会将触摸的文件快照到 `~/.ratel/backups/<ISO>/` 并带有 `manifest.json`。 `ratel-mcp backup list` 显示可用内容。 ### 浏览器 UI ```bash ratel-mcp ui # 在临时 127.0.0.1 端口启动本地 UI，打开浏览器 ratel-mcp ui --port 5731 # 绑定特定端口 ratel-mcp ui --no-open # 打印 URL 而不启动浏览器 ``` UI 在所有三个范围内镜像 CLI 动词：查看/添加/编辑/删除服务器，驱动 OAuth，从 Claude Code 导入/链接，并检查备份。服务器仅绑定到 `127.0.0.1` 并在启动 URL 中打印一次性会话令牌。 使用 `Ctrl-C` 停止它。 ## 库快速入门 ```ts import { ToolCatalog } from "@ratel-ai/sdk"; import { createMcpServer } from "@ratel-ai/mcp-server"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const catalog = new ToolCatalog(); catalog.register({ id: "read_file", name: "read_file", description: "从本地磁盘读取文件。", inputSchema: { type: "object", properties: { path: { type: "string" } } }, outputSchema: { type: "object", properties: { contents: { type: "string" } } }, execute: async ({ path }) => ({ contents: await fs.readFile(path, "utf8") }), }); const handle = await createMcpServer(catalog, { name: "my-gateway", version: "0.1.0", transport: new StdioServerTransport(), }); // 稍后，在关闭时： await handle.close(); ``` 连接到的 MCP 客户端将在另一端看到 `search_capabilities` 和 `invoke_tool`（以及存在技能时的 `get_skill_content`）。 `search_capabilities` 返回一个 `tools` 桶和一个 `skills` 桶。为了向后兼容，服务器还宣传了废弃的 `search_tools`（其 0.2.0 之前的仅工具结果），因此依赖该名称的客户端保持正常工作；新客户端应使用 `search_capabilities`。目录的工具通过 `invoke_tool` 可访问，直接列出 - 这就是全部内容（参见 [ADR 0003 `ratel-ai/ratel`](https://github.com/ratel-ai/ratel/blob/main/docs/adr/0003-tool-selection-replace-vs-suggest.md））。 ### `buildGatewayFromConfig` 更高级别的入口点，接受解析的 Ratel 配置（一个 `mcpServers` 映射，镜像 Claude Code 的形状），并启动每个条目的上游 MCP `Client`，将每个上游的工具注册到一个全新的目录中，并返回目录以及每个上游的元数据。 ```ts import { buildGatewayFromConfig, parseConfig } from "@ratel-ai/mcp-server"; const config = parseConfig(JSON.parse(await fs.readFile("./ratel-config.json", "utf8"))); const gateway = await buildGatewayFromConfig(config, { logger: (m) => console.error(m), }); // gateway.catalog -> ToolCatalog 包含每个上游工具 // gateway.upstreamServers -> [{ name, description?, toolCount }] 用于搜索工具描述块 // await gateway.close() -> 拆除每个上游客户端 ``` 如果单个上游启动失败，`buildGatewayFromConfig` 记录失败并且其他仍然注册 - 网关保持可用。句柄公开 `runAuthFlow()`（刷新优先；PKCE 回退）用于标记为 `needsAuth` 的 HTTP/SSE 上游，以及 `setListChangedNotifier()`，以便 MCP 服务器可以在成功流后重新列出。 ## 配置形状 配置镜像 Claude Code 的 `.claude.json` `mcpServers` 形状： ```json { "mcpServers": { "ev": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"], "description": "文件系统 & shell 实用程序" }, "remote": { "type": "http", "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer xyz" } } } } ``` `type` 在不存在时默认为 `"stdio"`。 `description` 是可选的元数据 - 用于从 `search_capabilities` 的描述中获取每个上游的描述符永远不会发送上游传输。 `stdio` 和 `http` 由 `defaultTransport stdio` 启用；`sse` 和未知类型由 `parseConfig` 接受，但未运行时被默认工厂跳过（提供自己的工厂以支持 sse）。 ## 结果包装 每个 `tools/call` 响应都带有网关的返回值作为 JSON 序列化文本块；纯对象返回也作为 `structuredContent` 公开： ```json { "content": [{ "type": "text", "text": "{\"foo\":1}" }], "structuredContent": { "foo": 1 } } ``` 数组（例如工具命中返回的工具）仅在 `content[0].text` 中传输，因为 MCP 需要 `structuredContent` 为 JSON 对象。 当 `invoke_tool` 驱动一个本身通过 `registerMcpServer` 注册的工具时，上游的 MCP 形状结果（ `{ content, structuredContent }`）嵌套在我们的 `structuredContent` 中一层更深。 `invoke_tool` 和 `get_skill_content` 的错误有效载荷（`{ error: "...", isError: true }` 表示未知 ID，错误参数或执行器抛出）由服务器提升为 MCP `isError: true` 结果，因此主机和模型可以从实际内容中区分出失败的调用 - 错误字段仍然包含原因。 ## 示例 - [`examples/claude-with-ratel/`](examples/claude-with-ratel/README.md) - Claude Code 会话由 `ratel-mcp` 作为唯一的 MCP 服务器。 ## 构建和测试 ```bash pnpm install pnpm build # tsc → dist/ pnpm typecheck pnpm lint # biome pnpm test # vitest ``` CI 在每个 PR 上运行所有上述操作。 ## 许可 **MIT**。免费使用，修改和重新分发。参见 [LICENSE.md](LICENSE.md)。 ## 相关 - [`@ratel-ai/sdk`](https://github.com/ratel-ai/ratel/blob/main/src/sdk/ts/README.md) - 带有 `ToolCatalog`，`searchCapabilitiesTool`，`invokeToolTool`，`registerMcpServer` 的 TypeScript SDK。 通过 NAPI-RS 捆绑 `ratel-ai-core`（BM25 检索）。 - [`@ratel-ai/cli`](https://github.com/ratel-ai/ratel/tree/main/src/integrations/cli) - 长期 Ratel 工件 CLI（今天的遥测检查）。 - [`ratel-ai/ratel`](https://github.com/ratel-ai/ratel) - 概述，路线图，ADR，基准链接。