把 MCP 服务器管起来：按需加载、只放部分工具、一键导入 Claude 配置

[zhang-guo-wen]

一句话：在设置页管理 MCP 服务器——按需加载、只把你要的那部分工具交给模型、一键导入已有的 Claude Code MCP 配置。

它解决什么问题

MCP 服务器原本只能手写组合行，而且一旦挂上，整套工具 schema 就常驻每一次请求；一台服务器几十个工具、常用只有几个时，代价全由上下文付。

这个插件把 MCP 行放进 设置 → MCP 管理：全局平面和每个 Agent 预设的行分 tab 列出，带实时状态；新增、编辑、启停都在这里。

按需加载：允许用 ≠ 现在就占上下文

行上的启用开关回答「这台服务器允不允许用」，加载方式回答「允许的服务器什么时候进上下文」：

模式	行为
全部加载（eager）	允许的行在会话开始时就挂载，工具常驻请求
动态插入（dynamic，默认）	允许的行默认不挂载，mcp_load 把一台挂进调用方会话——绑定质量最好，但工具列表每次加载会变一次
延迟加载（lazy）	mcp_load 只连不注册，把工具 schema 作为结果返回，模型经固定的 mcp_call 代理调用——工具列表永不变，请求缓存前缀零失效

dynamic / lazy 下系统提示里会列出每一台可加载的服务器（名字 + 你为它写的描述），模型按名字调 mcp_load / mcp_unload。连接按会话隔离：一个会话加载的服务器不会漏给别的会话，会话结束会自动关掉它开的连接。

只要一部分工具

编辑弹窗的「工具列表」tab 列出这台服务器发布的所有方法，默认全勾。取消勾选即隐藏——它不进上下文，按名字调用也会被拒绝。要写通配规则就手写在 mcp-manager 设置的 tools 字段里（create_* 是白名单，!delete_* 是黑名单，支持 * / ?）。

配了规则的行在 dynamic 下改走原生注册：只把可见工具注册进当前会话，被隐藏的工具根本没有注册。

一键导入 Claude 的 MCP 配置

导入 Claude 配置会读 Claude Code 自己写的那几个文件（~/.claude.json、~/.claude/settings.json、项目里的 .mcp.json），把找到的服务器列成勾选清单，一次提交导入；env / headers 一起带过去（弹窗只显示键名，不显示值），源文件不被改动。

安装

npx @deepseek-ai/dsh plugin --profile web add @guowenzhang/dsh-mcp-manager

装完重启宿主。

适合谁

• 接了一堆 MCP 服务器，但每个会话其实只用到一两台
• 想让某台服务器的几十个工具里只暴露常用的几个
• 从 Claude Code 迁过来，不想把 MCP 配置再手敲一遍

链接

• 仓库：https://github.com/zhang-guo-wen/dsh-mcp-manager
• npm：@guowenzhang/dsh-mcp-manager
• 设计取舍：仓库里的 docs/design-decisions.md（为什么三种模式、否决过什么）

[MaoJianwei]

dsh: warning: 1 entry did not activate
mcp-manager (@guowenzhang/dsh-mcp-manager): failed to import

在0.2.0-rc.1不能用

[zhang-guo-wen]

@MaoJianwei 抱歉，这个我来跟一下。

先说排查结果：0.2.0-rc.1 上插件本身能加载 —— 我用发布版 CLI 在干净 profile 里分别装了 0.1.0 / 0.2.0 / 1.0.0 起 rc.1（以及 rc.2），三次都正常激活。所以你这台机器上还有别的因素。

麻烦帮我抓一下根因：终端那句 failed to import 是兜底文案，真正的错误只写进文件：

1. %USERPROFILE%\.dsh\logs\startup-*.log（最近那个；里面是完整错误栈，可能含配置文本，贴之前可以自行打码）
2. dsh plugin --profile web list
3. %USERPROFILE%\.dsh\profiles\web\package.json 里 @guowenzhang/dsh-mcp-manager 那一行的版本范围

同时可以先按这两步试，大概率直接好：

dsh plugin --profile web remove @guowenzhang/dsh-mcp-manager
dsh plugin --profile web add @guowenzhang/dsh-mcp-manager
# 重启宿主

说明：

• 如果是在 09-23/09-24 装的，profile 里存的是 ^0.1.0 / ^0.2.0 这类范围，按 semver 永远不会自动升到 1.0.x，必须显式重装。
• 我这边在 1.0.1 里修了一个打包声明缺陷：lib/index.mjs 顶层静态导入 @deepseek-ai/schemastery，但 manifest 里既没写 peer 也没写 dependency —— profile 只安装插件的 dependencies，这份包此前只能指望宿主安装闭包恰好提供；落在闭包之外时的表现恰好就是 failed to import。现在它作为真实依赖装进 profile（实测装完后 profile 里有 @deepseek-ai/schemastery@3.18.4，干净环境启动无告警）。1.0.1 稍后发布，add 不带版本会取到最新版。
• 如果重装后仍然失败：多半是 profile 里残留了旧的核心包副本（profiles\web\node_modules\@deepseek-ai\*）遮蔽了宿主安装；把上面第 1 条日志贴出来，我帮你确认，必要的话重建 profile 一次即可。

[zhang-guo-wen]

v1.0.1 更新（修复一次安装环境的坑）

lib/index.mjs 顶层 import 了 @deepseek-ai/schemastery，但 manifest 里既没声明 peer 也没声明 dependency。profile 只安装插件的 dependencies，所以这份包此前只能靠宿主安装闭包恰好提供它——落在闭包之外时表现为启动告警 failed to import，而且终端不打印原因，根因要去 /logs/startup-*.log 里翻。

1.0.1 按 harness 的 out-of-tree 规则把 schemastery 写进 dependencies（纯函数包，模块实例没有同一性状态）；身份敏感的宿主包继续留在 peerDependencies。lib/ 未变（host 产物哈希不变），所以这次只需升级依赖声明。

如果你之前遇到过「插件装了但启动告警、功能不出现」，从 1.0.0 升到 1.0.1 再重启宿主。

[wzhao]

为什么我安装了，没看到插件 npx @deepseek-ai/dsh plugin --profile web add @guowenzhang/dsh-mcp-manager

npx @deepseek-ai/dsh plugin --profile web list
(node:56389) ExperimentalWarning: CommonJS module /Users/zhaowei/.nvm/versions/node/v23.1.0/lib/node_modules/npm/node_modules/debug/src/node.js is loading ES Module /Users/zhaowei/.nvm/versions/node/v23.1.0/lib/node_modules/npm/node_modules/supports-color/index.js using require().
Support for loading ES Module in require() is an experimental feature and might change at any time
(Use node --trace-warnings ... to show where the warning was created)

版本： Version 0.2.0-rc.2

[zhang-guo-wen]

你这台机器上，这两条命令其实一个字都没执行。

证据就在你自己的输出里：只有 npm 打的 ExperimentalWarning，没有任何 dsh 的输出 —— 这正是 CLI 静默退出的样子。你用的 Node 是 v23.1.0（warning 路径里就写着），而 dsh CLI 的入口靠 import.meta.main 判断自己是不是主模块：

if (import.meta.main) await runCli();   // @deepseek-ai/dsh/lib/bin.js

import.meta.main 只在 Node ≥22.18 / ≥24.2 存在，v23 整条线都没有。所以 runCli() 永远不会执行：零输出、退出码 0、插件根本没被安装（连 ~/.dsh/profiles/web 都不会创建）。plugin --profile web list 一片空白，也不是"列表里没有插件"，而是那个 profile 里确实什么都没有。这是宿主侧已知问题：#6273。

麻烦按这个顺序试：

1. node -v —— 如果是 v23.x（或 v22 < 22.18 / v24 < 24.2），换到 ≥22.18 且不是 23，或 ≥24.2，例如 nvm install 22 && nvm use 22；

2. pnpm -v —— dsh plugin 是把参数转发给 profile 目录里的 pnpm 的，缺 pnpm 会报 dsh: pnpm was not found，可以 corepack enable pnpm；

3. 用带下限的命令重装（原因见下）：

   npx @deepseek-ai/dsh plugin --profile web add @guowenzhang/dsh-mcp-manager@^1.0.1
   npx @deepseek-ai/dsh plugin --profile web list

4. 确认 ~/.dsh/profiles/web/package.json 里的 dependencies 与 dsh.profile.bundles 都含有 @guowenzhang/dsh-mcp-manager；

5. 重启宿主（host 半边是进程内模块，只在启动时被 import），设置页里就会出现「MCP 管理」。

为什么命令要写 @^1.0.1：pnpm 11 默认 minimumReleaseAge 为 24 小时，不带版本号的 add 现在会解析到 1.0.0 —— 而 1.0.0 的 manifest 里没有 @deepseek-ai/schemastery，正是上面 MaoJianwei 踩到的 failed to import。写下限可以直接装到 1.0.1（实测 pnpm 会顺带写入 minimumReleaseAgeExclude）。

如果重装后启动仍有告警，根因只写在文件里：~/.dsh/logs/startup-*.log 最新的那个（可能含配置文本，贴之前可自行打码）。