feat(mcp): codedb_context — task-shaped composer (1 call replaces 3-5)#477
Conversation
Adds a new MCP tool that takes a natural-language task and returns ONE
tight bundle: extracted keywords + symbol definitions + ranked files +
top file:line snippets per file. Targets feature parity with
codegraph_context (the codegraph project's killer first-touch tool) on
per-call token economy.
How it works:
- Extract candidate identifiers from the task string. Heuristic admits
snake_case (any underscore), all-caps acronyms 3-8 chars (API, TODO),
and camelCase/PascalCase with an internal lower→upper transition
(useEffect, getNextLanes). Rejects sentence-leading English words
("Find", "React", "Want") that just happen to be capitalized.
- For each candidate (capped at 5): one findAllSymbols + one searchContent
call, both into a function-scoped arena so we don't track per-result
frees. Aggregate hits per file.
- Render: keywords block, symbol definitions block, top 5 files ranked
by total match count, then 3 file:line snippets per file.
Measured on 4 react bench tasks (T0-T3):
T0_getNextLanes 347 tok → correctly extracts `getNextLanes`,
top file ReactFiberRootScheduler.js
T1_setState_trace 689 tok → extracts setState, enqueueUpdate,
scheduleUpdateOnFiber
T2_snapshot_flag_sites 353 tok → renderRootSync + CompleteWork,
top file ReactFiberWorkLoop.js (11 hits)
T3_compare 629 tok → ensureRootIsScheduled + scheduleUpdateOnFiber
------
AVG ~505 tokens/call
vs ~1050 tokens/call observed for codegraph_context on the same corpus;
vs ~645 tokens/call for codedb_search default (single-keyword, no symbol
defs, no ranking).
For narrow follow-ups, codedb_search and codedb_symbol still win on
focus. codedb_context is the first-touch tool for unfamiliar territory.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68473734b6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| .codedb_query => handleQuery(alloc, args, out, ctx.explorer, ctx.store), | ||
| .codedb_glob => handleGlob(alloc, args, out, ctx.explorer), | ||
| .codedb_ls => handleLs(alloc, args, out, ctx.explorer), | ||
| .codedb_context => handleContext(alloc, args, out, ctx.explorer), |
There was a problem hiding this comment.
The new codedb_context path is dispatched here, but it is not included in toolDependsOnScannedIndex, so it skips the startup wait and also skips the incomplete-results hint logic. In the common "call immediately after server start" case, this tool can return partial/empty ranked files and snippets while presenting them as final output, which is a correctness regression compared with other index-backed tools. Please include codedb_context in the scan-dependent tool set so behavior matches codedb_search/codedb_symbol during initial indexing.
Useful? React with 👍 / 👎.
Benchmark Regression ReportThresholds: 10.00% and 50,000 ns absolute delta
|
1 participant
Summary
Adds a new MCP tool
codedb_contextthat takes a natural-language task and returns ONE composite block:findAllSymbolshits for each keywordfile:line snippetlinesThis is the codegraph-style "first-touch" tool — one call to orient on an unfamiliar task — but it composes only the engine primitives codedb already has, no new index structures.
Identifier extraction heuristic
Admits:
find_iter,pair_freqAPI,TODO,URLuseEffect,getNextLanes,scheduleUpdateOnFiberRejects sentence-leading capitalized English words (
Find,React,Want,Compare) that incidentally start with a capital but have no internal transition. Also accepts"…"and`…`quoted strings literally; apostrophes are deliberately NOT treated as quotes soit'sdoesn't open a fake quote.Capped at 5 keywords / 20 content hits per keyword / 5 ranked files / 3 snippets per file — bounded output, no pathological responses.
Measured tokens on the 4 react bench tasks
getNextLanessetState,enqueueUpdate,scheduleUpdateOnFiberrenderRootSync,CompleteWorkensureRootIsScheduled,scheduleUpdateOnFiberAverage: ≈505 tokens/call. For comparison, codegraph_context on the same corpus averaged ≈1050 tokens/call in the §17 shootout; codedb_search after PR #476 averages ≈645 tokens/call but returns a single flat search rather than a composed bundle.
When to pick each tool
codedb_context— first call on an unfamiliar task (composes search + symbols + ranking).codedb_search— narrow follow-up: "more matches for that one substring".codedb_symbol— exact-name definition lookup.codedb_callers— call-site walk after you know the symbol.The composer doesn't replace the focused tools; it replaces the 3-5 chained calls an agent would otherwise issue to bootstrap context.
Test plan
zig build(ReleaseFast) passeszig build test— 486/487 pass (1 pre-existing failure onmain:issue-44)codedb_search,codedb_word, etc.) — only adds an enum value + dispatch case + handler fn