@colbymchenry/codegraph 0.3.1 → 0.5.1

package/dist/mcp/tools.js

@@ -4,13 +4,75 @@
  *
  * Defines the tools exposed by the CodeGraph MCP server.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolHandler = exports.tools = void 0;
+const index_1 = __importStar(require("../index"));
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const utils_1 = require("../utils");
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * Mark a Claude session as having consulted MCP tools.
+ * This enables Grep/Glob/Bash commands that would otherwise be blocked.
+ */
+function markSessionConsulted(sessionId) {
+    try {
+        const hash = (0, crypto_1.createHash)('md5').update(sessionId).digest('hex').slice(0, 16);
+        const markerPath = (0, path_1.join)((0, os_1.tmpdir)(), `codegraph-consulted-${hash}`);
+        (0, fs_1.writeFileSync)(markerPath, new Date().toISOString(), 'utf8');
+    }
+    catch {
+        // Silently fail - don't break MCP on marker write failure
+    }
+}
+/**
+ * Common projectPath property for cross-project queries
+ */
+const projectPathProperty = {
+    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.
  */
 exports.tools = [
     {
@@ -33,6 +95,7 @@ exports.tools = [
                     description: 'Maximum results (default: 10)',
                     default: 10,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['query'],
         },
@@ -57,6 +120,7 @@ exports.tools = [
                     description: 'Include code snippets for key symbols (default: true)',
                     default: true,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['task'],
         },
@@ -76,6 +140,7 @@ exports.tools = [
                     description: 'Maximum number of callers to return (default: 20)',
                     default: 20,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['symbol'],
         },
@@ -95,6 +160,7 @@ exports.tools = [
                     description: 'Maximum number of callees to return (default: 20)',
                     default: 20,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['symbol'],
         },
@@ -114,6 +180,7 @@ exports.tools = [
                     description: 'How many levels of dependencies to traverse (default: 2)',
                     default: 2,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['symbol'],
         },
@@ -133,6 +200,7 @@ exports.tools = [
                     description: 'Include full source code (default: false to minimize context)',
                     default: false,
                 },
+                projectPath: projectPathProperty,
             },
             required: ['symbol'],
         },
@@ -142,18 +210,128 @@ exports.tools = [
         description: 'Get the status of the CodeGraph index, including statistics about indexed files, nodes, and edges.',
         inputSchema: {
             type: 'object',
-            properties: {},
+            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.
  */
 class ToolHandler {
     cg;
+    // Cache of opened CodeGraph instances for cross-project queries
+    projectCache = new Map();
     constructor(cg) {
         this.cg = cg;
     }
+    /**
+     * Update the default CodeGraph instance (e.g. after lazy initialization)
+     */
+    setDefaultCodeGraph(cg) {
+        this.cg = cg;
+    }
+    /**
+     * Whether a default CodeGraph instance is available
+     */
+    hasDefaultCodeGraph() {
+        return this.cg !== null;
+    }
+    /**
+     * 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.
+     */
+    getCodeGraph(projectPath) {
+        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 = (0, index_1.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 = index_1.default.openSync(resolvedRoot);
+        this.projectCache.set(resolvedRoot, cg);
+        if (projectPath !== resolvedRoot) {
+            this.projectCache.set(projectPath, cg);
+        }
+        return cg;
+    }
+    /**
+     * Close all cached project connections
+     */
+    closeAll() {
+        for (const cg of this.projectCache.values()) {
+            cg.close();
+        }
+        this.projectCache.clear();
+    }
+    /**
+     * Validate that a value is a non-empty string
+     */
+    validateString(value, name) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return this.errorResult(`${name} must be a non-empty string`);
+        }
+        return value;
+    }
     /**
      * Execute a tool by name
      */
@@ -173,12 +351,19 @@ class ToolHandler {
                 case 'codegraph_node':
                     return await this.handleNode(args);
                 case 'codegraph_status':
-                    return await this.handleStatus();
+                    return await this.handleStatus(args);
+                case 'codegraph_files':
+                    return await this.handleFiles(args);
                 default:
                     return this.errorResult(`Unknown tool: ${toolName}`);
             }
         }
         catch (err) {
+            try {
+                const { captureException } = require('../sentry');
+                captureException(err, { tool: toolName });
+            }
+            catch { }
             return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
@@ -186,10 +371,14 @@ class ToolHandler {
      * Handle codegraph_search
      */
     async handleSearch(args) {
-        const query = args.query;
+        const query = this.validateString(args.query, 'query');
+        if (typeof query !== 'string')
+            return query;
+        const cg = this.getCodeGraph(args.projectPath);
         const kind = args.kind;
-        const limit = args.limit || 10;
-        const results = this.cg.searchNodes(query, {
+        const rawLimit = Number(args.limit) || 10;
+        const limit = (0, utils_1.clamp)(rawLimit, 1, 100);
+        const results = cg.searchNodes(query, {
             limit,
             kinds: kind ? [kind] : undefined,
         });
@@ -197,16 +386,24 @@ class ToolHandler {
             return this.textResult(`No results found for "${query}"`);
         }
         const formatted = this.formatSearchResults(results);
-        return this.textResult(formatted);
+        return this.textResult(this.truncateOutput(formatted));
     }
     /**
      * Handle codegraph_context
      */
     async handleContext(args) {
-        const task = args.task;
+        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);
         const maxNodes = args.maxNodes || 20;
         const includeCode = args.includeCode !== false;
-        const context = await this.cg.buildContext(task, {
+        const context = await cg.buildContext(task, {
             maxNodes,
             includeCode,
             format: 'markdown',
@@ -253,85 +450,88 @@ class ToolHandler {
      * Handle codegraph_callers
      */
     async handleCallers(args) {
-        const symbol = args.symbol;
-        const limit = args.limit || 20;
-        // First find the node by name
-        const results = this.cg.searchNodes(symbol, { limit: 1 });
-        if (results.length === 0 || !results[0]) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const match = this.findSymbol(cg, symbol);
+        if (!match) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const node = results[0].node;
-        const callers = this.cg.getCallers(node.id);
+        const callers = cg.getCallers(match.node.id);
         if (callers.length === 0) {
-            return this.textResult(`No callers found for "${symbol}"`);
+            return this.textResult(`No callers found for "${symbol}"${match.note}`);
         }
-        // Extract just the nodes from the { node, edge } tuples
         const callerNodes = callers.slice(0, limit).map(c => c.node);
-        const formatted = this.formatNodeList(callerNodes, `Callers of ${symbol}`);
-        return this.textResult(formatted);
+        const formatted = this.formatNodeList(callerNodes, `Callers of ${symbol}`) + match.note;
+        return this.textResult(this.truncateOutput(formatted));
     }
     /**
      * Handle codegraph_callees
      */
     async handleCallees(args) {
-        const symbol = args.symbol;
-        const limit = args.limit || 20;
-        // First find the node by name
-        const results = this.cg.searchNodes(symbol, { limit: 1 });
-        if (results.length === 0 || !results[0]) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const limit = (0, utils_1.clamp)(args.limit || 20, 1, 100);
+        const match = this.findSymbol(cg, symbol);
+        if (!match) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const node = results[0].node;
-        const callees = this.cg.getCallees(node.id);
+        const callees = cg.getCallees(match.node.id);
         if (callees.length === 0) {
-            return this.textResult(`No callees found for "${symbol}"`);
+            return this.textResult(`No callees found for "${symbol}"${match.note}`);
         }
-        // Extract just the nodes from the { node, edge } tuples
         const calleeNodes = callees.slice(0, limit).map(c => c.node);
-        const formatted = this.formatNodeList(calleeNodes, `Callees of ${symbol}`);
-        return this.textResult(formatted);
+        const formatted = this.formatNodeList(calleeNodes, `Callees of ${symbol}`) + match.note;
+        return this.textResult(this.truncateOutput(formatted));
     }
     /**
      * Handle codegraph_impact
      */
     async handleImpact(args) {
-        const symbol = args.symbol;
-        const depth = args.depth || 2;
-        // First find the node by name
-        const results = this.cg.searchNodes(symbol, { limit: 1 });
-        if (results.length === 0 || !results[0]) {
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
+        const depth = (0, utils_1.clamp)(args.depth || 2, 1, 10);
+        const match = this.findSymbol(cg, symbol);
+        if (!match) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const node = results[0].node;
-        const impact = this.cg.getImpactRadius(node.id, depth);
-        const formatted = this.formatImpact(symbol, impact);
-        return this.textResult(formatted);
+        const impact = cg.getImpactRadius(match.node.id, depth);
+        const formatted = this.formatImpact(symbol, impact) + match.note;
+        return this.textResult(this.truncateOutput(formatted));
     }
     /**
      * Handle codegraph_node
      */
     async handleNode(args) {
-        const symbol = args.symbol;
+        const symbol = this.validateString(args.symbol, 'symbol');
+        if (typeof symbol !== 'string')
+            return symbol;
+        const cg = this.getCodeGraph(args.projectPath);
         // Default to false to minimize context usage
         const includeCode = args.includeCode === true;
-        // Find the node by name
-        const results = this.cg.searchNodes(symbol, { limit: 1 });
-        if (results.length === 0 || !results[0]) {
+        const match = this.findSymbol(cg, symbol);
+        if (!match) {
             return this.textResult(`Symbol "${symbol}" not found in the codebase`);
         }
-        const node = results[0].node;
         let code = null;
         if (includeCode) {
-            code = await this.cg.getCode(node.id);
+            code = await cg.getCode(match.node.id);
         }
-        const formatted = this.formatNodeDetails(node, code);
-        return this.textResult(formatted);
+        const formatted = this.formatNodeDetails(match.node, code) + match.note;
+        return this.textResult(this.truncateOutput(formatted));
     }
     /**
      * Handle codegraph_status
      */
-    async handleStatus() {
-        const stats = this.cg.getStats();
+    async handleStatus(args) {
+        const cg = this.getCodeGraph(args.projectPath);
+        const stats = cg.getStats();
         const lines = [
             '## CodeGraph Status',
             '',
@@ -355,6 +555,199 @@ class ToolHandler {
         }
         return this.textResult(lines.join('\n'));
     }
+    /**
+     * Handle codegraph_files - get project file structure from the index
+     */
+    async handleFiles(args) {
+        const cg = this.getCodeGraph(args.projectPath);
+        const pathFilter = args.path;
+        const pattern = args.pattern;
+        const format = args.format || 'tree';
+        const includeMetadata = args.includeMetadata !== false;
+        const maxDepth = args.maxDepth != null ? (0, utils_1.clamp)(args.maxDepth, 1, 20) : undefined;
+        // Get all files from the index
+        const allFiles = cg.getFiles();
+        if (allFiles.length === 0) {
+            return this.textResult('No files indexed. Run `codegraph index` first.');
+        }
+        // Filter by path prefix
+        let files = pathFilter
+            ? allFiles.filter(f => f.path.startsWith(pathFilter) || f.path.startsWith('./' + pathFilter))
+            : allFiles;
+        // Filter by glob pattern
+        if (pattern) {
+            const regex = this.globToRegex(pattern);
+            files = files.filter(f => regex.test(f.path));
+        }
+        if (files.length === 0) {
+            return this.textResult(`No files found matching the criteria.`);
+        }
+        // Format output
+        let output;
+        switch (format) {
+            case 'flat':
+                output = this.formatFilesFlat(files, includeMetadata);
+                break;
+            case 'grouped':
+                output = this.formatFilesGrouped(files, includeMetadata);
+                break;
+            case 'tree':
+            default:
+                output = this.formatFilesTree(files, includeMetadata, maxDepth);
+                break;
+        }
+        return this.textResult(this.truncateOutput(output));
+    }
+    /**
+     * Convert glob pattern to regex
+     */
+    globToRegex(pattern) {
+        const escaped = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars except * and ?
+            .replace(/\*\*/g, '{{GLOBSTAR}}') // Temp placeholder for **
+            .replace(/\*/g, '[^/]*') // * matches anything except /
+            .replace(/\?/g, '[^/]') // ? matches single char except /
+            .replace(/\{\{GLOBSTAR\}\}/g, '.*'); // ** matches anything including /
+        return new RegExp(escaped);
+    }
+    /**
+     * Format files as a flat list
+     */
+    formatFilesFlat(files, includeMetadata) {
+        const lines = [`## Files (${files.length})`, ''];
+        for (const file of files.sort((a, b) => a.path.localeCompare(b.path))) {
+            if (includeMetadata) {
+                lines.push(`- ${file.path} (${file.language}, ${file.nodeCount} symbols)`);
+            }
+            else {
+                lines.push(`- ${file.path}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Format files grouped by language
+     */
+    formatFilesGrouped(files, includeMetadata) {
+        const byLang = new Map();
+        for (const file of files) {
+            const existing = byLang.get(file.language) || [];
+            existing.push(file);
+            byLang.set(file.language, existing);
+        }
+        const lines = [`## Files by Language (${files.length} total)`, ''];
+        // Sort languages by file count (descending)
+        const sortedLangs = [...byLang.entries()].sort((a, b) => b[1].length - a[1].length);
+        for (const [lang, langFiles] of sortedLangs) {
+            lines.push(`### ${lang} (${langFiles.length})`);
+            for (const file of langFiles.sort((a, b) => a.path.localeCompare(b.path))) {
+                if (includeMetadata) {
+                    lines.push(`- ${file.path} (${file.nodeCount} symbols)`);
+                }
+                else {
+                    lines.push(`- ${file.path}`);
+                }
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Format files as a tree structure
+     */
+    formatFilesTree(files, includeMetadata, maxDepth) {
+        const root = { name: '', children: new Map() };
+        for (const file of files) {
+            const parts = file.path.split('/');
+            let current = root;
+            for (let i = 0; i < parts.length; i++) {
+                const part = parts[i];
+                if (!part)
+                    continue;
+                if (!current.children.has(part)) {
+                    current.children.set(part, { name: part, children: new Map() });
+                }
+                current = current.children.get(part);
+                // If this is the last part, it's a file
+                if (i === parts.length - 1) {
+                    current.file = { language: file.language, nodeCount: file.nodeCount };
+                }
+            }
+        }
+        // Render tree
+        const lines = [`## Project Structure (${files.length} files)`, ''];
+        const renderNode = (node, prefix, isLast, depth) => {
+            if (maxDepth !== undefined && depth > maxDepth)
+                return;
+            const connector = isLast ? '└── ' : '├── ';
+            const childPrefix = isLast ? '    ' : '│   ';
+            if (node.name) {
+                let line = prefix + connector + node.name;
+                if (node.file && includeMetadata) {
+                    line += ` (${node.file.language}, ${node.file.nodeCount} symbols)`;
+                }
+                lines.push(line);
+            }
+            const children = [...node.children.values()];
+            // Sort: directories first, then files, both alphabetically
+            children.sort((a, b) => {
+                const aIsDir = a.children.size > 0 && !a.file;
+                const bIsDir = b.children.size > 0 && !b.file;
+                if (aIsDir !== bIsDir)
+                    return aIsDir ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (let i = 0; i < children.length; i++) {
+                const child = children[i];
+                const nextPrefix = node.name ? prefix + childPrefix : prefix;
+                renderNode(child, nextPrefix, i === children.length - 1, depth + 1);
+            }
+        };
+        renderNode(root, '', true, 0);
+        return lines.join('\n');
+    }
+    // =========================================================================
+    // Symbol resolution helpers
+    // =========================================================================
+    /**
+     * Find a symbol by name, handling disambiguation when multiple matches exist.
+     * Returns the best match and a note about alternatives if any.
+     */
+    findSymbol(cg, symbol) {
+        const results = cg.searchNodes(symbol, { limit: 10 });
+        if (results.length === 0 || !results[0]) {
+            return null;
+        }
+        // If only one result, or first is an exact name match, use it directly
+        const exactMatches = results.filter(r => r.node.name === symbol);
+        if (exactMatches.length === 1) {
+            return { node: exactMatches[0].node, note: '' };
+        }
+        if (exactMatches.length > 1) {
+            // Multiple exact matches - pick first, note the others
+            const picked = exactMatches[0].node;
+            const others = exactMatches.slice(1).map(r => `${r.node.name} (${r.node.kind}) at ${r.node.filePath}:${r.node.startLine}`);
+            const note = `\n\n> **Note:** ${exactMatches.length} symbols named "${symbol}". Showing results for \`${picked.filePath}:${picked.startLine}\`. Others: ${others.join(', ')}`;
+            return { node: picked, note };
+        }
+        // No exact match, use best fuzzy match
+        return { node: results[0].node, note: '' };
+    }
+    /**
+     * Maximum output length to prevent context bloat (characters)
+     */
+    MAX_OUTPUT_LENGTH = 15000;
+    /**
+     * Truncate output if it exceeds the maximum length
+     */
+    truncateOutput(text) {
+        if (text.length <= this.MAX_OUTPUT_LENGTH)
+            return text;
+        const truncated = text.slice(0, this.MAX_OUTPUT_LENGTH);
+        const lastNewline = truncated.lastIndexOf('\n');
+        const cutPoint = lastNewline > this.MAX_OUTPUT_LENGTH * 0.8 ? lastNewline : this.MAX_OUTPUT_LENGTH;
+        return truncated.slice(0, cutPoint) + '\n\n... (output truncated)';
+    }
     // =========================================================================
     // Formatting helpers (compact by default to reduce context usage)
     // =========================================================================