callgraph-mcp 1.4.1 → 1.4.3

package/README.md

@@ -8,6 +8,8 @@ Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/co
 
 **Supports:** TypeScript · JavaScript · TSX · JSX · Python · Go
 
+![Cyclic call graph demo](https://raw.githubusercontent.com/devricky-codes/callgraph-mcp/refs/heads/main/assets/cyclic.gif)
+
 > **Bundled grammars:** TypeScript, JavaScript, TSX, JSX, Python, and Go grammars are included. After install, they are available in `callgraph-mcp/grammars`.
 
 ---
@@ -16,15 +18,15 @@ Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/co
 
 Most AI coding tools answer structural questions about your codebase by reading source files as text and reasoning over them. This causes three compounding failure modes:
 
-**Hallucination.** When asked "what calls `processPayment`?", a model without structural grounding will guess based on naming patterns and training priors. It will confidently name callers that don't exist and miss ones that do. The larger the codebase, the worse this gets.
+- **Hallucination.** When asked "what calls `processPayment`?", a model without structural grounding will guess based on naming patterns and training priors. It will confidently name callers that don't exist and miss ones that do.
+- **Lost in the middle.** Research shows that LLMs systematically fail to recall information from the middle of long contexts. Paste a 200-file codebase into context and the model will answer based on whatever happened to land near the top or bottom.
+- **Attention dilution.** Even when information is present, spreading the model's attention across tens of thousands of lines means each individual fact gets less weight. A critical edge in the call graph competed for attention with everything else.
 
-**Lost in the middle.** Research shows that LLMs systematically fail to recall information from the middle of long contexts. Paste a 200-file codebase into context and the model will answer based on whatever happened to land near the top or bottom. Functions buried in the middle of that context window are effectively invisible.
+**callgraph-mcp eliminates all three.** It never reads your code as prose. It parses every file into an AST using Tree-sitter, builds an exact directed call graph, and answers structural queries against that graph. Every caller, every callee, every reachable function, every cycle - returned as a precise index. The answer is always the same regardless of how large your codebase is, which files happen to be in context, or how deeply buried a function is. **There is no probability involved. There is no attention to dilute.**
 
-**Attention dilution.** Even when information is present, spreading the model's attention across tens of thousands of lines means each individual fact gets less weight. A critical edge in the call graph mentioned once in one file competes for attention with everything else. The model's confidence in its answer has no relationship to whether the answer is correct.
+---
 
-**callgraph-mcp eliminates all three.** It never reads your code as prose. It parses every file into an AST using Tree-sitter, builds an exact directed call graph, and answers structural queries against that graph. Every caller, every callee, every reachable function, every cycle — returned as a precise index. The answer is always the same regardless of how large your codebase is, which files happen to be in context, or how deeply buried a function is. **There is no probability involved. There is no attention to dilute.**
 
----
 
 
 ## Setup
@@ -81,17 +83,21 @@ Then point your client at it:
 
 Optional parameters shown in `[brackets]`.
 
-| 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 |
+<table>
+<colgroup><col width="22%"><col width="38%"><col width="40%"></colgroup>
+<thead><tr><th>Tool</th><th>Parameters</th><th>Returns</th></tr></thead>
+<tbody>
+<tr><td><code>flowmap_analyze_workspace</code></td><td><code>workspacePath</code>, [<code>exclude</code>], [<code>language</code>]</td><td>Full call graph: nodes, edges, flows, orphans</td></tr>
+<tr><td><code>flowmap_analyze_file</code></td><td><code>filePath</code></td><td>Functions and call sites in one file</td></tr>
+<tr><td><code>flowmap_get_callers</code></td><td><code>functionName</code>, <code>workspacePath</code></td><td>Direct callers of the function</td></tr>
+<tr><td><code>flowmap_get_callees</code></td><td><code>functionName</code>, <code>workspacePath</code></td><td>Functions the named function calls</td></tr>
+<tr><td><code>flowmap_get_flow</code></td><td><code>functionName</code>, <code>workspacePath</code>, [<code>maxDepth</code>=10]</td><td>Full BFS subgraph reachable from a function</td></tr>
+<tr><td><code>flowmap_list_entry_points</code></td><td><code>workspacePath</code></td><td>Mains, route handlers, CLI commands, React roots</td></tr>
+<tr><td><code>flowmap_find_orphans</code></td><td><code>workspacePath</code></td><td>Functions unreachable from any entry point</td></tr>
+<tr><td><code>flowmap_find_cycles</code></td><td><code>workspacePath</code>, [<code>minCycleLength</code>], [<code>exclude</code>]</td><td>All circular call chains with exact edges</td></tr>
+<tr><td><code>flowmap_find_duplicates</code> <em>(experimental)</em></td><td><code>workspacePath</code>, [<code>similarityThreshold</code>=0.75], [<code>minCallees</code>=2], [<code>exclude</code>]</td><td>Function clusters with similar callee sets</td></tr>
+</tbody>
+</table>
 
 **`workspacePath`** — absolute path to the repo root (e.g. `/home/user/my-project` or `C:\projects\my-app`).
 
@@ -99,13 +105,17 @@ Optional parameters shown in `[brackets]`.
 
 ## Environment Variable Reference
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `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` |
+<table>
+<colgroup><col width="22%"><col width="15%"><col width="63%"></colgroup>
+<thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td><code>FLOWMAP_TRANSPORT</code></td><td><code>stdio</code></td><td><code>stdio</code> or <code>http</code></td></tr>
+<tr><td><code>FLOWMAP_PORT</code></td><td><code>3100</code></td><td>HTTP port (http transport only)</td></tr>
+<tr><td><code>FLOWMAP_GRAMMARS</code></td><td><em>(bundled)</em></td><td>Override path to WASM grammar files</td></tr>
+<tr><td><code>FLOWMAP_DUP_THRESHOLD</code></td><td><code>0.75</code></td><td>Jaccard similarity threshold for <code>find_duplicates</code> (0–1)</td></tr>
+<tr><td><code>FLOWMAP_DUP_MIN_CALLEES</code></td><td><code>2</code></td><td>Min callee count for <code>find_duplicates</code></td></tr>
+</tbody>
+</table>
 
 ---
 
@@ -145,7 +155,7 @@ The agent calls `flowmap_find_cycles(workspacePath)`. Each cycle is returned as
 
 > *"I want to delete code safely. Give me every function that is provably unreachable — not called by anything, not an entry point. Include file and line number."*
 
-The agent calls `flowmap_find_orphans(workspacePath)`. This returns every function not reachable from any entry point in the call graph — with file path and line number for each one. These are not "probably unused" — they are graph-theoretically unreachable. Safe to delete. No cross-checking required.
+The agent calls `flowmap_find_orphans(workspacePath)`. This returns every function not reachable from any entry point in the call graph — with file path and line number for each one. 
 
 ---
 
@@ -173,14 +183,6 @@ The agent calls `flowmap_get_callers` for each modified function and `flowmap_ge
 
 ---
 
-### Understand a single file before editing it
-
-> *"What does `src/auth/middleware.ts` export and what does it call?"*
-
-The agent calls `flowmap_analyze_file("/abs/path/to/src/auth/middleware.ts")` to get a precise list of every function, its parameters, return type, and all outgoing calls — without needing to read the file itself.
-
----
-
 ### Agentic code generation with structural guardrails
 
 When an agent is generating new code, it can call `flowmap_analyze_workspace` before and after to verify:
@@ -194,9 +196,9 @@ When an agent is generating new code, it can call `flowmap_analyze_workspace` be
 
 > *"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.
+Agents optimize for the current instruction, not long-term architecture. It copies, tweaks slightly, and moves on. It satisfied the local goal.
 
-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.
+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. 
 
 ---
 
@@ -204,9 +206,7 @@ The agent calls `flowmap_find_duplicates(workspacePath)`. Each cluster in the re
 
 > *"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.
+The agent calls `flowmap_find_cycles(workspacePath)`. Every cycle is returned with the exact functions involved.
 
 ---
 

package/package.json

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