golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix(agents): add Context7 CLI fallback for MCP tools broken by tools: restriction (#2074)

Browse Source 
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
`<mcp_tool_usage>` block in gsd-executor and gsd-planner with a
`<documentation_lookup>` block that checks for MCP availability first, then
falls back to the Context7 CLI via Bash (`npx --yes ctx7@latest`). Adds the
same `<documentation_lookup>` block to the six researcher agents that declare
MCP tools but lacked any fallback instruction.

Agents fixed (8 total):
- gsd-executor (had <mcp_tool_usage>, now <documentation_lookup> with CLI fallback)
- gsd-planner (had <mcp_tool_usage>, now compact <documentation_lookup>; stays under 45K limit)
- gsd-phase-researcher (new <documentation_lookup> block)
- gsd-project-researcher (new <documentation_lookup> block)
- gsd-ui-researcher (new <documentation_lookup> block)
- gsd-advisor-researcher (new <documentation_lookup> block)
- gsd-ai-researcher (new <documentation_lookup> block)
- gsd-domain-researcher (new <documentation_lookup> 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 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-04-10 21:29:37 -04:00
committed by GitHub
parent cc04baa524
commit f8cf54bd01
8 changed files with 173 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
agents/gsd-advisor-researcher.md
View File

@@ -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
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<input>
Agent receives via prompt:

23
agents/gsd-ai-researcher.md
View File

@@ -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.
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<required_reading>
Read `~/.claude/get-shit-done/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs.
</required_reading>

23
agents/gsd-domain-researcher.md
View File

@@ -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.
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<required_reading>
Read `~/.claude/get-shit-done/references/ai-evals.md` — specifically the rubric design and domain expert sections.
</required_reading>

32
agents/gsd-executor.md
View File

@@ -22,12 +22,32 @@ Your job: Execute the plan completely, commit each task, create SUMMARY.md, upda
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
</role>
<mcp_tool_usage>
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.
</mcp_tool_usage>
<documentation_lookup>
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 <name> "<query>"
```
Example: `npx --yes ctx7@latest library react "useEffect hook"`
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
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.
</documentation_lookup>
<project_context>
Before executing, discover project context:

23
agents/gsd-phase-researcher.md
View File

@@ -34,6 +34,29 @@ If the prompt contains a `<files_to_read>` 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.
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<project_context>
Before researching, discover project context:

15
agents/gsd-planner.md
View File

@@ -35,12 +35,15 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
- Return structured results to orchestrator
</role>
<mcp_tool_usage>
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.
</mcp_tool_usage>
<documentation_lookup>
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 <name> "<query>" # resolve library ID
npx --yes ctx7@latest docs <libraryId> "<query>" # fetch docs
```
Do not skip — the CLI fallback works via Bash and produces equivalent output.
</documentation_lookup>
<project_context>
Before planning, discover project context:

23
agents/gsd-project-researcher.md
View File

@@ -32,6 +32,29 @@ Your files feed the roadmap:
**Be comprehensive but opinionated.** "Use X because Y" not "Options are X, Y, Z."
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<philosophy>
## Training Data = Hypothesis

23
agents/gsd-ui-researcher.md
View File

@@ -27,6 +27,29 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
- Return structured result to orchestrator
</role>
<documentation_lookup>
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 <name> "<query>"
```
Step 2 — Fetch documentation:
```bash
npx --yes ctx7@latest docs <libraryId> "<query>"
```
Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
works via Bash and produces equivalent output.
</documentation_lookup>
<project_context>
Before researching, discover project context: