callgraph-mcp 1.4.2 → 1.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +59 -49
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# callgraph-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p>**CallGraph MCP Server** — exposes deterministic call-graph analysis for any codebase as [Model Context Protocol](https://modelcontextprotocol.io/) tools. Give your AI agent a precise, structural map of your code — no hallucination, no guessing.</p>
|
|
4
4
|
|
|
5
|
-
Fully local. No cloud. No LLM. No telemetry
|
|
5
|
+
<p>Fully local. No cloud. No LLM. No telemetry.</p>
|
|
6
6
|
|
|
7
|
-
Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/core) and Tree-sitter WASM parsers
|
|
7
|
+
<p>Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/core) and Tree-sitter WASM parsers.</p>
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
<p>**Supports:** TypeScript · JavaScript · TSX · JSX · Python · Go</p>
|
|
10
|
+
|
|
11
|
+
|
|
10
12
|
|
|
11
13
|
> **Bundled grammars:** TypeScript, JavaScript, TSX, JSX, Python, and Go grammars are included. After install, they are available in `callgraph-mcp/grammars`.
|
|
12
14
|
|
|
@@ -14,24 +16,24 @@ Powered by [`@codeflow-map/core`](https://www.npmjs.com/package/@codeflow-map/co
|
|
|
14
16
|
|
|
15
17
|
## Why Deterministic Analysis Matters
|
|
16
18
|
|
|
17
|
-
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
|
|
19
|
+
<p>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:</p>
|
|
18
20
|
|
|
19
|
-
**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.
|
|
21
|
+
- **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.
|
|
22
|
+
- **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.
|
|
23
|
+
- **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.
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
<p>**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.**</p>
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
---
|
|
24
28
|
|
|
25
|
-
**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.**
|
|
26
29
|
|
|
27
|
-
---
|
|
28
30
|
|
|
29
31
|
|
|
30
32
|
## Setup
|
|
31
33
|
|
|
32
34
|
### Option 1 — VS Code via `npx` (no install required)
|
|
33
35
|
|
|
34
|
-
Add to your project's `.vscode/mcp.json
|
|
36
|
+
<p>Add to your project's `.vscode/mcp.json`:</p>
|
|
35
37
|
|
|
36
38
|
```json
|
|
37
39
|
{
|
|
@@ -48,15 +50,15 @@ Add to your project's `.vscode/mcp.json`:
|
|
|
48
50
|
}
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
Start the server in your editor. WASM grammars are bundled — no environment variables needed
|
|
53
|
+
<p>Start the server in your editor. WASM grammars are bundled — no environment variables needed.</p>
|
|
52
54
|
|
|
53
55
|
> **Tip:** Create `.vscode/mcp.json` via the Command Palette -> **MCP: Add Server** -> **stdio**.
|
|
54
56
|
|
|
55
57
|
### Option 2 — HTTP-SSE (shared or remote server)
|
|
56
58
|
|
|
57
|
-
Use `FLOWMAP_TRANSPORT=http` for HTTP-SSE compatible clients
|
|
59
|
+
<p>Use `FLOWMAP_TRANSPORT=http` for HTTP-SSE compatible clients.</p>
|
|
58
60
|
|
|
59
|
-
Start the server
|
|
61
|
+
<p>Start the server:</p>
|
|
60
62
|
|
|
61
63
|
```bash
|
|
62
64
|
FLOWMAP_TRANSPORT=http FLOWMAP_PORT=3100 npx callgraph-mcp
|
|
@@ -64,7 +66,7 @@ FLOWMAP_TRANSPORT=http FLOWMAP_PORT=3100 npx callgraph-mcp
|
|
|
64
66
|
# $env:FLOWMAP_TRANSPORT="http"; $env:FLOWMAP_PORT="3100"; npx callgraph-mcp
|
|
65
67
|
```
|
|
66
68
|
|
|
67
|
-
Then point your client at it
|
|
69
|
+
<p>Then point your client at it:</p>
|
|
68
70
|
|
|
69
71
|
```json
|
|
70
72
|
{
|
|
@@ -79,33 +81,41 @@ Then point your client at it:
|
|
|
79
81
|
|
|
80
82
|
## Tools Reference
|
|
81
83
|
|
|
82
|
-
Optional parameters shown in `[brackets]
|
|
84
|
+
<p>Optional parameters shown in `[brackets]`.</p>
|
|
83
85
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
86
|
+
<table>
|
|
87
|
+
<colgroup><col width="22%"><col width="38%"><col width="40%"></colgroup>
|
|
88
|
+
<thead><tr><th>Tool</th><th>Parameters</th><th>Returns</th></tr></thead>
|
|
89
|
+
<tbody>
|
|
90
|
+
<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>
|
|
91
|
+
<tr><td><code>flowmap_analyze_file</code></td><td><code>filePath</code></td><td>Functions and call sites in one file</td></tr>
|
|
92
|
+
<tr><td><code>flowmap_get_callers</code></td><td><code>functionName</code>, <code>workspacePath</code></td><td>Direct callers of the function</td></tr>
|
|
93
|
+
<tr><td><code>flowmap_get_callees</code></td><td><code>functionName</code>, <code>workspacePath</code></td><td>Functions the named function calls</td></tr>
|
|
94
|
+
<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>
|
|
95
|
+
<tr><td><code>flowmap_list_entry_points</code></td><td><code>workspacePath</code></td><td>Mains, route handlers, CLI commands, React roots</td></tr>
|
|
96
|
+
<tr><td><code>flowmap_find_orphans</code></td><td><code>workspacePath</code></td><td>Functions unreachable from any entry point</td></tr>
|
|
97
|
+
<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>
|
|
98
|
+
<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>
|
|
99
|
+
</tbody>
|
|
100
|
+
</table>
|
|
95
101
|
|
|
96
|
-
|
|
102
|
+
<p>**`workspacePath`** — absolute path to the repo root (e.g. `/home/user/my-project` or `C:\projects\my-app`).</p>
|
|
97
103
|
|
|
98
104
|
---
|
|
99
105
|
|
|
100
106
|
## Environment Variable Reference
|
|
101
107
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
108
|
+
<table>
|
|
109
|
+
<colgroup><col width="22%"><col width="15%"><col width="63%"></colgroup>
|
|
110
|
+
<thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead>
|
|
111
|
+
<tbody>
|
|
112
|
+
<tr><td><code>FLOWMAP_TRANSPORT</code></td><td><code>stdio</code></td><td><code>stdio</code> or <code>http</code></td></tr>
|
|
113
|
+
<tr><td><code>FLOWMAP_PORT</code></td><td><code>3100</code></td><td>HTTP port (http transport only)</td></tr>
|
|
114
|
+
<tr><td><code>FLOWMAP_GRAMMARS</code></td><td><em>(bundled)</em></td><td>Override path to WASM grammar files</td></tr>
|
|
115
|
+
<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>
|
|
116
|
+
<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>
|
|
117
|
+
</tbody>
|
|
118
|
+
</table>
|
|
109
119
|
|
|
110
120
|
---
|
|
111
121
|
|
|
@@ -117,13 +127,13 @@ Optional parameters shown in `[brackets]`.
|
|
|
117
127
|
|
|
118
128
|
> *"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."*
|
|
119
129
|
|
|
120
|
-
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
|
|
130
|
+
<p>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.</p>
|
|
121
131
|
|
|
122
132
|
---
|
|
123
133
|
|
|
124
134
|
> *"We're about to merge a PR that touches `validateCart`. Give me an impact report — what's the worst case if this function throws."*
|
|
125
135
|
|
|
126
|
-
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
|
|
136
|
+
<p>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.</p>
|
|
127
137
|
|
|
128
138
|
---
|
|
129
139
|
|
|
@@ -131,13 +141,13 @@ The agent calls `flowmap_get_flow("validateCart", workspacePath)` to map every f
|
|
|
131
141
|
|
|
132
142
|
> *"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."*
|
|
133
143
|
|
|
134
|
-
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
|
|
144
|
+
<p>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.</p>
|
|
135
145
|
|
|
136
146
|
---
|
|
137
147
|
|
|
138
148
|
> *"Find every cycle in the call graph. For each one tell me which file I should break the dependency in to resolve it cleanly."*
|
|
139
149
|
|
|
140
|
-
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
|
|
150
|
+
<p>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.</p>
|
|
141
151
|
|
|
142
152
|
---
|
|
143
153
|
|
|
@@ -145,7 +155,7 @@ The agent calls `flowmap_find_cycles(workspacePath)`. Each cycle is returned as
|
|
|
145
155
|
|
|
146
156
|
> *"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."*
|
|
147
157
|
|
|
148
|
-
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
|
|
158
|
+
<p>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.</p>
|
|
149
159
|
|
|
150
160
|
---
|
|
151
161
|
|
|
@@ -153,7 +163,7 @@ The agent calls `flowmap_find_orphans(workspacePath)`. This returns every functi
|
|
|
153
163
|
|
|
154
164
|
> *"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."*
|
|
155
165
|
|
|
156
|
-
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
|
|
166
|
+
<p>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.</p>
|
|
157
167
|
|
|
158
168
|
---
|
|
159
169
|
|
|
@@ -161,7 +171,7 @@ The agent calls `flowmap_list_entry_points(workspacePath)` to find every main, r
|
|
|
161
171
|
|
|
162
172
|
> *"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."*
|
|
163
173
|
|
|
164
|
-
The agent calls `flowmap_analyze_workspace(workspacePath)` and uses the graph to find the connected component of functions reachable from payment-related entry points
|
|
174
|
+
<p>The agent calls `flowmap_analyze_workspace(workspacePath)` and uses the graph to find the connected component of functions reachable from payment-related entry points.</p>
|
|
165
175
|
|
|
166
176
|
---
|
|
167
177
|
|
|
@@ -169,13 +179,13 @@ The agent calls `flowmap_analyze_workspace(workspacePath)` and uses the graph to
|
|
|
169
179
|
|
|
170
180
|
> *"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."*
|
|
171
181
|
|
|
172
|
-
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"
|
|
182
|
+
<p>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".</p>
|
|
173
183
|
|
|
174
184
|
---
|
|
175
185
|
|
|
176
186
|
### Agentic code generation with structural guardrails
|
|
177
187
|
|
|
178
|
-
When an agent is generating new code, it can call `flowmap_analyze_workspace` before and after to verify
|
|
188
|
+
<p>When an agent is generating new code, it can call `flowmap_analyze_workspace` before and after to verify:</p>
|
|
179
189
|
- New functions are connected to the call graph (not accidentally orphaned)
|
|
180
190
|
- No existing entry points were broken
|
|
181
191
|
- The intended call relationships were actually created
|
|
@@ -186,9 +196,9 @@ When an agent is generating new code, it can call `flowmap_analyze_workspace` be
|
|
|
186
196
|
|
|
187
197
|
> *"We've been using an AI agent to build this codebase for 3 months. How much logic has it silently duplicated?"*
|
|
188
198
|
|
|
189
|
-
Agents optimize for the current instruction, not long-term architecture. It copies, tweaks slightly, and moves on. It satisfied the local goal
|
|
199
|
+
<p>Agents optimize for the current instruction, not long-term architecture. It copies, tweaks slightly, and moves on. It satisfied the local goal.</p>
|
|
190
200
|
|
|
191
|
-
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
|
|
201
|
+
<p>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.</p>
|
|
192
202
|
|
|
193
203
|
---
|
|
194
204
|
|
|
@@ -196,7 +206,7 @@ The agent calls `flowmap_find_duplicates(workspacePath)`. Each cluster in the re
|
|
|
196
206
|
|
|
197
207
|
> *"The agent has been adding features for weeks. Are there any circular call dependencies I should know about before this becomes a production problem?"*
|
|
198
208
|
|
|
199
|
-
The agent calls `flowmap_find_cycles(workspacePath)`. Every cycle is returned with the exact functions involved
|
|
209
|
+
<p>The agent calls `flowmap_find_cycles(workspacePath)`. Every cycle is returned with the exact functions involved.</p>
|
|
200
210
|
|
|
201
211
|
---
|
|
202
212
|
|
|
@@ -208,7 +218,7 @@ The agent calls `flowmap_find_cycles(workspacePath)`. Every cycle is returned wi
|
|
|
208
218
|
4. Entry points are detected: functions that are never called but call others
|
|
209
219
|
5. The graph is partitioned into independent execution flows via BFS from each entry point
|
|
210
220
|
|
|
211
|
-
Files are parsed in parallel batches of 50. Results are cached for 30 seconds — repeated calls within a session are instant
|
|
221
|
+
<p>Files are parsed in parallel batches of 50. Results are cached for 30 seconds — repeated calls within a session are instant.</p>
|
|
212
222
|
|
|
213
223
|
---
|
|
214
224
|
|
|
@@ -221,4 +231,4 @@ Files are parsed in parallel batches of 50. Results are cached for 30 seconds
|
|
|
221
231
|
|
|
222
232
|
## License
|
|
223
233
|
|
|
224
|
-
MIT
|
|
234
|
+
<p>MIT</p>
|