ln-012-mcp-configurator

Paths: File paths (references/) are relative to this skill directory.

MCP Configurator

Type: L3 Worker Category: 0XX Shared

Invocation is agent-agnostic. Target surfaces are Claude-specific: this skill configures Claude Code MCP settings, hook/style sync, permissions, and Claude Code IDE extension permission mode.

MANDATORY READ

MANDATORY READ: Load references/coordinator_summary_contract.md, references/environment_worker_runtime_contract.md, and references/worker_runtime_contract.md

Target MCP availability is not a precondition for this worker. If a server is not connected yet, use config files, package metadata, and CLI state to continue registration and cleanup work; report provider checks or live verification as skipped when they cannot run without MCP.

Input / Output

| Direction | Content | |-----------|---------| | Input | OS info, dry_run flag, optional apply_ide_override flag (default false — Phase 6b is detection-only without it), optional runId, optional summaryArtifactPath | | Output | Structured summary envelope with payload.status = completed / skipped / error, plus per-server outcomes in changes / detail, plus IDE extension state in payload.ide_extension |

If 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.

Runtime

Runtime family: environment-worker-runtime

Phase profile:

1. PHASE_0_CONFIG
2. PHASE_1_CHECK_STATUS_AND_VERSION
3. PHASE_2_REGISTER_AND_CONFIGURE
4. PHASE_3_VERIFY_GRAPH_PROVIDER_DEPS
5. PHASE_4_HOOKS_AND_OUTPUT_STYLE
6. PHASE_5_GRAPH_INDEXING
7. PHASE_6_MIGRATE_ALLOWED_TOOLS
8. PHASE_7_PERMISSION_SURFACES
9. PHASE_8_WRITE_SUMMARY
10. PHASE_9_SELF_CHECK

Runtime rules:

• emit summary_kind=env-mcp-config
• standalone runs generate their own run_id and write the default worker-family artifact path
• managed runs require both runId and summaryArtifactPath and must write the summary to the exact provided path
• always write the validated summary artifact before terminal outcome

Output Contract

Always build a structured env-mcp-config summary envelope per:

• references/coordinator_summary_contract.md
• references/environment_worker_runtime_contract.md

Payload fields:

• servers
• permissions
• ide_extension
• hooks_synced
• output_style_synced
• allowed_tools_migrated
• graph_provider_status
• status

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 | | hex-research | stdio | npx -y @levnikolaevich/hex-research-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) |

Workflow

Check Status & Version → Register & Configure → Verify Graph Provider Deps → Hooks → Permissions → IDE Extension Mode → Migrate → Report

Phase 1: Check Status & Version

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 published hex server, run in parallel:

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

Then compare npm latest against the running local version:

1. 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: published 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 |

Phase 2: Register & Configure

One pass: use Phase 1 state (do NOT re-run claude mcp list) -> remove unsupported -> register/update -> verify.

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

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

1. Register missing OR update outdated servers:
2. IF already configured AND connected AND cached local version matches -> SKIP
3. IF connected but outdated -> remove + re-add (forces npx to fetch latest)
4. IF dry_run: true -> show planned command
5. 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 | | hex-research | MSYS_NO_PATHCONV=1 claude mcp add -s user hex-research -- cmd /c npx -y @levnikolaevich/hex-research-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 |

1. 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] is "/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 |

Phase 2b: Verify Graph Provider Depend