dsh-mcp

dsh-mcp — MCP 管理界面 + tool search：稳定工具列表、命中缓存、不撑爆上下文

English | 简体中文 支持版本：dsh 0.2.0-rc.2 —— 最新版本在 0.2.0-rc.2 上开发与验证，package.json → dsh.supported 同步声明。DSH 与插件两侧版本不匹配时，设置页会给出排查诊断（检查 bundle 是否已选中 → 重启 dsh web → 硬刷新 → 同步升级）。

为什么用 dsh-mcp？

解决的核心问题： MCP 工具全量注入烧 token：接入多个 MCP 服务器后工具可达上百个，每轮全量注入开销巨大。search 按需检索模式让模型通过 mcp_tool_search 热注入所需工具，大幅节省 token。 工具列表反复更新破坏缓存：tools/list_changed 通知会让同名工具被反复注销/重注册，系统提示词工具列表抖动、prompt cache 频繁失效。工具列表稳定化让未变化的工具保留原注册，最大化 cache 命中。 没有可视化管理入口：服务器配置、启停、工具勾选全靠手工改文件。Settings → MCP 一站式可视化完成。

功能优势： 可视化管理：服务器列表 / 新建 / 编辑 / 删除 / 测试连接 / 启停 / 刷新，全 UI 操作 进程级环境变量：全局 KV 配置（默认展开、支持批量添加）；stdio 服务器的子进程直接注入，streamable-http 服务器的请求头 value 写 变量名 或 ${变量名} 即可在连接时自动替换为配置值（如 Authorization: Bearer ${TOKEN}）；同名时服务器自身 env 优先 JSON 全量配置：「JSON 维护配置」面板以一段 JSON 数组查看/编辑全部服务器配置，应用即保存（新增/更新/删除） 工具级精细控制：每个服务器展开工具列表，默认全选，可取消勾选只加载需要的部分 图片结果透传：MCP 工具返回的图片（截图/图表等）经附件服务投影为图片引用进入模型上下文，带严格预检与有界降级文案（PR #4） 双注入模式：search（按需检索，省 token）与 full（全量注入） 零 npm 依赖：直接对接 DeepSeek Harness 内部能力，安装即用 OAuth 认证支持：streamable-http 服务器若走 MCP OAuth（授权码 + PKCE），服务器卡片点「OAuth 授权」按钮，由宿主打开系统浏览器完成授权，本页每 5 秒轮询授权状态；token 与 client 信息持久化在凭据文档；access token 过期后由 SDK 用存储的 refresh token 静默续期（不会打断使用、也不会再弹浏览器），只有 refresh token 也被吊销/过期时才需要重新授权。授权完成前只显示「授权中」，授权失败会写明原因 HTTPS 默认按系统证书校验：内网/公司 CA（只装在系统钥匙串里的根证书）无需再给 dsh web 加 NODE_OPTIONS=--use-system-ca，插件启动时把系统信任库并入 Node 默认根证书库 三种安装方式：npm / GitHub git 源 / 本地 link；中英文界面与文档 功能 托管 MCP 服务器注册表（host）：持久化定义（storage-domain mcp_servers）、按服务器挂载 @deepseek-ai/dsh-mcp-client 实例、环境变量注入（明文入定义、secret 走 credentials）、 连接探测（test）。 Web 设置管理页（client）：Settings → MCP，列表/编辑/删除/测试服务器。 OAuth 认证（host，lib/oauth.js）：streamable-http 服务器遇 401 + OAuth 挑战时走 授权码 + PKCE 流程，回环回调收码、token 持久化并按需自动刷新；设置页提供「OAuth 授权」按钮 （Remote oau

1.11.0 起，这些声明会出现在 Settings → MCP 列表中，标记「cordis 声明」，只读展示来源文件。 规则： 声明优先：同一 serverName 若已被 patch 层声明（且未 disabled），插件不再挂载存储里 的同名行——同名双挂载会撞工具注册表并让该服务器的工具整代回滚，页面会给出冲突说明。 只读：声明式服务器在本页不可启停/编辑，改配置请直接改 cordis.patch.yml（web/desktop 为 live reload，改完即生效；headless/sdk 等下次启动生效）。 导入 storages（镜像行）：启动与每次刷新会把声明导入存储 domain（id cordis: ， 带 origin/declaredIn/declaredRowId 来源标记），只导入不覆盖——插件自建行永不被改写； 声明消失的镜像自动删除（镜像只是声明的副本，无主后不应堆积）；含 !!js 表达式的声明跳过导入并在页面标注 原因（值只能在 Loader 内求值）。镜像行永不挂载，挂载始终归组合。 接管 / 释放：点击「接管」后，插件在 cordis.patch.yml 的受管块内写入 id-targeted disabled: true （首次写入前生成 .dsh-mcp.bak 备份；原子替换、幂等、可逆，只动该块），声明让出 serverName，改由插件挂载 同名行——由此启用 OAuth 授权、凭据托管、${VAR} 头替换、测试连接。挂载硬失败会自动回滚（移除受管块、 行退回镜像）并返回失败原因；「释放」把挂载交还声明行并删除插件行。缺少显式 id 或含 !!js 的声明不可接管。 OAuth / 占位符限制（needsPlugin）：声明行本身既不能携带 OAuth provider，也不能解析 ${VAR}/裸变量名占位符——这两件事只有插件会做。因此这类声明只能由插件挂载：页面会把它们标为 挂载失败并说明原因（不是"连接中"），「释放」会让工具消失（确认框与结果告警都会提示），恢复只需 重新「接管」。 OAuth 是显式开关（1.11.1 起）：服务器配置里的 oauth: true（设置页「使用 OAuth 授权」勾选，默认关） 才会挂 OAuth provider。用静态 token 或自定义头认证的服务器不要勾——否则它返回 401 时会被当成 OAuth 挑战，起 127.0.0.1: /callback 回环回调。授权由设置页的按钮发起（见下节）：挂载阶段同一服务器 每个进程最多自动弹一次浏览器，未授权时页面显示「等待授权」并每 5 秒轮询状态，不报授权失败； 「测试连接」不再自动弹浏览器，而是返回需要授权的标记，由按钮打开授

构建 esbuild 从 DSH 源码 checkout 解析：$DSH_SOURCE 未设置时尝试 ~/.dsh/source/current。 运行时依赖（@deepseek-ai/*、zod、@modelcontextprotocol/sdk）不装 npm 包， 从 $DSH_HOME/profiles/node_modules（DSH profiles 模块 fallback，$DSH_HOME 默认 ~/.dsh）解析；构建时经 nodePaths 指向同一目录。 CSS Modules 由 esbuild onLoad 插件处理：样式注入 ，默认导出 identity 类名映射。 测试 npm test 会自动适配环境：依赖 DSH 模块闭包（@deepseek-ai/*、js-yaml）的测试文件 （cordis-servers / patch-writer / takeover）在缺少本地 DSH 安装时会被跳过（公共 CI 即如此），本