ln-012-mcp-configurator

What this skill does

> **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:
```bash
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
   - Fallback (standalone only): read `~/.claude.json` + `~/.claude/settings.json`
2. 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 |

3. 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` |
| 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` |

4. 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 Depen