callgraph-mcp 1.3.0 → 1.4.0

package/dist/tools/getFlow.js

@@ -0,0 +1,140 @@
+"use strict";
+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.registerGetFlow = registerGetFlow;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const analysis_1 = require("../utils/analysis");
+const toolHelper_1 = require("../utils/toolHelper");
+function registerGetFlow(server) {
+    (0, toolHelper_1.registerTool)(server, 'flowmap_get_flow', 'Return the complete sub-graph reachable from a given function — every function it calls, every function those call, and so on recursively. Use this to understand the full execution path of a feature or entry point.', {
+        functionName: zod_1.z.string().describe('The starting function name'),
+        workspacePath: zod_1.z.string().describe('Absolute path to the repository root'),
+        maxDepth: zod_1.z.number().optional().describe('Maximum recursion depth. Default 10.'),
+    }, async ({ functionName, workspacePath, maxDepth: rawMaxDepth }) => {
+        const maxDepth = rawMaxDepth ?? 10;
+        try {
+            if (!fs.existsSync(workspacePath)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: true,
+                                code: 'WORKSPACE_NOT_FOUND',
+                                message: `Directory does not exist: ${workspacePath}`,
+                                workspacePath,
+                            }),
+                        }],
+                };
+            }
+            const graph = await (0, analysis_1.analyzeWorkspace)(workspacePath);
+            const targets = graph.nodes.filter(n => n.name === functionName);
+            if (targets.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: true,
+                                code: 'FUNCTION_NOT_FOUND',
+                                message: `No function named "${functionName}" found in the codebase.`,
+                                workspacePath,
+                            }),
+                        }],
+                };
+            }
+            const target = targets[0];
+            // Build adjacency map for BFS
+            const outgoing = new Map();
+            for (const edge of graph.edges) {
+                const list = outgoing.get(edge.from) || [];
+                const toNode = graph.nodes.find(n => n.id === edge.to);
+                if (toNode) {
+                    list.push({ edge, node: toNode });
+                    outgoing.set(edge.from, list);
+                }
+            }
+            // BFS from target, depth-limited
+            const visitedIds = new Set();
+            const reachableNodes = [];
+            const reachableEdges = [];
+            let currentDepth = 0;
+            let frontier = [target.id];
+            visitedIds.add(target.id);
+            reachableNodes.push(target);
+            while (frontier.length > 0 && currentDepth < maxDepth) {
+                const nextFrontier = [];
+                for (const nodeId of frontier) {
+                    const neighbours = outgoing.get(nodeId) || [];
+                    for (const { edge, node } of neighbours) {
+                        reachableEdges.push(edge);
+                        if (!visitedIds.has(node.id)) {
+                            visitedIds.add(node.id);
+                            reachableNodes.push(node);
+                            nextFrontier.push(node.id);
+                        }
+                    }
+                }
+                frontier = nextFrontier;
+                currentDepth++;
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            entryFunction: functionName,
+                            nodes: reachableNodes,
+                            edges: reachableEdges,
+                            depth: currentDepth,
+                            totalFunctions: reachableNodes.length,
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: true,
+                            code: 'PARSE_ERROR',
+                            message,
+                            workspacePath,
+                        }),
+                    }],
+            };
+        }
+    });
+}

package/dist/tools/listEntryPoints.js

@@ -0,0 +1,96 @@
+"use strict";
+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.registerListEntryPoints = registerListEntryPoints;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const analysis_1 = require("../utils/analysis");
+const toolHelper_1 = require("../utils/toolHelper");
+function registerListEntryPoints(server) {
+    (0, toolHelper_1.registerTool)(server, 'flowmap_list_entry_points', 'Return all detected entry points in the codebase — main functions, HTTP route handlers, React root renders, CLI commands, etc. Always call this first when exploring a new codebase to understand where execution begins.', {
+        workspacePath: zod_1.z.string().describe('Absolute path to the repository root'),
+    }, async ({ workspacePath }) => {
+        try {
+            if (!fs.existsSync(workspacePath)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: true,
+                                code: 'WORKSPACE_NOT_FOUND',
+                                message: `Directory does not exist: ${workspacePath}`,
+                                workspacePath,
+                            }),
+                        }],
+                };
+            }
+            const graph = await (0, analysis_1.analyzeWorkspace)(workspacePath);
+            const entryNodes = graph.nodes.filter(n => n.isEntryPoint);
+            const entryPoints = entryNodes.map(n => ({
+                id: n.id,
+                name: n.name,
+                filePath: n.filePath,
+                startLine: n.startLine,
+                language: n.language,
+                isExported: n.isExported,
+                isAsync: n.isAsync,
+            }));
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            entryPoints,
+                            count: entryPoints.length,
+                            durationMs: graph.durationMs,
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: true,
+                            code: 'PARSE_ERROR',
+                            message,
+                            workspacePath,
+                        }),
+                    }],
+            };
+        }
+    });
+}

package/dist/utils/analysis.js

@@ -0,0 +1,113 @@
+"use strict";
+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.resolveWasmDir = resolveWasmDir;
+exports.analyzeWorkspace = analyzeWorkspace;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const core_1 = require("@codeflow-map/core");
+const cache_1 = require("./cache");
+const fileDiscovery_1 = require("./fileDiscovery");
+const BATCH_SIZE = 50;
+let treeSitterInitialized = false;
+function resolveWasmDir() {
+    // 1. Explicit env var
+    if (process.env.FLOWMAP_GRAMMARS) {
+        return process.env.FLOWMAP_GRAMMARS;
+    }
+    const candidates = [
+        // Bundled runtime: dist/index.js => <package-root>/grammars
+        path.resolve(__dirname, '..', 'grammars'),
+        // Dev/tsc layout: src/utils or dist/utils => <package-root>/grammars
+        path.resolve(__dirname, '..', '..', 'grammars'),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(candidate, 'tree-sitter.wasm'))) {
+            return candidate;
+        }
+    }
+    // Last-resort fallback keeps previous behavior for unexpected layouts.
+    return candidates[0];
+}
+async function ensureTreeSitter() {
+    if (!treeSitterInitialized) {
+        const wasmDir = resolveWasmDir();
+        const wasmPath = path.join(wasmDir, 'tree-sitter.wasm');
+        const wasmExists = fs.existsSync(wasmPath);
+        console.error(`[flowmap] Grammar directory: ${wasmDir} (tree-sitter.wasm ${wasmExists ? 'found' : 'missing'})`);
+        await (0, core_1.initTreeSitter)(wasmDir);
+        treeSitterInitialized = true;
+    }
+}
+async function analyzeWorkspace(workspacePath, options = {}) {
+    // Check cache
+    const cached = (0, cache_1.getCached)(workspacePath);
+    if (cached)
+        return cached;
+    await ensureTreeSitter();
+    const wasmDir = resolveWasmDir();
+    const startTime = Date.now();
+    // Discover files
+    const files = await (0, fileDiscovery_1.discoverFiles)(workspacePath, options);
+    const allFunctions = [];
+    const allCalls = [];
+    let scannedFiles = 0;
+    // Batch-parse to avoid EMFILE
+    for (let i = 0; i < files.length; i += BATCH_SIZE) {
+        const batch = files.slice(i, i + BATCH_SIZE);
+        const results = await Promise.all(batch.map(f => (0, core_1.parseFile)(f.filePath, f.absPath, wasmDir, f.languageId).catch(() => null)));
+        for (const result of results) {
+            if (result) {
+                allFunctions.push(...result.functions);
+                allCalls.push(...result.calls);
+                scannedFiles++;
+            }
+        }
+    }
+    // Build graph
+    const edges = (0, core_1.buildCallGraph)(allFunctions, allCalls);
+    (0, core_1.detectEntryPoints)(allFunctions, edges);
+    const { flows, orphans } = (0, core_1.partitionFlows)(allFunctions, edges);
+    const graph = {
+        nodes: allFunctions,
+        edges,
+        flows,
+        orphans,
+        scannedFiles,
+        durationMs: Date.now() - startTime,
+    };
+    (0, cache_1.setCached)(workspacePath, graph);
+    return graph;
+}

package/dist/utils/cache.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCached = getCached;
+exports.setCached = setCached;
+exports.clearCache = clearCache;
+const cache = new Map();
+const TTL_MS = 30_000; // 30 seconds
+function getCached(workspacePath) {
+    const entry = cache.get(workspacePath);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.cachedAt > TTL_MS) {
+        cache.delete(workspacePath);
+        return null;
+    }
+    return entry.graph;
+}
+function setCached(workspacePath, graph) {
+    cache.set(workspacePath, { graph, cachedAt: Date.now(), workspacePath });
+}
+function clearCache(workspacePath) {
+    if (workspacePath) {
+        cache.delete(workspacePath);
+    }
+    else {
+        cache.clear();
+    }
+}

package/dist/utils/fileDiscovery.js

@@ -0,0 +1,94 @@
+"use strict";
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverFiles = discoverFiles;
+const path = __importStar(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const core_1 = require("@codeflow-map/core");
+const DISCOVERY_EXCLUDES = [
+    '**/node_modules/**', '**/venv/**', '**/.venv/**',
+    '**/__pycache__/**', '**/vendor/**', '**/target/**',
+    '**/.git/**', '**/dist/**', '**/build/**',
+    '**/.next/**', '**/.turbo/**', '**/coverage/**',
+    '**/.gradle/**', '**/.cache/**', '**/site-packages/**',
+    '**/.mypy_cache/**', '**/.pytest_cache/**',
+    '**/out/**', '**/bin/**', '**/obj/**', '**/tests/**', '**/__tests__/**',
+    '**/spec/**', '**/__specs__/**', '**/test/**',
+];
+async function discoverFiles(workspacePath, options = {}) {
+    const { exclude = [], language } = options;
+    // Build extension list — either filtered to one language or all supported
+    let extensions;
+    if (language) {
+        const matching = Object.entries(core_1.FILE_EXTENSION_MAP)
+            .filter(([, lang]) => lang === language)
+            .map(([ext]) => ext.replace('.', ''));
+        extensions = matching.length > 0 ? matching : [];
+    }
+    else {
+        extensions = Object.keys(core_1.FILE_EXTENSION_MAP).map(e => e.replace('.', ''));
+    }
+    if (extensions.length === 0)
+        return [];
+    const pattern = extensions.length === 1
+        ? `**/*.${extensions[0]}`
+        : `**/*.{${extensions.join(',')}}`;
+    const allExcludes = [...DISCOVERY_EXCLUDES, ...exclude];
+    // fast-glob expects forward-slash paths
+    const cwd = workspacePath.replace(/\\/g, '/');
+    const relativePaths = await (0, fast_glob_1.default)(pattern, {
+        cwd,
+        ignore: allExcludes,
+        absolute: false,
+        dot: false,
+        onlyFiles: true,
+    });
+    const results = [];
+    for (const rel of relativePaths) {
+        const ext = path.extname(rel);
+        const lang = core_1.FILE_EXTENSION_MAP[ext];
+        if (!lang)
+            continue;
+        results.push({
+            filePath: rel.replace(/\\/g, '/'),
+            absPath: path.resolve(workspacePath, rel),
+            languageId: lang,
+        });
+    }
+    return results;
+}

package/dist/utils/formatGraph.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGraphSummary = formatGraphSummary;
+/**
+ * Produce an LLM-friendly text summary of a Graph for use alongside JSON responses.
+ */
+function formatGraphSummary(graph) {
+    const entryPoints = graph.nodes.filter(n => n.isEntryPoint);
+    const lines = [
+        `Scanned ${graph.scannedFiles} files in ${graph.durationMs}ms.`,
+        `Found ${graph.nodes.length} functions, ${graph.edges.length} call edges.`,
+        `${graph.flows.length} execution flows, ${graph.orphans.length} orphan functions.`,
+    ];
+    if (entryPoints.length > 0) {
+        lines.push('');
+        lines.push(`Entry points (${entryPoints.length}):`);
+        for (const ep of entryPoints.slice(0, 20)) {
+            lines.push(`  - ${ep.name} (${ep.filePath}:${ep.startLine})`);
+        }
+        if (entryPoints.length > 20) {
+            lines.push(`  ... and ${entryPoints.length - 20} more`);
+        }
+    }
+    if (graph.orphans.length > 0) {
+        lines.push('');
+        lines.push(`Orphan functions (${graph.orphans.length}):`);
+        const orphanNodes = graph.orphans
+            .map(id => graph.nodes.find(n => n.id === id))
+            .filter(Boolean);
+        for (const n of orphanNodes.slice(0, 10)) {
+            lines.push(`  - ${n.name} (${n.filePath}:${n.startLine})`);
+        }
+        if (graph.orphans.length > 10) {
+            lines.push(`  ... and ${graph.orphans.length - 10} more`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/utils/toolHelper.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+/**
+ * Registers a tool on the McpServer with explicit type handling to avoid
+ * TS2589 "Type instantiation is excessively deep" errors that occur with
+ * the MCP SDK 1.27.x + Zod 3.25.x combination.
+ */
+function registerTool(server, name, description, schema, handler) {
+    server.tool(name, description, schema, handler);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "callgraph-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "MCP server for codebase call-flow analysis. Local, deterministic, language-agnostic. Powered by @codeflow-map/core.",
   "keywords": [
     "mcp",