feat: add MCP migration helper and subagent connectivity pre-check#814
Open
Tibsfox wants to merge 7 commits intogsd-build:mainfrom
Open
feat: add MCP migration helper and subagent connectivity pre-check#814Tibsfox wants to merge 7 commits intogsd-build:mainfrom
Tibsfox wants to merge 7 commits intogsd-build:mainfrom
Conversation
Add 'never use heredoc' instruction to 6 agents that were missing it: gsd-codebase-mapper, gsd-debugger, gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-roadmapper. All 9 file-writing agents now consistently prevent settings.local.json corruption from heredoc permission entries (GSD gsd-build#526). Read-only agents (plan-checker, integration-checker) excluded as they cannot write files. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add skills: field to all 11 agent frontmatter files with forward-compatible GSD workflow skill references (silently ignored until skill files are created). Add commented hooks: examples to 9 file-writing agents showing PostToolUse hook syntax for project-specific linting/formatting. Read-only agents (plan-checker, integration-checker) skip hooks as they cannot modify files. Per Claude Code docs: subagents don't inherit skills or hooks from the parent conversation — they must be explicitly listed in frontmatter. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Replace general-purpose workaround pattern with named subagent types: - plan-phase: researcher and planner now spawn as gsd-phase-researcher/gsd-planner - new-project: 4 researcher spawns now use gsd-project-researcher - research-phase: researcher spawns now use gsd-phase-researcher - quick: planner revision now uses gsd-planner - diagnose-issues: debug agents now use gsd-debugger (matches template spec) Removes 'First, read agent .md file' prompt prefix — named agent types auto-load their .md file as system prompt, making the workaround redundant. Preserves intentional general-purpose orchestrator spawns in discuss-phase and plan-phase (auto-advance) where the agent runs an entire workflow. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Document analysis of Claude Code mcpServers frontmatter behavior based on official documentation. Key finding: frontmatter mcpServers creates independent connections but cannot solve GSD's problem because agent definitions are generic templates, not project-specific. Strategy decision: proceed with MCP migration helper (PR-6) as the practical solution. General-purpose fallback (PR-5) deprioritized. Co-Authored-By: Claude Opus 4.6 <[email protected]>
New test suite covering: - HDOC: anti-heredoc instruction present in all 9 file-writing agents - SKILL: skills: frontmatter present in all 11 agents - HOOK: commented hooks pattern in file-writing agents - SPAWN: no stale workaround patterns, valid agent type references - AGENT: required frontmatter fields (name, description, tools, color) 509 total tests (462 existing + 47 new), 0 failures. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add /gsd:migrate-mcp slash command that reads project .mcp.json, displays configured servers, and offers to merge them into ~/.claude/mcp.json (global scope). This provides the primary workaround for Claude Code bug #13898 where project-scoped MCP servers don't propagate to custom subagents. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add <mcp_check> block to every agent that instructs them to verify MCP tool availability before use, report clearly when unavailable instead of hallucinating results, and reference /gsd:migrate-mcp as the fix. Placed after </project_context> or </role> depending on agent structure. Co-Authored-By: Claude Opus 4.6 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/gsd:migrate-mcpcommand 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<mcp_check>connectivity pre-check block to all 11 GSD agent definitions, preventing subagents from silently hallucinating MCP results when project-scoped servers are inaccessibledocs/MCP-FRONTMATTER-FINDINGS.mdRoot 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 (seedocs/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-mcpcommand (commands/gsd/migrate-mcp.md, +117 lines)A guided 5-step interactive command that:
.mcp.jsonand displays discovered servers~/.claude/mcp.json(if it exists)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:/gsd:migrate-mcp)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-verifierRelationship to Other PRs
This is PR-1 of 6 from the
dev-bugfixbranch. It is the only PR that targetsdev-bugfix(the others targetmain):dev-bugfixmainmainmainmainmainMerge order recommendation: Merge PR #5 to
mainfirst (addsmcpServers:frontmatter to agents), then mergedev-bugfixtomain, then this PR todev-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-mcpis a prompt-based command (markdown instruction file), not executable code. It cannot be unit-tested. The test plan is manual:Manual Test Plan
/gsd:migrate-mcpin a project with.mcp.jsoncontaining 2+ servers — verify it reads config, displays server table, presents merge plan, and writes to~/.claude/mcp.json/gsd:migrate-mcpin a project without.mcp.json— verify graceful "no servers found" message with guidance/gsd:migrate-mcpwhen~/.claude/mcp.jsonalready has some servers — verify correct ADD/SKIP/CONFLICT classification/gsd:migrate-mcpwhen project and global configs have identical servers — verify SKIP (idempotent)/gsd:migrate-mcpwhen project and global configs have conflicting servers (same name, different config) — verify CONFLICT resolution prompt<mcp_check>block is present in all 11 agent.mdfilesgsd-executor) in a project with only project-scoped MCP — verify the pre-check catches itRegression Test Suite
Full test suite passes with no regressions:
Test suites include agent frontmatter validation (47 tests), anti-heredoc verification, spawn consistency checks, and command structure validation — all passing.
Impact
/gsd:migrate-mcp) resolves the issue.<mcp_check>block is a no-op when MCP tools are available. The command is opt-in.Future Considerations
/gsd:migrate-mcpbecomes 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 addmcpServers: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.Addresses: BUG-5 (Global MCP Migration Helper), MCP Connectivity Pre-Check
Upstream: Claude Code #13898