MCPcopy Create free account
hub / github.com/colbymchenry/codegraph / handleExplore

Method handleExplore

src/mcp/tools.ts:4455–8120  ·  view source on GitHub ↗

* Handle codegraph_explore — deep exploration in a single call * * Strategy: find relevant symbols via graph traversal, group by file, * then read contiguous file sections covering all symbols per file. * This replaces multiple codegraph_node + Read calls. * * Output size is adapti

(args: Record<string, unknown>)

Source from the content-addressed store, hash-verified

4453 * tax on small projects while earning its keep on large ones.
4454 */
4455 private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {
4456 const rawQuery = this.validateString(args.query, 'query');
4457 if (typeof rawQuery !== 'string') return rawQuery;
4458 // One normalization point so the flow-builder, relevance search, and
4459 // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
4460 const query = normalizeQuerySpelling(rawQuery);
4461
4462 const cg = this.getCodeGraph(args.projectPath as string | undefined);
4463 const projectRoot = cg.getProjectRoot();
4464
4465 // Resolve adaptive output budget from project size. Falls back to the
4466 // largest-tier defaults if stats aren't available, which preserves
4467 // pre-#185 behavior for callers that hit the rare stats failure.
4468 let budget: ExploreOutputBudget;
4469 let indexedFileCount = -1;
4470 let indexedNodeCount = -1;
4471 try {
4472 const stats = cg.getStats();
4473 indexedFileCount = stats.fileCount;
4474 indexedNodeCount = stats.nodeCount;
4475 budget = getExploreOutputBudget(indexedFileCount);
4476 } catch {
4477 budget = getExploreOutputBudget(Infinity);
4478 }
4479 const maxFiles = clamp((args.maxFiles as number) || budget.defaultMaxFiles, 1, 20);
4480
4481 // File paths named in the query become PINNED files: guaranteed admission,
4482 // top of the rank order, funded first — and their span is REMOVED from the
4483 // matching query. Runs on the RAW query (normalizeQuerySpelling strips
4484 // `/digits` tails, which would mangle numeric path segments). Without this,
4485 // a SvelteKit path like `runs/[runId]/+page.svelte` was shredded by the
4486 // seeding tokenizer (splits on brackets → `runId` seeded as a "named
4487 // symbol") and by FTS (`page`/`runs` fragments admitted every sibling
4488 // `+page.svelte`), starving the very files the agent asked for.
4489 let pinnedFiles: string[] = [];
4490 let unresolvedPathSpans: string[] = [];
4491 let lineAnchors: QueryLineAnchor[] = [];
4492 let setAsideMatches: QuerySetAsideMatch[] = [];
4493 let matchQuery = query;
4494 if (queryMightContainPaths(rawQuery)) {
4495 try {
4496 const extraction = extractQueryPaths(
4497 rawQuery,
4498 cg.getFiles().map((f) => f.path),
4499 {
4500 maxPins: maxFiles,
4501 existsOnDisk: (rel) => pathIsProjectFile(projectRoot, rel),
4502 symbolFiles: (symbol) => filesDefiningSymbol(cg, symbol),
4503 },
4504 );
4505 if (extraction.pinnedFiles.length > 0 || extraction.unresolvedPathSpans.length > 0) {
4506 pinnedFiles = extraction.pinnedFiles;
4507 unresolvedPathSpans = extraction.unresolvedPathSpans;
4508 lineAnchors = extraction.lineAnchors;
4509 setAsideMatches = extraction.setAsideMatches;
4510 matchQuery = normalizeQuerySpelling(extraction.strippedQuery);
4511 }
4512 } catch { /* path pinning must never fail an explore call */ }

Callers 1

dispatchToolMethod · 0.95

Calls 15

validateStringMethod · 0.95
getCodeGraphMethod · 0.95
exploreOneSymbolMethod · 0.95
textResultMethod · 0.95
findAllSymbolsMethod · 0.95
computeGraphRelevanceMethod · 0.95
buildCopybookSectionMethod · 0.95
isFileStaleOnDiskMethod · 0.95
isToolServedMethod · 0.95
answerResultMethod · 0.95

Tested by

no test coverage detected