dsh-project-mcp-manager 0.1.1 → 0.3.1

package/README.md

@@ -33,7 +33,7 @@ dsh plugin --profile web add dsh-project-mcp-manager@latest
 
 # Install a specific version (check available versions with
 # npm view dsh-project-mcp-manager versions)
-dsh plugin --profile web add dsh-project-mcp-manager@0.1.0
+dsh plugin --profile web add dsh-project-mcp-manager@0.2.0
 ```
 
 **Option 2: install directly with pnpm** (equivalent to option 1):
@@ -53,7 +53,7 @@ pnpm add link:<path-to-your-dsh-mcp-project-source>   # e.g. D:\dev\dsh-mcp-proj
 ```
 
 **Upgrading / pinning versions**: re-run the `add` command from option 1 with
-the desired version suffix — `@latest` upgrades to the newest release, `@0.1.0`
+the desired version suffix — `@latest` upgrades to the newest release, `@0.2.0`
 pins to a specific version.
 
 ## Build & test
@@ -61,8 +61,7 @@ pins to a specific version.
 ```powershell
 npm install
 npm run build     # tsc → lib/
-node test/test-model.mjs
-node test/test-registry.mjs
+npm test          # node test/test-model.mjs / test-mcp-file / test-cc-file / test-registry / test-cli
 ```
 
 ## Configuration format
@@ -96,6 +95,152 @@ MCP server per line:
 (url/headers). Add `disabled: true` to a line to deactivate it. Content outside
 the markers is preserved byte-for-byte.
 
+**Divergences from the native cordis dialect**: the `!!js` tag (a js-yaml
+expression evaluated by the profile loader, e.g. the official README's
+`env: { TOKEN: !!js process.env.GITHUB_TOKEN }`) is **not supported** in
+project files — an unresolved tag inside the managed block makes the whole
+file fail with an explicit error (logged and written to `.dsh/.mcp-diag.json`)
+instead of silently mounting the expression text as a literal string. Values
+in `env`/`headers` are otherwise literal, except for `${VAR}` references
+which are interpolated at mount time (see `${VAR}` expansion below);
+`disabled` must be `true`/`false`. The project file is otherwise a superset
+grammar: `env`/`headers` accept `KEY: null` to delete a key (stripped at
+mount), which the official mcp-client schema rejects — such lines would fail
+if moved back to `cordis.patch.yml`.
+
+## Claude Code compatibility (read-only)
+
+To fit the habits of Claude Code users, two CC locations are **loaded** but
+never written by this plugin — with different defaults, because they are
+different risk classes:
+
+- `<projectRoot>/.mcp.json` — the CC project file (`{ "mcpServers": { … } }`).
+  An in-repo, version-controlled project declaration: **on by default**,
+  read-only. Turn the whole layer off with `DSH_MCP_IGNORE_MCP_JSON=1`.
+- `~/.claude.json` — only the **top-level `mcpServers`** subtree is read, and
+  only **on explicit request**: set `DSH_MCP_READ_CLAUDE_USER=1`. This is CC's
+  machine-wide user state, not something any one project asked for: mounting
+  it unconditionally fans every such server into *every* known dsh project as
+  its own process — the exact incident that made it opt-in. Nothing else in
+  the file is ever touched, logged or displayed (strict allowlist: oauth
+  credentials, per-project history and UI state stay invisible to this
+  plugin).
+
+Notes and limits:
+
+- **No `local` scope.** CC's `claude mcp add` defaults to a per-project
+  section inside `~/.claude.json` (`projects.<cwd>.mcpServers`); this plugin
+  does not read it. Use `dsh-mcp add --scope user` or the project files.
+- `type: "sse"` entries are rejected with a per-entry diagnostic — the mount
+  backend (`dsh-mcp-client`) only speaks `stdio` and `streamable-http`.
+  CC's `type: "http"` and an explicit `type: "streamable-http"` both map to
+  `streamable-http`; with `type` omitted, an entry that has only `url` (no
+  `command`) is treated as http, everything else as stdio.
+- stdio `cwd`: for project-layer rows an empty `cwd` resolves to the project
+  root; for user-layer rows (both `~/.dsh/mcp.yml` and `~/.claude.json`) it
+  resolves to the dsh host's working directory. Note what "user layer" does
+  *not* mean: user rows still mount **one process per known project** (a
+  session in two projects gets two fibers, renamed `p<hash>_…` per the
+  effective-name rules) — only their `cwd` is shared, not the connection.
+- Unknown CC keys are ignored per entry. `enabled: false` — and, as an alias,
+  `disabled: true` — skips the row silently (no diagnostic, and no name
+  occupancy — see below).
+- A `disabled: true` row in a **native yml** still holds its shadow keys in
+  the shadow chain (see dedup below): same-name rows in lower layers are
+  shadowed too and stay unmounted — disabled means "this name must not run",
+  not "let the CC copy through". CC-side `enabled: false` has no placeholder
+  effect. Consequence: switching off a `.mcp.json` entry without deleting it
+  lets a **same-named user-layer row surface** in that project; to suppress a
+  server across all layers, keep a `disabled: true` placeholder row (matching
+  name or normalized name) in `.dsh/mcp.yml`.
+- Broken files/entries never take down the valid ones; each source fails
+  independently, so an unreadable `.mcp.json` cannot unmount the project's
+  yml rows (and vice versa). Entry errors land in `.dsh/.mcp-diag.json` and
+  the host log (file content is never echoed). A project whose only MCP
+  config is `.mcp.json` still gets a `.dsh/` directory as soon as there is
+  anything worth reporting there.
+- `~/.claude.json` is rewritten by CC on every session; the watcher re-reads
+  it but only triggers reconciliation when the `mcpServers` subtree actually
+  changed (canonical-JSON hash gate).
+- Boundary switches (dsh host environment): `DSH_MCP_READ_CLAUDE_USER=1`
+  opts the `~/.claude.json` user layer in; `DSH_MCP_IGNORE_MCP_JSON=1` turns
+  the project `.mcp.json` layer off; the legacy `DSH_MCP_IGNORE_CLAUDE_JSON=1`
+  force-disables the user layer and **wins over the opt-in** (a one-shot
+  warning names the winner; the legacy switch will be removed in a later
+  release). While the user layer is on, the host logs its fan-out size once
+  ("N servers will join M known projects") so extra spawns are explainable.
+
+**Shadow priority** — layers merge first-come-first-served (1 → 4 below), and
+a row is shadowed when it collides with an earlier row on **any** of three
+keys: the exact `serverName`; the *normalized name* (lowercased with
+non-alphanumerics stripped — `unityMCP` and `unity-mcp` are one service
+written two ways); or the *service identity* (`stdio`: command + args,
+path-case-insensitive on Windows; `streamable-http`: the url). Rows without a
+command/url register no identity key — `node a.js` and `node b.js` stay
+different services — while `disabled` placeholder rows hold all three keys
+without mounting anything. Identity is compared on the **raw strings as
+written in the file, before `${VAR}` expansion**, and `env`, `headers`, `cwd`
+are *not* part of the key: two genuinely different servers sharing one command
+line (but e.g. different env) still collapse to the winner, while the same
+server written once with a `${VAR}` and once as a literal does not match. If a
+drop was unintended, rename the loser (past normalization) or adjust its
+command line. Losers are reported in `.dsh/.mcp-diag.json`
+(`shadowedByYml` / `shadowedByProject` / `shadowedIdentity`) and every
+identity/normalized-name drop warns in the host log:
+
+1. `<projectRoot>/.dsh/mcp.yml` (native, panel/CLI-managed)
+2. `<projectRoot>/.mcp.json` (CC project)
+3. `~/.dsh/mcp.yml` (native user layer — see CLI)
+4. `~/.claude.json` top-level `mcpServers` (CC user, opt-in)
+
+User-layer rows apply to every known project, so a name defined both in one
+project and in a user layer (or in two projects) participates in the regular
+effective-name conflict renaming (see How it works).
+
+## `${VAR}` expansion
+
+`${VAR}` references (matching `\$\{[A-Za-z_][A-Za-z0-9_]*\}` anywhere in the
+string) in `command`, `args[*]`, `env[*]`, `cwd`, `url` and `headers[*]` — from
+**any** of the four sources above — are **interpolated** from the dsh host
+process environment at mount time (same semantics as Claude Code, so
+`"Authorization": "Bearer ${TOKEN}"` works). An unset or empty variable makes
+the row skip with an `env-missing` diagnostic naming the variable (never its
+value); a literal `${NAME}` that must survive unexpanded is not expressible.
+A `url` containing a reference is accepted by the pre-mount schema in any
+position — including the host part, e.g. `https://${HOST}/mcp` — because
+validity is judged only after expansion: expanded inputs are re-validated
+against the mount schema before spawn, and a malformed result (e.g. a non-URL
+`${GATEWAY}/mcp`) skips the row with an `env-invalid` diagnostic instead of
+reaching the mount backend. In the snapshot/row views, `fiberPhase` stays on
+the mount-lifecycle vocabulary (`pending` for a row that never mounted) and
+the reason rides on a separate `skipReason` field (`env-missing` /
+`env-invalid` / `config-invalid` / `plugin-throw`). Values are never
+persisted anywhere by the plugin; the CLI writes `${VAR}` through literally,
+so secrets can live in the environment while configs live in git.
+
+## CLI: `dsh-mcp`
+
+CC-style command-line management for the **native** files (writes only
+`.dsh/mcp.yml` — never `.mcp.json` / `~/.claude.json`; running hosts
+converge via the file watchers, no dsh connection needed):
+
+```powershell
+dsh-mcp add gitlab npx -y @modelcontextprotocol/server-gitlab -e GITLAB_TOKEN=${GITLAB_TOKEN}
+dsh-mcp add --transport http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ${SENTRY_TOKEN}"
+dsh-mcp add --scope user shared node ./tools/shared.js   # writes ~/.dsh/mcp.yml
+dsh-mcp list          # all four layers, with shadow annotations
+dsh-mcp get gitlab    # winning entry, secret values shown as key names only
+dsh-mcp remove gitlab # native yml only; read-only layers get guidance
+```
+
+Scopes: `--scope project` (default; writes `<projectRoot>/.dsh/mcp.yml` under
+the nearest `.git` ancestor) and `--scope user` (writes `~/.dsh/mcp.yml`,
+mounted into every project). `add` defaults `cwd` to `"."` (project root) for
+project scope and `""` (host directory) for user scope; `-c` overrides.
+There is no `local` scope — `--scope local`
+fails with an explanation. `--transport` accepts `stdio` (default) and `http`;
+`sse` is refused (unsupported by the backend).
+
 ## How it works
 
 - **Project discovery**: the `session.header.cwd` of an active agent session,
@@ -107,18 +252,29 @@ the markers is preserved byte-for-byte.
   registers it into the global tool layer. Multiple sessions inside the same
   project share a single connection.
 - **Hot reload**: chokidar watches each project root (depth 2, ignoring
-  node_modules/.git/.hg/.svn); changes to `.dsh/mcp.yml` trigger a full
-  reconciliation after a 150 ms debounce: added lines are mounted, removed
-  lines are unmounted, and config changes are remounted.
+  node_modules/.git/.hg/.svn), but only edits to the **exact** config files of
+  known project roots — `<projectRoot>/.dsh/mcp.yml` and
+  `<projectRoot>/.mcp.json` — trigger a full reconciliation after a 150 ms
+  debounce: added lines are mounted, removed lines are unmounted, and config
+  changes are remounted. A second watcher covers the user layer as two
+  **exact file paths** — `~/.dsh/mcp.yml` and `~/.claude.json` (chokidar v5
+  notices a watched file being created as long as its parent directory
+  exists) — never the home directory at large. `~/.claude.json` events are
+  arbitrated by the canonical-JSON content hash alone (no size/mtime fast
+  path: same-instant, same-length rewrites with different content must not be
+  swallowed).
 - **Effective names**: when the original `serverName` is unique across the
-  whole catalog (global lines + all project lines) it keeps its name; on a
-  conflict both sides are renamed to
+  whole catalog (global lines + all project lines, where each project's
+  merged rows include the user-layer rows that survived shadowing) it keeps
+  its name; on a conflict both sides are renamed to
   `p<first 6 chars of sha256(projectRoot)>_<original name>` (truncated to 32
   characters, deterministic and independent of mount order) to avoid the
   serverName reservation conflicts that `dsh-mcp-client` makes per process
   root. Global lines (profile `cordis.patch.yml` / mcp-client lines already
   mounted at the bundle level) participate in occupancy determination but are
-  never renamed.
+  never renamed. Model-visible tool names are built from the **effective**
+  server name and the MCP tool's own name (`mcp__<effectiveServerName>__<toolName>`),
+  which may differ from the `serverName` written in the file.
 - **Session visibility**: when an agent is created, its session cwd resolves
   to a project, and `tools.restrict({ deny })` is applied to that agent to deny
   every project server except those of the session's own project; a session
@@ -128,7 +284,13 @@ the markers is preserved byte-for-byte.
 
 ## Security boundary
 
-`stdio` lines in `.dsh/mcp.yml` spawn their `command` inside the dsh host
-process — project files are **executable code carriers**, so only add them in
-projects you trust. Lines that fail to mount or are invalid are skipped with a
-warning and do not affect other servers.
+`stdio` lines in `.dsh/mcp.yml` (and `.mcp.json` rows mounted from it) spawn
+their `command` inside the dsh host process — project files are **executable
+code carriers**, so only add them in projects you trust. Lines that fail to
+mount or are invalid are skipped with a warning and do not affect other
+servers. CC's machine-wide `~/.claude.json` user layer is therefore **off by
+default**: reading it opts foreign, environment-level servers into every
+project's spawn set, which must be a deliberate `DSH_MCP_READ_CLAUDE_USER=1`.
+The read-only allowlist exists precisely because that file also holds
+credentials: nothing from it is ever written out, echoed into diagnostics, or
+printed by the CLI.

package/docs/README.zh.md

@@ -28,7 +28,7 @@ npm install -g deepseek-ai/dsh         # 或从 GitHub 源码安装
 dsh plugin --profile web add dsh-project-mcp-manager@latest
 
 # 安装指定版本（版本号可先 npm view dsh-project-mcp-manager versions 查看）
-dsh plugin --profile web add dsh-project-mcp-manager@0.1.0
+dsh plugin --profile web add dsh-project-mcp-manager@0.2.0
 ```
 
 **方式二：直接 pnpm 安装**（与方式一等价）：
@@ -47,15 +47,14 @@ pnpm add link:<你的 dsh-mcp-project 源码目录>   # 例如 D:\dev\dsh-mcp-pr
 ```
 
 **升级/锁定版本**：重跑方式一的 `add` 命令并带上目标版本后缀——`@latest`
-升级到最新，`@0.1.0` 锁定到指定版本。
+升级到最新，`@0.2.0` 锁定到指定版本。
 
 ## 构建与测试
 
 ```powershell
 npm install
 npm run build     # tsc → lib/
-node test/test-model.mjs
-node test/test-registry.mjs
+npm test          # node 直跑 test/ 下五个 .mjs（model / mcp-file / cc-file / registry / cli）
 ```
 
 ## 配置格式
@@ -87,6 +86,126 @@ node test/test-registry.mjs
 `transport` 支持 `stdio`（command/args/env/cwd）与 `streamable-http`
 （url/headers）。行加 `disabled: true` 即停用。标记之外的内容逐字节保留。
 
+**与原生 cordis 方言的差异**：`!!js` 标签（profile 的 `cordis.patch.yml` 由
+Loader 求值的 js-yaml 表达式，如官方 README 示例 `env: { TOKEN: !!js
+process.env.GITHUB_TOKEN }`）在项目文件里**不支持**——受管块内出现未解析
+标签会使该文件整体报错跳过（写入 `.dsh/.mcp-diag.json` 并打日志），不会把
+表达式当字面量字符串静默装载。`env`/`headers` 的值 otherwise 是字面量，仅
+`${VAR}` 引用会在装载时做串内插值（见下文「${VAR} 展开」）；`disabled` 只能是
+`true`/`false`。反之项目文件是超集语法：`env`/`headers` 允许 `KEY: null`
+表示删除该键（装载时被剔除），这在官方 mcp-client 校验里会被拒绝——把这类
+行原样挪回 `cordis.patch.yml` 会装载失败。
+
+## Claude Code 兼容层（只读）
+
+为顺应 CC 用户习惯，插件会**装载**以下两个 CC 配置位置，但从不写入它们。
+两者的默认姿态不同，因为风险等级不同：
+
+- `<projectRoot>/.mcp.json` —— CC 的 project 层文件（`{ "mcpServers": { … } }`）。
+  它是随仓库版本管理的项目自身声明：**默认开启**、只读。设
+  `DSH_MCP_IGNORE_MCP_JSON=1` 可整层停用。
+- `~/.claude.json` —— 只读取**顶层 `mcpServers`** 子树，且**只在显式请求时**：
+  设 `DSH_MCP_READ_CLAUDE_USER=1` 才读。这是 CC 的机器级用户状态，不属于任何
+  项目：无条件读取会把每台这样的服务器扇出到**每个已知 dsh 项目**各起一个
+  进程——这正是把它改为 opt-in 的事故根因。该文件其余内容一律不读入配置、
+  不写、不打日志、不在任何输出里回显（严格 allowlist：oauth 凭据、项目历史、
+  UI 状态对本插件不可见）。
+
+边界与限制：
+
+- **没有 local 作用域**。CC 的 `claude mcp add` 默认写进 `~/.claude.json` 的
+  `projects.<cwd>.mcpServers`（local 层），本插件不读取该层；请用
+  `dsh-mcp add --scope user` 或项目文件。
+- `type: "sse"` 条目按条目报错跳过——装载后端（`dsh-mcp-client`）只支持
+  `stdio` 与 `streamable-http`。CC 的 `type: "http"` 与显式
+  `type: "streamable-http"` 都映射为 `streamable-http`；缺省 `type` 时，
+  只带 `url` 不带 `command` 的条目按 http 处理，其余视为 stdio。
+- stdio 的 `cwd`：项目层行的空 `cwd` 解析为项目根；用户层行
+  （`~/.dsh/mcp.yml` 与 `~/.claude.json`）解析为 dsh 宿主的工作目录。
+  注意"用户层"不等于共享进程：用户层行仍**按每个已知项目各装一个进程**
+  （两个项目各开会话就是两个 fiber，按生效名规则改名为 `p<hash>_…`）——
+  共享的只是 `cwd`，不是连接。
+- 未知 CC 键容忍忽略；`enabled: false`（以及作为别名的 `disabled: true`）
+  静默跳过该条目（不记诊断，也不占名）。
+- 原生 yml 里 `disabled: true` 的行仍**占住影子键**（见下方去重规则）：下层
+  同名行一并被遮蔽不装载——禁用意味着"这个名字不许跑"，而不是"让位给 CC
+  副本"。CC 侧的 `enabled: false` 没有占位效果。推论：不删除、只在
+  `.mcp.json` 里关掉一条，同名的**用户层行会在该项目浮上来**装载；要把某台
+  服务器在所有层压住，请在 `.dsh/mcp.yml` 留一条 `disabled: true` 占位行
+  （名字或归一化名字对上即可）。
+- 坏文件/坏条目不影响其他服务器，且**按源隔离**：`.mcp.json` 坏了不会卸掉
+  同项目的 yml 行（反之亦然）；条目错误写入 `.dsh/.mcp-diag.json` 与宿主
+  日志（诊断从不带文件内容）。只有 `.mcp.json`、没用过原生 yml 的项目，
+  一旦有可报内容也会创建 `.dsh/` 目录。
+- CC 每次会话都会重写 `~/.claude.json`；watcher 会对该文件做
+  `mcpServers` 子树的规范化哈希门控——子树没变就不触发对账。
+- 共存边界开关（dsh 宿主环境变量）：`DSH_MCP_READ_CLAUDE_USER=1` 显式启用
+  `~/.claude.json` 用户层；`DSH_MCP_IGNORE_MCP_JSON=1` 停用项目 `.mcp.json`
+  层；旧开关 `DSH_MCP_IGNORE_CLAUDE_JSON=1` 为强制关闭用户层，**优先级高于
+  opt-in**（冲突时打一次「胜出」告警；旧开关将在后续版本移除）。用户层开启
+  时，宿主一次性日志提示扇出规模（「N 条服务器将并入 M 个已知项目」），
+  让多出来的 spawn 可解释、可回退。
+
+**影子优先序**——按 1→4 先到先得合并，后到行与已收录行命中**三把键中的任何
+一把**即被遮蔽：精确 `serverName`；*归一化名称*（转小写去掉非字母数字后相同
+——`unityMCP` 与 `unity-mcp` 就是一台服务器的两种写法）；*服务身份*
+（`stdio` 取 command + args，Windows 下路径大小写不敏感；`streamable-http`
+取 url）。command/url 为空的行不注册身份键——`node a.js` 与 `node b.js` 是
+不同服务、绝不互杀——而 `disabled` 占位行三键全占、自身不装载。身份比对用的
+是**文件里的原始字符串，发生在 `${VAR}` 展开之前**，且 `env`、`headers`、
+`cwd` **不参与**身份键：同一命令行、仅 env 不同的两台真不同服务器仍会被去重
+（只留高优先级一条），同一台服务器一条写 `${VAR}`、一条写字面量则**不**互认。
+误剔时的处置：给被剔行改名（归一化后不同）或调整命令与参数。被遮蔽方写入
+`.dsh/.mcp-diag.json`（`shadowedByYml` / `shadowedByProject` /
+`shadowedIdentity`），身份/归一名去重剔除的每行还会在宿主日志告警「跳过重复
+服务定义」：
+
+1. `<projectRoot>/.dsh/mcp.yml`（原生格式，面板/CLI 管理）
+2. `<projectRoot>/.mcp.json`（CC project 层）
+3. `~/.dsh/mcp.yml`（原生用户层，见 CLI）
+4. `~/.claude.json` 顶层 `mcpServers`（CC user 层，opt-in）
+
+用户层行适用于所有已知项目，因此「某项目与用户层同名」（或两个项目同名）
+会走常规的生效名冲突改名规则（见工作原理）。
+
+## `${VAR}` 展开
+
+以上任一来源中，`command`、`args[*]`、`env[*]`、`cwd`、`url`、`headers[*]` 里的
+`${VAR}` 引用（正则 `\$\{[A-Za-z_][A-Za-z0-9_]*\}`，允许出现在字符串任意
+位置）在装载时刻从 dsh 宿主进程环境做**串内插值**——与 Claude Code 同语义，
+`"Authorization": "Bearer ${TOKEN}"` 这类写法可用。变量未设置**或为空串**时
+该行跳过装载，诊断记 `env-missing` 并只带变量名（绝不带值）；需要保留字面
+`${NAME}` 的写法目前不可表达。含引用的 `url` 在装载前的 schema 校验里任意
+位置都放行（包括 host 段，如 `https://${HOST}/mcp`）——合法性只在展开后判定：
+展开结果会再过一遍装载 schema 复验，产出非法配置（如 `${GATEWAY}/mcp` 拼出
+非 URL）时以 `env-invalid` 跳过，不把坏值递给装载后端。快照/行视图里
+`fiberPhase` 保持装载生命周期枚举（未挂上的行是 `pending`），跳过原因走独立
+的 `skipReason` 字段（`env-missing` / `env-invalid` / `config-invalid` /
+`plugin-throw`）。插件任何写路径都不落盘展开后的值；
+CLI 写入时 `${VAR}` 原样保留——配置可以进 git，凭据留在环境里。
+
+## CLI：`dsh-mcp`
+
+CC 风格的原生文件命令行管理（**只写** `.dsh/mcp.yml`——从不写
+`.mcp.json` / `~/.claude.json`；不连接运行中的 dsh 宿主，宿主经文件监听自动
+收敛）：
+
+```powershell
+dsh-mcp add gitlab npx -y @modelcontextprotocol/server-gitlab -e GITLAB_TOKEN=${GITLAB_TOKEN}
+dsh-mcp add --transport http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ${SENTRY_TOKEN}"
+dsh-mcp add --scope user shared node ./tools/shared.js   # 写 ~/.dsh/mcp.yml
+dsh-mcp list          # 四个来源全展示，带遮蔽标注
+dsh-mcp get gitlab    # 优先层条目；密钥值只显示键名
+dsh-mcp remove gitlab # 只动原生 yml；命中只读层时给出编辑指引
+```
+
+作用域：`--scope project`（缺省，写最近 `.git` 祖先下的
+`.dsh/mcp.yml`）与 `--scope user`（写 `~/.dsh/mcp.yml`，装载进每个项目）。
+`add` 的 `cwd` 缺省随作用域而变：project 为 `"."`（项目根），user 为 `""`
+（宿主目录）；`-c` 显式覆盖。
+没有 `local` 作用域——`--scope local` 会报错并解释。`--transport` 接受
+`stdio`（缺省）与 `http`；`sse` 拒绝（后端不支持）。
+
 ## 工作原理
 
 - **项目发现**：在线 agent 会话的 `session.header.cwd` + dsh 进程启动目录 →
@@ -95,13 +214,20 @@ node test/test-registry.mjs
   `@deepseek-ai/dsh-mcp-client` 实例（`ctx.plugin`），注册进全局工具层。
   同一项目内多会话共享同一连接。
 - **热重载**：chokidar 监听各项目根（depth 2，忽略 node_modules/.git/.hg/
-  .svn），`.dsh/mcp.yml` 的增删改经 150ms 防抖触发全量对账：新增行装载、
-  删除行卸载、配置变化重装。
-- **生效名**：原始 `serverName` 在整个目录（全局行 + 全部项目行）中唯一时
+  .svn），但只有**已知项目根的精确配置文件**（`<projectRoot>/.dsh/mcp.yml`
+  与 `<projectRoot>/.mcp.json`）的改动经 150ms 防抖触发全量对账：新增行
+  装载、删除行卸载、配置变化重装。另有独立 watcher 以**两个精确文件路径**
+  监听用户层：`~/.dsh/mcp.yml` 与 `~/.claude.json`（chokidar v5 对被监听的
+  缺失文件能在其创建时补发事件，前提是父目录已存在）——不监听家目录整体。
+  `~/.claude.json` 事件只由规范化内容哈希门裁决（没有 size/mtime 快路径：
+  同刻、同体积而内容不同的重写不能被吞掉）。
+- **生效名**：原始 `serverName` 在整个目录（全局行 + 全部项目行；每个项目的
+  行集合含遮蔽后幸存的用户层行）中唯一时
   保持原名；冲突时双方都改为 `p<sha256(项目根)前6位>_<原名>`（截断 32 字符，
   确定性、与装载顺序无关），避免 `dsh-mcp-client` 按进程根的 serverName
   预留冲突。全局行（profile `cordis.patch.yml` / bundle 层已装载的
-  mcp-client 行）参与占用判定但不改名。
+  mcp-client 行）参与占用判定但不改名。模型可见的工具名由生效服务器名与
+     MCP 工具自身的名字拼成 `mcp__<生效名>__<工具名>`，与文件里写的 `serverName` 可能不同。
 - **会话可见性**：agent 创建时按其会话 cwd 解析项目，对该 agent 应用
   `tools.restrict({ deny })`，deny 掉除本会话项目外的全部项目服务器；会话
   无 cwd 时回退 owner 项目（子代理），再回退 dsh 进程 cwd 所在项目。会话
@@ -109,6 +235,10 @@ node test/test-registry.mjs
 
 ## 安全边界
 
-`.dsh/mcp.yml` 中的 `stdio` 行会在 dsh 宿主进程内 spawn 其 `command`——
-项目文件是**可执行代码载体**，只应在可信项目中添加。装载失败/配置无效行
-仅告警跳过，不影响其他服务器。
+`.dsh/mcp.yml` 中的 `stdio` 行（以及经兼容层装载的 `.mcp.json` 行）会在 dsh
+宿主进程内 spawn 其 `command`——项目文件是**可执行代码载体**，只应在可信项目
+中添加。装载失败/配置无效行仅告警跳过，不影响其他服务器。CC 的机器级
+`~/.claude.json` 用户层因此**默认关闭**：读取它等于把外来的环境级服务器塞进
+每个项目的 spawn 集合，必须是显式决定（`DSH_MCP_READ_CLAUDE_USER=1`）。
+`~/.claude.json` 之所以同时按严格 allowlist 只读，正是因为该文件还存放凭据：
+其中未使用的部分不会被读出、写入任何文件，也不会在 CLI 或诊断输出里出现。

package/lib/cc-file.js

@@ -0,0 +1,192 @@
+/**
+ * dsh-project-mcp-manager —— Claude Code MCP 兼容层（严格只读）。
+ *
+ * 两个来源：
+ *   1. `<projectRoot>/.mcp.json` —— CC 的 project scope（约定 commit 进 git）；
+ *   2. `~/.claude.json` 顶层 `mcpServers` —— CC 的 user scope。
+ *
+ * 职责边界：`~/.claude.json` 是 CC 的单体状态文件（混杂登录凭证、onboarding
+ * 状态、每项目会话历史等，见 anthropics/claude-code#83143），本模块按严格
+ * allowlist **只摘取顶层 `mcpServers` 键**，其余内容解析后即弃，永不进入
+ * 行、诊断或日志；JSON parse 失败时诊断不带原始错误文本（V8 的消息会引用
+ * 文件内容片段）。兼容层永不写入，两个文件都只读。
+ *
+ * 明确不支持：
+ *   - local scope（`~/.claude.json` 的 `projects[<cwd>].mcpServers`）：其键按
+ *     会话 cwd 匹配，会把 cwd 粒度可见性引入项目粒度管线；`claude mcp add`
+ *     不带 `--scope` 默认写这里，文档指引用户改用 `--scope user` 或 `dsh-mcp`。
+ *   - `type:"sse"` 条目：dsh-mcp-client 仅支持 stdio | streamable-http，
+ *     entry-level 报错跳过。
+ *
+ * 行归一后与 `.dsh/mcp.yml` 受管行同构（PatchRow），复用主管线；`${VAR}`
+ * 占位保持字面值进配置，由 model.expandEnvRefs 在 mount 时运行时展开。
+ */
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { SERVER_NAME_RE, ccServerEntrySchema, mcpServerInputSchema, toPatchRow } from "./model.js";
+/** CC project scope 文件名（位于项目根，与 .dsh 并列）。 */
+export const CC_PROJECT_FILE = ".mcp.json";
+/** CC user scope 单体状态文件名（位于家目录，allowlist 只读其顶层 mcpServers）。 */
+export const CLAUDE_USER_FILE = ".claude.json";
+/** 旧开关（保留一个版本）：置为 "1" 时强制停用 ~/.claude.json 的读取与监听，
+ * 优先于 DSH_MCP_READ_CLAUDE_USER（两者同时设置时本开关胜出并告警一次）。
+ * TODO(v0.4)：删除本开关——连同 claudeUserLayerConflict 的胜出分支、
+ * readUserLayer 的冲突告警闩、CLI 提示与文档中的旧开关说明。 */
+export const IGNORE_CLAUDE_JSON_ENV = "DSH_MCP_IGNORE_CLAUDE_JSON";
+/** 置为 "1" 才选择启用对 ~/.claude.json 顶层 mcpServers 的读取与监听。
+ * cc-user 层默认关闭：CC 用户级配置属于机器环境级外部状态，不应隐式挂进每个项目。 */
+export const READ_CLAUDE_USER_ENV = "DSH_MCP_READ_CLAUDE_USER";
+/** 置为 "1" 时跳过项目 .mcp.json（cc-project 层）的读取与监听；该层默认开启。 */
+export const IGNORE_MCP_JSON_ENV = "DSH_MCP_IGNORE_MCP_JSON";
+/** cc-user 层是否启用：须显式设 READ_CLAUDE_USER=1；IGNORE_CLAUDE_JSON 为强制关闭（胜出）。 */
+export function claudeUserLayerEnabled(env = process.env) {
+    return env[READ_CLAUDE_USER_ENV] === "1" && env[IGNORE_CLAUDE_JSON_ENV] !== "1";
+}
+/** READ 与 IGNORE 同时置位：语义冲突，调用方应告警一次「IGNORE 胜出」。 */
+export function claudeUserLayerConflict(env = process.env) {
+    return env[READ_CLAUDE_USER_ENV] === "1" && env[IGNORE_CLAUDE_JSON_ENV] === "1";
+}
+/** 项目 .mcp.json（cc-project 层）是否启用：默认开，IGNORE_MCP_JSON=1 关。 */
+export function mcpJsonLayerEnabled(env = process.env) {
+    return env[IGNORE_MCP_JSON_ENV] !== "1";
+}
+/** 键排序的规范化 JSON 序列化（哈希与内容等价性判定共用）。 */
+export function canonicalJsonString(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+            // 码元序是刻意选择：serversHash 门要求跨环境稳定，locale 排序会改变既有哈希。
+            return Object.keys(item).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).reduce((acc, k) => {
+                acc[k] = item[k];
+                return acc;
+            }, {});
+        }
+        return item;
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * 单条 CC 条目 → 官方输入。stdio 的 cwd：project 层条目固定为项目根（CC spawn
+ * 于配置文件所在项目）；user 层条目留空（继承宿主进程 cwd，文档披露的偏差——
+ * 同一用户行会被挂到多个项目，无法逐项目定 cwd）。
+ */
+function ccEntryToInput(name, entry, projectRoot) {
+    if (entry.type === "sse") {
+        return { error: 'sse transport not supported（dsh-mcp-client 仅支持 stdio | streamable-http）' };
+    }
+    try {
+        // url 而无 type/command：按 http 处理（手写文件常见，CC 官方要求 type 但容忍度向实用倾斜）
+        const inferredHttp = entry.type === undefined && typeof entry.url === "string" && entry.command === undefined;
+        if (entry.type === "http" || entry.type === "streamable-http" || inferredHttp) {
+            if (typeof entry.url !== "string" || entry.url === "")
+                return { error: 'type:"http" 条目缺少 url' };
+            const input = mcpServerInputSchema.parse({
+                serverName: name,
+                transport: "streamable-http",
+                url: entry.url,
+                headers: entry.headers
+            });
+            return { input };
+        }
+        if (typeof entry.command !== "string" || entry.command === "") {
+            return { error: entry.type === "stdio" ? 'type:"stdio" 条目缺少 command' : "条目缺少 command（且无 type:\"http\"/url）" };
+        }
+        const input = mcpServerInputSchema.parse({
+            serverName: name,
+            transport: "stdio",
+            command: entry.command,
+            args: entry.args ?? [],
+            env: entry.env,
+            cwd: projectRoot
+        });
+        return { input };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** CC 条目对象（mcpServers 的值）→ SourcedRow 列表；坏条目逐条报错跳过。 */
+function parseMcpServersValue(mcpServers, source, projectRoot) {
+    const rows = [];
+    const entryErrors = [];
+    if (mcpServers === undefined || mcpServers === null)
+        return { rows, entryErrors };
+    if (!isPlainObject(mcpServers)) {
+        entryErrors.push("mcpServers 必须是对象（serverName → 配置）");
+        return { rows, entryErrors };
+    }
+    for (const [name, raw] of Object.entries(mcpServers)) {
+        // enabled:false / disabled:true 同等对待（后者在社区与 CC 讨论里同样常见，
+        // 写错键名却照样装载比不装载危险）：静默不装载、不报错、不占名。
+        if (isPlainObject(raw) && (raw.enabled === false || raw.disabled === true))
+            continue;
+        if (!SERVER_NAME_RE.test(name)) {
+            entryErrors.push(`"${name}": serverName 非法（允许 1-32 位字母、数字、下划线或连字符）`);
+            continue;
+        }
+        const parsed = ccServerEntrySchema.safeParse(raw);
+        if (!parsed.success) {
+            const detail = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("；");
+            entryErrors.push(`"${name}": 条目字段无效：${detail}`);
+            continue;
+        }
+        const mapped = ccEntryToInput(name, parsed.data, projectRoot);
+        if ("error" in mapped) {
+            entryErrors.push(`"${name}": ${mapped.error}`);
+            continue;
+        }
+        rows.push({ rawName: name, row: toPatchRow(mapped.input), source });
+    }
+    return { rows, entryErrors };
+}
+/** 读取 JSON 文件并 parse；缺失返回 missing:true；parse 错误消息不含内容片段。 */
+async function readJsonFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return { missing: true };
+        return { error: "读取失败" };
+    }
+    try {
+        return { value: JSON.parse(raw) };
+    }
+    catch {
+        // V8 的 JSON.parse 错误消息会引用文件内容片段；这里必须只报类别。
+        return { error: "JSON 解析失败" };
+    }
+}
+/** 读项目根 `.mcp.json`（CC project scope）。文件缺失 → 空结果不算错误。 */
+export async function readMcpJsonFile(path, projectRoot) {
+    const result = await readJsonFile(path);
+    if (result.missing === true)
+        return { rows: [], entryErrors: [] };
+    if (result.error !== undefined)
+        return { rows: [], entryErrors: [], fileError: `${CC_PROJECT_FILE} ${result.error}` };
+    if (!isPlainObject(result.value))
+        return { rows: [], entryErrors: [], fileError: `${CC_PROJECT_FILE} 顶层必须是 JSON 对象` };
+    if (!("mcpServers" in result.value))
+        return { rows: [], entryErrors: [], fileError: `${CC_PROJECT_FILE} 缺少 mcpServers 字段` };
+    const { rows, entryErrors } = parseMcpServersValue(result.value.mcpServers, "cc-project", projectRoot);
+    return { rows, entryErrors };
+}
+/**
+ * 读 `~/.claude.json` 的顶层 `mcpServers`（CC user scope，allowlist 摘取）。
+ * 文件缺失或未设 mcpServers → 空结果；同时输出 serversHash 供 watcher 门控
+ * （CC 每次会话都重写该文件，与 MCP 无关的状态变化不应触发 reconcile）。
+ */
+export async function readClaudeUserFile(path) {
+    const result = await readJsonFile(path);
+    const emptyHash = createHash("sha256").update(canonicalJsonString({})).digest("hex");
+    if (result.missing === true)
+        return { rows: [], entryErrors: [], fileError: undefined, serversHash: emptyHash };
+    if (result.error !== undefined)
+        return { rows: [], entryErrors: [], fileError: `${CLAUDE_USER_FILE} ${result.error}` };
+    const servers = isPlainObject(result.value) ? result.value.mcpServers : undefined;
+    const serversHash = createHash("sha256").update(canonicalJsonString(servers ?? {})).digest("hex");
+    const { rows, entryErrors } = parseMcpServersValue(servers, "cc-user", "");
+    return { rows, entryErrors, serversHash };
+}