From f8cf54bd01700ba4362e2d538663c79785403c3c Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 10 Apr 2026 21:29:37 -0400 Subject: [PATCH] fix(agents): add Context7 CLI fallback for MCP tools broken by tools: restriction (#2074) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #1885 The upstream bug anthropics/claude-code#13898 causes Claude Code to strip all inherited MCP tools from agents that declare a `tools:` frontmatter restriction, making `mcp__context7__*` declarations in agent frontmatter completely inert. Implements Fix 2 from issue #1885 (trek-e's chosen approach): replace the `` block in gsd-executor and gsd-planner with a `` block that checks for MCP availability first, then falls back to the Context7 CLI via Bash (`npx --yes ctx7@latest`). Adds the same `` block to the six researcher agents that declare MCP tools but lacked any fallback instruction. Agents fixed (8 total): - gsd-executor (had , now with CLI fallback) - gsd-planner (had , now compact ; stays under 45K limit) - gsd-phase-researcher (new block) - gsd-project-researcher (new block) - gsd-ui-researcher (new block) - gsd-advisor-researcher (new block) - gsd-ai-researcher (new block) - gsd-domain-researcher (new block) When the upstream Claude Code bug is fixed, the MCP path in step 1 of the block will become active automatically — no agent changes needed. Co-authored-by: Claude Sonnet 4.6 --- agents/gsd-advisor-researcher.md | 23 +++++++++++++++++++++++ agents/gsd-ai-researcher.md | 23 +++++++++++++++++++++++ agents/gsd-domain-researcher.md | 23 +++++++++++++++++++++++ agents/gsd-executor.md | 32 ++++++++++++++++++++++++++------ agents/gsd-phase-researcher.md | 23 +++++++++++++++++++++++ agents/gsd-planner.md | 15 +++++++++------ agents/gsd-project-researcher.md | 23 +++++++++++++++++++++++ agents/gsd-ui-researcher.md | 23 +++++++++++++++++++++++ 8 files changed, 173 insertions(+), 12 deletions(-) diff --git a/agents/gsd-advisor-researcher.md b/agents/gsd-advisor-researcher.md index cd3ef5885..0a7b27f9a 100644 --- a/agents/gsd-advisor-researcher.md +++ b/agents/gsd-advisor-researcher.md @@ -17,6 +17,29 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t - Return structured markdown output for the main agent to synthesize + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + Agent receives via prompt: diff --git a/agents/gsd-ai-researcher.md b/agents/gsd-ai-researcher.md index 74edf079f..aa2625540 100644 --- a/agents/gsd-ai-researcher.md +++ b/agents/gsd-ai-researcher.md @@ -16,6 +16,29 @@ You are a GSD AI researcher. Answer: "How do I correctly implement this AI syste Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation guidance, and AI systems best practices. + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + Read `~/.claude/get-shit-done/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs. diff --git a/agents/gsd-domain-researcher.md b/agents/gsd-domain-researcher.md index ac85ff8be..5c4245c89 100644 --- a/agents/gsd-domain-researcher.md +++ b/agents/gsd-domain-researcher.md @@ -16,6 +16,29 @@ You are a GSD domain researcher. Answer: "What do domain experts actually care a Research the business domain — not the technical framework. Write Section 1b of AI-SPEC.md. + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + Read `~/.claude/get-shit-done/references/ai-evals.md` — specifically the rubric design and domain expert sections. diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index 7fc58e8f8..de8a038ec 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -22,12 +22,32 @@ Your job: Execute the plan completely, commit each task, create SUMMARY.md, upda If the prompt contains a `` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context. - -Use all tools available in your environment, including MCP servers. If Context7 MCP -(`mcp__context7__*`) is available, use it for library documentation lookups instead of -relying on training knowledge. Do not skip MCP tools because they are not mentioned in -the task — use them when they are the right tool for the job. - + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Example: `npx --yes ctx7@latest library react "useEffect hook"` + + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + Example: `npx --yes ctx7@latest docs /facebook/react "useEffect hook"` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. Do not rely on training knowledge alone +for library APIs where version-specific behavior matters. + Before executing, discover project context: diff --git a/agents/gsd-phase-researcher.md b/agents/gsd-phase-researcher.md index 0c43f7949..c259a7ad3 100644 --- a/agents/gsd-phase-researcher.md +++ b/agents/gsd-phase-researcher.md @@ -34,6 +34,29 @@ If the prompt contains a `` block, you MUST use the `Read` tool t Claims tagged `[ASSUMED]` signal to the planner and discuss-phase that the information needs user confirmation before becoming a locked decision. Never present assumed knowledge as verified fact — especially for compliance requirements, retention policies, security standards, or performance targets where multiple valid approaches exist. + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + Before researching, discover project context: diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 1a2f16580..98a188a8f 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -35,12 +35,15 @@ If the prompt contains a `` block, you MUST use the `Read` tool t - Return structured results to orchestrator - -Use all tools available in your environment, including MCP servers. If Context7 MCP -(`mcp__context7__*`) is available, use it for library documentation lookups instead of -relying on training knowledge. Do not skip MCP tools because they are not mentioned in -the task — use them when they are the right tool for the job. - + +For library docs: use Context7 MCP (`mcp__context7__*`) if available. If not (upstream +bug #13898 strips MCP from `tools:`-restricted agents), use the Bash CLI fallback: +```bash +npx --yes ctx7@latest library "" # resolve library ID +npx --yes ctx7@latest docs "" # fetch docs +``` +Do not skip — the CLI fallback works via Bash and produces equivalent output. + Before planning, discover project context: diff --git a/agents/gsd-project-researcher.md b/agents/gsd-project-researcher.md index 809110ffe..d756455ce 100644 --- a/agents/gsd-project-researcher.md +++ b/agents/gsd-project-researcher.md @@ -32,6 +32,29 @@ Your files feed the roadmap: **Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z." + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + ## Training Data = Hypothesis diff --git a/agents/gsd-ui-researcher.md b/agents/gsd-ui-researcher.md index d82685e8a..afe2ecd9d 100644 --- a/agents/gsd-ui-researcher.md +++ b/agents/gsd-ui-researcher.md @@ -27,6 +27,29 @@ If the prompt contains a `` block, you MUST use the `Read` tool t - Return structured result to orchestrator + +When you need library or framework documentation, check in this order: + +1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them: + - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName` + - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic` + +2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP + tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash: + + Step 1 — Resolve library ID: + ```bash + npx --yes ctx7@latest library "" + ``` + Step 2 — Fetch documentation: + ```bash + npx --yes ctx7@latest docs "" + ``` + +Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback +works via Bash and produces equivalent output. + + Before researching, discover project context: