callgraph-mcp 1.3.0 → 1.4.1

package/README.md

@@ -29,7 +29,7 @@ Most AI coding tools answer structural questions about your codebase by reading
 
 ## Setup
 
-### Option 1 — VS Code Copilot via `npx` (no install required)
+### Option 1 — VS Code via `npx` (no install required)
 
 Add to your project's `.vscode/mcp.json`:
 
@@ -79,17 +79,21 @@ Then point your client at it:
 
 ## Tools Reference
 
-| Tool | Required params | Optional | What it returns |
-|------|----------------|----------|-----------------|
-| `flowmap_analyze_workspace` | `workspacePath` | `exclude`, `language` | Full call graph: all nodes, edges, flows, orphans |
-| `flowmap_analyze_file` | `filePath` | — | Functions and call sites in a single file |
-| `flowmap_get_callers` | `functionName`, `workspacePath` | — | Every function across the workspace that directly calls the named function |
-| `flowmap_get_callees` | `functionName`, `workspacePath` | — | Every function the named function directly calls |
-| `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 |
+Optional parameters shown in `[brackets]`.
 
-**`workspacePath`** is the absolute path to the repository root (e.g. `/home/user/my-project` or `C:\projects\my-app`).
+| Tool | Parameters | Returns |
+|------|-----------|---------|
+| `flowmap_analyze_workspace` | `workspacePath`, [`exclude`], [`language`] | Full call graph: nodes, edges, flows, orphans |
+| `flowmap_analyze_file` | `filePath` | Functions and call sites in one file |
+| `flowmap_get_callers` | `functionName`, `workspacePath` | Direct callers of the function |
+| `flowmap_get_callees` | `functionName`, `workspacePath` | Functions the named function calls |
+| `flowmap_get_flow` | `functionName`, `workspacePath`, [`maxDepth`=10] | Full BFS subgraph reachable from a function |
+| `flowmap_list_entry_points` | `workspacePath` | Mains, route handlers, CLI commands, React roots |
+| `flowmap_find_orphans` | `workspacePath` | Functions unreachable from any entry point |
+| `flowmap_find_cycles` | `workspacePath`, [`minCycleLength`], [`exclude`] | All circular call chains with exact edges |
+| `flowmap_find_duplicates` *(experimental)* | `workspacePath`, [`similarityThreshold`=0.75], [`minCallees`=2], [`exclude`] | Function clusters with similar callee sets |
+
+**`workspacePath`** — absolute path to the repo root (e.g. `/home/user/my-project` or `C:\projects\my-app`).
 
 ---
 
@@ -97,29 +101,29 @@ Then point your client at it:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `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_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `FLOWMAP_PORT` | `3100` | HTTP port (http transport only) |
+| `FLOWMAP_GRAMMARS` | *(bundled)* | Override path to WASM grammar files |
+| `FLOWMAP_DUP_THRESHOLD` | `0.75` | Jaccard similarity threshold for `find_duplicates` (0–1) |
+| `FLOWMAP_DUP_MIN_CALLEES` | `2` | Min callee count for `find_duplicates` |
 
 ---
 
 ## Example Use Cases
 
-These prompts work because the answers come from the call graph index — not from the model's memory of what your code might look like. Every result is exact, reproducible, and complete regardless of codebase size.
-
 ---
 
 ### PR review and change safety
 
 > *"I just modified `processPayment`. Without reading any code, tell me every function that could break and rank them by how many hops away they are from the change."*
 
-The agent calls `flowmap_get_callers("processPayment", workspacePath)` for the direct impact radius (1 hop), then recursively traverses callers-of-callers to build a ranked list by distance. The output is a tiered risk report: direct callers first, then second-order, then third-order. No file needs to be read. No attention dilution across 300 files. Just the graph.
+The agent calls `flowmap_get_callers("processPayment", workspacePath)` for the direct impact radius (1 hop), then recursively traverses callers-of-callers to build a ranked list by distance.
 
 ---
 
 > *"We're about to merge a PR that touches `validateCart`. Give me an impact report — what's the worst case if this function throws."*
 
-The agent calls `flowmap_get_flow("validateCart", workspacePath)` to map every function reachable downstream, then `flowmap_get_callers("validateCart", workspacePath)` to map every upstream caller. Together these define the complete risk surface: everything that feeds into it and everything that depends on it. Worst-case impact is the union of both subgraphs — stated precisely, not estimated.
+The agent calls `flowmap_get_flow("validateCart", workspacePath)` to map every function reachable downstream, then `flowmap_get_callers("validateCart", workspacePath)` to map every upstream caller.
 
 ---
 
@@ -133,7 +137,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.
 
 ---
 
@@ -149,7 +153,7 @@ The agent calls `flowmap_find_orphans(workspacePath)`. This returns every functi
 
 > *"I just joined this team. Walk me through this codebase starting from the entry points — explain each major flow in plain English without me having to read a single file."*
 
-The agent calls `flowmap_list_entry_points(workspacePath)` to find every main, route handler, CLI command, and React root. Then it calls `flowmap_get_flow` on each one to trace the execution. It can then narrate each flow top-to-bottom — what each function does in the chain, where the boundaries are, and how the pieces connect. A new engineer can understand the architecture in minutes, not days. And because the graph is built from actual parse results, nothing is invented.
+The agent calls `flowmap_list_entry_points(workspacePath)` to find every main, route handler, CLI command, and React root. Then it calls `flowmap_get_flow` on each one to trace the execution.
 
 ---
 
@@ -157,7 +161,7 @@ The agent calls `flowmap_list_entry_points(workspacePath)` to find every main, r
 
 > *"I want to extract the payment logic into its own module. Based purely on call relationships, which functions naturally belong together and which ones would need to stay behind."*
 
-The agent calls `flowmap_analyze_workspace(workspacePath)` and uses the graph to find the connected component of functions reachable from payment-related entry points. Functions that are exclusively reachable through payment flows are natural candidates to extract. Functions that are shared with other flows are the cut points — they stay, or need to be duplicated. This is module boundary detection from the graph structure, not from naming conventions or folder layout.
+The agent calls `flowmap_analyze_workspace(workspacePath)` and uses the graph to find the connected component of functions reachable from payment-related entry points. 
 
 ---
 
@@ -184,6 +188,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;