feat(mcp): lean output mode for search_documents (full | locations)#10
Merged
Conversation
…ions) Lean output slice 1: `locations` returns only file + line per match, dropping the (often paragraph-sized) matched text. Far more token-efficient — a small local model fits many more results in its context window, and it's a natural "which files mention X?" first pass before reading specific ones with get_document_context. Attacks the context-overflow problem from peekdocs's side rather than only via LM Studio settings. Design (per discussion): - Default is `full` (unchanged behavior); the model only sees less when a request explicitly asks for `locations`, and the tool description tells it to say so when it does — avoids "answered confidently from a partial picture". - `_match_dicts(matches, detail)` is the single chokepoint; unknown values fall back to full. - Truncation `note` now points at `detail=locations` as a way to fit more — gated by `_cap(..., detail_hint=True)` so it appears ONLY on search_documents (the tool that accepts the param), never on get_document_context / suite / collection notes (which would be an invent-a-param trap). Scope: search_documents only (MVP). `snippet` mode and suite/collection fan-out are deliberate follow-up slices. Tests: full-includes-text, locations-omits-text, unknown-falls-back, detail-hint-gating. Docs: USER_GUIDE Tools row + "want to see more" third lever; LOCAL_AI_SETUP overflow troubleshooting (c); CHANGELOG. No version bump. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Robert D. Schoening <bobschoening@gmail.com>
exbuf
force-pushed
the
feat/mcp-lean-output
branch
from
July 20, 2026 21:04
1ff07cc to
9d9713c
Compare
exbuf
marked this pull request as ready for review
July 20, 2026 21:09
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.
What
Adds a
detailoutput mode to the MCPsearch_documentstool. Slice 1 of the "lean output" idea discussed in-session.full(default) — unchanged: each match returns{file, line, text}.locations— returns only{file, line}, dropping the (often paragraph-sized) matched text.Why
Directly addresses the context-overflow we hit while testing the local stack: on a paragraph-heavy corpus, 25 full matches + tool definitions overflowed an 8192-token window even at
--max-results 25.locationsattacks it from peekdocs's side — a small local model fits far more results — and enables a clean two-phase pattern: broadlocationssweep → read the few that matter withget_document_context.Design choices (per discussion)
full— the model only sees less when a request explicitly asks forlocations. The tool description tells it to say so when it does, to avoid "answered confidently from a partial picture."detail=locations— but only onsearch_documents(gated via_cap(..., detail_hint=True)), so the note never suggests a param the other tools don't accept._match_dictsis the single chokepoint; unknowndetailvalues fall back tofull.Scope
search_documentsonly (MVP). Deliberate follow-up slices:snippetmode (centered window; needs term relocation + fuzzy fallback) and threadingdetailintorun_search_suite/run_regex_collection.Verification
TestDetailModes+detail_hintgating test.detailconfirmed present in the live tool schema.Docs
CHANGELOG (Unreleased), USER_GUIDE (Tools row + "want to see more" third lever), LOCAL_AI_SETUP (overflow troubleshooting option c).
🤖 Generated with Claude Code