fix: add MCP migration helper and subagent connectivity pre-check

[Tibsfox]

Summary

• Add /gsd:migrate-mcp command that guides users through migrating project-scoped MCP servers (.mcp.json) to global scope (~/.claude/mcp.json) — the proven workaround for Claude Code bug #13898
• Add <mcp_check> connectivity pre-check block to all 11 GSD agent definitions, preventing subagents from silently hallucinating MCP results when project-scoped servers are inaccessible
• Implements BUG-5 (Global MCP Migration Helper) and the MCP Connectivity Pre-Check from the GSD Subagent Capability Inheritance analysis documented in docs/MCP-FRONTMATTER-FINDINGS.md

Root Cause

Claude Code bug #13898 prevents custom subagents (agents defined in .claude/agents/ or ~/.claude/*/agents/) from accessing project-scoped MCP servers configured in .mcp.json. When a subagent attempts to use an MCP tool (e.g., mcp__context7__*, mcp__slack__*), the call silently fails and the agent hallucinate results rather than reporting an error. Global MCP servers (~/.claude/mcp.json) propagate correctly to all agent types.

The mcpServers: frontmatter field was investigated as an alternative solution (see docs/MCP-FRONTMATTER-FINDINGS.md). While it works for project-specific agents in .claude/agents/, it cannot solve GSD's problem because GSD agents are generic templates installed globally — we cannot hardcode user-specific MCP server configurations into them.

Fix

Two complementary, defense-in-depth changes:

1. /gsd:migrate-mcp command (commands/gsd/migrate-mcp.md, +117 lines)

A guided 5-step interactive command that:

1. Reads the project's .mcp.json and displays discovered servers
2. Reads the user's global ~/.claude/mcp.json (if it exists)
3. Classifies each server as ADD / SKIP (already identical) / CONFLICT (same name, different config)
4. Presents a merge plan with trade-off warnings (global = available in ALL projects)
5. Performs the migration using the Write tool (not heredoc) and verifies the result

Handles edge cases: missing .mcp.json, empty configs, conflicting server names with interactive resolution, and idempotent re-runs.

2. MCP connectivity pre-check in all 11 agents (+12 lines each, +132 lines total)

Adds a <mcp_check> block after each agent's <role> or <project_context> section with four directives:

1. Check availability — attempt to call expected MCP tools before relying on them
2. Report clearly — if unavailable, stop and show the user the exact fix (/gsd:migrate-mcp)
3. Never hallucinate — treat failed MCP calls as connectivity issues, not data issues
4. Graceful fallback — continue without MCP if the task can use other tools (Read, Bash, WebSearch)

Agents modified: gsd-codebase-mapper, gsd-debugger, gsd-executor, gsd-integration-checker, gsd-phase-researcher, gsd-plan-checker, gsd-planner, gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper, gsd-verifier

Relationship to Other PRs

This is PR-1 of 6 from the dev-bugfix branch. It is the only PR that targets dev-bugfix (the others target main):

PR	Title	Target	Status
#1 (this)	MCP migration helper + connectivity pre-check	dev-bugfix	Open
#2	Milestone completion bugs	main	Open
#3	Cross-platform Windows CI	main	Open
#4	Feature enhancements	main	Open
#5	Agent frontmatter + heredoc fix	main	Open
#6	CLI/config bug fixes	main	Open

Merge order recommendation: Merge PR #5 to main first (adds mcpServers: frontmatter to agents), then merge dev-bugfix to main, then this PR to dev-bugfix. The <mcp_check> blocks added here do not conflict with PR #5's frontmatter additions — they modify different sections of the agent files.

Relationship to PR #5: PR #5 adds YAML frontmatter (including mcpServers: field support) and anti-heredoc instructions to agent files. This PR adds <mcp_check> blocks in the agent body. Both modify the same 11 agent files but in non-overlapping sections — frontmatter vs. body content.

Testing

/gsd:migrate-mcp is a prompt-based command (markdown instruction file), not executable code. It cannot be unit-tested. The test plan is manual:

Manual Test Plan

• Run /gsd:migrate-mcp in a project with .mcp.json containing 2+ servers — verify it reads config, displays server table, presents merge plan, and writes to ~/.claude/mcp.json
• Run /gsd:migrate-mcp in a project without .mcp.json — verify graceful "no servers found" message with guidance
• Run /gsd:migrate-mcp when ~/.claude/mcp.json already has some servers — verify correct ADD/SKIP/CONFLICT classification
• Run /gsd:migrate-mcp when project and global configs have identical servers — verify SKIP (idempotent)
• Run /gsd:migrate-mcp when project and global configs have conflicting servers (same name, different config) — verify CONFLICT resolution prompt
• Verify <mcp_check> block is present in all 11 agent .md files
• Verify agents with MCP access (global scope) execute normally — no behavioral regression
• Verify agents without MCP access report the issue clearly instead of hallucinating results
• Spawn a subagent (e.g., gsd-executor) in a project with only project-scoped MCP — verify the pre-check catches it

Regression Test Suite

Full test suite passes with no regressions:

509 tests passed, 0 failed, 0 skipped
93 test suites
Duration: 4.96s

Test suites include agent frontmatter validation (47 tests), anti-heredoc verification, spawn consistency checks, and command structure validation — all passing.

Impact

• Users with project-scoped MCP servers: Get a clear, guided migration path instead of mysterious subagent failures. One command (/gsd:migrate-mcp) resolves the issue.
• All GSD subagent users: Agents now self-diagnose MCP connectivity issues instead of silently hallucinating. This eliminates a class of hard-to-debug failures where agents return plausible but fabricated MCP data.
• No breaking changes: Both additions are purely additive. The <mcp_check> block is a no-op when MCP tools are available. The command is opt-in.
• Files changed: 12 files, +249 lines, 0 deletions from existing content

Future Considerations

• Claude Code #13898 resolution: When the upstream bug is fixed, /gsd:migrate-mcp becomes optional (nice-to-have convenience rather than required workaround). The <mcp_check> blocks remain useful as defense-in-depth regardless.
• mcpServers: frontmatter for project agents: Users with project-specific custom agents (.claude/agents/) can add mcpServers: directly to their frontmatter today. This doesn't help GSD's globally-installed templates but is a valid approach for per-project agents.
• /gsd:health --mcp-check: A future health command could auto-detect whether #13898 is fixed by testing MCP propagation to a subagent, eliminating the need for users to know about the bug at all.
• Dynamic frontmatter injection: If Claude Code adds support for runtime frontmatter generation, GSD could dynamically inject the user's MCP server list into agent definitions at spawn time, removing the need for global scope migration entirely.

---

Addresses: BUG-5 (Global MCP Migration Helper), MCP Connectivity Pre-Check
Upstream: Claude Code #13898

[Tibsfox]

Code Logic Verification of PR #1

PR: feat: add MCP migration helper and subagent connectivity pre-check
Branch: fix/mcp-migration-helper → dev-bugfix
Commits: 3addc10 (migrate-mcp command, +117 lines) + f32bfa1 (mcp_check blocks, +12 lines × 11 agents)

---

1. The Before State (Bug Path)

Claude Code bug #13898 prevents project-scoped MCP servers (.mcp.json) from propagating to custom subagents. The execution path before this PR:

1. User configures MCP servers in .mcp.json (e.g., Context7 for library docs)
2. GSD spawns a subagent (e.g., gsd-phase-researcher with tools: mcp__context7__*)
3. Subagent attempts mcp__context7__resolve-library-id → fails silently
4. Agent has zero fallback logic — no instructions for what to do when MCP is unavailable
5. Agent may hallucinate MCP results or fail with cryptic errors
6. No migration path exists for users to move servers to global scope

Affected agents: Primarily gsd-phase-researcher and gsd-project-researcher (which declare mcp__context7__* in frontmatter tools), but all 11 agents could encounter MCP references in user tasks.

---

2. The After State (Fix Path)

The PR applies a belt-and-suspenders approach: fix the root cause (migration command) + add runtime resilience (pre-check blocks).

Component A — commands/gsd/migrate-mcp.md (+117 lines)

New user-facing command /gsd:migrate-mcp with a 5-step guided process:

1. Read .mcp.json from project root → early exit if missing/empty
2. Parse and display server list in table format with status
3. Read ~/.claude/mcp.json → categorize servers as ADD / SKIP (identical) / CONFLICT
4. Merge and write using the Write tool (explicitly mandates: "ALWAYS use the Write tool — never use heredoc")
5. Verify by reading back the written file and displaying final status

Edge cases handled: missing .mcp.json (early exit), no global config yet (starts with {"mcpServers": {}}), name collisions (CONFLICT category with per-server user decision: overwrite/keep/skip), already-migrated servers (SKIP with "identical" note).

Component B — <mcp_check> blocks (12 lines × 11 agents)

Identical block inserted in all 11 agents/gsd-*.md files, placed after <role> or <project_context> (whichever is last), before workflow content. The block instructs agents to:

1. Check MCP tool availability before using them
2. Report clearly if unavailable (with bug reference and fix instruction)
3. Never hallucinate MCP results
4. Continue without MCP using alternative tools (Read, Bash, WebSearch)

Block placement verified via MD5 checksum — all 11 are byte-identical. Architecturally correct: fires after identity/context, before workflow execution.

---

3. Key Correctness Checks

#	Check	Result	Notes
1	Block placement consistency	✅ PASS	All 11 agents, identical content, correct ordering
2	Command YAML frontmatter	✅ PASS	Follows GSD command format
3	5-step process logic	✅ PASS	Handles missing files, conflicts, already-migrated
4	No unintended file changes	✅ PASS	Exactly 12 files, 249 insertions, 0 deletions
5	GSD architectural alignment	✅ PASS	Follows existing structural patterns
6	Write tool mandated for config	✅ PASS	Step 4 explicitly requires Write tool
7	Conflict detection	✅ PASS	NEW/SKIP/CONFLICT categorization
8	Bug reference accuracy	✅ PASS	Correctly references #13898
9	Bash in allowed-tools	⚠️ CONCERN	Read tool handles missing files — Bash not strictly needed
10	No backup before global write	⚠️ CONCERN	Should backup ~/.claude/mcp.json before overwriting
11	MCP check wording	⚠️ CONCERN	"attempt to list or call" could trigger side effects — safer to just check tool listings
12	Blanket application to all agents	⚠️ CONCERN	Only 2-3 agents declare MCP tools; others get unused context
13	Missing AskUserQuestion tool	⚠️ MINOR	Conflict resolution needs interactive input
14	Anti-hallucination guidance	✅ PASS	Addresses real LLM failure mode
15	Graceful degradation	✅ PASS	Correct fail-open to alternative tools

---

4. Verdict

PASS — The PR addresses a real platform bug (#13898) with a sound two-component architecture: a user-facing migration command that fixes the root cause, plus runtime pre-check blocks that provide graceful degradation. Code trace confirms clean implementation: 12 files, 249 insertions, 0 deletions, consistent block placement, correct architectural ordering.

Noted concerns (non-blocking, suitable for follow-up):

• Remove Bash from migrate-mcp allowed-tools (principle of least privilege)
• Add backup step before writing ~/.claude/mcp.json
• Tighten mcp_check wording to "verify presence in tool listings"
• Consider limiting mcp_check to agents that actually declare MCP tools
• Add AskUserQuestion to allowed-tools for conflict resolution

These are improvements, not blockers. The current implementation is safe and functional.

Upstream: gsd-build/get-shit-done#814 — open and mergeable.

---

Verification performed using parallel adversarial review, security analysis, and code trace teams.

- Tibsfox ^.^