callgraph-mcp 1.4.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,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.
 
 ---
 
@@ -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. 
 
 ---
 

package/package.json

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