lywsvip/DeepSeek-TUI
1
0
Fork 0
mirror of https://github.com/Hmbown/DeepSeek-TUI.git synced 2026-09-03 06:50:13 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
DeepSeek-TUI/docs/zh_hans/MCP.md
Sh1Zuku 2ab5c78c06 docs(i18n): complete Tier-2 must-haves for EPIC #5482 (#5793) 
* Complete Tier-2 Must-haves for the EPIC #5482

* docs: remove legacy zh-CN redirect files

* docs: improve Agent Runtime diagram

---------

Co-authored-by: CodeWhale Bot <bot@codewhale.net>
2026-08-31 23:08:41 -07:00

19 KiB
Raw Permalink Blame History

MCP（外部工具服务器）

本文翻译自英文版 MCP.md，与英文修订 4d915398f（2026-08-19）同步。

codewhale 可以通过 MCP（Model Context Protocol，模型上下文协议）加载额外工具。MCP 服务器可以是 TUI 启动的本地 stdio 进程，也可以是使用 Streamable HTTP（带传统 SSE 回退）的远程基于 URL 的服务器。

浏览说明：

  • Web 是规范的、延迟加载的内置浏览工具；在网络策略允许时，它提供 search、fetch 和 wait 操作。
  • web_search、fetch_url 和 wait_for_dev_server 是隐藏的仅回放别名。新的提示和集成应使用 Web。

服务器模式说明：

  • codewhale-tui serve --mcp 运行 MCP stdio 服务器。
  • codewhale-tui serve --http 运行运行时 HTTP/SSE API（独立模式）。
  • codewhale 调度器将 codewhale mcp-server 作为等价的 stdio 入口点暴露出来，供独立分发的 CLI 使用。

设置向导与手动 MCP 设置（#3407）

/setup 中心包含一个可选的 Tools and MCP 步骤。该步骤仅用于发现/就绪检查：

向导可以做的 仍然需要手动/显式操作
将已配置的服务器显示为 healthy / needs_config / off 启动或连接 MCP 服务器
报告配置路径是否存在（全局 + 项目） 写入或编辑 mcp.json 内容
安全的静态健康探测（缺少 command/url、损坏的绝对路径、缺少 bearer 环境变量） codewhale mcp validate、实时连接、OAuth 登录
指向安全的入门路径（/mcp、codewhale mcp init、codewhale doctor） 安装社区技能、信任技能、启用插件
共享来自同一 skill/MCP 适配器的 Hotbar 来源计数（#3399） 绑定 Hotbar 槽位（Hotbar 步骤 / H）
记录可选的/needs_action setup_state，不阻塞首次运行 任何会生成进程或安装包的操作

空清单不是错误：首次运行的用户会看到"尚未配置任何内容，这没关系。"失败或不完整的已配置服务器会以 needs_config 状态显示，并附带可操作的提示，绝不会阻塞设置完成。枚举过程除静态探测外，绝不执行 MCP/插件命令。摘要会隐去命令、参数、环境变量、请求头和令牌。

codewhale doctor 以相同的可选表面意图（路径、计数、静态检查）报告 MCP/技能/工具/插件的健康状态，使向导与 doctor 保持一致。

插件贡献的 MCP

通过审查的本地插件包可以贡献 MCP 服务器，而无需创建第二套传输或审批系统。这些服务器使用本文档记载的同一条 MCP 管理器、工具审批、资源、提示、超时和网络策略路径，并以命名空间化的 <plugin>-<server> 身份出现。

插件包边界有意比用户编写的 mcp.json 更严格：未知字段和模糊的传输方式默认失败关闭；stdio 环境变量值必须是精确的环境来源引用；远程字面量请求头和含机密信息的 URL 会被拒绝；声明的网络主机必须与规范化后的端点主机集合完全匹配；重定向保持在已审查的源站内。已审查的插件远程端点还会完全绕过环境中的 HTTP 代理配置；代理凭据和代理可见流量不属于 v1 审查范围。插件审查会披露本地主机用户权限、结构化 argv、环境来源、端点、认证来源名称、作用域和工具过滤器，但不会读取或打印机密值。

信任（Trust）会暂存已审查的内容，但不会启用它。启用操作会把该暂存快照附加到当前工作区的 MCP 池。禁用、撤销以及其他跨进程的代际变更会移除目录条目、取消进行中的操作，并终止插件的 stdio 子进程。在每次分派/目录边界之前，源码或暂存树的漂移都会被完全重新验证，并让下一个边界失败关闭；v0.9.1 不会在已经运行的调用期间持续对可变树做哈希，因此不承诺由漂移触发的调用中途取消。MCP 订阅不会通过插件包暴露。完整的生命周期契约请参阅插件包。

MCP 配置引导

在解析出的 MCP 路径处创建一份入门 MCP 配置：

codewhale-tui mcp init

codewhale-tui setup --mcp 会在技能设置的同时执行相同的 MCP 引导。

常用管理命令：

codewhale-tui mcp list
codewhale-tui mcp tools [server]
codewhale-tui mcp add <name> --command "<cmd>" --arg "<arg>"
codewhale-tui mcp add <name> --url "http://localhost:3000/mcp"
codewhale-tui mcp add <name> --url "https://example.com/mcp" --bearer-token-env-var MCP_TOKEN
codewhale-tui mcp login <name>
codewhale-tui mcp logout <name>
codewhale-tui mcp enable <name>
codewhale-tui mcp disable <name>
codewhale-tui mcp remove <name>
codewhale-tui mcp validate

TUI 内管理器

在交互式 TUI 中，/mcp 会为解析出的 MCP 配置路径打开一个紧凑的管理器。它显示每个已配置的服务器、该服务器是启用还是禁用、其传输方式、命令或 URL、超时值、连接错误，以及运行发现后得到的工具/资源/提示。

TUI 内支持的操作：

/mcp init
/mcp init --force
/mcp import
/mcp recommendations
/mcp add recommended <id>
/mcp add stdio <name> <command> [args...]
/mcp add http <name> <url>
/mcp login <name> [--scope scope]
/mcp logout <name>
/mcp enable <name>
/mcp disable <name>
/mcp remove <name>
/mcp validate
/mcp reload

推荐插件与配套集成

/mcp recommendations 是 Codewhale 原生的精选建议界面。条目被描述为产品插件，带有其组件类型和来源，但 /mcp add recommended <id> 仍然只写入指定的 MCP 服务器组件。查看推荐绝不会获取、安装、信任或启用任何内容。添加一条推荐会写入配置；服务器只有在显式执行 /mcp restart 之后才会首次启动。

v0.9.10 的产品建议使用这些经过审查的固定版本定义。Plugins 视图是产品/安装界面；MCP、Skills 和沙箱适配器是透明的组件类型，它们各自的标签页仍然是可操作和可诊断的界面：

插件 组件 固定版本定义 来源与成熟度 安装边界
Chrome DevTools MCP 服务器（stdio） npx -y chrome-devtools-mcp@1.7.0（Windows 上为 npx.cmd） ChromeDevTools 官方项目 用户重启 MCP 时，npm 可能会下载固定版本的包。
Playwright MCP 服务器（stdio） npx -y @playwright/mcp@0.0.79 --isolated（Windows 上为 npx.cmd） 微软官方项目 --isolated 会启动全新的浏览器配置文件；npm 只会在显式重启后才下载固定版本的包。
Cua Computer Use MCP 服务器（stdio） cua-driver mcp；Driver 0.20.0 已为本版本审查 Cua 官方项目；预览集成 签名驱动和操作系统权限是分开的、显式的安装。/mcp add recommended cua 只写入配置，绝不会安装或授予其中任何一项。
Browser Use Skill 加单独安装的 Python 运行时 Skill/运行时版本 0.13.8 browser-use 官方项目 可选配套：不是 MCP 服务器。Codewhale 不会自动运行上游的 Skill 安装器，也不会安装其浏览器/运行时依赖。
Anthropic Sandbox Runtime 沙箱适配器配套 @anthropic-ai/sandbox-runtime@0.0.73 anthropic-experimental 官方项目；测试版 v0.9.10 中仅文档说明的适配器候选：不是 MCP 服务器，也不是活跃的 Codewhale 插件适配器。它不会取代 Codewhale 的沙箱策略。

Container Use 仍然是一个带有 MCP 服务器组件（container-use stdio）的额外实验性建议。该二进制必须单独安装；/mcp add recommended container-use 只写入配置，Codewhale 绝不会下载它。

这种呈现方式遵循了本地 Grokbuild 扩展视图中的同样有用的边界（一个产品插件可以暴露 MCP 或 Skill 组件，同时组件标签页仍可检查）、Kimi 市场的显式显示名称/层级/来源字段，以及 Codex 市场的显式来源和安装策略字段。Codewhale 保持其更严格的规则：来源和外部策略只是显示元数据，绝不会被继承为信任或自动安装。完整的插件包和市场语义请参阅插件包。

/mcp validate（别名 /mcp doctor）只为了 UI 发现而重新连接：它刷新你在分页器中看到的管理器快照，而不是模型拿到的目录。

/mcp reload（别名 /mcp reconnect、/mcp restart）是热重载路径。它会重新读取 MCP 配置来源，并通过引擎持有的连接池重新连接，因此重建后的目录正是下一个模型回合所用的目录——无需重启 TUI。从 TUI 中做出的配置修改会立即写入，管理器会把快照标记为需要重载，直到你运行它；重载失败会保留之前活跃的连接池不变，并如实说明。

无头界面是例外：ConfigReload 应用服务器请求不会刷新 MCP 连接，因此无头运行时在 MCP 配置变更后仍然需要重启。

远程 HTTP 认证

基于 URL 的 MCP 服务器可以使用静态请求头、环境变量派生的请求头、bearer-token 环境变量或 OAuth。授权优先级是保守的：

  1. headers 和 env_headers 首先应用。
  2. 若 Authorization 头尚未设置，bearer_token_env_var 会添加 Authorization: Bearer <env value>。
  3. 仅当不存在 Authorization 头时，才使用存储的 OAuth 凭据。

对于 bearer-token 认证，推荐使用环境变量支持的配置：

{
  "servers": {
    "remote": {
      "url": "https://example.com/mcp",
      "bearer_token_env_var": "EXAMPLE_MCP_TOKEN"
    }
  }
}

对于通用的远程 MCP OAuth，添加 URL 服务器并运行登录：

codewhale-tui mcp add remote --url "https://example.com/mcp"
codewhale-tui mcp login remote

Codewhale 会发现服务器的 OAuth 元数据，在你的浏览器中打开授权 URL，监听本地回调，交换授权码，并通过 Codewhale 的机密后端存储令牌响应。存储的 OAuth 令牌会按服务器名称加 URL 查找，并在可能的情况下于请求前刷新。登录期间，CLI 会打印授权 URL 和等待状态，同时本地回调监听器处于活动状态。如果基于 URL 的服务器在连接/发现期间返回 401 或 Unauthorized，codewhale mcp connect <name> 会报告需要 OAuth 认证，并指向 codewhale mcp login <name>。资源辅助工具的列表还会为认证类失败显示 authentication_required 条目，而不是静默地看起来为空。

可选的 OAuth 字段：

{
  "servers": {
    "remote": {
      "url": "https://example.com/mcp",
      "scopes": ["tools/read"],
      "oauth": {
        "client_id": "public-client-id"
      },
      "oauth_resource": "https://example.com"
    }
  }
}

当提供方要求固定重定向时，用户级配置可以设置回调行为：

mcp_oauth_callback_port = 1455
mcp_oauth_callback_url = "http://127.0.0.1:1455/callback"

这些回调字段会在项目作用域的配置覆盖中被忽略。

Hugging Face MCP

Hugging Face 为 Hub 资源、文档、数据集、Spaces 和社区工具提供了一个托管的 MCP 服务器。Codewhale 不会从 /hf 调用 Hugging Face 的 Hub HTTP API；它只帮助你检查并设置常规 MCP 管理器将要加载的 MCP 配置。

推荐的设置路径是 Hugging Face 的设置页生成的配置：

  1. 登录后访问 https://huggingface.co/settings/mcp。
  2. 选择最接近你的 Codewhale 配置形态的 MCP 客户端，并复制生成的服务器片段。
  3. 将 Hugging Face 服务器条目粘贴到解析出的 MCP 配置文件中。
  4. 运行 /mcp reload 重建模型可见的实时工具池。

Codewhale 同时读取 servers 和 mcpServers，因此设置页生成的片段可以在不更改 MCP 文件其余部分的情况下适配。纯占位符的形态如下所示：

{
  "servers": {
    "huggingface": {
      "url": "https://huggingface.co/mcp",
      "headers": {
        "Authorization": "Bearer ${HF_TOKEN}"
      }
    }
  }
}

上面的占位符不是可运行的机密。请在私有 MCP 配置中使用设置页生成的值，并且永远不要提交真实的 Hugging Face 令牌。

交互式辅助命令：

/hf mcp status
/hf mcp setup
/hf concepts

/hf mcp status 会检查已配置的 MCP 文件，查找常见的 Hugging Face 服务器名称或 Hugging Face MCP URL。/hf concepts 解释 Hugging Face provider 路由、Hugging Face MCP 和显式 Hub 工作流之间的区别。

官方文档：https://huggingface.co/docs/hub/hf-mcp-server

配置文件位置

默认路径：

  • ~/.codewhale/mcp.json（当 Codewhale 文件不存在时，仍会读取 ~/.deepseek/mcp.json）

覆盖方式：

  • 配置项：mcp_config_path = "/path/to/mcp.json"
  • 环境变量：DEEPSEEK_MCP_CONFIG=/path/to/mcp.json

codewhale-tui mcp init（以及 codewhale-tui setup --mcp）会写入这个解析出的路径。

交互式 /config 编辑器也会暴露 mcp_config_path。在 TUI 中更改它，会更新 /mcp 使用的路径，并将连接池标记为需要重载；随后 /mcp reload 会把实时连接池切换到新的配置来源。

编辑 MCP 文件或更改 mcp_config_path 后，运行 /mcp reload。无需重启 TUI。

工具命名

发现的 MCP 工具会以如下形式暴露给模型：

  • mcp_<server>_<tool>

例如：名为 git 的服务器上的名为 status 的工具会变成 mcp_git_status。

命令面板包含按服务器分组的 MCP 条目。它会显示已禁用和失败的服务器，而不是隐藏它们，并使用与展示给模型的相同的运行时工具名。

资源与提示辅助工具

启用 MCP 时，CLI 还会暴露辅助工具：

  • list_mcp_resources（可选 server 过滤器）
  • list_mcp_resource_templates（可选 server 过滤器）
  • mcp_read_resource / read_mcp_resource（别名）
  • mcp_get_prompt

最小示例

{
  "timeouts": {
    "connect_timeout": 10,
    "execute_timeout": 60,
    "read_timeout": 120
  },
  "servers": {
    "example": {
      "command": "node",
      "args": ["./path/to/your-mcp-server.js"],
      "env": {},
      "disabled": false
    }
  }
}

为了与其他客户端兼容，你也可以使用 mcpServers 而不是 servers。

将 Codewhale 作为 MCP 服务器运行

你可以把本地 Codewhale 二进制注册为 MCP 服务器，这样其他 Codewhale 会话（或任何 MCP 客户端）就能调用它的工具。

快速设置

codewhale-tui mcp add-self

这会解析当前二进制路径，生成一个运行 codewhale-tui serve --mcp 的配置条目，并将其写入你的 MCP 配置文件。默认服务器名称是 codewhale。

选项：

  • --name <NAME> — 自定义服务器名称（默认：codewhale）
  • --workspace <PATH> — 服务器的工作目录

手动配置

~/.codewhale/mcp.json 中等价的手动条目：

{
  "servers": {
    "codewhale": {
      "command": "/path/to/codewhale",
      "args": ["serve", "--mcp"],
      "env": {}
    }
  }
}

codewhale-tui 二进制直接支持 serve --mcp。codewhale 调度器提供等价的 codewhale mcp-server stdio 入口点。使用你 PATH 中的那一个（运行 which codewhale 或 which codewhale-tui 找到完整路径）。mcp add-self 命令会自动解析出正确的二进制。

前提条件

  • command 引用的二进制必须存在且可执行。
  • MCP 服务器通过 stdio 作为子进程运行——不需要网络端口。
  • 每个 MCP 客户端会话都会生成自己的服务器进程。

工具命名

来自 MCP 服务器的工具遵循标准命名约定：

  • mcp_<server>_<tool>

例如，来自默认服务器（名为 codewhale）的 shell 工具会变成 mcp_codewhale_shell。

MCP 服务器 vs HTTP/SSE API vs ACP

codewhale-tui serve --mcp codewhale-tui serve --http codewhale-tui serve --acp
协议 MCP stdio HTTP/SSE JSON-RPC ACP stdio
用例 面向 MCP 客户端的工具服务器 面向应用的运行时 API 面向 Zed/自定义 ACP 客户端的编辑器代理
配置 ~/.codewhale/mcp.json 条目 直接 URL 连接 编辑器的 agent_servers 自定义命令
生命周期 按客户端会话生成 长时间运行的守护进程 按编辑器代理会话生成

当你希望 Codewhale 工具对其他 MCP 客户端可用时，使用 mcp add-self。在构建直接消费 API 的应用时，使用 serve --http。当编辑器想以 ACP 代理身份与 Codewhale 对话时，使用 serve --acp。

验证

添加之后，测试连接：

codewhale-tui mcp validate
codewhale-tui mcp tools codewhale

服务器字段

每个服务器的设置：

  • command（字符串，必需）
  • args（字符串数组，可选）
  • env（对象，可选）
  • connect_timeout、execute_timeout、read_timeout（秒，可选）
  • disabled（布尔值，可选）
  • enabled（布尔值，可选，默认 true）
  • required（布尔值，可选）：如果该服务器无法初始化，启动/连接验证会失败。
  • enabled_tools（数组，可选）：该服务器的工具名称允许列表。
  • disabled_tools（数组，可选）：在 enabled_tools 之后应用的拒绝列表。
  • url（字符串，可选）：远程 MCP 服务器的 Streamable HTTP 端点。
  • transport（字符串，可选）：对于传统 SSE 端点，设为 "sse"。
  • headers（对象，可选）：基于 URL 的服务器使用的字面量 HTTP 请求头。
  • env_headers 或 env_http_headers（对象，可选）：请求头名称到环境变量名称的映射。
  • bearer_token_env_var（字符串，可选）：包含 bearer token 的环境变量。
  • scopes（数组，可选）：mcp login 的默认 OAuth 作用域。
  • oauth.client_id（字符串，可选）：预先注册的 OAuth 客户端 ID。
  • oauth_resource（字符串，可选）：附加到授权 URL 的资源参数。

安全说明

MCP 工具与内置工具走相同的审批框架。只读的 MCP 辅助工具（资源/提示的列出与读取）在策略允许时，可以在 Ask 和 Auto-Review 中无提示地运行，而会产生副作用的 MCP 工具则需要审批。Full Access 不会绕过强制性的策略拦截。

你仍然应该只配置你信任的 MCP 服务器，并把 MCP 服务器配置视为与在你的机器上运行代码等价。避免提交字面量的 Authorization 请求头。优先使用 env_headers、bearer_token_env_var 或 OAuth 登录，让机密保持在 MCP 文件之外。

故障排查

  • 运行 codewhale-tui doctor 确认它解析出的 MCP 配置路径以及该路径是否存在。
  • 在 TUI 中运行 /mcp validate 刷新可见的服务器/工具快照。
  • 如果配置或凭据变更后模型的目录中缺少工具，运行 /mcp reload —— /mcp validate 只刷新 UI 快照。
  • 如果 MCP 配置缺失，运行 codewhale-tui mcp init --force 重新生成它。
  • 如果工具没有出现，请验证服务器命令能否在你的 shell 中工作，以及服务器是否支持 MCP 的 tools/list。
Reference in New Issue View Git Blame Copy Permalink