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

Method handleExplore

src/mcp/tools.ts:4409–8064  ·  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

4407 * tax on small projects while earning its keep on large ones.
4408 */
4409 private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {
4410 const rawQuery = this.validateString(args.query, 'query');
4411 if (typeof rawQuery !== 'string') return rawQuery;
4412 // One normalization point so the flow-builder, relevance search, and
4413 // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
4414 const query = normalizeQuerySpelling(rawQuery);
4415
4416 const cg = this.getCodeGraph(args.projectPath as string | undefined);
4417 const projectRoot = cg.getProjectRoot();
4418
4419 // Resolve adaptive output budget from project size. Falls back to the
4420 // largest-tier defaults if stats aren't available, which preserves
4421 // pre-#185 behavior for callers that hit the rare stats failure.
4422 let budget: ExploreOutputBudget;
4423 let indexedFileCount = -1;
4424 let indexedNodeCount = -1;
4425 try {
4426 const stats = cg.getStats();
4427 indexedFileCount = stats.fileCount;
4428 indexedNodeCount = stats.nodeCount;
4429 budget = getExploreOutputBudget(indexedFileCount);
4430 } catch {
4431 budget = getExploreOutputBudget(Infinity);
4432 }
4433 const maxFiles = clamp((args.maxFiles as number) || budget.defaultMaxFiles, 1, 20);
4434
4435 // File paths named in the query become PINNED files: guaranteed admission,
4436 // top of the rank order, funded first — and their span is REMOVED from the
4437 // matching query. Runs on the RAW query (normalizeQuerySpelling strips
4438 // `/digits` tails, which would mangle numeric path segments). Without this,
4439 // a SvelteKit path like `runs/[runId]/+page.svelte` was shredded by the
4440 // seeding tokenizer (splits on brackets → `runId` seeded as a "named
4441 // symbol") and by FTS (`page`/`runs` fragments admitted every sibling
4442 // `+page.svelte`), starving the very files the agent asked for.
4443 let pinnedFiles: string[] = [];
4444 let unresolvedPathSpans: string[] = [];
4445 let lineAnchors: QueryLineAnchor[] = [];
4446 let setAsideMatches: QuerySetAsideMatch[] = [];
4447 let matchQuery = query;
4448 if (queryMightContainPaths(rawQuery)) {
4449 try {
4450 const extraction = extractQueryPaths(
4451 rawQuery,
4452 cg.getFiles().map((f) => f.path),
4453 {
4454 maxPins: maxFiles,
4455 existsOnDisk: (rel) => pathIsProjectFile(projectRoot, rel),
4456 symbolFiles: (symbol) => filesDefiningSymbol(cg, symbol),
4457 },
4458 );
4459 if (extraction.pinnedFiles.length > 0 || extraction.unresolvedPathSpans.length > 0) {
4460 pinnedFiles = extraction.pinnedFiles;
4461 unresolvedPathSpans = extraction.unresolvedPathSpans;
4462 lineAnchors = extraction.lineAnchors;
4463 setAsideMatches = extraction.setAsideMatches;
4464 matchQuery = normalizeQuerySpelling(extraction.strippedQuery);
4465 }
4466 } catch { /* path pinning must never fail an explore call */ }

Callers 1

dispatchToolMethod · 0.95

Calls 15

validateStringMethod · 0.95
getCodeGraphMethod · 0.95
textResultMethod · 0.95
findAllSymbolsMethod · 0.95
computeGraphRelevanceMethod · 0.95
buildCopybookSectionMethod · 0.95
isFileStaleOnDiskMethod · 0.95
isToolServedMethod · 0.95
answerResultMethod · 0.95
clampFunction · 0.90

Tested by

no test coverage detected