Repository navigation
[AI-1271] MCP tool discoverability — route why/history/prior-work intents to the kcap tools - #319
Merged
Merged
Conversation
…nts to the kcap tools Registration alone didn't make agents USE the kcap tools — "review this PR" went to native GitHub/git, "have we done X" went to grep. This sharpens the one lever that reaches every MCP client identically (the per-tool descriptions from tools/list) plus the server-level instructions preamble. - Entrypoint tool descriptions get a comparative routing cue naming the native alternative to beat + the unique value kcap adds (still complementary to the diff, never a replacement): - kcap-review get_pr_summary / get_file_context / search_context → "before git blame or git log" - kcap-sessions search_sessions → "before grepping the code or git log" - kcap-memory search_memories → "before assuming there's no prior art" Drill-down tools (list_pr_files, list_turns, get_turn, …) are left unchanged. - Add the optional server-level `instructions` field to McpInitResult (camelCase, omitted-when-null); kcap-review / kcap-sessions / kcap-memory return a one-paragraph usage preamble on initialize. kcap-flows (and every other server) return none — its defensive posture is intentional (no extra routing to a paid hosted reviewer). - Fill the missing kcap-sessions description in both the canonical KcapMcpServers list and the bundled kcap/.mcp.json (kept Claude-.mcp.json-only; routing rides on tools/list, so the writer is not threaded). Tests: integration handshake asserts non-empty `instructions` + the entrypoint routing-cue markers for review/sessions/memory (new McpMemoryServerTests) and that kcap-flows returns no instructions; a contract test pins that every canonical server + every bundled .mcp.json entry has a description so the gap can't reopen. Full suite green (1 unrelated pre-existing turn-buffer flake, passes in isolation). Spec: docs/superpowers/specs/2026-07-08-mcp-tool-discoverability-design.md (kcap-server). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
PR Summary by QodoMCP tool discoverability: add routing cues + server-level instructions
AI Description
Diagram
High-Level Assessment
Files changed (10)
|
Code Review by Qodo
Context used 1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Repo rule (PR Compliance ID 4) forbids Linear IDs in source comments. Removed the AI-1271 references from the MCP handshake/contract test comments, keeping the durable rationale. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
2 participants
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
Registration ≠ routing. The kcap MCP servers are wired across harnesses, but agents still reach for native tools — "review this PR" → GitHub/
git blame, "have we done X" → grep. This sharpens the one lever that reaches every MCP client identically (per-tooldescriptionfromtools/list) plus the server-levelinstructionspreamble. Implements AI-1271.Changes
kcap-reviewget_pr_summary/get_file_context/search_context→ "before git blame or git log … which commits and diffs don't capture; still read the diff for correctness"kcap-sessionssearch_sessions→ "before grepping the code or git log — searches the reasoning across past sessions"kcap-memorysearch_memories→ "before assuming there's no prior art"list_pr_files,list_turns,get_turn,get_transcript, …) unchanged — they're reached only after an entrypoint already selected kcap.instructions— added optionalstring? InstructionstoMcpInitResult(camelCase, omitted-when-null via the existing source-gen options).kcap-review/kcap-sessions/kcap-memoryreturn a one-paragraph usage preamble oninitialize.kcap-flowsreturns none — its defensive posture is intentional (no extra routing to a paid hosted reviewer).kcap-sessionsdescription filled in both the canonicalKcapMcpServerslist and the bundledkcap/.mcp.json. Kept Claude-.mcp.json-only (routing rides ontools/list, soJsonMcpConfigWriteris not threaded — a conscious §3 decision).Why this reaches Claude (and every harness)
These live in the MCP servers and are answered over JSON-RPC, so the exact same text lands on every client that launches the server — Claude, Cursor, Codex, Gemini, Kiro, OpenCode, Pi — with no per-harness code. (The
*-instructions.mdsteering files we added earlier only reach the JSON harnesses; Claude doesn't read them.)Testing
kcap mcp review|sessions|memory|flows): asserts non-emptyinstructionsfor review/sessions/memory, absent for flows, and the entrypoint routing-cue marker substrings ontools/list(newMcpMemoryServerTests). Hard-gate so a future edit can't silently drop a cue.KcapMcpServerand every bundled.mcp.jsonentry must carry a description — so thekcap-sessionsgap can't reopen.Spec:
docs/superpowers/specs/2026-07-08-mcp-tool-discoverability-design.md(kcap-server).🤖 Generated with Claude Code