dsh-destinywind-mcp

安装使用

1. 安装

本插件声明了 dsh.bundle.patch，用 plugin_manager 的 install_bundle 指向本目录即可， 依赖写入 profile、注册行自动追加，无需手工编辑任何配置文件：

plugin_manager { action: "install_bundle", target: "" }

命令行等价形式（把包装进 profile，随后由 bundle 补丁自动注册）：

dsh plugin --profile web add link:

注意：本地 link: 安装时，插件目录内含 node_modules -> $DSH_HOME/profiles/node_modules symlink（本机开发用，不入库），否则 link: 安装的 symlink 被 realpath 后无法解析 @deepseek-ai/*。

2. 生效

重启 dsh web，然后硬刷新浏览器（Ctrl + Shift + R）：

⚠️ 重启 + 硬刷新缺一不可：

• 宿主半部（mcpManager 服务）变更必须重启 dsh web，仅刷新浏览器不够；
• 重启后浏览器必须硬刷新，普通刷新可能仍使用缓存的旧页面。

已启用后再改动插件代码时：只改客户端半部（lib/client.js）刷新页面即可， 改宿主半部（lib/index.js 等）仍需重启。

3. 使用

打开管理页：重启后浏览器打开 DSH Web → 设置（Settings）→ MCP， 入口位于「技能」正下方。

4. 常见问题排查

Q1：安装后设置页看不到「MCP」？

按顺序检查：

1. 是否重启了 dsh web：仅刷新浏览器不够。宿主半部与 client roster 都在进程启动时装载， 插件集变更必须重启进程；若插件是在进程启动之后才装进去的，重启前它一直不会激活。
2. 是否硬刷新了浏览器：重启后用 Ctrl + Shift + R 强制刷新；普通 F5 可能加载缓存的旧页面。
3. 是否装到了正确的 profile：确认装进了当前 profile（web）；装到其他 profile 则在其他 profile 的设置页查看。
4. 依赖是否声明完整：@deepseek-ai/* 的导入依赖本插件 package.json 的 peerDependencies 声明，DSH 的模块拦截层据此决定是否路由到安装级副本。 可用 node tests/check-peers.mjs 检查是否有未声明的导入。

Q2：设置页能看到「MCP」，但服务器列表为空/报错？

• 确认 dsh web 进程日志中 mcp-manager 没有初始化错误；
• 若升级过插件，请重启后硬刷新，避免旧 client bundle 与新版 host 不匹配 （典型现象：操作报 client api: ... 404 或 env is not iterable，都是新旧版本混用所致）；
• 报错形如 transport failure for /api/mcpManager/list: HTTP 404 表示宿主端没有注册 mcpManager 服务：多半是插件宿主半部未生效（装错 profile，或装了之后没重启 dsh web） 或 client 与 host 版本不一致。请按 Q1 逐项核对，重启后硬刷新； 仍不行则把 dsh web 与插件版本都升到最新再试。

Q3：MCP 工具没有出现在 agent 会话里？

• 确认对应服务器状态为「已连接」且工具已勾选（默认全选）；
• 注入模式为「按需检索」时，模型会通过 mcp_tool_search 检索后热注入，未检索到的工具不在 系统提示词中属正常现象；可切换到「全量注入」验证。

Q4：服务器配置了 Authorization 头却提示需要 OAuth 授权 / 挂载失败？

• 只要在请求头里配置了 Authorization（静态 Bearer/token），dsh-mcp 就不会把它当作 OAuth 服务器：真正的 OAuth（授权码 + PKCE）只对没有静态 Authorization 头的服务器启用，避免 401 被误当成 OAuth 挑战而打开浏览器授权。若你连的是需要静态 token 的服务器，确认请求头 正确即可；
• 若 https 内网域名报 fetch failed / unable to verify the first certificate，是宿主 Node 不信任公司内网 CA：用 NODE_OPTIONS=--use-system-ca 启动 dsh web（或把根证书加入 NODE_EXTRA_CA_CERTS），再重启宿主与硬刷新浏览器。

添加服务器：

1. 点击「添加服务器」（表单在列表上方就地展开）
2. 填写：服务器名称（serverName，决定工具前缀 mcp____）、传输方式 （streamable-http 填 URL / stdio 填命令）、请求头、工具调用超时等
3. 点「测试连接」确认连通性与工具列表，点「保存」

进程环境变量（注入模式下方，默认展开）：

• 配置全局键值对，供所有服务器的请求头替换引用；secret 值写入凭据文档，留空保留原值
• process.env 优先：若变量在进程环境变量（process.env）中已存在同名值，连接/展示时直接采用该值（不改名）， 存储值仅作为兜底——请先在启动脚本里 export ADA_TOKEN=... 再重启 dsh web
• 支持「批量添加」（粘贴多行 NAME=value；带值的行默认按 secret 添加，可在保存前取消勾选）与「添加变量」逐行添加
• 服务器请求头 value 可直接写变量名或 ${变量名}（如 Authorization: Bearer ${GITLAB_TOKEN}）， 连接时自动替换（优先级：服务器 env > 进程级 env > 系统环境变量）

JSON 维护配置（MCP 配置模块右上角）：

• 以一段 JSON 数组查看/编辑全部服务器配置；应用后按列表全量替换（新增/更新/删除）， 自动刷新列表与工具列表；JSON 面板展开时隐藏 UI 列表，应用后恢复
• 服务器级 env（含 secret 标记与 stdio 子进程注入）仍通过 JSON 配置维护

OAuth 服务器（streamable-http 走 MCP OAuth，如受 OAuth 保护的网关服务）：

• 只需正常填写 URL 并测试连接；服务器返回 401 + OAuth 挑战时，插件自动打开浏览器完成授权
• 在浏览器中登录/同意后返回 DSH，测试结果自动刷新（「连接成功 + 工具数」）
• token 与 OAuth client 信息持久化在凭据文档（按 serverName 隔离），由 MCP SDK 自动刷新 （24 小时内活跃自动续期）；失效后自动重新授权，授权一次后挂载与测试复用
• 首次授权需浏览器交互，测试/连接等待时间放宽至 5 分钟；非 OAuth 服务器不受影响，连接失败即时返回

日常管理：

• 启用 / 禁用：列表行按钮，禁用后该服务器所有工具即时注销，不再注入
• 刷新：重新拉取服务器状态与工具列表（服务器重启后可同步新工具）
• 测试连接：编辑页可随时测试

工具控制（省 token 的关键）：

• 注入模式：页面顶部切换 search（按需检索，默认）或 full（全量注入）
  • search 模式下，模型需要某 MCP 工具时调用 mcp_tool_search 检索并热注入当前对话
• 工具勾选：点「展开工具」查看该服务器全部工具（默认全选），取消勾选 = 不注入该工具， 即时生效，无需保存

验证效果：

• 在任意 agent 会话中，可用工具应包含 mcp____
• search 模式下未检索到的工具不占系统提示词，节省 token 并提升 prompt cache 命中率
• 工具内容未变化时，list_changed 通知不会反复注销/重注册同名工具，工具列表保持稳定

3. 使用

打开管理页：重启后浏览器打开 DSH Web → 设置（Settings）→ MCP， 入口位于「技能」正下方。