| 1 | import type { DocsMcpDict } from "../types"; |
| 2 | |
| 3 | /** 「用 MCP 连接工具」页的简体中文词典；与 `en/docs-mcp.ts` 逐段对应。 */ |
| 4 | export const docsMcp: DocsMcpDict = { |
| 5 | metaTitle: "用 MCP 连接工具 · Codewhale 文档", |
| 6 | metaDescription: |
| 7 | "添加 Model Context Protocol 服务器让 Codewhale 使用更多工具，登录远程服务器，把 Codewhale 本身作为 MCP 服务器运行，并试用代码模式。", |
| 8 | bodyClassName: "text-ink-soft leading-[1.9] tracking-wide", |
| 9 | title: "用 MCP 连接工具", |
| 10 | lede: |
| 11 | "MCP 服务器能为 Codewhale 带来更多工具——数据库、问题跟踪系统、浏览器等。你可以添加一个由 Codewhale 替你启动的本地服务器，也可以通过 URL 添加远程服务器。这些工具与内置工具走同一套审批流程。", |
| 12 | sections: [ |
| 13 | { |
| 14 | id: "add", |
| 15 | title: "添加服务器", |
| 16 | blocks: [ |
| 17 | { |
| 18 | code: `codewhale mcp add git --command "uvx" --arg "mcp-server-git" |
| 19 | codewhale mcp add docs --url "https://example.com/mcp" |
| 20 | codewhale mcp list |
| 21 | codewhale mcp validate`, |
| 22 | lang: "终端", |
| 23 | }, |
| 24 | { |
| 25 | p: "`--command` 通过 stdio 启动本地服务器，每个参数用一个 `--arg`。`--url` 通过 Streamable HTTP 连接远程服务器，必要时回退到旧版 SSE。`mcp validate` 会检查配置文件以及你标记为必需的服务器。", |
| 26 | }, |
| 27 | { |
| 28 | p: "在会话中，`/mcp` 会打开 MCP 管理器：显示每个服务器的状态、传输方式、超时设置、错误信息和已发现的工具。同样的操作在那里也能完成，例如 `/mcp add stdio <name> <command>` 和 `/mcp add http <name> <url>`。", |
| 29 | }, |
| 30 | { |
| 31 | note: "MCP 服务器以你的权限运行。只添加你信任的服务器，就像只安装你信任的程序一样。", |
| 32 | }, |
| 33 | ], |
| 34 | }, |
| 35 | { |
| 36 | id: "remote-auth", |
| 37 | title: "登录远程服务器", |
| 38 | blocks: [ |
| 39 | { |
| 40 | p: "使用 OAuth 的服务器，先用 URL 添加再登录。使用 bearer token 的服务器，把令牌放在环境变量里，而不是写进配置文件：", |
| 41 | }, |
| 42 | { |
| 43 | code: `codewhale mcp login docs |
| 44 | codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var TRACKER_TOKEN`, |
| 45 | lang: "终端", |
| 46 | }, |
| 47 | { |
| 48 | p: "显式设置的 Authorization 请求头始终优先：先应用配置中的请求头，其次是 bearer token 环境变量，最后才是已保存的 OAuth 登录。`codewhale mcp logout <name>` 会删除本机保存的登录信息；提供商那边的授权可能仍然有效，需要到提供商处撤销。", |
| 49 | }, |
| 50 | ], |
| 51 | }, |
| 52 | { |
| 53 | id: "config", |
| 54 | title: "编辑配置文件", |
| 55 | blocks: [ |
| 56 | { |
| 57 | p: "服务器配置保存在 `~/.codewhale/mcp.json`，`codewhale mcp init` 会生成一个初始文件。其他客户端使用的 `mcpServers` 键同样可用，现成的配置可以直接粘贴进来。", |
| 58 | }, |
| 59 | { |
| 60 | code: `{ |
| 61 | "servers": { |
| 62 | "example": { |
| 63 | "command": "node", |
| 64 | "args": ["./path/to/your-mcp-server.js"], |
| 65 | "env": {}, |
| 66 | "disabled": false |
| 67 | } |
| 68 | } |
| 69 | }`, |
| 70 | lang: "mcp.json", |
| 71 | }, |
| 72 | { |
| 73 | p: "修改文件后，在会话中运行 `/mcp reload` 即可，无需重启。服务器只在某个回合需要它的工具时才启动；如果希望它在启动时就连接，把它标记为 `\"required\": true`。", |
| 74 | }, |
| 75 | ], |
| 76 | }, |
| 77 | { |
| 78 | id: "tool-names", |
| 79 | title: "找到这些工具", |
| 80 | blocks: [ |
| 81 | { |
| 82 | p: "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`：名为 `git` 的服务器提供的 `status` 工具，就叫 `mcp_git_status`。`codewhale mcp tools <server>` 会列出某个服务器提供的工具。连接失败或已禁用的服务器，其工具永远不会显示为可用。", |
| 83 | }, |
| 84 | { |
| 85 | p: "MCP 工具遵循你的[审批设置](/docs/modes)：在策略允许时，列出和读取服务器的资源与提示词无需确认；有副作用的工具会先征求你的同意。Full Access 也不会绕过仓库规则或托管策略。", |
| 86 | }, |
| 87 | ], |
| 88 | }, |
| 89 | { |
| 90 | id: "serve", |
| 91 | title: "把 Codewhale 作为 MCP 服务器运行", |
| 92 | blocks: [ |
| 93 | { |
| 94 | p: "其他 MCP 客户端——包括另一个 Codewhale 会话——都可以使用 Codewhale 的工具。只需注册一次：", |
| 95 | }, |
| 96 | { |
| 97 | code: `codewhale mcp add-self |
| 98 | codewhale mcp tools codewhale`, |
| 99 | lang: "终端", |
| 100 | }, |
| 101 | { |
| 102 | p: "`add-self` 会写入一条通过 stdio 运行 `codewhale serve --mcp` 的配置。每个客户端各自启动一个进程，不会打开任何网络端口。`codewhale serve --http` 则是另一回事——它是供应用使用的 [Runtime API](/docs/runtime-api)。", |
| 103 | }, |
| 104 | ], |
| 105 | }, |
| 106 | { |
| 107 | id: "code-mode", |
| 108 | title: "用代码模式组合工具调用（实验性）", |
| 109 | blocks: [ |
| 110 | { |
| 111 | p: "代码模式让模型写一段简短的 JavaScript 程序，在其中调用多个工具、循环和筛选结果，而不必把每次调用都作为单独的一步。只有程序的最终结果会返回给模型，长时间的查找因此更紧凑。它默认关闭。可以只在一次会话中试用，也可以在配置中开启：", |
| 112 | }, |
| 113 | { |
| 114 | code: `codewhale --enable code_mode |
| 115 | |
| 116 | # ~/.codewhale/config.toml |
| 117 | [features] |
| 118 | code_mode = true`, |
| 119 | lang: "终端 / config.toml", |
| 120 | }, |
| 121 | { |
| 122 | list: [ |
| 123 | "程序中只能调用无需审批的只读工具。任何写入、运行 shell 命令或需要征求你同意的调用，都会让程序停止，并报告被拒绝的是哪一次调用。", |
| 124 | "程序中暂时还不能调用 MCP 工具，请把它们作为普通工具调用来使用。", |
| 125 | "每个程序的上限：50 次工具调用、同时最多 4 次、30 秒、返回 16 KiB。", |
| 126 | "Plan 模式下不能使用代码模式。", |
| 127 | ], |
| 128 | }, |
| 129 | ], |
| 130 | }, |
| 131 | ], |
| 132 | next: [ |
| 133 | { |
| 134 | href: "/docs/hooks", |
| 135 | label: "在事件发生时运行命令", |
| 136 | note: "在工具调用执行前检查或改写它，MCP 工具也不例外。", |
| 137 | }, |
| 138 | { |
| 139 | href: "/docs/modes", |
| 140 | label: "设置模式与审批", |
| 141 | note: "决定哪些 MCP 调用需要你批准。", |
| 142 | }, |
| 143 | { |
| 144 | href: "/docs/runtime-api", |
| 145 | label: "用 Runtime API 自动化", |
| 146 | note: "通过 HTTP 从你自己的应用或脚本驱动 Codewhale。", |
| 147 | }, |
| 148 | ], |
| 149 | sourceNote: |
| 150 | "来源文档：docs/MCP.md、crates/tui/src/tools/codemode.rs · 修改时同步更新 docs-map.ts。", |
| 151 | }; |
| 152 |