callgraph-mcp 1.3.0 → 1.4.0

package/README.md

@@ -88,6 +88,15 @@ Then point your client at it:
 | `flowmap_get_flow` | `functionName`, `workspacePath` | `maxDepth` (default 10) | Full BFS subgraph reachable from a function — the complete execution path |
 | `flowmap_list_entry_points` | `workspacePath` | — | All entry points: mains, route handlers, CLI commands, React roots |
 | `flowmap_find_orphans` | `workspacePath` | — | Functions unreachable from any entry point — potential dead code |
+| `flowmap_find_cycles` | `workspacePath` | `minCycleLength`, `exclude` | All call cycles (circular dependencies / mutual recursion) with exact member functions and the edges forming each loop |
+
+### Experimental
+
+> These tools are functional but the heuristics may produce false positives depending on codebase patterns. Tune the parameters if needed.
+
+| Tool | Required params | Optional | What it returns |
+|------|----------------|----------|-----------------|
+| `flowmap_find_duplicates` | `workspacePath` | `similarityThreshold` (default `0.75`), `minCallees` (default `2`), `exclude` | Clusters of functions with similar callee sets — different names, same business logic. Candidates for extraction into a shared utility. |
 
 **`workspacePath`** is the absolute path to the repository root (e.g. `/home/user/my-project` or `C:\projects\my-app`).
 
@@ -100,6 +109,8 @@ Then point your client at it:
 | `FLOWMAP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` (`http` is used for HTTP-SSE clients) |
 | `FLOWMAP_PORT` | `3100` | HTTP server port (only used for `http` transport) |
 | `FLOWMAP_GRAMMARS` | *(bundled)* | Override path to Tree-sitter WASM grammar files |
+| `FLOWMAP_DUP_THRESHOLD` | `0.75` | Default Jaccard similarity threshold for `flowmap_find_duplicates` (0–1). Lower = more matches. Can be overridden per-call. |
+| `FLOWMAP_DUP_MIN_CALLEES` | `2` | Default minimum callee count for `flowmap_find_duplicates`. Raise to filter out trivial wrappers. Can be overridden per-call. |
 
 ---
 
@@ -133,7 +144,7 @@ The agent calls `flowmap_analyze_workspace(workspacePath)` to get the full graph
 
 > *"Find every cycle in the call graph. For each one tell me which file I should break the dependency in to resolve it cleanly."*
 
-The agent calls `flowmap_analyze_workspace(workspacePath)` to retrieve the full edge list, then runs cycle detection over it. Each cycle is reported as an ordered list of functions and files. Because the graph is exact, the cycle membership is exact — not a guess about which modules "seem" circular.
+The agent calls `flowmap_find_cycles(workspacePath)`. Each cycle is returned as an ordered list of functions with file paths and the exact call edges forming the loop — no post-processing needed. Because the graph is exact, cycle membership is exact — not a guess about which modules "seem" circular.
 
 ---
 
@@ -184,6 +195,28 @@ When an agent is generating new code, it can call `flowmap_analyze_workspace` be
 - No existing entry points were broken
 - The intended call relationships were actually created
 
+---
+
+### Catching agent-introduced duplication before it compounds
+
+> *"We've been using an AI agent to build this codebase for 3 months. How much logic has it silently duplicated?"*
+
+Agents optimize for the current instruction, not long-term architecture. When a task requires shared logic, the agent rarely stops to ask "does this already exist?" — refactoring requires understanding dependencies and predicting side effects, which is harder than just writing new code that works. So it copies, tweaks slightly, and moves on. It satisfied the step. It made the problem worse.
+
+The agent calls `flowmap_find_duplicates(workspacePath)`. Each cluster in the result is a group of functions with different names — often in different components — that call the same set of dependencies. That's the callee-set fingerprint of duplicated business logic. The output names exactly which functions to merge and which file to consolidate them into.
+
+---
+
+### Detecting circular dependencies introduced by agent-generated code
+
+> *"The agent has been adding features for weeks. Are there any circular call dependencies I should know about before this becomes a production problem?"*
+
+Agents don't track long-term call structure. When told to wire up a feature quickly, they take the fastest path: call whatever is needed, from wherever is convenient. Over time this creates circular dependencies — `A` calls `B` calls `C` calls `A` — that are invisible until something breaks or hangs at runtime.
+
+The agent calls `flowmap_find_cycles(workspacePath)`. Every cycle is returned with the exact functions involved, their file locations, and the specific edges forming the loop. No guessing about which modules "seem" circular. The result tells you precisely where to break the chain.
+
+---
+
 ## How It Works
 
 1. Tree-sitter WASM grammars parse each source file into an AST — no runtime execution, no imports

package/dist/index.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
-"use strict";var me=Object.create;var P=Object.defineProperty;var ge=Object.getOwnPropertyDescriptor;var ue=Object.getOwnPropertyNames;var ye=Object.getPrototypeOf,he=Object.prototype.hasOwnProperty;var xe=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of ue(t))!he.call(e,n)&&n!==r&&P(e,n,{get:()=>t[n],enumerable:!(o=ge(t,n))||o.enumerable});return e};var g=(e,t,r)=>(r=e!=null?me(ye(e)):{},xe(t||!e||!e.__esModule?P(r,"default",{value:e,enumerable:!0}):r,e));var ie=require("http"),ae=require("@modelcontextprotocol/sdk/server/mcp.js"),ce=require("@modelcontextprotocol/sdk/server/stdio.js"),le=require("@modelcontextprotocol/sdk/server/streamableHttp.js"),pe=require("crypto");var b=require("zod"),$=g(require("fs"));var v=g(require("path")),M=g(require("fs")),h=require("@codeflow-map/core");var D=new Map,Se=3e4;function U(e){let t=D.get(e);return t?Date.now()-t.cachedAt>Se?(D.delete(e),null):t.graph:null}function z(e,t){D.set(e,{graph:t,cachedAt:Date.now(),workspacePath:e})}var w=g(require("path")),I=g(require("fast-glob")),E=require("@codeflow-map/core"),_e=["**/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 J(e,t={}){let{exclude:r=[],language:o}=t,n;if(o){let c=Object.entries(E.FILE_EXTENSION_MAP).filter(([,f])=>f===o).map(([f])=>f.replace(".",""));n=c.length>0?c:[]}else n=Object.keys(E.FILE_EXTENSION_MAP).map(c=>c.replace(".",""));if(n.length===0)return[];let s=n.length===1?`**/*.${n[0]}`:`**/*.{${n.join(",")}}`,a=[..._e,...r],l=e.replace(/\\/g,"/"),p=await(0,I.default)(s,{cwd:l,ignore:a,absolute:!1,dot:!1,onlyFiles:!0}),i=[];for(let c of p){let f=w.extname(c),x=E.FILE_EXTENSION_MAP[f];x&&i.push({filePath:c.replace(/\\/g,"/"),absPath:w.resolve(e,c),languageId:x})}return i}var G=50,W=!1;function R(){if(process.env.FLOWMAP_GRAMMARS)return process.env.FLOWMAP_GRAMMARS;let e=[v.resolve(__dirname,"..","grammars"),v.resolve(__dirname,"..","..","grammars")];for(let t of e)if(M.existsSync(v.join(t,"tree-sitter.wasm")))return t;return e[0]}async function ve(){if(!W){let e=R(),t=v.join(e,"tree-sitter.wasm"),r=M.existsSync(t);console.error(`[flowmap] Grammar directory: ${e} (tree-sitter.wasm ${r?"found":"missing"})`),await(0,h.initTreeSitter)(e),W=!0}}async function u(e,t={}){let r=U(e);if(r)return r;await ve();let o=R(),n=Date.now(),s=await J(e,t),a=[],l=[],p=0;for(let S=0;S<s.length;S+=G){let y=s.slice(S,S+G),_=await Promise.all(y.map(m=>(0,h.parseFile)(m.filePath,m.absPath,o,m.languageId).catch(()=>null)));for(let m of _)m&&(a.push(...m.functions),l.push(...m.calls),p++)}let i=(0,h.buildCallGraph)(a,l);(0,h.detectEntryPoints)(a,i);let{flows:c,orphans:f}=(0,h.partitionFlows)(a,i),x={nodes:a,edges:i,flows:c,orphans:f,scannedFiles:p,durationMs:Date.now()-n};return z(e,x),x}function d(e,t,r,o,n){e.tool(t,r,o,n)}var Oe=["typescript","javascript","python","java","go","rust","tsx","jsx"],Ne=["node_modules","dist",".git","__pycache__","*.test.*","*.spec.*"];function j(e){d(e,"flowmap_analyze_workspace","Scan an entire codebase and return a full call graph \u2014 all functions, their parameters, and all call relationships between them. Use this first when exploring an unfamiliar codebase.",{workspacePath:b.z.string().describe("Absolute path to the repository root"),exclude:b.z.string().optional().describe("Comma-separated glob patterns to exclude. Defaults: node_modules,dist,.git,__pycache__,*.test.*,*.spec.*"),language:b.z.string().optional().describe("Filter to a single language: typescript, javascript, python, java, go, rust, tsx, jsx. Omit to scan all.")},async({workspacePath:t,exclude:r,language:o})=>{try{if(!$.existsSync(t))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${t}`,workspacePath:t})}]};let n=r?r.split(",").map(l=>l.trim()).filter(Boolean):Ne,s=o&&Oe.includes(o)?o:void 0,a=await u(t,{exclude:n,language:s});return{content:[{type:"text",text:JSON.stringify(a)}]}}catch(n){let s=n instanceof Error?n.message:String(n);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:s,workspacePath:t})}]}}})}var H=require("zod"),X=g(require("fs")),T=g(require("path")),O=require("@codeflow-map/core");var K=!1;function k(e){d(e,"flowmap_analyze_file","Scan a single file and return all functions defined in it, their parameters, and calls made within the file.",{filePath:H.z.string().describe("Absolute path to the file to analyse")},async({filePath:t})=>{try{if(!X.existsSync(t))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"FILE_NOT_FOUND",message:`File does not exist: ${t}`})}]};let r=T.extname(t),o=O.FILE_EXTENSION_MAP[r];if(!o)return{content:[{type:"text",text:JSON.stringify({error:!0,code:"UNSUPPORTED_LANGUAGE",message:`Unsupported file extension: ${r}`})}]};let n=R();K||(await(0,O.initTreeSitter)(n),K=!0);let s=Date.now(),a=T.basename(t),l=await(0,O.parseFile)(a,t,n,o);return{content:[{type:"text",text:JSON.stringify({filePath:a,functions:l.functions,calls:l.calls,durationMs:Date.now()-s})}]}}catch(r){let o=r instanceof Error?r.message:String(r);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:o})}]}}})}var C=require("zod"),B=g(require("fs"));function Z(e){d(e,"flowmap_get_callers","Return all functions that directly call the named function. Use this for impact analysis \u2014 to understand what breaks if you change a function's signature.",{functionName:C.z.string().describe("The function name to find callers of"),workspacePath:C.z.string().describe("Absolute path to the repository root")},async({functionName:t,workspacePath:r})=>{try{if(!B.existsSync(r))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${r}`,workspacePath:r})}]};let o=await u(r),n=o.nodes.filter(i=>i.name===t);if(n.length===0)return{content:[{type:"text",text:JSON.stringify({error:!0,code:"FUNCTION_NOT_FOUND",message:`No function named "${t}" found in the codebase.`,workspacePath:r})}]};let s=n[0],a=new Set(n.map(i=>i.id)),p=o.edges.filter(i=>a.has(i.to)).map(i=>{let c=o.nodes.find(f=>f.id===i.from);return{id:i.from,name:c?.name??"unknown",filePath:c?.filePath??"unknown",startLine:c?.startLine??0,callLine:i.line}});return{content:[{type:"text",text:JSON.stringify({target:t,targetId:s.id,callers:p,count:p.length})}]}}catch(o){let n=o instanceof Error?o.message:String(o);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:n,workspacePath:r})}]}}})}var L=require("zod"),V=g(require("fs"));function Y(e){d(e,"flowmap_get_callees","Return all functions directly called by the named function. Use this to understand what a function depends on.",{functionName:L.z.string().describe("The function name to find callees of"),workspacePath:L.z.string().describe("Absolute path to the repository root")},async({functionName:t,workspacePath:r})=>{try{if(!V.existsSync(r))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${r}`,workspacePath:r})}]};let o=await u(r),n=o.nodes.filter(i=>i.name===t);if(n.length===0)return{content:[{type:"text",text:JSON.stringify({error:!0,code:"FUNCTION_NOT_FOUND",message:`No function named "${t}" found in the codebase.`,workspacePath:r})}]};let s=n[0],a=new Set(n.map(i=>i.id)),p=o.edges.filter(i=>a.has(i.from)).map(i=>{let c=o.nodes.find(f=>f.id===i.to);return{id:i.to,name:c?.name??"unknown",filePath:c?.filePath??"unknown",startLine:c?.startLine??0,callLine:i.line}});return{content:[{type:"text",text:JSON.stringify({target:t,targetId:s.id,callees:p,count:p.length})}]}}catch(o){let n=o instanceof Error?o.message:String(o);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:n,workspacePath:r})}]}}})}var F=require("zod"),q=g(require("fs"));function Q(e){d(e,"flowmap_get_flow","Return the complete sub-graph reachable from a given function \u2014 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:F.z.string().describe("The starting function name"),workspacePath:F.z.string().describe("Absolute path to the repository root"),maxDepth:F.z.number().optional().describe("Maximum recursion depth. Default 10.")},async({functionName:t,workspacePath:r,maxDepth:o})=>{let n=o??10;try{if(!q.existsSync(r))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${r}`,workspacePath:r})}]};let s=await u(r),a=s.nodes.filter(y=>y.name===t);if(a.length===0)return{content:[{type:"text",text:JSON.stringify({error:!0,code:"FUNCTION_NOT_FOUND",message:`No function named "${t}" found in the codebase.`,workspacePath:r})}]};let l=a[0],p=new Map;for(let y of s.edges){let _=p.get(y.from)||[],m=s.nodes.find(A=>A.id===y.to);m&&(_.push({edge:y,node:m}),p.set(y.from,_))}let i=new Set,c=[],f=[],x=0,S=[l.id];for(i.add(l.id),c.push(l);S.length>0&&x<n;){let y=[];for(let _ of S){let m=p.get(_)||[];for(let{edge:A,node:N}of m)f.push(A),i.has(N.id)||(i.add(N.id),c.push(N),y.push(N.id))}S=y,x++}return{content:[{type:"text",text:JSON.stringify({entryFunction:t,nodes:c,edges:f,depth:x,totalFunctions:c.length})}]}}catch(s){let a=s instanceof Error?s.message:String(s);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:a,workspacePath:r})}]}}})}var ee=require("zod"),te=g(require("fs"));function re(e){d(e,"flowmap_list_entry_points","Return all detected entry points in the codebase \u2014 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:ee.z.string().describe("Absolute path to the repository root")},async({workspacePath:t})=>{try{if(!te.existsSync(t))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${t}`,workspacePath:t})}]};let r=await u(t),n=r.nodes.filter(s=>s.isEntryPoint).map(s=>({id:s.id,name:s.name,filePath:s.filePath,startLine:s.startLine,language:s.language,isExported:s.isExported,isAsync:s.isAsync}));return{content:[{type:"text",text:JSON.stringify({entryPoints:n,count:n.length,durationMs:r.durationMs})}]}}catch(r){let o=r instanceof Error?r.message:String(r);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:o,workspacePath:t})}]}}})}var ne=require("zod"),oe=g(require("fs"));function se(e){d(e,"flowmap_find_orphans","Return all functions that are never called from any entry point \u2014 potential dead code. Use this during refactoring to identify code that can safely be removed.",{workspacePath:ne.z.string().describe("Absolute path to the repository root")},async({workspacePath:t})=>{try{if(!oe.existsSync(t))return{content:[{type:"text",text:JSON.stringify({error:!0,code:"WORKSPACE_NOT_FOUND",message:`Directory does not exist: ${t}`,workspacePath:t})}]};let r=await u(t),o=r.orphans.map(n=>{let s=r.nodes.find(a=>a.id===n);return s?{id:s.id,name:s.name,filePath:s.filePath,startLine:s.startLine,language:s.language,isExported:s.isExported}:{id:n,name:"unknown",filePath:"unknown",startLine:0}});return{content:[{type:"text",text:JSON.stringify({orphans:o,count:o.length,durationMs:r.durationMs,note:"Exported functions may be used by external consumers \u2014 verify before deleting."})}]}}catch(r){let o=r instanceof Error?r.message:String(r);return{content:[{type:"text",text:JSON.stringify({error:!0,code:"PARSE_ERROR",message:o,workspacePath:t})}]}}})}function fe(){let e=new ae.McpServer({name:"callgraph-mcp",version:"1.0.0"});return Ee(e),e}function Ee(e){j(e),k(e),Z(e),Y(e),Q(e),re(e),se(e)}async function de(){let e=(process.env.FLOWMAP_TRANSPORT||"stdio").toLowerCase();e==="http"||e==="sse"?await Re():await we()}async function we(){let e=fe(),t=new ce.StdioServerTransport;await e.connect(t)}async function Re(){let e=parseInt(process.env.FLOWMAP_PORT||"3100",10),t=fe(),r=new le.StreamableHTTPServerTransport({sessionIdGenerator:()=>(0,pe.randomUUID)()}),o=(0,ie.createServer)(async(n,s)=>{let a=n.url||"/";a==="/mcp"||a==="/"?await r.handleRequest(n,s):s.writeHead(404).end("Not Found")});await t.connect(r),o.listen(e,()=>{process.stderr.write(`FlowMap MCP server listening on http://localhost:${e}/mcp
-`)})}de().catch(e=>{process.stderr.write(`FlowMap MCP server failed to start: ${e}
-`),process.exit(1)});
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+(0, server_1.startServer)().catch((err) => {
+    process.stderr.write(`FlowMap MCP server failed to start: ${err}\n`);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+exports.startServer = startServer;
+const http_1 = require("http");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const crypto_1 = require("crypto");
+const analyzeWorkspace_1 = require("./tools/analyzeWorkspace");
+const analyzeFile_1 = require("./tools/analyzeFile");
+const getCallers_1 = require("./tools/getCallers");
+const getCallees_1 = require("./tools/getCallees");
+const getFlow_1 = require("./tools/getFlow");
+const listEntryPoints_1 = require("./tools/listEntryPoints");
+const findOrphans_1 = require("./tools/findOrphans");
+const findCycles_1 = require("./tools/findCycles");
+const findDuplicates_1 = require("./tools/findDuplicates");
+function createMcpServer() {
+    const server = new mcp_js_1.McpServer({
+        name: 'callgraph-mcp',
+        version: '1.0.0',
+    });
+    registerTools(server);
+    return server;
+}
+function registerTools(server) {
+    (0, analyzeWorkspace_1.registerAnalyzeWorkspace)(server);
+    (0, analyzeFile_1.registerAnalyzeFile)(server);
+    (0, getCallers_1.registerGetCallers)(server);
+    (0, getCallees_1.registerGetCallees)(server);
+    (0, getFlow_1.registerGetFlow)(server);
+    (0, listEntryPoints_1.registerListEntryPoints)(server);
+    (0, findOrphans_1.registerFindOrphans)(server);
+    (0, findCycles_1.registerFindCycles)(server);
+    (0, findDuplicates_1.registerFindDuplicates)(server);
+}
+async function startServer() {
+    const mode = (process.env.FLOWMAP_TRANSPORT || 'stdio').toLowerCase();
+    if (mode === 'http' || mode === 'sse') {
+        await startHttpServer();
+    }
+    else {
+        await startStdioServer();
+    }
+}
+async function startStdioServer() {
+    const server = createMcpServer();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+async function startHttpServer() {
+    const port = parseInt(process.env.FLOWMAP_PORT || '3100', 10);
+    const server = createMcpServer();
+    const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+        sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
+    });
+    const httpServer = (0, http_1.createServer)(async (req, res) => {
+        const url = req.url || '/';
+        if (url === '/mcp' || url === '/') {
+            await transport.handleRequest(req, res);
+        }
+        else {
+            res.writeHead(404).end('Not Found');
+        }
+    });
+    await server.connect(transport);
+    httpServer.listen(port, () => {
+        process.stderr.write(`FlowMap MCP server listening on http://localhost:${port}/mcp\n`);
+    });
+}

package/dist/tools/analyzeFile.js

@@ -0,0 +1,109 @@
+"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.registerAnalyzeFile = registerAnalyzeFile;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const core_1 = require("@codeflow-map/core");
+const analysis_1 = require("../utils/analysis");
+const toolHelper_1 = require("../utils/toolHelper");
+let treeSitterInitialized = false;
+function registerAnalyzeFile(server) {
+    (0, toolHelper_1.registerTool)(server, 'flowmap_analyze_file', 'Scan a single file and return all functions defined in it, their parameters, and calls made within the file.', {
+        filePath: zod_1.z.string().describe('Absolute path to the file to analyse'),
+    }, async ({ filePath: absolutePath }) => {
+        try {
+            if (!fs.existsSync(absolutePath)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: true,
+                                code: 'FILE_NOT_FOUND',
+                                message: `File does not exist: ${absolutePath}`,
+                            }),
+                        }],
+                };
+            }
+            const ext = path.extname(absolutePath);
+            const languageId = core_1.FILE_EXTENSION_MAP[ext];
+            if (!languageId) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: true,
+                                code: 'UNSUPPORTED_LANGUAGE',
+                                message: `Unsupported file extension: ${ext}`,
+                            }),
+                        }],
+                };
+            }
+            const wasmDir = (0, analysis_1.resolveWasmDir)();
+            if (!treeSitterInitialized) {
+                await (0, core_1.initTreeSitter)(wasmDir);
+                treeSitterInitialized = true;
+            }
+            const startTime = Date.now();
+            const relativePath = path.basename(absolutePath);
+            const result = await (0, core_1.parseFile)(relativePath, absolutePath, wasmDir, languageId);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            filePath: relativePath,
+                            functions: result.functions,
+                            calls: result.calls,
+                            durationMs: Date.now() - startTime,
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: true,
+                            code: 'PARSE_ERROR',
+                            message,
+                        }),
+                    }],
+            };
+        }
+    });
+}

package/dist/tools/analyzeWorkspace.js

@@ -0,0 +1,95 @@
+"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.registerAnalyzeWorkspace = registerAnalyzeWorkspace;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const analysis_1 = require("../utils/analysis");
+const toolHelper_1 = require("../utils/toolHelper");
+const SUPPORTED_LANGUAGES = ['typescript', 'javascript', 'python', 'java', 'go', 'rust', 'tsx', 'jsx'];
+const DEFAULT_EXCLUDES = ['node_modules', 'dist', '.git', '__pycache__', '*.test.*', '*.spec.*'];
+function registerAnalyzeWorkspace(server) {
+    (0, toolHelper_1.registerTool)(server, 'flowmap_analyze_workspace', 'Scan an entire codebase and return a full call graph — all functions, their parameters, and all call relationships between them. Use this first when exploring an unfamiliar codebase.', {
+        workspacePath: zod_1.z.string().describe('Absolute path to the repository root'),
+        exclude: zod_1.z.string().optional().describe('Comma-separated glob patterns to exclude. Defaults: node_modules,dist,.git,__pycache__,*.test.*,*.spec.*'),
+        language: zod_1.z.string().optional().describe('Filter to a single language: typescript, javascript, python, java, go, rust, tsx, jsx. Omit to scan all.'),
+    }, async ({ workspacePath, exclude, language }) => {
+        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 excludeList = exclude
+                ? exclude.split(',').map(s => s.trim()).filter(Boolean)
+                : DEFAULT_EXCLUDES;
+            const lang = language && SUPPORTED_LANGUAGES.includes(language)
+                ? language
+                : undefined;
+            const graph = await (0, analysis_1.analyzeWorkspace)(workspacePath, {
+                exclude: excludeList,
+                language: lang,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(graph),
+                    }],
+            };
+        }
+        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/findCycles.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFindCycles(server: McpServer): void;

package/dist/tools/findCycles.js

@@ -0,0 +1,177 @@
+"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.registerFindCycles = registerFindCycles;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const analysis_1 = require("../utils/analysis");
+const toolHelper_1 = require("../utils/toolHelper");
+/** Tarjan's SCC — returns groups of node IDs that form cycles. */
+function findStronglyConnectedComponents(nodeIds, edges) {
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Map();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    // Build adjacency list
+    const adj = new Map();
+    for (const id of nodeIds)
+        adj.set(id, []);
+    for (const e of edges) {
+        if (adj.has(e.from) && adj.has(e.to)) {
+            adj.get(e.from).push(e.to);
+        }
+    }
+    function strongConnect(v) {
+        index.set(v, counter);
+        lowlink.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.set(v, true);
+        for (const w of (adj.get(v) ?? [])) {
+            if (!index.has(w)) {
+                strongConnect(w);
+                lowlink.set(v, Math.min(lowlink.get(v), lowlink.get(w)));
+            }
+            else if (onStack.get(w)) {
+                lowlink.set(v, Math.min(lowlink.get(v), index.get(w)));
+            }
+        }
+        if (lowlink.get(v) === index.get(v)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.set(w, false);
+                scc.push(w);
+            } while (w !== v);
+            sccs.push(scc);
+        }
+    }
+    for (const id of nodeIds) {
+        if (!index.has(id))
+            strongConnect(id);
+    }
+    return sccs;
+}
+function describeCycleEdges(cycle, edges) {
+    const memberSet = new Set(cycle);
+    return edges
+        .filter(e => memberSet.has(e.from) && memberSet.has(e.to))
+        .map(e => ({ from: e.from, to: e.to, line: e.line }));
+}
+function registerFindCycles(server) {
+    (0, toolHelper_1.registerTool)(server, 'flowmap_find_cycles', 'Detect all call cycles (circular dependencies / mutual recursion) in the codebase. Returns each cycle as an ordered list of functions that call each other in a loop, along with the exact call edges forming the cycle. Use this to identify architectural problems, infinite-recursion risks, or tightly coupled modules.', {
+        workspacePath: zod_1.z.string().describe('Absolute path to the repository root'),
+        minCycleLength: zod_1.z.number().int().min(1).optional().describe('Minimum number of functions in a cycle to report (default: 1, includes self-recursion)'),
+        exclude: zod_1.z.string().optional().describe('Comma-separated glob patterns to exclude. Defaults: node_modules,dist,.git,__pycache__,*.test.*,*.spec.*'),
+    }, async ({ workspacePath, minCycleLength = 1, exclude }) => {
+        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 DEFAULT_EXCLUDES = ['node_modules', 'dist', '.git', '__pycache__', '*.test.*', '*.spec.*'];
+            const excludeList = exclude
+                ? exclude.split(',').map(s => s.trim()).filter(Boolean)
+                : DEFAULT_EXCLUDES;
+            const graph = await (0, analysis_1.analyzeWorkspace)(workspacePath, { exclude: excludeList });
+            const nodeIds = graph.nodes.map(n => n.id);
+            const sccs = findStronglyConnectedComponents(nodeIds, graph.edges);
+            // A self-loop counts as a cycle of length 1
+            const selfLoopIds = new Set(graph.edges.filter(e => e.from === e.to).map(e => e.from));
+            const cyclesRaw = sccs.filter(scc => {
+                if (scc.length > 1)
+                    return scc.length >= minCycleLength;
+                // single-node SCC — only a cycle if there's a self-edge
+                return minCycleLength <= 1 && selfLoopIds.has(scc[0]);
+            });
+            const nodeById = new Map(graph.nodes.map(n => [n.id, n]));
+            const cycles = cyclesRaw.map((scc, i) => {
+                const members = scc.map(id => {
+                    const n = nodeById.get(id);
+                    return n
+                        ? { id, name: n.name, filePath: n.filePath, startLine: n.startLine, language: n.language }
+                        : { id, name: 'unknown', filePath: 'unknown', startLine: 0, language: 'unknown' };
+                });
+                const cycleEdges = describeCycleEdges(scc, graph.edges);
+                return {
+                    cycleIndex: i + 1,
+                    length: scc.length,
+                    members,
+                    edges: cycleEdges,
+                };
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            cycles,
+                            totalCycles: cycles.length,
+                            durationMs: graph.durationMs,
+                            scannedFiles: graph.scannedFiles,
+                            note: cycles.length === 0
+                                ? 'No cycles detected — the call graph is acyclic.'
+                                : `${cycles.length} cycle(s) found. Cycles involving many functions or cross-module calls are the highest priority to review.`,
+                        }),
+                    }],
+            };
+        }
+        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/findDuplicates.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFindDuplicates(server: McpServer): void;