ln-012-mcp-configurator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
) are relative to skills repo root. Locate this SKILL.md directory and go up one level for repo root.

路径： 文件路径（
shared/
、
references/
）是相对于技能仓库根目录的相对路径。找到本SKILL.md所在的目录，向上一级即为仓库根目录。

MCP Configurator

MCP配置器

Type: L3 Worker Category: 0XX Shared

Configures MCP servers in Claude Code: installs npm packages, registers servers, installs hooks and output style, migrates allowed-tools, updates instruction files, grants permissions.

类型： L3 Worker 分类： 0XX Shared

在Claude Code中配置MCP服务器：安装npm包、注册服务器、安装钩子和输出样式、迁移允许使用的工具列表、更新说明文件、授予权限。

Input / Output

输入/输出

Direction	Content
Input	OS info, `dry_run` flag, optional `runId` , optional `summaryArtifactPath`
Output	Structured summary envelope with `payload.status` = `completed` / `skipped` / `error` , plus per-server outcomes in `changes` / `detail`

summaryArtifactPath

is provided, write the same summary JSON there. If not provided, return the summary inline and remain fully standalone. If

runId

is not provided, generate a standalone

run_id

before emitting the summary envelope.

方向	内容
输入	操作系统信息、 `dry_run` 标记、可选 `runId` 、可选 `summaryArtifactPath`
输出	结构化摘要封包，其中 `payload.status` 取值为 `completed` / `skipped` / `error` ，同时在 `changes` / `detail` 字段中返回每个服务器的配置结果

如果提供了

summaryArtifactPath

，将相同的摘要JSON写入该路径。如果未提供，则直接返回摘要，保持完全独立运行。如果未提供

runId

，则在输出摘要封包前生成一个独立的

run_id

。

Server Registry

服务器注册表

Two transport types: stdio (local process) and HTTP (cloud endpoint).

Server	Transport	Install	Required	API Key
hex-line	stdio	`npx -y @levnikolaevich/hex-line-mcp`	Yes	No
hex-ssh	stdio	`npx -y @levnikolaevich/hex-ssh-mcp`	No	No
hex-graph	stdio	`npx -y @levnikolaevich/hex-graph-mcp`	No	No
context7	HTTP	`https://mcp.context7.com/mcp`	Yes	Optional
Ref	HTTP	`https://api.ref.tools/mcp`	Yes	Yes (prompt user)
linear	HTTP	`https://mcp.linear.app/mcp`	Ask user	No (OAuth)

支持两种传输类型：stdio（本地进程）和HTTP（云端端点）。

服务器	传输类型	安装方式	是否必填	API密钥
hex-line	stdio	`npx -y @levnikolaevich/hex-line-mcp`	是	否
hex-ssh	stdio	`npx -y @levnikolaevich/hex-ssh-mcp`	否	否
hex-graph	stdio	`npx -y @levnikolaevich/hex-graph-mcp`	否	否
context7	HTTP	`https://mcp.context7.com/mcp`	是	可选
Ref	HTTP	`https://api.ref.tools/mcp`	是	是（需提示用户输入）
linear	HTTP	`https://mcp.linear.app/mcp`	需询问用户	否（使用OAuth）

Workflow

工作流

Check Status & Version → Register & Configure → Verify Runtime Deps → Hooks → Permissions → Migrate → Report

检查状态与版本 → 注册与配置 → 验证运行时依赖 → 配置钩子 → 配置权限 → 迁移 → 生成报告

Phase 1: Check Status & Version

阶段1：检查状态与版本

Smart install: check MCP status AND package drift. npx -y caches aggressively — a connected server may still be backed by an older cached package.

Step 1a: Check MCP server status

Run

claude mcp list

-> parse each hex server:

Server	Status	Action
Registered + Connected	Working	Check version (Step 1b)
Registered + Disconnected	Broken	Re-register (Phase 2)
Not registered	Missing	Register in Phase 2

Step 1b: Version check for connected hex- servers*

For each connected hex server, run in parallel:

bash

npm view @levnikolaevich/${PKG} version 2>/dev/null

Then compare npm latest against the running local version:

npx cache probe:

npm config get cache

-> scan

{cacheRoot}/_npx/**/node_modules/@levnikolaevich/${PKG}/package.json

-> pick newest by semver/mtime

Use the npx cache version. If probe returns nothing, report

running=unknown

and treat the server as refresh-recommended rather than claiming it is current.

Note: hex packages run via

npx -y

, NOT global install. Never probe global npm paths.

npm latest	cached local version	Action
Same	Same	SKIP
Newer	Older	Mark "needs update" -> Phase 2 re-registers
Unknown	Any	WARN, proceed

Skip conditions:

Condition	Action
`disabled: true`	SKIP
`dry_run: true`	Show planned commands
Connected + cached local version matches npm latest	SKIP, report version

智能安装逻辑：同时检查MCP状态和包版本偏差。npx -y的缓存机制非常激进，已连接的服务器背后运行的可能仍然是旧的缓存包。

步骤1a：检查MCP服务器状态

运行

claude mcp list

→ 解析每个hex服务器的状态：

服务器	状态	操作
已注册+已连接	正常运行	检查版本（步骤1b）
已注册+未连接	异常	重新注册（阶段2）
未注册	缺失	阶段2注册

*步骤1b：已连接的hex-服务器版本检查

对每个已连接的hex服务器并行执行以下命令：

bash

npm view @levnikolaevich/${PKG} version 2>/dev/null

然后对比npm最新版本和本地运行的版本：

npx缓存探测： 执行

npm config get cache

→ 扫描

{cacheRoot}/_npx/**/node_modules/@levnikolaevich/${PKG}/package.json

→ 按语义版本号/修改时间取最新版本

使用npx缓存的版本。如果探测无结果，上报

running=unknown

，并标记建议刷新服务器，而非判定为当前已是最新版本。

注意：hex包通过

npx -y

运行，而非全局安装。绝对不要探测全局npm路径。

npm最新版本	本地缓存版本	操作
相同	相同	跳过
更新	较旧	标记为"需要更新" → 阶段2重新注册
未知	任意	告警，继续执行

跳过条件：

条件	操作
`disabled: true`	跳过
`dry_run: true`	展示计划执行的命令
已连接且本地缓存版本与npm最新版本一致	跳过，上报版本信息

Phase 2: Register & Configure

阶段2：注册与配置

One pass: use Phase 1 state (do NOT re-run

claude mcp list

) -> remove deprecated -> register/update -> verify.

Reuse Phase 1 state — server map from Step 1a already has registration + connection status
- Fallback (standalone only): read
```
~/.claude.json
```
  +
```
~/.claude/settings.json
```
Remove deprecated servers:

Deprecated Server	Action
hashline-edit	Remove if found
pencil	Remove if found
lighthouse	Remove if found
playwright	Remove if found
browsermcp	Remove if found

Register missing OR update outdated servers:
- IF already configured AND connected AND cached local version matches -> SKIP
- IF connected but outdated -> remove + re-add (forces npx to fetch latest)
- IF
```
dry_run: true
```
  -> show planned command
- IF linear -> ask user: "Do you use Linear?" -> no -> SKIP

Registration commands (OS-dependent prefix):

OS	Prefix	Why
Windows (bash/MSYS2)	`MSYS_NO_PATHCONV=1 claude mcp add ... -- cmd /c npx`	MSYS2/Git Bash converts `/c` -> `C:/` in args. `MSYS_NO_PATHCONV=1` prevents this
Windows (PowerShell/cmd)	`cmd /c npx`	No path conversion issue in native shells
macOS / Linux	`npx`	Direct execution

Server	Command (Windows bash — always prefix with `MSYS_NO_PATHCONV=1` )
hex-line	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-line -- cmd /c npx -y @levnikolaevich/hex-line-mcp`
hex-ssh	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-ssh -- cmd /c npx -y @levnikolaevich/hex-ssh-mcp`
hex-graph	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-graph -- cmd /c npx -y @levnikolaevich/hex-graph-mcp`
context7	`claude mcp add -s user --transport http context7 https://mcp.context7.com/mcp`
Ref	`claude mcp add -s user --transport http Ref https://api.ref.tools/mcp`
linear	`claude mcp add -s user --transport http linear-server https://mcp.linear.app/mcp`

Verify:
```
claude mcp list
```
-> check all registered show
```
Connected
```
. This is the only second
```
claude mcp list
```
call (post-mutation verify). Retry + report failures.

Windows MSYS2 path validation (MANDATORY on win32): After registration, read

~/.claude.json

-> verify each hex server's

args[0]

"/c"

not

"C:/"

. If corrupted: fix via

mcp__hex-line__edit_file

(set_line the arg to

"/c"

Error handling:

Error	Response
`claude` CLI not found	FAIL, report "Claude CLI not in PATH"
Server already exists	SKIP, report "already configured"
Connection failed after add	WARN, report detail from `claude mcp list`
API key missing (Ref)	Prompt user for key, skip if declined

单次执行：使用阶段1的状态（不要重新运行

claude mcp list

） → 移除废弃服务器 → 注册/更新服务器 → 验证。

复用阶段1状态 — 步骤1a生成的服务器映射已经包含注册和连接状态
- 降级方案（仅独立运行时）：读取
```
~/.claude.json
```
  +
```
~/.claude/settings.json
```
移除废弃服务器：

废弃服务器	操作
hashline-edit	存在则移除
pencil	存在则移除
lighthouse	存在则移除
playwright	存在则移除
browsermcp	存在则移除

注册缺失的服务器或更新过时的服务器：
- 如果已配置、已连接且本地缓存版本匹配 → 跳过
- 如果已连接但版本过时 → 移除并重新添加（强制npx拉取最新版本）
- 如果
```
dry_run: true
```
  → 展示计划执行的命令
- 如果是linear → 询问用户："你是否使用Linear？" → 否 → 跳过

注册命令（前缀与操作系统相关）：

操作系统	前缀	原因
Windows (bash/MSYS2)	`MSYS_NO_PATHCONV=1 claude mcp add ... -- cmd /c npx`	MSYS2/Git Bash会将参数中的 `/c` 转换为 `C:/` ， `MSYS_NO_PATHCONV=1` 可阻止该转换
Windows (PowerShell/cmd)	`cmd /c npx`	原生shell无路径转换问题
macOS / Linux	`npx`	直接执行

服务器	命令（Windows bash环境下始终添加 `MSYS_NO_PATHCONV=1` 前缀）
hex-line	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-line -- cmd /c npx -y @levnikolaevich/hex-line-mcp`
hex-ssh	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-ssh -- cmd /c npx -y @levnikolaevich/hex-ssh-mcp`
hex-graph	`MSYS_NO_PATHCONV=1 claude mcp add -s user hex-graph -- cmd /c npx -y @levnikolaevich/hex-graph-mcp`
context7	`claude mcp add -s user --transport http context7 https://mcp.context7.com/mcp`
Ref	`claude mcp add -s user --transport http Ref https://api.ref.tools/mcp`
linear	`claude mcp add -s user --transport http linear-server https://mcp.linear.app/mcp`

验证：运行
```
claude mcp list
```
→ 检查所有已注册服务器状态为
```
Connected
```
。这是第二次也是最后一次调用
```
claude mcp list
```
（变更后验证）。重试并上报失败情况。

Windows MSYS2路径验证（win32环境下强制执行）： 注册完成后，读取

~/.claude.json

→ 验证每个hex服务器的

args[0]

是

"/c"

而非

"C:/"

。如果被篡改：通过

mcp__hex-line__edit_file

修复（将参数设置为

"/c"

）。

错误处理：

错误	响应
未找到 `claude` CLI	失败，上报"Claude CLI不在PATH中"
服务器已存在	跳过，上报"已配置"
添加后连接失败	告警，上报 `claude mcp list` 返回的详细信息
API密钥缺失（Ref）	提示用户输入密钥，用户拒绝则跳过

Phase 2b: Verify Runtime Dependencies

阶段2b：验证运行时依赖

After registration + connection, verify that MCP packages have all system-level dependencies available. npx installs npm modules, but some packages require system binaries or native compilation that may silently fail.

Step 1: Identify which servers are connected Reuse Phase 2 verification state. Only check deps for connected hex-* servers.

Step 2: Verify hex-line-mcp dependencies

Dependency	Check	Required	Auto-fix	Fallback
ripgrep	`rg --version`	Yes	See install table	grep_search fails
git	`git --version`	No	Inform only	`changes` tool disabled

Ripgrep install by platform:

Platform	Command
Linux (apt)	`sudo apt-get install -y ripgrep`
Linux (yum)	`sudo yum install -y ripgrep`
macOS	`brew install ripgrep`
Windows (winget)	`winget install BurntSushi.ripgrep.MSVC`
Windows (scoop)	`scoop install ripgrep`
Fallback (npm)	`npm exec --yes -- @vscode/ripgrep-postinstall`

rg --version

fails: ask user whether to auto-install (suggest platform-appropriate command). If user declines, WARN but continue — hex-line will degrade on grep.

Step 3: Verify hex-graph-mcp dependencies

Dependency	Check	Required	Auto-fix	Fallback
better-sqlite3	hex-graph connected (Phase 2)	Yes	Needs C++ build tools	hex-graph won't start
basedpyright	`basedpyright-langserver --version`	No	`pip install basedpyright`	Python precise analysis skipped
csharp-ls	`csharp-ls --version`	No	`dotnet tool install -g csharp-ls`	C# precise analysis skipped
phpactor	`phpactor --version`	No	—	PHP precise analysis skipped

For optional language servers: check availability, report status. Auto-install only if the corresponding runtime is already present (Python for basedpyright, .NET for csharp-ls). Never install a runtime just for a language server.

Step 4: Verify hex-ssh-mcp dependencies

No system dependencies (pure JS ssh2). Skip.

Step 5: Report dependency table

Print table with columns: Server | Dependency | Status | Action.

Status	Meaning
OK	Available and functional
INSTALLED	Was missing, auto-installed
WARN	Missing, user declined install
SKIP	Optional, runtime not present
FAIL	Required, cannot install

Error handling:

Error	Response
Required dep missing + user declines	WARN, continue with degraded functionality
Auto-install fails	WARN, show manual install instructions
Optional dep missing	INFO, note in report

注册并连接成功后，验证MCP包所需的所有系统级依赖是否可用。npx会安装npm模块，但部分包需要系统二进制文件或原生编译，这些可能会静默失败。

步骤1：识别已连接的服务器 复用阶段2的验证状态，仅检查已连接的hex-*服务器的依赖。

步骤2：验证hex-line-mcp依赖

依赖	检查命令	是否必填	自动修复	降级方案
ripgrep	`rg --version`	是	参考安装表	grep_search功能失效
git	`git --version`	否	仅提示	`changes` 工具禁用

不同平台的Ripgrep安装命令：

平台	命令
Linux (apt)	`sudo apt-get install -y ripgrep`
Linux (yum)	`sudo yum install -y ripgrep`
macOS	`brew install ripgrep`
Windows (winget)	`winget install BurntSushi.ripgrep.MSVC`
Windows (scoop)	`scoop install ripgrep`
降级方案（npm）	`npm exec --yes -- @vscode/ripgrep-postinstall`

如果

rg --version

执行失败：询问用户是否允许自动安装（推荐对应平台的命令）。如果用户拒绝，告警但继续执行 — hex-line的grep功能会降级。

步骤3：验证hex-graph-mcp依赖

依赖	检查方式	是否必填	自动修复	降级方案
better-sqlite3	hex-graph已连接（阶段2）	是	需要C++编译工具	hex-graph无法启动
basedpyright	`basedpyright-langserver --version`	否	`pip install basedpyright`	跳过Python精确分析
csharp-ls	`csharp-ls --version`	否	`dotnet tool install -g csharp-ls`	跳过C#精确分析
phpactor	`phpactor --version`	否	—	跳过PHP精确分析

对于可选的语言服务器：检查可用性，上报状态。仅当对应运行时已存在时才自动安装（basedpyright需要Python，csharp-ls需要.NET）。绝对不要仅为了安装语言服务器而安装运行时。

步骤4：验证hex-ssh-mcp依赖

无系统依赖（纯JS实现的ssh2），跳过。

步骤5：上报依赖检查表

打印包含以下列的表格：服务器 | 依赖 | 状态 | 操作。

状态	含义
OK	可用且功能正常
INSTALLED	之前缺失，已自动安装
WARN	缺失，用户拒绝安装
SKIP	可选，对应运行时不存在
FAIL	必填，无法安装

错误处理：

错误	响应
必填依赖缺失且用户拒绝安装	告警，以降级功能继续运行
自动安装失败	告警，展示手动安装说明
可选依赖缺失	提示，在报告中说明

Phase 3: Hooks & Output Style [CRITICAL]

阶段3：钩子与输出样式配置【关键】

MUST call

mcp__hex-line__setup_hooks(agent="all")

AFTER all Phase 2 registrations complete (not just hex-line). This ensures the latest hook.mjs and output-style.md from the updated package are installed.

Hooks (in

~/.claude/settings.json

```
PreToolUse
```
hook — redirects built-in Read/Edit/Write/Grep to hex-line equivalents
```
PostToolUse
```
hook — compresses verbose tool output (RTK filter)
```
SessionStart
```
hook — injects MCP Tool Preferences reminder
Sets
```
disableAllHooks: false
```

Output Style: 5. Copies

output-style.md

~/.claude/output-styles/hex-line.md

6. Sets

outputStyle: "hex-line"

if no style is active (preserves existing style)

Verification: Response must contain

Hooks configured for

. If

SKIPPED

UNKNOWN_AGENT

Error

, or

failed

— STOP.

Note:

setup_hooks(agent="all")

also syncs MCP server entries and hook paths for Gemini. Codex is reported as "not supported" (expected). After this call, ln-013 should verify Gemini state rather than blindly overwriting.

Note:

setup_hooks(agent="all")

is idempotent. Calling it again during later verification is safe and keeps hooks current.

必须在阶段2所有注册操作完成后调用

mcp__hex-line__setup_hooks(agent="all")

（不能仅在hex-line注册后调用）。这会确保安装更新后的包中最新的hook.mjs和output-style.md。

钩子（存储在

~/.claude/settings.json

中）：

```
PreToolUse
```
钩子 — 将内置的读/编辑/写/ grep操作重定向到hex-line的对应实现
```
PostToolUse
```
钩子 — 压缩冗长的工具输出（RTK过滤器）
```
SessionStart
```
钩子 — 注入MCP工具偏好提示
设置
```
disableAllHooks: false
```

输出样式： 5. 将

output-style.md

复制到

~/.claude/output-styles/hex-line.md

6. 如果没有激活的样式，设置

outputStyle: "hex-line"

（保留已有样式）

验证： 响应必须包含

Hooks configured for

。如果返回

SKIPPED

、

UNKNOWN_AGENT

、

Error

或

failed

— 终止执行。

注意：

setup_hooks(agent="all")

也会同步Gemini的MCP服务器条目和钩子路径。Codex会返回"不支持"，属于预期结果。调用完成后，ln-013应该验证Gemini状态，而非盲目覆盖。

注意：

setup_hooks(agent="all")

是幂等的。后续验证阶段再次调用是安全的，可保持钩子为最新版本。

Phase 4: Graph Indexing

阶段4：图谱索引

After hex-graph registration + connected status:

mcp__hex-graph__index_project({ path: "{project_path}" })

— build initial code knowledge graph

mcp__hex-graph__watch_project({ path: "{project_path}" })

— enable live incremental updates

Skip if hex-graph not registered or not connected.

hex-graph注册并连接成功后：

执行

mcp__hex-graph__index_project({ path: "{project_path}" })

— 构建初始代码知识图谱

执行

mcp__hex-graph__watch_project({ path: "{project_path}" })

— 开启实时增量更新

如果hex-graph未注册或未连接则跳过。

Phase 5: Migrate allowed-tools [CRITICAL]

阶段5：迁移允许使用的工具列表【关键】

Scan project commands/skills to replace built-in tools with hex-line equivalents in

allowed-tools

frontmatter.

Tool mapping:

Built-in	Hex equivalent
`Read`	`mcp__hex-line__read_file`
`Edit`	`mcp__hex-line__edit_file`
`Write`	`mcp__hex-line__write_file`
`Grep`	`mcp__hex-line__grep_search`

Steps:

Glob

.claude/commands/*.md

.claude/skills/*/SKILL.md

in current project

For each file: parse YAML frontmatter, extract
```
allowed-tools
```
For each mapping entry: a. If built-in present AND hex equivalent absent -> add hex equivalent, remove built-in (except
```
Read
```
and
```
Bash
```
) b. If built-in present AND hex equivalent already present -> remove built-in (except
```
Read
```
and
```
Bash
```
) c. Preserve ALL existing
```
mcp__*
```
tools not in the replacement table
Write back updated frontmatter (preserve quoting style)

Skip conditions:

Condition	Action
No `.claude/` directory	Skip entire phase
File has no `allowed-tools`	Skip file
All hex equivalents present	Skip file, report "already migrated"
`dry_run: true`	Show planned changes

扫描项目命令/技能，将

allowed-tools

前置元数据中的内置工具替换为hex-line的对应实现。

工具映射关系：

内置工具	Hex对应实现
`Read`	`mcp__hex-line__read_file`
`Edit`	`mcp__hex-line__edit_file`
`Write`	`mcp__hex-line__write_file`
`Grep`	`mcp__hex-line__grep_search`

步骤：

全局匹配当前项目中的

.claude/commands/*.md

.claude/skills/*/SKILL.md

文件

对每个文件：解析YAML前置元数据，提取
```
allowed-tools
```
列表
对每个映射条目： a. 如果存在内置工具且不存在hex对应实现 → 添加hex对应实现，移除内置工具（
```
Read
```
和
```
Bash
```
除外） b. 如果存在内置工具且已存在hex对应实现 → 移除内置工具（
```
Read
```
和
```
Bash
```
除外） c. 保留所有不在替换表中的现有
```
mcp__*
```
工具
回写更新后的前置元数据（保留原有引号风格）

跳过条件：

条件	操作
无 `.claude/` 目录	跳过整个阶段
文件无 `allowed-tools` 字段	跳过该文件
所有hex对应实现都已存在	跳过该文件，上报"已迁移"
`dry_run: true`	展示计划变更

Phase 6: Update Instruction Files [CRITICAL]

阶段6：更新说明文件【关键】

Ensure instruction files have MCP Tool Preferences section.

MANDATORY READ: Load

mcp/hex-line-mcp/output-style.md

-> use its

# MCP Tool Preferences

section as template.

Steps:

For each file: CLAUDE.md, GEMINI.md, AGENTS.md (if exists in project)

Search for

## MCP Tool Preferences

### MCP Tool Preferences

If MISSING -> insert before
```
## Navigation
```
(or at end of conventions/rules block)
If PRESENT but OUTDATED -> update table rows to match template

For GEMINI.md: adapt tool names (

Read

read_file

Edit

edit_file

Grep

search_files

)

Skip conditions:

Condition	Action
File doesn't exist	Skip
Section already matches template	Skip, report "up to date"

确保说明文件包含MCP工具偏好章节。

强制要求： 加载

mcp/hex-line-mcp/output-style.md

→ 使用其中的

# MCP Tool Preferences

章节作为模板。

步骤：

处理以下文件：CLAUDE.md、GEMINI.md、AGENTS.md（如果项目中存在）

搜索

## MCP Tool Preferences

或

### MCP Tool Preferences

章节

如果不存在 → 插入到
```
## Navigation
```
之前（或约定/规则块的末尾）
如果存在但已过时 → 更新表格行以匹配模板
对于GEMINI.md：适配工具名称（
```
Read
```
→
```
read_file
```
，
```
Edit
```
→
```
edit_file
```
，
```
Grep
```
→
```
search_files
```
）

跳过条件：

条件	操作
文件不存在	跳过
章节内容已匹配模板	跳过，上报"已是最新版本"

Phase 7: Grant Permissions

阶段7：授予权限

For each configured MCP server, add

mcp__{name}

~/.claude/settings.json

permissions.allow[]

Server	Permission entry
hex-line	`mcp__hex-line`
hex-ssh	`mcp__hex-ssh`
hex-graph	`mcp__hex-graph`
context7	`mcp__context7`
Ref	`mcp__Ref`
linear	`mcp__linear-server`

Read

~/.claude/settings.json

(create if missing:

{"permissions":{"allow":[]}}

)

For each configured server: check if
```
mcp__{name}
```
already in
```
allow[]
```
Missing -> append
Write back (2-space indent JSON)

Idempotent: existing entries skipped.

对每个已配置的MCP服务器，将

mcp__{name}

添加到

~/.claude/settings.json

的

permissions.allow[]

数组中。

服务器	权限条目
hex-line	`mcp__hex-line`
hex-ssh	`mcp__hex-ssh`
hex-graph	`mcp__hex-graph`
context7	`mcp__context7`
Ref	`mcp__Ref`
linear	`mcp__linear-server`

读取

~/.claude/settings.json

（如果不存在则创建：

{"permissions":{"allow":[]}}

）

对每个已配置的服务器：检查
```
mcp__{name}
```
是否已在
```
allow[]
```
中
不存在则追加
回写文件（JSON使用2空格缩进）

幂等性： 已存在的条目会被跳过。

Phase 8: Report

阶段8：生成报告

Status table:

MCP Configuration:
| Server    | Transport | Version | Status        | Permission | Detail                  |
|-----------|-----------|---------|---------------|------------|-------------------------|
| hex-line  | stdio     | 1.5.0   | configured    | granted    | global npm (hex-line-mcp) |
| hex-ssh   | stdio     | 1.2.0   | updated       | granted    | was 1.1.6, now 1.2.0     |
| context7  | HTTP      | —       | configured    | granted    | mcp.context7.com        |
| Ref       | HTTP      | —       | configured    | granted    | api.ref.tools (key set) |
| linear    | HTTP      | —       | skipped       | skipped    | user declined           |

状态表示例：

MCP Configuration:
| Server    | Transport | Version | Status        | Permission | Detail                  |
|-----------|-----------|---------|---------------|------------|-------------------------|
| hex-line  | stdio     | 1.5.0   | configured    | granted    | global npm (hex-line-mcp) |
| hex-ssh   | stdio     | 1.2.0   | updated       | granted    | was 1.1.6, now 1.2.0     |
| context7  | HTTP      | —       | configured    | granted    | mcp.context7.com        |
| Ref       | HTTP      | —       | configured    | granted    | api.ref.tools (key set) |
| linear    | HTTP      | —       | skipped       | skipped    | user declined           |

Critical Rules

关键规则

Write only via sanctioned paths. Register servers via
```
claude mcp add
```
. Write to
```
~/.claude/settings.json
```
ONLY for hooks (via
```
setup_hooks
```
), permissions (
```
permissions.allow[]
```
), and
```
outputStyle
```
Verify after add. Always run
```
claude mcp list
```
after registration to confirm connection
Ask before optional servers. Linear requires explicit user consent
npx -y for all hex MCP. Never
```
npm i -g
```
— npx provides process isolation and avoids EBUSY on Windows. On Windows, wrap with
```
cmd /c npx
```
(see Phase 2 OS prefix table)
Remove deprecated servers. Clean up servers no longer in the registry
Grant permissions. After registration, add
```
mcp__{server}
```
to user settings
Minimize
claude mcp list
calls. Phase 1 runs it once (discovery). Phase 2 reuses that data. Only Phase 2 Step 4 runs it again (post-mutation verify). Max 2 calls total
Always check npm drift. Connected != up to date. Compare npm latest against the newest locally cached npx package version before skipping
MSYS2 path safety. On Windows with Git Bash/MSYS2, always prefix
```
claude mcp add
```
with
```
MSYS_NO_PATHCONV=1
```
. After registration, verify
```
args[0]
```
in
```
.claude.json
```
is
```
"/c"
```
not
```
"C:/"
```
. Fix inline if corrupted.
Verify runtime deps after install. After Phase 2 registration, check system binaries (rg, git) and optional language servers. Auto-install only with user consent. Never install a runtime just for a language server.

仅通过授权路径写入数据。 通过
```
claude mcp add
```
注册服务器。仅允许在配置钩子（通过
```
setup_hooks
```
）、配置权限（
```
permissions.allow[]
```
）和设置
```
outputStyle
```
时写入
```
~/.claude/settings.json
```
添加后必须验证。 注册完成后始终运行
```
claude mcp list
```
确认连接状态
可选服务器需提前询问。 Linear需要用户明确同意才能添加
所有hex MCP使用npx -y运行。 绝对不要使用
```
npm i -g
```
— npx提供进程隔离，避免Windows上的EBUSY错误。Windows环境下使用
```
cmd /c npx
```
包裹（参考阶段2的操作系统前缀表）
移除废弃服务器。 清理注册表中不再使用的服务器
授予权限。 注册完成后，将
```
mcp__{server}
```
添加到用户设置中
尽量减少
claude mcp list
调用次数。阶段1运行1次（发现），阶段2复用该数据，仅阶段2步骤4再次运行（变更后验证）。最多总共调用2次
始终检查npm版本偏差。 已连接≠版本最新。跳过前需对比npm最新版本和本地最新缓存的npx包版本
MSYS2路径安全。 Windows下使用Git Bash/MSYS2时，
```
claude mcp add
```
始终添加
```
MSYS_NO_PATHCONV=1
```
前缀。注册完成后验证
```
.claude.json
```
中的
```
args[0]
```
是
```
"/c"
```
而非
```
"C:/"
```
，被篡改则直接修复
安装后验证运行时依赖。 阶段2注册完成后，检查系统二进制文件（rg、git）和可选语言服务器。仅在用户同意的情况下自动安装，绝对不要仅为了语言服务器安装运行时

Anti-Patterns

反模式

DON'T	DO
Write arbitrary fields to `~/.claude.json`	Use `claude mcp add` for servers, `setup_hooks` for hooks
Skip verification after add	Always check `claude mcp list` after mutations
Auto-add optional servers	Ask user for Linear and other optional servers
Leave deprecated servers	Remove hashline-edit, pencil, etc.
Calculate token budget	Not this worker's responsibility
Run `claude mcp list` in every phase	Run once in Phase 1, reuse in Phase 2, verify once after mutations
Assume connected = up to date	Check `npm view` version vs newest cached npx package version
Call `setup_hooks` before all packages re-registered	Call `setup_hooks(agent="all")` AFTER all Phase 2 registrations complete
Run `claude mcp add` without MSYS_NO_PATHCONV on Windows bash	Always `MSYS_NO_PATHCONV=1 claude mcp add ...` or verify+fix args after
Skip runtime dependency verification	Always run Phase 2b after registration to catch missing system binaries
Auto-install system packages without asking	Ask user before running platform package managers (apt, brew, winget)

禁止操作	推荐操作
向 `~/.claude.json` 写入任意字段	服务器使用 `claude mcp add` 注册，钩子使用 `setup_hooks` 配置
添加后跳过验证	变更后始终检查 `claude mcp list` 结果
自动添加可选服务器	Linear和其他可选服务器需提前询问用户
保留废弃服务器	移除hashline-edit、pencil等废弃服务器
计算token预算	不属于本worker的职责
每个阶段都运行 `claude mcp list`	阶段1运行1次，阶段2复用，变更后验证1次即可
假设已连接=版本最新	对比 `npm view` 返回的版本和最新缓存的npx包版本
所有包重新注册前调用 `setup_hooks`	阶段2所有注册完成后再调用 `setup_hooks(agent="all")`
Windows bash环境下不加MSYS_NO_PATHCONV运行 `claude mcp add`	始终添加 `MSYS_NO_PATHCONV=1 claude mcp add ...` 前缀，或注册后验证修复参数
跳过运行时依赖验证	注册后始终运行阶段2b，检查缺失的系统二进制文件
未询问用户自动安装系统包	运行平台包管理器（apt、brew、winget）前需询问用户

Definition of Done

完成标准

MCP packages installed and versions verified against npm registry (Phase 1)
Missing servers registered and verified connected (Phase 2)
Outdated servers re-registered with latest version (Phase 2)
Runtime dependencies verified: ripgrep available, optional deps reported (Phase 2b)
Hooks installed (PreToolUse, PostToolUse, SessionStart) and
```
disableAllHooks: false
```
(Phase 3)
Output style installed (Phase 3)
Permissions granted for all configured servers (Phase 7)
Project allowed-tools migrated (Phase 5)
MCP Tool Preferences in all instruction files (Phase 6)
Status table with version column displayed (Phase 8)

Version: 1.5.0 Last Updated: 2026-04-01

MCP包已安装，版本已与npm仓库校验（阶段1）
缺失的服务器已注册并验证连接正常（阶段2）
过时的服务器已重新注册为最新版本（阶段2）
运行时依赖已验证：ripgrep可用，可选依赖已上报（阶段2b）
钩子已安装（PreToolUse、PostToolUse、SessionStart），且
```
disableAllHooks: false
```
（阶段3）
输出样式已安装（阶段3）
所有已配置服务器的权限已授予（阶段7）
项目允许使用的工具列表已迁移（阶段5）
所有说明文件已添加MCP工具偏好章节（阶段6）
已展示包含版本列的状态表（阶段8）

版本： 1.5.0 最后更新： 2026-04-01