Remove codegraph_explore tool in favor of native Explore agents
The hybrid approach (Claude's native Explore agents using codegraph tools) is more effective than a custom explore tool because Explore agents already know what format the main session needs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Colby McHenry
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
a4ddedb197
commit
47af81aee7
@@ -122,26 +122,16 @@ codegraph serve --mcp # Start MCP server
|
|||||||
|
|
||||||
## MCP Tools Best Practices
|
## MCP Tools Best Practices
|
||||||
|
|
||||||
When using CodeGraph MCP tools, follow these guidelines to minimize context usage:
|
These tools are designed to be used by **Explore agents** for faster codebase exploration:
|
||||||
|
|
||||||
### For Complex Tasks (features, refactoring, architecture)
|
| Tool | Use For |
|
||||||
Use `codegraph_explore` - it does intensive exploration internally and returns a condensed brief:
|
|------|---------|
|
||||||
```
|
| `codegraph_search` | Find symbols by name (functions, classes, types) |
|
||||||
codegraph_explore(task: "implement user authentication with OAuth")
|
| `codegraph_context` | Get relevant code context for a task |
|
||||||
```
|
| `codegraph_callers` | Find what calls a function |
|
||||||
This replaces multiple tool calls and keeps your main context clean.
|
| `codegraph_callees` | Find what a function calls |
|
||||||
|
| `codegraph_impact` | See what's affected by changing a symbol |
|
||||||
### For Simple Lookups
|
| `codegraph_node` | Get details + source code for a symbol |
|
||||||
Use targeted tools directly:
|
|
||||||
- `codegraph_search` - Find symbols by name
|
|
||||||
- `codegraph_node` - Get details about one symbol
|
|
||||||
- `codegraph_callers/callees` - Understand usage patterns
|
|
||||||
|
|
||||||
### Context Usage Comparison
|
|
||||||
| Approach | Context Impact |
|
|
||||||
|----------|---------------|
|
|
||||||
| Multiple `codegraph_*` calls | High - each result stays in context |
|
|
||||||
| Single `codegraph_explore` | Low - returns condensed summary |
|
|
||||||
|
|
||||||
### Important
|
### Important
|
||||||
CodeGraph provides **code context**, not product requirements. For new features, still ask the user about:
|
CodeGraph provides **code context**, not product requirements. For new features, still ask the user about:
|
||||||
|
|||||||
@@ -389,17 +389,7 @@ codegraph serve --mcp --path /project # Specify project path
|
|||||||
|
|
||||||
## 🔌 MCP Tools Reference
|
## 🔌 MCP Tools Reference
|
||||||
|
|
||||||
When running as an MCP server, CodeGraph exposes these tools to AI assistants:
|
When running as an MCP server, CodeGraph exposes these tools to AI assistants. **These tools are designed to be used by Claude's Explore agents** for faster, more efficient codebase exploration.
|
||||||
|
|
||||||
### `codegraph_explore` ⭐ Recommended for complex tasks
|
|
||||||
|
|
||||||
Deep exploration that returns a condensed brief. Use this for features, refactoring, or multi-file changes to keep your main context clean.
|
|
||||||
|
|
||||||
```
|
|
||||||
codegraph_explore(task: "implement user authentication", keywords: "auth,login,user")
|
|
||||||
```
|
|
||||||
|
|
||||||
**Returns:** Key files, entry points, types, functions, data flow, and suggested next steps.
|
|
||||||
|
|
||||||
### `codegraph_context`
|
### `codegraph_context`
|
||||||
|
|
||||||
@@ -446,13 +436,18 @@ codegraph_node(symbol: "authenticate", includeCode: true)
|
|||||||
|
|
||||||
Check index health and statistics.
|
Check index health and statistics.
|
||||||
|
|
||||||
### Context Usage Best Practices
|
### How It Works With Claude Code
|
||||||
|
|
||||||
| Approach | Context Impact | When to Use |
|
Claude's **Explore agents** use these tools instead of grep/glob/Read for faster exploration:
|
||||||
|----------|----------------|-------------|
|
|
||||||
| `codegraph_explore` | **Low** - condensed summary | Complex features, refactoring |
|
| Without CodeGraph | With CodeGraph | Benefit |
|
||||||
| Multiple tool calls | **High** - each result accumulates | Avoid for complex tasks |
|
|-------------------|----------------|---------|
|
||||||
| `codegraph_context` | **Medium** | Focused, single-area queries |
|
| `grep -r "auth"` | `codegraph_search("auth")` | Instant symbol lookup |
|
||||||
|
| Multiple `Read` calls | `codegraph_context(task)` | Related code in one call |
|
||||||
|
| Manual file tracing | `codegraph_callers/callees` | Call graph traversal |
|
||||||
|
| Guessing impact | `codegraph_impact(symbol)` | Know what breaks |
|
||||||
|
|
||||||
|
This hybrid approach gives you **~30% fewer tokens** and **~25% fewer tool calls** while letting Claude's native agents handle synthesis.
|
||||||
|
|
||||||
## 📚 Library Usage
|
## 📚 Library Usage
|
||||||
|
|
||||||
|
|||||||
@@ -4,8 +4,6 @@
|
|||||||
* Defines the tools exposed by the CodeGraph MCP server.
|
* Defines the tools exposed by the CodeGraph MCP server.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
import * as fs from 'fs';
|
|
||||||
import * as path from 'path';
|
|
||||||
import CodeGraph from '../index';
|
import CodeGraph from '../index';
|
||||||
import type { Node, SearchResult, Subgraph, TaskContext, NodeKind } from '../types';
|
import type { Node, SearchResult, Subgraph, TaskContext, NodeKind } from '../types';
|
||||||
|
|
||||||
@@ -179,29 +177,6 @@ export const tools: ToolDefinition[] = [
|
|||||||
properties: {},
|
properties: {},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
{
|
|
||||||
name: 'codegraph_explore',
|
|
||||||
description: 'RECOMMENDED FOR COMPLEX TASKS: Deep exploration that READS CODE INTERNALLY and returns synthesis with key snippets. You do NOT need to make separate Read calls - the code is included in the response. Checks for existing implementations, traces data flow, and includes relevant code. For feature requests, use AskUserQuestion to clarify requirements BEFORE planning.',
|
|
||||||
inputSchema: {
|
|
||||||
type: 'object',
|
|
||||||
properties: {
|
|
||||||
task: {
|
|
||||||
type: 'string',
|
|
||||||
description: 'Detailed description of the feature, bug, or task to explore',
|
|
||||||
},
|
|
||||||
focus: {
|
|
||||||
type: 'string',
|
|
||||||
description: 'Optional focus area: "architecture" (structure & patterns), "implementation" (specific code), or "impact" (what would change). Default: auto-detect.',
|
|
||||||
enum: ['architecture', 'implementation', 'impact'],
|
|
||||||
},
|
|
||||||
keywords: {
|
|
||||||
type: 'string',
|
|
||||||
description: 'Optional comma-separated keywords to search for (e.g., "bundle,swap,subscription")',
|
|
||||||
},
|
|
||||||
},
|
|
||||||
required: ['task'],
|
|
||||||
},
|
|
||||||
},
|
|
||||||
];
|
];
|
||||||
|
|
||||||
/**
|
/**
|
||||||
@@ -230,8 +205,6 @@ export class ToolHandler {
|
|||||||
return await this.handleNode(args);
|
return await this.handleNode(args);
|
||||||
case 'codegraph_status':
|
case 'codegraph_status':
|
||||||
return await this.handleStatus();
|
return await this.handleStatus();
|
||||||
case 'codegraph_explore':
|
|
||||||
return await this.handleExplore(args);
|
|
||||||
default:
|
default:
|
||||||
return this.errorResult(`Unknown tool: ${toolName}`);
|
return this.errorResult(`Unknown tool: ${toolName}`);
|
||||||
}
|
}
|
||||||
@@ -448,305 +421,6 @@ export class ToolHandler {
|
|||||||
return this.textResult(lines.join('\n'));
|
return this.textResult(lines.join('\n'));
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Handle codegraph_explore - deep exploration with internal file reading
|
|
||||||
* Returns synthesized context so Claude doesn't need separate Read calls
|
|
||||||
*/
|
|
||||||
private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {
|
|
||||||
const task = args.task as string;
|
|
||||||
const keywordsArg = args.keywords as string | undefined;
|
|
||||||
const projectRoot = this.cg.getProjectRoot();
|
|
||||||
|
|
||||||
// Phase 1: Extract search terms
|
|
||||||
const keywords = this.extractKeywords(task, keywordsArg);
|
|
||||||
|
|
||||||
// Phase 2: Find relevant symbols
|
|
||||||
const symbolMap = new Map<string, Node>();
|
|
||||||
const fileSet = new Set<string>();
|
|
||||||
|
|
||||||
for (const keyword of keywords.slice(0, 5)) {
|
|
||||||
const results = this.cg.searchNodes(keyword, { limit: 10 });
|
|
||||||
for (const r of results) {
|
|
||||||
if (!symbolMap.has(r.node.id)) {
|
|
||||||
symbolMap.set(r.node.id, r.node);
|
|
||||||
fileSet.add(r.node.filePath);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Phase 3: Look for EXISTING implementations
|
|
||||||
const existingImplNodes: Node[] = [];
|
|
||||||
const searchPatterns = this.generateExistingPatternSearches(keywords);
|
|
||||||
|
|
||||||
for (const pattern of searchPatterns) {
|
|
||||||
const results = this.cg.searchNodes(pattern, { limit: 5 });
|
|
||||||
for (const r of results) {
|
|
||||||
const node = r.node;
|
|
||||||
if (['function', 'method', 'component'].includes(node.kind)) {
|
|
||||||
if (!symbolMap.has(node.id)) {
|
|
||||||
symbolMap.set(node.id, node);
|
|
||||||
fileSet.add(node.filePath);
|
|
||||||
}
|
|
||||||
existingImplNodes.push(node);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Phase 4: Categorize symbols by type
|
|
||||||
const allSymbols = Array.from(symbolMap.values());
|
|
||||||
const functions = allSymbols.filter(n => n.kind === 'function' || n.kind === 'method');
|
|
||||||
const components = allSymbols.filter(n => n.kind === 'component');
|
|
||||||
const types = allSymbols.filter(n => n.kind === 'interface' || n.kind === 'type_alias');
|
|
||||||
const apiRoutes = allSymbols.filter(n => n.filePath.includes('/api/') || n.kind === 'route');
|
|
||||||
|
|
||||||
// Phase 5: READ CODE INTERNALLY for key symbols (the sub-agent behavior)
|
|
||||||
// Prioritize: existing implementations > API routes > types > functions
|
|
||||||
const codeSnippets: Array<{ node: Node; code: string }> = [];
|
|
||||||
const maxSnippets = 8;
|
|
||||||
const maxCodeLength = 1500; // chars per snippet
|
|
||||||
|
|
||||||
const priorityNodes = [
|
|
||||||
...existingImplNodes.slice(0, 3),
|
|
||||||
...apiRoutes.slice(0, 2),
|
|
||||||
...types.slice(0, 2),
|
|
||||||
...components.slice(0, 2),
|
|
||||||
...functions.filter(n => !existingImplNodes.includes(n)).slice(0, 1),
|
|
||||||
];
|
|
||||||
|
|
||||||
for (const node of priorityNodes) {
|
|
||||||
if (codeSnippets.length >= maxSnippets) break;
|
|
||||||
|
|
||||||
const code = this.extractNodeCode(projectRoot, node, maxCodeLength);
|
|
||||||
if (code) {
|
|
||||||
codeSnippets.push({ node, code });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Phase 6: Trace call graphs for data flow understanding
|
|
||||||
const dataFlowInsights: string[] = [];
|
|
||||||
for (const node of existingImplNodes.slice(0, 3)) {
|
|
||||||
const callers = this.cg.getCallers(node.id);
|
|
||||||
const callees = this.cg.getCallees(node.id);
|
|
||||||
|
|
||||||
if (callers.length > 0 || callees.length > 0) {
|
|
||||||
let flow = `${node.name}`;
|
|
||||||
if (callers.length > 0) flow = `${callers.slice(0, 2).map(c => c.node.name).join(', ')} → ${flow}`;
|
|
||||||
if (callees.length > 0) flow = `${flow} → ${callees.slice(0, 2).map(c => c.node.name).join(', ')}`;
|
|
||||||
dataFlowInsights.push(flow);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Phase 7: Build comprehensive synthesis
|
|
||||||
const isFeatureQuery = this.looksLikeFeatureRequest(task);
|
|
||||||
const hasExistingImpl = existingImplNodes.length > 0;
|
|
||||||
|
|
||||||
const synthesis = this.buildExploreSynthesis({
|
|
||||||
task,
|
|
||||||
existingImplNodes,
|
|
||||||
codeSnippets,
|
|
||||||
types,
|
|
||||||
apiRoutes,
|
|
||||||
dataFlowInsights,
|
|
||||||
totalSymbols: symbolMap.size,
|
|
||||||
totalFiles: fileSet.size,
|
|
||||||
isFeatureQuery,
|
|
||||||
hasExistingImpl,
|
|
||||||
});
|
|
||||||
|
|
||||||
return this.textResult(synthesis);
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Extract code from a node's source file
|
|
||||||
*/
|
|
||||||
private extractNodeCode(projectRoot: string, node: Node, maxLength: number): string | null {
|
|
||||||
const filePath = path.join(projectRoot, node.filePath);
|
|
||||||
|
|
||||||
if (!fs.existsSync(filePath)) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
try {
|
|
||||||
const content = fs.readFileSync(filePath, 'utf-8');
|
|
||||||
const lines = content.split('\n');
|
|
||||||
|
|
||||||
const startIdx = Math.max(0, node.startLine - 1);
|
|
||||||
const endIdx = Math.min(lines.length, node.endLine);
|
|
||||||
|
|
||||||
let code = lines.slice(startIdx, endIdx).join('\n');
|
|
||||||
|
|
||||||
// Truncate if too long
|
|
||||||
if (code.length > maxLength) {
|
|
||||||
code = code.slice(0, maxLength) + '\n// ... truncated ...';
|
|
||||||
}
|
|
||||||
|
|
||||||
return code;
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Build comprehensive synthesis with code included
|
|
||||||
*/
|
|
||||||
private buildExploreSynthesis(data: {
|
|
||||||
task: string;
|
|
||||||
existingImplNodes: Node[];
|
|
||||||
codeSnippets: Array<{ node: Node; code: string }>;
|
|
||||||
types: Node[];
|
|
||||||
apiRoutes: Node[];
|
|
||||||
dataFlowInsights: string[];
|
|
||||||
totalSymbols: number;
|
|
||||||
totalFiles: number;
|
|
||||||
isFeatureQuery: boolean;
|
|
||||||
hasExistingImpl: boolean;
|
|
||||||
}): string {
|
|
||||||
const lines: string[] = [];
|
|
||||||
|
|
||||||
// Critical warnings at TOP
|
|
||||||
if (data.hasExistingImpl) {
|
|
||||||
lines.push('⚠️ **EXISTING IMPLEMENTATIONS FOUND** - Review code below before planning. Feature may already exist.');
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
if (data.isFeatureQuery) {
|
|
||||||
lines.push('📋 **BEFORE PLANNING:** Use `AskUserQuestion` to clarify UX preferences and requirements.');
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
|
|
||||||
// Summary stats
|
|
||||||
lines.push(`**Explored ${data.totalSymbols} symbols across ${data.totalFiles} files**`);
|
|
||||||
lines.push('');
|
|
||||||
|
|
||||||
// Data flow (if available)
|
|
||||||
if (data.dataFlowInsights.length > 0) {
|
|
||||||
lines.push('**Data Flow:**');
|
|
||||||
for (const flow of data.dataFlowInsights.slice(0, 3)) {
|
|
||||||
lines.push(` ${flow}`);
|
|
||||||
}
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
|
|
||||||
// Key types (signatures only, no code)
|
|
||||||
if (data.types.length > 0) {
|
|
||||||
lines.push('**Key Types:**');
|
|
||||||
for (const t of data.types.slice(0, 4)) {
|
|
||||||
lines.push(` - \`${t.name}\` (${t.filePath}:${t.startLine})`);
|
|
||||||
}
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
|
|
||||||
// API routes (signatures only)
|
|
||||||
if (data.apiRoutes.length > 0) {
|
|
||||||
lines.push('**API Routes:**');
|
|
||||||
for (const r of data.apiRoutes.slice(0, 3)) {
|
|
||||||
const routePath = r.filePath.split('/api/')[1] || r.filePath;
|
|
||||||
lines.push(` - \`/api/${routePath}\` (${r.name})`);
|
|
||||||
}
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
|
|
||||||
// CODE SNIPPETS - the key sub-agent behavior
|
|
||||||
if (data.codeSnippets.length > 0) {
|
|
||||||
lines.push('---');
|
|
||||||
lines.push('**Key Code (read internally):**');
|
|
||||||
lines.push('');
|
|
||||||
|
|
||||||
for (const { node, code } of data.codeSnippets) {
|
|
||||||
lines.push(`### ${node.name} (${node.kind}) - ${node.filePath}:${node.startLine}`);
|
|
||||||
lines.push('```' + (node.language || 'typescript'));
|
|
||||||
lines.push(code);
|
|
||||||
lines.push('```');
|
|
||||||
lines.push('');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return lines.join('\n');
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Generate search patterns to find existing implementations
|
|
||||||
* Language-agnostic: generates patterns for multiple naming conventions
|
|
||||||
*/
|
|
||||||
private generateExistingPatternSearches(keywords: string[]): string[] {
|
|
||||||
const patterns: string[] = [];
|
|
||||||
|
|
||||||
for (const keyword of keywords.slice(0, 3)) {
|
|
||||||
// Skip very short or common words
|
|
||||||
if (keyword.length < 3) continue;
|
|
||||||
|
|
||||||
const lower = keyword.toLowerCase();
|
|
||||||
const capitalized = keyword.charAt(0).toUpperCase() + keyword.slice(1).toLowerCase();
|
|
||||||
|
|
||||||
// The keyword itself in various cases
|
|
||||||
patterns.push(lower);
|
|
||||||
patterns.push(capitalized);
|
|
||||||
|
|
||||||
// Common suffixes (work across most languages)
|
|
||||||
// These patterns find: SwapService, swap_service, SwapHandler, etc.
|
|
||||||
const suffixes = ['Service', 'Handler', 'Controller', 'Manager', 'Helper', 'Util', 'Utils'];
|
|
||||||
for (const suffix of suffixes) {
|
|
||||||
patterns.push(`${capitalized}${suffix}`); // PascalCase: SwapService
|
|
||||||
patterns.push(`${lower}_${suffix.toLowerCase()}`); // snake_case: swap_service
|
|
||||||
}
|
|
||||||
|
|
||||||
// Common prefixes (work across most languages)
|
|
||||||
const prefixes = ['handle', 'process', 'do', 'execute', 'perform', 'run'];
|
|
||||||
for (const prefix of prefixes) {
|
|
||||||
patterns.push(`${prefix}_${lower}`); // snake_case: handle_swap
|
|
||||||
patterns.push(`${prefix}${capitalized}`); // camelCase: handleSwap
|
|
||||||
}
|
|
||||||
|
|
||||||
// Common action patterns
|
|
||||||
patterns.push(`create_${lower}`);
|
|
||||||
patterns.push(`update_${lower}`);
|
|
||||||
patterns.push(`delete_${lower}`);
|
|
||||||
patterns.push(`get_${lower}`);
|
|
||||||
patterns.push(`create${capitalized}`);
|
|
||||||
patterns.push(`update${capitalized}`);
|
|
||||||
patterns.push(`delete${capitalized}`);
|
|
||||||
patterns.push(`get${capitalized}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return [...new Set(patterns)];
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Extract keywords from task description
|
|
||||||
*/
|
|
||||||
private extractKeywords(task: string, explicitKeywords?: string): string[] {
|
|
||||||
const keywords: string[] = [];
|
|
||||||
|
|
||||||
// Add explicit keywords first
|
|
||||||
if (explicitKeywords) {
|
|
||||||
keywords.push(...explicitKeywords.split(',').map(k => k.trim()).filter(Boolean));
|
|
||||||
}
|
|
||||||
|
|
||||||
// Extract likely code identifiers from task (camelCase, PascalCase, snake_case)
|
|
||||||
const identifierPattern = /\b([A-Z][a-zA-Z0-9]*|[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*|[a-z]+_[a-z_]+)\b/g;
|
|
||||||
const matches = task.match(identifierPattern) || [];
|
|
||||||
keywords.push(...matches);
|
|
||||||
|
|
||||||
// Extract quoted terms
|
|
||||||
const quotedPattern = /"([^"]+)"|'([^']+)'/g;
|
|
||||||
let match;
|
|
||||||
while ((match = quotedPattern.exec(task)) !== null) {
|
|
||||||
const quoted = match[1] || match[2];
|
|
||||||
if (quoted) keywords.push(quoted);
|
|
||||||
}
|
|
||||||
|
|
||||||
// Extract domain-specific terms (nouns that might be code concepts)
|
|
||||||
const commonTerms = task.toLowerCase()
|
|
||||||
.split(/\s+/)
|
|
||||||
.filter(word =>
|
|
||||||
word.length > 3 &&
|
|
||||||
!['this', 'that', 'with', 'from', 'have', 'been', 'will', 'would', 'could', 'should', 'when', 'where', 'what', 'which', 'their', 'there', 'these', 'those', 'about', 'into', 'then', 'than', 'some', 'other', 'after', 'before'].includes(word)
|
|
||||||
);
|
|
||||||
keywords.push(...commonTerms);
|
|
||||||
|
|
||||||
// Deduplicate and return
|
|
||||||
return [...new Set(keywords)];
|
|
||||||
}
|
|
||||||
|
|
||||||
// =========================================================================
|
// =========================================================================
|
||||||
// Formatting helpers (compact by default to reduce context usage)
|
// Formatting helpers (compact by default to reduce context usage)
|
||||||
// =========================================================================
|
// =========================================================================
|
||||||
|
|||||||
Reference in New Issue
Block a user