# 伙伴 MCP 服务

功能 → MCP 服务与 Skill 市场使用相同的工作区、卡片和弹窗。支持新增、JSON 导入、编辑、停用、删除、连接测试及刷新工具。能力 → MCP 只展示当前伙伴获授权的服务，默认展示四张卡片，其余可展开。

## 配置与授权

1. 在 MCP 服务页新增连接，或导入标准 `mcpServers` JSON。
2. 点击服务卡片的「连接 / 刷新工具」，确认工具列表读取成功。
3. 在伙伴能力中开启 MCP 并应用，再选择授权的服务。
4. 原会话下一轮对话即可使用工具，无需新建会话。多个客户端操作共享同一服务端配置。

```json
{
  "mcpServers": {
    "viora": {
      "type": "http",
      "url": "https://example.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

直接新增时填写页面显示名称，连接配置填入上述 `viora` 对象；也兼容仅包含一个服务的完整 `mcpServers` 配置。多个服务必须用「导入 JSON」。两个入口均有常驻格式说明和可展开示例，示例不会覆盖草稿。支持 `http` / `streamable-http`，以及包含 `command`、`args`、`env`、可选 `cwd` 的 `stdio`。stdio 在 DSH 所在机器执行，不是浏览器所在机器；Docker 中在容器内执行。只添加可信服务。当前不支持旧版 SSE 或 OAuth 交互登录。

编辑时自动回填配置。headers、env、命令参数及含查询串或片段的 URL 默认以 `{{DSH_MCP_SAVED:…}}` 占位符显示，保持原样保存会沿用对应值；也可点击「显示完整配置」显式读取原值。修改后不能切换显示方式覆盖草稿。删除字段会移除原值，填写新值会替换；占位符不能移动到其他字段或用于导入新服务。配置读取失败时禁用保存并提供重试，保存检查读取时的版本，防止覆盖其他客户端修改。未改变连接配置的保存保留工具目录；实际改变连接才清空旧目录并要求重新刷新。导入遇到重名或保存失败不提交部分服务，不自动覆盖已有配置。

## 下一轮生效

### 官方 stdio 示例与启动排查

`npx -y mcp-remote` 的官方配置可原样导入，不需要改写成 HTTP 配置。使用非 localhost 的明文 HTTP 时，mcp-remote 自身要求在 args 中显式提供 `--allow-http`；请仅用于可信网络。DSH 不自动绕过这个安全检查。

启动失败会区分依赖缺失、HTTP 限制、认证失败、命令缺失、DNS、连接拒绝、证书与超时，并在刷新错误中提示处理方向。原始 stderr 仅在握手期间使用最多 16 KiB 的内存尾部缓冲，随后清空，不写入状态或展示，以免输出 Authorization、环境变量或命令参数中的密钥。npx 缓存损坏需要在 DSH 实际运行环境修复对应包的缓存并重新安装；不需要删除 MCP 服务或重填凭据。不自动清空全局 npm 缓存或重放业务工具调用。

授权绑定、服务启停、配置版本及成功刷新的工具目录版本参与 `SessionConfigurationIndex` 修订计算。`agent/pre-step` 在下一轮组装提示和工具前重新注册；同一轮不热换工具列表，不唤醒空闲伙伴，不重建会话。新增、删除、参数变化都会在成功刷新后的下一轮体现。

服务级授权包含该服务以后刷新得到的新工具。每次调用前还会复查当前授权、服务状态和工具参数；撤权、停用、删除后即使旧工具仍在当前轮列表中也不能继续调用。已发送到远端的操作不能因此撤销。参数已变化的旧工具要求下一轮重试。

工具目录刷新失败保留上次成功版本，显示失败状态，允许手动重试；不会把失败保存成空目录。刷新期间修改或删除配置，旧请求不能覆盖新配置。工具描述和授权持久化，重启后仍可在下一轮注册，连接按需恢复。

## 安全与运行边界

- 完整连接配置（包括 URL、headers、命令参数和 env）保存在 DSH 凭据提供方的独立 `dsh-partner-mcp` 记录，不写入公共状态、页面列表或模型提示；保密能力取决于宿主凭据提供方。列表只返回名称、状态和工具说明。配置读取接口沿用本地管理 API 的登录与同源校验，默认隐藏敏感值；用户显式查看完整配置时会在编辑器中显示，响应禁止缓存。
- 工具只注册到获授权的伙伴作用域。临时任务会话在创建时读取最新授权，仍受其自身工具限制约束。普通会话不因安装服务自动获得工具。
- 使用官方 MCP SDK，共享连接，空闲 60 秒释放。连接和目录刷新限时 30 秒，单次工具请求限时 60 秒；取消信号传递至请求。业务调用不会自动重放，避免重复创建、扣费或修改数据。
- 单服务最多 200 个工具、目录最多 512 KB，一次导入最多 30 个服务，总计最多 50 个服务。响应文本超过 256 KB 明确报错，建议缩小查询或返回下载地址。
- 当前桥接 MCP Tools，保留文本、结构化结果、文本资源和资源链接；内联图片、音视频等二进制不会直接投影成会话附件。可使用 Viora 等服务提供的下载链接，再通过现有下载和附件工具交付。MCP Resources / Prompts 浏览暂不支持。

## 代码职责与验证

`src/mcp/` 分离配置解析、凭据、连接生命周期、持久化校验和业务服务；API 在 `src/api/features/mcp-api.ts`，管理页和授权组件分别位于 `src/ui/mcp-panel.tsx`、`src/ui/mcp-capabilities.tsx`，不修改 DSH 核心。

测试覆盖原会话下一轮注册、工具刷新、立即撤权、失败保留目录、配置变更拒绝旧调用、重启恢复、导入原子性、实际 HTTP / stdio 通信及旧存储迁移。`scripts/verify-mcp.mjs` 使用隔离浏览器数据检查 375 / 844 / 1440 宽度、浅深色主题、弹窗、错误反馈和授权交互，不写入用户配置。