callgraph-mcp 1.4.0 → 1.4.2

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,26 +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 |
-| `flowmap_find_cycles` | `workspacePath` | `minCycleLength`, `exclude` | All call cycles (circular dependencies / mutual recursion) with exact member functions and the edges forming each loop |
+Optional parameters shown in `[brackets]`.
 
-### Experimental
+| 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 |
 
-> 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`).
+**`workspacePath`** — absolute path to the repo root (e.g. `/home/user/my-project` or `C:\projects\my-app`).
 
 ---
 
@@ -106,31 +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_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. |
+| `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.
 
 ---
 
@@ -152,7 +145,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. 
 
 ---
 
@@ -160,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.
 
 ---
 
@@ -168,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. 
 
 ---
 
@@ -180,14 +173,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:
@@ -201,9 +186,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. 
 
 ---
 
@@ -211,9 +196,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.0",
+  "version": "1.4.2",
   "description": "MCP server for codebase call-flow analysis. Local, deterministic, language-agnostic. Powered by @codeflow-map/core.",
   "keywords": [
     "mcp",