callgraph-mcp 1.1.0 → 1.3.0

package/README.md

@@ -10,6 +10,22 @@ Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/co
 
 > **Bundled grammars:** TypeScript, JavaScript, TSX, JSX, Python, and Go grammars are included. After install, they are available in `callgraph-mcp/grammars`.
 
+---
+
+## Why Deterministic Analysis Matters
+
+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.
+
+**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.
+
+**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
 
@@ -89,43 +105,67 @@ Then point your client at it:
 
 ## Example Use Cases
 
-### Explore an unfamiliar codebase
+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.
+
+---
+
+> *"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.
+
+---
+
+### Architecture problems
+
+> *"Which functions in this codebase are architectural nasty-surprises — called by everything but calling a lot themselves. I want names, file paths, and exact counts."*
 
-> *"I just cloned this repo. Walk me through where execution starts and what the main flows are."*
+The agent calls `flowmap_analyze_workspace(workspacePath)` to get the full graph, then filters for nodes with high in-degree (many callers) and high out-degree (many callees). These are the structural chokepoints — functions where a bug propagates in both directions. Returned with exact counts. No approximation.
 
-The agent calls `flowmap_list_entry_points` to find where code begins, then `flowmap_get_flow` on each entry point to trace the full execution paths. It can describe the architecture without reading every file.
+---
+
+> *"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.
 
 ---
 
-### Understand the impact of a change before making it
+### Dead code and cleanup
 
-> *"I need to change the signature of `processPayment`. What will break?"*
+> *"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_get_callers("processPayment", workspacePath)` to get every call site across the entire codebase — with file paths and line numbers — so it knows exactly what needs updating before touching anything.
+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.
 
 ---
 
-### Safe refactoring — find what to clean up
+### Onboarding
 
-> *"We're doing a big cleanup. What functions are safe to delete?"*
+> *"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_find_orphans(workspacePath)`. Functions with zero reachability from entry points and not exported are strong deletion candidates. Combined with `flowmap_get_callers` for verification, this gives a confident dead-code list.
+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.
 
 ---
 
-### Trace a bug through the call chain
+### Refactoring
 
-> *"The `submitOrder` function is failing. What does it call, and what does each of those call?"*
+> *"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_get_flow("submitOrder", workspacePath, maxDepth: 5)` to get the full downstream call tree — showing exactly which functions are in the execution path and which files they live in.
+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.
 
 ---
 
-### PR review — understand what changed
+### AI agent review
 
-> *"This PR modifies `validateUser`. What's the blast radius?"*
+> *"Cursor just made changes across 14 files. Based on what it touched, what else in the codebase should I be nervous about that it didn't touch."*
 
-The agent calls `flowmap_get_callers("validateUser", workspacePath)` to enumerate every caller, then `flowmap_get_flow("validateUser", workspacePath)` to show all downstream dependency. It can summarise the risk surface of the change deterministically.
+The agent calls `flowmap_get_callers` for each modified function and `flowmap_get_flow` for each modified function. The union of those results — minus the files already touched — is the set of functions that depend on the changes but weren't updated. These are the places where silent breakage is most likely. Returned as a precise list, not a guess about what "might be related".
 
 ---
 
@@ -144,34 +184,6 @@ 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
 
----
-
-## Example Prompts for VS Code Copilot
-
-```
-List all entry points in this workspace
-```
-```
-What functions call `buildCallGraph` anywhere in the codebase?
-```
-```
-Show me the full execution path starting from `startServer`, up to 6 levels deep
-```
-```
-Find all dead code — functions that are never reached from any entry point
-```
-```
-What does `parseFile` directly depend on?
-```
-```
-I'm changing `connectDb`. Who calls it? Give me file paths and line numbers.
-```
-```
-Analyze just src/api/routes.ts and tell me what it exports and what it calls
-```
-
----
-
 ## How It Works
 
 1. Tree-sitter WASM grammars parse each source file into an AST — no runtime execution, no imports

package/package.json

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