/**

* MCP Tool Definitions

*

* Defines the tools exposed by the CodeGraph MCP server.

*/

import CodeGraph, { findNearestCodeGraphRoot } from '../index';

import type { Node, Edge, SearchResult, Subgraph, TaskContext, NodeKind } from '../types';

import { createHash } from 'crypto';

import { writeFileSync, readFileSync, existsSync } from 'fs';

import { clamp, validatePathWithinRoot } from '../utils';

import { tmpdir } from 'os';

import { join } from 'path';

/** Maximum output length to prevent context bloat (characters) */

const MAX_OUTPUT_LENGTH = 15000;

/**

* Calculate the recommended number of codegraph_explore calls based on project size.

* Larger codebases need more exploration calls to cover their surface area,

* but smaller ones should use fewer to avoid unnecessary overhead.

*/

export function getExploreBudget(fileCount: number): number {

if (fileCount < 500) return 1;

if (fileCount < 5000) return 2;

if (fileCount < 15000) return 3;

if (fileCount < 25000) return 4;

return 5;

}

/**

* Mark a Claude session as having consulted MCP tools.

* This enables Grep/Glob/Bash commands that would otherwise be blocked.

*/

function markSessionConsulted(sessionId: string): void {

try {

const hash = createHash('md5').update(sessionId).digest('hex').slice(0, 16);

const markerPath = join(tmpdir(), `codegraph-consulted-${hash}`);

writeFileSync(markerPath, new Date().toISOString(), 'utf8');

} catch {

// Silently fail - don't break MCP on marker write failure

}

}

/**

* MCP Tool definition

*/

export interface ToolDefinition {

name: string;

description: string;

inputSchema: {

type: 'object';

properties: Record<string, PropertySchema>;

required?: string[];

};

}

interface PropertySchema {

type: string;

description: string;

enum?: string[];

default?: unknown;

}

/**

* Tool execution result

*/

export interface ToolResult {

content: Array<{

type: 'text';

text: string;

}>;

isError?: boolean;

}

/**

* Common projectPath property for cross-project queries

*/

const projectPathProperty: PropertySchema = {

type: 'string',

description: 'Path to a different project with .codegraph/ initialized. If omitted, uses current project. Use this to query other codebases.',

};

/**

* All CodeGraph MCP tools

*

* Designed for minimal context usage - use codegraph_context as the primary tool,

* and only use other tools for targeted follow-up queries.

*

* All tools support cross-project queries via the optional `projectPath` parameter.

*/

export const tools: ToolDefinition[] = [

{

name: 'codegraph_search',

description: 'Quick symbol search by name. Returns locations only (no code). Use codegraph_context instead for comprehensive task context.',

inputSchema: {

type: 'object',

properties: {

query: {

type: 'string',

description: 'Symbol name or partial name (e.g., "auth", "signIn", "UserService")',

},

kind: {

type: 'string',

description: 'Filter by node kind',

enum: ['function', 'method', 'class', 'interface', 'type', 'variable', 'route', 'component'],

},

limit: {

type: 'number',

description: 'Maximum results (default: 10)',

default: 10,

},

projectPath: projectPathProperty,

},

required: ['query'],

},

},

{

name: 'codegraph_context',

description: 'PRIMARY TOOL: Build comprehensive context for a task. Returns entry points, related symbols, and key code - often enough to understand the codebase without additional tool calls. NOTE: This provides CODE context, not product requirements. For new features, still clarify UX/behavior questions with the user before implementing.',

inputSchema: {

type: 'object',

properties: {

task: {

type: 'string',

description: 'Description of the task, bug, or feature to build context for',

},

maxNodes: {

type: 'number',

description: 'Maximum symbols to include (default: 20)',

default: 20,

},

includeCode: {

type: 'boolean',

description: 'Include code snippets for key symbols (default: true)',

default: true,

},

projectPath: projectPathProperty,

},

required: ['task'],

},

},

{

name: 'codegraph_callers',

description: 'Find all functions/methods that call a specific symbol. Useful for understanding usage patterns and impact of changes.',

inputSchema: {

type: 'object',

properties: {

symbol: {

type: 'string',

description: 'Name of the function, method, or class to find callers for',

},

limit: {

type: 'number',

description: 'Maximum number of callers to return (default: 20)',

default: 20,

},

projectPath: projectPathProperty,

},

required: ['symbol'],

},

},

{

name: 'codegraph_callees',

description: 'Find all functions/methods that a specific symbol calls. Useful for understanding dependencies and code flow.',

inputSchema: {

type: 'object',

properties: {

symbol: {

type: 'string',

description: 'Name of the function, method, or class to find callees for',

},

limit: {

type: 'number',

description: 'Maximum number of callees to return (default: 20)',

default: 20,

},

projectPath: projectPathProperty,

},

required: ['symbol'],

},

},

{

name: 'codegraph_impact',

description: 'Analyze the impact radius of changing a symbol. Shows what code could be affected by modifications.',

inputSchema: {

type: 'object',

properties: {

symbol: {

type: 'string',

description: 'Name of the symbol to analyze impact for',

},

depth: {

type: 'number',

description: 'How many levels of dependencies to traverse (default: 2)',

default: 2,

},

projectPath: projectPathProperty,

},

required: ['symbol'],

},

},

{

name: 'codegraph_node',

description: 'Get detailed information about a specific code symbol. Use includeCode=true only when you need the full source code - otherwise just get location and signature to minimize context usage.',

inputSchema: {

type: 'object',

properties: {

symbol: {

type: 'string',

description: 'Name of the symbol to get details for',

},

includeCode: {

type: 'boolean',

description: 'Include full source code (default: false to minimize context)',

default: false,

},

projectPath: projectPathProperty,

},

required: ['symbol'],

},

},

{

name: 'codegraph_explore',

description: 'Deep exploration tool — returns comprehensive context for a topic in a SINGLE call. Groups all relevant source code by file (contiguous sections, not snippets), includes a relationship map, and uses deeper graph traversal. Designed to replace multiple codegraph_node + file Read calls. Use this instead of codegraph_context when you need thorough understanding. IMPORTANT: Use specific symbol names, file names, or short code terms in your query — NOT natural language sentences. Before calling this, use codegraph_search to discover relevant symbol names, then include those names in your query. Bad: "how are agent prompts loaded and passed to the CLI". Good: "readAgentsFromDirectory createClaudeSession chat-manager agents.ts".',

inputSchema: {

type: 'object',

properties: {

query: {

type: 'string',

description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). Use codegraph_search first to find relevant names.',

},

maxFiles: {

type: 'number',

description: 'Maximum number of files to include source code from (default: 12)',

default: 12,

},

projectPath: projectPathProperty,

},

required: ['query'],

},

},

{

name: 'codegraph_status',

description: 'Get the status of the CodeGraph index, including statistics about indexed files, nodes, and edges.',

inputSchema: {

type: 'object',

properties: {

projectPath: projectPathProperty,

},

},

},

{

name: 'codegraph_files',

description: 'REQUIRED for file/folder exploration. Get the project file structure from the CodeGraph index. Returns a tree view of all indexed files with metadata (language, symbol count). Much faster than Glob/filesystem scanning. Use this FIRST when exploring project structure, finding files, or understanding codebase organization.',

inputSchema: {

type: 'object',

properties: {

path: {

type: 'string',

description: 'Filter to files under this directory path (e.g., "src/components"). Returns all files if not specified.',

},

pattern: {

type: 'string',

description: 'Filter files matching this glob pattern (e.g., "*.tsx", "**/*.test.ts")',

},

format: {

type: 'string',

description: 'Output format: "tree" (hierarchical, default), "flat" (simple list), "grouped" (by language)',

enum: ['tree', 'flat', 'grouped'],

default: 'tree',

},

includeMetadata: {

type: 'boolean',

description: 'Include file metadata like language and symbol count (default: true)',

default: true,

},

maxDepth: {

type: 'number',

description: 'Maximum directory depth to show (default: unlimited)',

},

projectPath: projectPathProperty,

},

},

},

];

/**

* Tool handler that executes tools against a CodeGraph instance

*

* Supports cross-project queries via the projectPath parameter.

* Other projects are opened on-demand and cached for performance.

*/

export class ToolHandler {

// Cache of opened CodeGraph instances for cross-project queries

private projectCache: Map<string, CodeGraph> = new Map();

constructor(private cg: CodeGraph | null) {}

/**

* Update the default CodeGraph instance (e.g. after lazy initialization)

*/

setDefaultCodeGraph(cg: CodeGraph): void {

this.cg = cg;

}

/**

* Whether a default CodeGraph instance is available

*/

hasDefaultCodeGraph(): boolean {

return this.cg !== null;

}

/**

* Get tool definitions with dynamic descriptions based on project size.

* The codegraph_explore tool description includes a budget recommendation

* scaled to the number of indexed files.

*/

getTools(): ToolDefinition[] {

if (!this.cg) return tools;

try {

const stats = this.cg.getStats();

const budget = getExploreBudget(stats.fileCount);

return tools.map(tool => {

if (tool.name === 'codegraph_explore') {

return {

...tool,

description: `${tool.description} Budget: make at most ${budget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).`,

};

}

return tool;

});

} catch {

return tools;

}

}

/**

* Get CodeGraph instance for a project

*

* If projectPath is provided, opens that project's CodeGraph (cached).

* Otherwise returns the default CodeGraph instance.

*

* Walks up parent directories to find the nearest .codegraph/ folder,

* similar to how git finds .git/ directories.

*/

private getCodeGraph(projectPath?: string): CodeGraph {

if (!projectPath) {

if (!this.cg) {

throw new Error('CodeGraph not initialized for this project. Run \'codegraph init\' first.');

}

return this.cg;

}

// Check cache first (using original path as key)

if (this.projectCache.has(projectPath)) {

return this.projectCache.get(projectPath)!;

}

// Walk up parent directories to find nearest .codegraph/

const resolvedRoot = findNearestCodeGraphRoot(projectPath);

if (!resolvedRoot) {

throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);

}

// Check if we already have this resolved root cached (different path, same project)

if (this.projectCache.has(resolvedRoot)) {

const cg = this.projectCache.get(resolvedRoot)!;

// Cache under original path too for faster future lookups

this.projectCache.set(projectPath, cg);

return cg;

}

// Open and cache under both paths

const cg = CodeGraph.openSync(resolvedRoot);

this.projectCache.set(resolvedRoot, cg);

if (projectPath !== resolvedRoot) {

this.projectCache.set(projectPath, cg);

}

return cg;

}

/**

* Close all cached project connections

*/

closeAll(): void {

for (const cg of this.projectCache.values()) {

cg.close();

}

this.projectCache.clear();

}

/**

* Validate that a value is a non-empty string

*/

private validateString(value: unknown, name: string): string | ToolResult {

if (typeof value !== 'string' || value.length === 0) {

return this.errorResult(`${name} must be a non-empty string`);

}

return value;

}

/**

* Execute a tool by name

*/

async execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult> {

try {

switch (toolName) {

case 'codegraph_search':

return await this.handleSearch(args);

case 'codegraph_context':

return await this.handleContext(args);

case 'codegraph_callers':

return await this.handleCallers(args);

case 'codegraph_callees':

return await this.handleCallees(args);

case 'codegraph_impact':

return await this.handleImpact(args);

case 'codegraph_explore':

return await this.handleExplore(args);

case 'codegraph_node':

return await this.handleNode(args);

case 'codegraph_status':

return await this.handleStatus(args);

case 'codegraph_files':

return await this.handleFiles(args);

default:

return this.errorResult(`Unknown tool: ${toolName}`);

}

} catch (err) {

return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);

}

}

/**

* Handle codegraph_search

*/

private async handleSearch(args: Record<string, unknown>): Promise<ToolResult> {

const query = this.validateString(args.query, 'query');

if (typeof query !== 'string') return query;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const kind = args.kind as string | undefined;

const rawLimit = Number(args.limit) || 10;

const limit = clamp(rawLimit, 1, 100);

const results = cg.searchNodes(query, {

limit,

kinds: kind ? [kind as NodeKind] : undefined,

});

if (results.length === 0) {

return this.textResult(`No results found for "${query}"`);

}

const formatted = this.formatSearchResults(results);

return this.textResult(this.truncateOutput(formatted));

}

/**

* Handle codegraph_context

*/

private async handleContext(args: Record<string, unknown>): Promise<ToolResult> {

const task = this.validateString(args.task, 'task');

if (typeof task !== 'string') return task;

// Mark session as consulted (enables Grep/Glob/Bash)

const sessionId = process.env.CLAUDE_SESSION_ID;

if (sessionId) {

markSessionConsulted(sessionId);

}

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const maxNodes = (args.maxNodes as number) || 20;

const includeCode = args.includeCode !== false;

const context = await cg.buildContext(task, {

maxNodes,

includeCode,

format: 'markdown',

});

// Detect if this looks like a feature request (vs bug fix or exploration)

const isFeatureQuery = this.looksLikeFeatureRequest(task);

const reminder = isFeatureQuery

? '\n\n⚠️ **Ask user:** UX preferences, edge cases, acceptance criteria'

: '';

// buildContext returns string when format is 'markdown'

if (typeof context === 'string') {

return this.textResult(context + reminder);

}

// If it returns TaskContext, format it

return this.textResult(this.formatTaskContext(context) + reminder);

}

/**

* Heuristic to detect if a query looks like a feature request

*/

private looksLikeFeatureRequest(task: string): boolean {

const featureKeywords = [

'add', 'create', 'implement', 'build', 'enable', 'allow',

'new feature', 'support for', 'ability to', 'want to',

'should be able', 'need to add', 'swap', 'edit', 'modify'

];

const bugKeywords = [

'fix', 'bug', 'error', 'broken', 'crash', 'issue', 'problem',

'not working', 'fails', 'undefined', 'null'

];

const explorationKeywords = [

'how does', 'where is', 'what is', 'find', 'show me',

'explain', 'understand', 'explore'

];

const lowerTask = task.toLowerCase();

// If it's clearly a bug or exploration, not a feature

if (bugKeywords.some(k => lowerTask.includes(k))) return false;

if (explorationKeywords.some(k => lowerTask.includes(k))) return false;

// If it matches feature keywords, it's likely a feature request

return featureKeywords.some(k => lowerTask.includes(k));

}

/**

* Handle codegraph_callers

*/

private async handleCallers(args: Record<string, unknown>): Promise<ToolResult> {

const symbol = this.validateString(args.symbol, 'symbol');

if (typeof symbol !== 'string') return symbol;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const limit = clamp((args.limit as number) || 20, 1, 100);

const allMatches = this.findAllSymbols(cg, symbol);

if (allMatches.nodes.length === 0) {

return this.textResult(`Symbol "${symbol}" not found in the codebase`);

}

// Aggregate callers across all matching symbols

const seen = new Set<string>();

const allCallers: Node[] = [];

for (const node of allMatches.nodes) {

for (const c of cg.getCallers(node.id)) {

if (!seen.has(c.node.id)) {

seen.add(c.node.id);

allCallers.push(c.node);

}

}

}

if (allCallers.length === 0) {

return this.textResult(`No callers found for "${symbol}"${allMatches.note}`);

}

const formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;

return this.textResult(this.truncateOutput(formatted));

}

/**

* Handle codegraph_callees

*/

private async handleCallees(args: Record<string, unknown>): Promise<ToolResult> {

const symbol = this.validateString(args.symbol, 'symbol');

if (typeof symbol !== 'string') return symbol;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const limit = clamp((args.limit as number) || 20, 1, 100);

const allMatches = this.findAllSymbols(cg, symbol);

if (allMatches.nodes.length === 0) {

return this.textResult(`Symbol "${symbol}" not found in the codebase`);

}

// Aggregate callees across all matching symbols

const seen = new Set<string>();

const allCallees: Node[] = [];

for (const node of allMatches.nodes) {

for (const c of cg.getCallees(node.id)) {

if (!seen.has(c.node.id)) {

seen.add(c.node.id);

allCallees.push(c.node);

}

}

}

if (allCallees.length === 0) {

return this.textResult(`No callees found for "${symbol}"${allMatches.note}`);

}

const formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;

return this.textResult(this.truncateOutput(formatted));

}

/**

* Handle codegraph_impact

*/

private async handleImpact(args: Record<string, unknown>): Promise<ToolResult> {

const symbol = this.validateString(args.symbol, 'symbol');

if (typeof symbol !== 'string') return symbol;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const depth = clamp((args.depth as number) || 2, 1, 10);

const allMatches = this.findAllSymbols(cg, symbol);

if (allMatches.nodes.length === 0) {

return this.textResult(`Symbol "${symbol}" not found in the codebase`);

}

// Aggregate impact across all matching symbols

const mergedNodes = new Map<string, Node>();

const mergedEdges: Edge[] = [];

const seenEdges = new Set<string>();

for (const node of allMatches.nodes) {

const impact = cg.getImpactRadius(node.id, depth);

for (const [id, n] of impact.nodes) {

mergedNodes.set(id, n);

}

for (const e of impact.edges) {

const key = `${e.source}->${e.target}:${e.kind}`;

if (!seenEdges.has(key)) {

seenEdges.add(key);

mergedEdges.push(e);

}

}

}

const mergedImpact = {

nodes: mergedNodes,

edges: mergedEdges,

roots: allMatches.nodes.map(n => n.id),

};

const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;

return this.textResult(this.truncateOutput(formatted));

}

/** Maximum output for explore tool — sized to stay under MCP client token limits (~10k tokens) */

private static readonly EXPLORE_MAX_OUTPUT = 35000;

/**

* 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.

*/

private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {

const query = this.validateString(args.query, 'query');

if (typeof query !== 'string') return query;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const maxFiles = clamp((args.maxFiles as number) || 12, 1, 20);

const projectRoot = cg.getProjectRoot();

// Step 1: Find relevant context with generous parameters.

// Use a large maxNodes budget — explore has its own 35k char output limit

// that prevents context bloat, so more nodes just means better coverage

// across entry points (especially for large files like Svelte components).

const subgraph = await cg.findRelevantContext(query, {

searchLimit: 8,

traversalDepth: 3,

maxNodes: 200,

minScore: 0.2,

});

if (subgraph.nodes.size === 0) {

return this.textResult(`No relevant code found for "${query}"`);

}

// Step 2: Group nodes by file, score by relevance

const fileGroups = new Map<string, { nodes: Node[]; score: number }>();

const entryNodeIds = new Set(subgraph.roots);

// Build a set of nodes directly connected to entry points (depth 1)

const connectedToEntry = new Set<string>();

for (const edge of subgraph.edges) {

if (entryNodeIds.has(edge.source)) connectedToEntry.add(edge.target);

if (entryNodeIds.has(edge.target)) connectedToEntry.add(edge.source);

}

for (const node of subgraph.nodes.values()) {

// Skip import/export nodes — they add noise without information

if (node.kind === 'import' || node.kind === 'export') continue;

const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };

group.nodes.push(node);

// Score: entry point nodes worth 10, directly connected worth 3, others worth 1

if (entryNodeIds.has(node.id)) {

group.score += 10;

} else if (connectedToEntry.has(node.id)) {

group.score += 3;

} else {

group.score += 1;

}

fileGroups.set(node.filePath, group);

}

// Only include files that have entry points or nodes directly connected to entry points

const relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);

// Extract query terms for relevance checking

const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length >= 3);

// Sort files: highest relevance first, deprioritize low-value files

const sortedFiles = relevantFiles.sort((a, b) => {

const aPath = a[0].toLowerCase();

const bPath = b[0].toLowerCase();

// Check if any node name or file path relates to query terms

const hasQueryRelevance = (filePath: string, nodes: Node[]) => {

const fp = filePath.toLowerCase();

if (queryTerms.some(t => fp.includes(t))) return true;

return nodes.some(n => queryTerms.some(t => n.name.toLowerCase().includes(t)));

};

const aRelevant = hasQueryRelevance(aPath, a[1].nodes);

const bRelevant = hasQueryRelevance(bPath, b[1].nodes);

if (aRelevant !== bRelevant) return aRelevant ? -1 : 1;

// Deprioritize test files, icon files, and i18n files

const isLowValue = (p: string) =>

/\/(tests?|__tests?__|spec)\//i.test(p) ||

/\bicons?\b/i.test(p) ||

/\bi18n\b/i.test(p);

const aLow = isLowValue(aPath);

const bLow = isLowValue(bPath);

if (aLow !== bLow) return aLow ? 1 : -1;

if (a[1].score !== b[1].score) return b[1].score - a[1].score;

return b[1].nodes.length - a[1].nodes.length;

});

// Step 3: Build relationship map

const lines: string[] = [

`## Exploration: ${query}`,

'',

`Found ${subgraph.nodes.size} symbols across ${fileGroups.size} files.`,

'',

];

// Relationship map — show how symbols connect

const significantEdges = subgraph.edges.filter(e =>

e.kind !== 'contains' // skip contains — it's implied by file grouping

);

if (significantEdges.length > 0) {

lines.push('### Relationships');

lines.push('');

// Group edges by kind for readability

const byKind = new Map<string, Array<{ source: string; target: string }>>();

for (const edge of significantEdges) {

const sourceNode = subgraph.nodes.get(edge.source);

const targetNode = subgraph.nodes.get(edge.target);

if (!sourceNode || !targetNode) continue;

const group = byKind.get(edge.kind) || [];

group.push({ source: sourceNode.name, target: targetNode.name });

byKind.set(edge.kind, group);

}

for (const [kind, edges] of byKind) {

// Show up to 15 relationships per kind

const shown = edges.slice(0, 15);

lines.push(`**${kind}:**`);

for (const e of shown) {

lines.push(`- ${e.source} → ${e.target}`);

}

if (edges.length > 15) {

lines.push(`- ... and ${edges.length - 15} more`);

}

lines.push('');

}

}

// Step 4: Read contiguous file sections

lines.push('### Source Code');

lines.push('');

let totalChars = lines.join('\n').length;

let filesIncluded = 0;

for (const [filePath, group] of sortedFiles) {

if (filesIncluded >= maxFiles) break;

if (totalChars > ToolHandler.EXPLORE_MAX_OUTPUT * 0.9) break;

const absPath = validatePathWithinRoot(projectRoot, filePath);

if (!absPath || !existsSync(absPath)) continue;

let fileContent: string;

try {

fileContent = readFileSync(absPath, 'utf-8');

} catch {

continue;

}

const fileLines = fileContent.split('\n');

const lang = group.nodes[0]?.language || '';

// Cluster nearby symbols to avoid reading huge gaps between distant symbols.

// Sort by start line, then merge overlapping/adjacent ranges (within 15 lines).

// Include both node ranges AND edge source locations so template sections

// with component usages/calls are covered (not just script block symbols).

const ranges: Array<{ start: number; end: number; name: string; kind: string }> = group.nodes

.filter(n => n.startLine > 0 && n.endLine > 0)

// Skip file/component nodes that span the entire file — they'd create one giant cluster

.filter(n => !(n.kind === 'component' && n.startLine === 1 && n.endLine >= fileLines.length - 1))

.map(n => ({ start: n.startLine, end: n.endLine, name: n.name, kind: n.kind }));

// Add edge source locations in this file — captures template references

// (component usages, event handlers) that aren't nodes themselves.

// Query edges directly from the DB (not just the subgraph) because BFS

// traversal may have pruned template reference targets due to node budget.

const edgeLines = new Set<string>(); // dedup by "line:name"

for (const node of group.nodes) {

const outgoing = cg.getOutgoingEdges(node.id);

for (const edge of outgoing) {

if (!edge.line || edge.line <= 0 || edge.kind === 'contains') continue;

const key = `${edge.line}:${edge.target}`;

if (edgeLines.has(key)) continue;

edgeLines.add(key);

// Look up target name from subgraph first, fall back to edge kind

const targetNode = subgraph.nodes.get(edge.target);

const targetName = targetNode?.name ?? edge.kind;

ranges.push({ start: edge.line, end: edge.line, name: targetName, kind: edge.kind });

}

}

ranges.sort((a, b) => a.start - b.start);

if (ranges.length === 0) continue;

const GAP_THRESHOLD = 15; // merge sections within 15 lines of each other

const clusters: Array<{ start: number; end: number; symbols: string[] }> = [];

let current = { start: ranges[0]!.start, end: ranges[0]!.end, symbols: [`${ranges[0]!.name}(${ranges[0]!.kind})`] };

for (let i = 1; i < ranges.length; i++) {

const r = ranges[i]!;

if (r.start <= current.end + GAP_THRESHOLD) {

current.end = Math.max(current.end, r.end);

current.symbols.push(`${r.name}(${r.kind})`);

} else {

clusters.push(current);

current = { start: r.start, end: r.end, symbols: [`${r.name}(${r.kind})`] };

}

}

clusters.push(current);

// Build file section output from clusters

const contextPadding = 3;

let fileSection = '';

const allSymbols: string[] = [];

for (const cluster of clusters) {

const startIdx = Math.max(0, cluster.start - 1 - contextPadding);

const endIdx = Math.min(fileLines.length, cluster.end + contextPadding);

const section = fileLines.slice(startIdx, endIdx).join('\n');

if (fileSection.length > 0) {

fileSection += '\n\n// ... (gap) ...\n\n';

}

fileSection += section;

allSymbols.push(...cluster.symbols);

}

// Skip if this section would blow the output limit

if (totalChars + fileSection.length + 200 > ToolHandler.EXPLORE_MAX_OUTPUT) {

const budget = ToolHandler.EXPLORE_MAX_OUTPUT - totalChars - 200;

if (budget < 500) break;

const trimmed = fileSection.slice(0, budget) + '\n// ... trimmed ...';

lines.push(`#### ${filePath} — ${allSymbols.join(', ')}`);

lines.push('');

lines.push('```' + lang);

lines.push(trimmed);

lines.push('```');

lines.push('');

totalChars += trimmed.length + 200;

filesIncluded++;

break;

}

lines.push(`#### ${filePath} — ${allSymbols.join(', ')}`);

lines.push('');

lines.push('```' + lang);

lines.push(fileSection);

lines.push('```');

lines.push('');

totalChars += fileSection.length + 200;

filesIncluded++;

}

// Add remaining files as references (from both relevant and peripheral files)

const remainingRelevant = sortedFiles.slice(filesIncluded);

const peripheralFiles = [...fileGroups.entries()]

.filter(([, group]) => group.score < 3)

.sort((a, b) => b[1].score - a[1].score);

const remainingFiles = [...remainingRelevant, ...peripheralFiles];

if (remainingFiles.length > 0) {

lines.push('### Additional relevant files (not shown)');

lines.push('');

for (const [filePath, group] of remainingFiles.slice(0, 10)) {

const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');

lines.push(`- ${filePath}: ${symbols}`);

}

if (remainingFiles.length > 10) {

lines.push(`- ... and ${remainingFiles.length - 10} more files`);

}

}

// Add completeness signal so agents know they don't need to re-read these files

lines.push('');

lines.push('---');

lines.push(`> **Complete source code is included above for ${filesIncluded} files.** You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);

// Add explore budget note based on project size

try {

const stats = cg.getStats();

const budget = getExploreBudget(stats.fileCount);

lines.push('');

lines.push(`> **Explore budget: ${budget} calls max for this project (${stats.fileCount.toLocaleString()} files indexed).** Stop exploring and synthesize your answer once you've used ${budget} calls — do NOT make additional explore calls beyond this budget.`);

} catch {

// Stats unavailable — skip budget note

}

return this.textResult(lines.join('\n'));

}

/**

* Handle codegraph_node

*/

private async handleNode(args: Record<string, unknown>): Promise<ToolResult> {

const symbol = this.validateString(args.symbol, 'symbol');

if (typeof symbol !== 'string') return symbol;

const cg = this.getCodeGraph(args.projectPath as string | undefined);

// Default to false to minimize context usage

const includeCode = args.includeCode === true;

const match = this.findSymbol(cg, symbol);

if (!match) {

return this.textResult(`Symbol "${symbol}" not found in the codebase`);

}

let code: string | null = null;

if (includeCode) {

code = await cg.getCode(match.node.id);

}

const formatted = this.formatNodeDetails(match.node, code) + match.note;

return this.textResult(this.truncateOutput(formatted));

}

/**

* Handle codegraph_status

*/

private async handleStatus(args: Record<string, unknown>): Promise<ToolResult> {

const cg = this.getCodeGraph(args.projectPath as string | undefined);

const stats = cg.getStats();

const lines: string[] = [

'## CodeGraph Status',

'',

`**Files indexed:** ${stats.fileCount}`,

`**Total nodes:** ${stats.nodeCount}`,

`**Total edges:** ${stats.edgeCount}`,

`**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`,

'',

'### Nodes by Kind:',

];

for (const [kind, count] of Object.entries(stats.nodesByKind)) {

if ((count as number) > 0) {

lines.push(`- ${kind}: ${count}`);

}

}

lines.push('', '### Languages:');

for (const [lang, count] of Object.entries(stats.filesByLanguage)) {

if ((count as number) > 0) {

lines.push(`- ${lang}: ${count}`);

}

}

return this.textResult(lines.join('\n'));

}

/**

* Handle codegraph_files - get project file structure from the index

*/

private async handleFiles(args: Record<string, unknown>): Promise<ToolResult> {

const cg = this.getCodeGraph(args.projectPath as string | undefined);