project-graph-mcp 1.2.0 → 1.2.1

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.
Files changed (2) hide show
  1. package/README.md +113 -232
  2. package/package.json +2 -1
package/README.md CHANGED
@@ -1,113 +1,86 @@
1
+ [![npm version](https://img.shields.io/npm/v/project-graph-mcp)](https://www.npmjs.com/package/project-graph-mcp)
2
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org)
4
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/project-graph-mcp)
5
+
1
6
  # project-graph-mcp
2
7
 
3
8
  **MCP server for AI agents** — multi-language project graph, code quality analysis, and framework-specific lint rules.
4
9
 
5
10
  > Developed by [RND-PRO](https://rnd-pro.com)
6
11
 
7
- ## Why?
8
-
9
- AI agents struggle with large codebases:
10
- - **Context limits** — can't read entire project at once
11
- - **No architecture awareness** — miss patterns and conventions
12
- - **Framework blindness** — don't know React vs Vue vs Symbiote best practices
13
- - **Manual verification** — no structured way to track what's tested
14
-
15
- **Project Graph MCP solves this:**
16
- - 📦 **10-50x compression** — skeleton view fits in context window
17
- - 🌐 **Multi-language** — JavaScript, TypeScript, Python, Go
18
- - 🔍 **Code quality analysis** — dead code, complexity, duplicates
19
- - 🎯 **Framework-specific rules** — auto-detect and apply (React, Vue, Express, Node.js, Symbiote)
20
- - ✅ **Test checklists** — track @test/@expect annotations
21
-
22
- ## Features
23
-
24
- ### 🗺️ Project Graph (10-50x compression)
25
- - `get_skeleton` — Compact project overview with class/function counts
26
- - `expand` — Expand minified symbol to full code
27
- - `deps` — Dependency tree for any symbol
28
- - `usages` — Find all usages of a symbol
29
- - `get_focus_zone` — Auto-enriched context from git diff
30
- - `get_call_chain` — BFS call path analysis between symbols
31
-
32
- **Supported languages:** JavaScript (AST via Acorn), TypeScript/TSX, Python, Go — all with unified ParseResult API.
33
-
34
- ### 🧪 Test Checklists (Universal)
35
- - `get_pending_tests` — List tests from `@test/@expect` JSDoc annotations
36
- - `mark_test_passed` / `mark_test_failed` — Track progress
37
- - `get_test_summary` — Progress report
38
-
39
- Supports: Browser, API, CLI, and Integration tests.
40
-
41
- ### 🔍 Code Quality Analysis
42
- - `get_dead_code` — Find unused functions/classes (never called, not exported)
43
- - `generate_jsdoc` — Auto-generate JSDoc templates with @test/@expect
44
- - `get_similar_functions` — Detect duplicates (signature + structure similarity)
45
- - `get_complexity` — Cyclomatic complexity metrics (flags >10)
46
- - `get_large_files` — Files needing split (lines, functions, exports)
47
- - `get_outdated_patterns` — Legacy code patterns + redundant npm deps (Node 18+ built-ins)
48
- - `get_undocumented` — Find missing JSDoc (@test, @param, @returns)
49
- - `get_full_analysis` — Run ALL checks + Health Score (0-100)
50
-
51
- ### 🔧 Custom Rules (Configurable)
52
- - `get_custom_rules` — List all rulesets and rules
53
- - `set_custom_rule` — Add/update a rule (agent can configure)
54
- - `check_custom_rules` — Run custom rules analysis
55
-
56
- Includes 10 pre-built rulesets (62 rules): React 18/19, Vue 3, Next.js 15, Express 5, Fastify 5, NestJS 10, TypeScript 5, Node.js 22, Symbiote 2.x
57
-
58
- ### ⚙️ Filter Configuration
59
- - `get_filters` / `set_filters` — Configure excluded directories and patterns
60
- - `add_excludes` / `remove_excludes` — Modify exclude list
61
- - Automatic `.gitignore` parsing
62
- - **`.graphignore`** — Project-specific ignore file for custom rules (like .gitignore)
63
-
64
- ### 📚 Framework References
65
- - `get_framework_reference` — Auto-detect project framework and return AI-optimized docs
66
- - Includes: React 18/19, Vue 3, Next.js, Express, Node.js, Symbiote.js
67
-
68
- ### 📘 Agent Instructions
69
- - `get_agent_instructions` — Get coding guidelines, JSDoc format, architecture standards
70
- - [AGENT_ROLE.md](AGENT_ROLE.md) — Full system prompt for agents
71
- - [AGENT_ROLE_MINIMAL.md](AGENT_ROLE_MINIMAL.md) — Minimal variant (agent self-discovers)
72
-
73
- ### 💡 Response Hints
74
- Every tool response includes contextual coaching hints:
75
- - `get_skeleton` → "Use expand() to see code, deps() for architecture"
76
- - `invalidate_cache` → "Cache cleared. Run get_skeleton() to rebuild"
77
- - `get_dead_code` → "Review before removing — some may be used dynamically"
78
- - `get_undocumented` → "Use generate_jsdoc() for auto-generation"
79
- - Large classes auto-detected → "Run get_complexity() to find refactoring targets"
12
+ An MCP server that parses your source code into a **10-50x compressed skeleton** — classes, functions, imports, and dependencies in a minified JSON. Agents navigate the graph using `expand`, `deps`, and `usages` without reading irrelevant files.
80
13
 
81
- ### 🛡️ Security
82
- - **Path Traversal Protection** all tool paths validated to stay within workspace root
83
- - **Workspace Isolation** — MCP roots set workspace boundary, tools cannot escape it
14
+ > [!TIP]
15
+ > **132 kB, 47 files, zero external dependencies.** Add one line to your MCP config and the server downloads itself on the next IDE restart.
84
16
 
85
- ### 🌐 MCP Ecosystem
86
- Best used together with [**agent-pool-mcp**](https://www.npmjs.com/package/agent-pool-mcp) — multi-agent task delegation via Gemini CLI:
87
-
88
- | Layer | project-graph-mcp | agent-pool-mcp |
89
- |-------|-------------------|----------------|
90
- | **Primary IDE agent** | Navigates codebase, runs analysis | Delegates tasks, consults peer |
91
- | **Gemini CLI workers** | Available as MCP tool inside workers | Executes delegated tasks |
17
+ ### Project Skeleton (10-50x compression)
92
18
 
93
- Combined config for both:
19
+ The server builds an AST-based graph of your project and outputs a minified JSON representation. The agent reads this to understand the architecture. When it needs deeper details, it calls `expand` or `deps`:
94
20
 
95
21
  ```json
96
22
  {
97
- "mcpServers": {
98
- "project-graph": {
99
- "command": "npx",
100
- "args": ["-y", "project-graph-mcp"]
101
- },
102
- "agent-pool": {
103
- "command": "npx",
104
- "args": ["-y", "agent-pool-mcp"]
105
- }
106
- }
23
+ "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
24
+ "s": { "files": 23, "classes": 10, "functions": 65 },
25
+ "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
26
+ "e": 35, "o": 7, "d": 5, "F": 63
107
27
  }
108
28
  ```
109
29
 
110
- ## Installation
30
+ `L` = legend (actual symbol names), `s` = stats, `n` = nodes with methods/properties, `e` = edges, `o` = orphans, `d` = duplicates, `F` = functions.
31
+
32
+ ### Multi-Language Parsers
33
+
34
+ JavaScript is parsed via AST (Acorn). TypeScript, Python, and Go use lightweight regex-based parsers — no heavy external binaries, just enough to extract classes, functions, imports, and calls. All parsers return a unified `ParseResult` structure.
35
+
36
+ ```javascript
37
+ // Python — triple quotes, hash comments
38
+ stripStringsAndComments(code, { tripleQuote: true, hashComment: true })
39
+
40
+ // Go — backtick strings without interpolation
41
+ stripStringsAndComments(code, { backtick: true, templateInterpolation: false })
42
+ ```
43
+
44
+ ### Code Quality Analysis
45
+
46
+ - **Dead code detection** — unused functions, classes, exports, variables, and imports
47
+ - **Cyclomatic complexity** — flags functions over threshold, identifies refactoring targets
48
+ - **Duplicate detection** — finds functionally similar functions by signature + structure similarity
49
+ - **Large file analysis** — candidates for splitting by lines, functions, and exports count
50
+ - **Legacy pattern finder** — outdated code patterns and redundant npm deps (built into Node.js 18+)
51
+ - **Health Score (0-100)** — aggregated result from all checks in one call
52
+
53
+ ### Test Checklists
54
+
55
+ JSDoc annotations (`@test` and `@expect`) define test checklists directly in the code:
56
+
57
+ ```javascript
58
+ /**
59
+ * Create new user via API
60
+ *
61
+ * @test request: POST /api/users with valid data
62
+ * @expect status: 201 Created
63
+ */
64
+ async createUser(data) { ... }
65
+ ```
66
+
67
+ The agent calls `get_pending_tests`, runs the test, then `mark_test_passed`. Supports browser, API, CLI, and integration test types.
68
+
69
+ ### Custom Rules & Framework References
70
+
71
+ 10 pre-built rulesets (62 rules) for React 18/19, Vue 3, Next.js 15, Express 5, Fastify 5, NestJS 10, TypeScript 5, Node.js 22, and [Symbiote.js](https://github.com/symbiotejs/symbiote.js). The server auto-detects your project type and returns adapted documentation via `get_framework_reference`.
72
+
73
+ Custom project conventions can be added in the `rules/` directory or configured by the agent via `set_custom_rule`.
74
+
75
+ ### Response Hints
76
+
77
+ Every tool response includes contextual coaching — if the agent finds a massive function, the server suggests checking its complexity. After expanding a class, it hints to explore dependencies.
78
+
79
+ ### Security
80
+
81
+ **Path Traversal Protection** — all incoming paths are validated using `resolve` and `startsWith`. The agent cannot escape the working directory. An attempt to read `../../etc/passwd` returns a direct error.
82
+
83
+ ## Quick Start
111
84
 
112
85
  Add to your IDE's MCP configuration:
113
86
 
@@ -122,11 +95,10 @@ Add to your IDE's MCP configuration:
122
95
  }
123
96
  ```
124
97
 
125
- Restart your IDE — project-graph-mcp will be downloaded and started automatically.
126
- **Zero dependencies** — only Node.js >= 18 required.
98
+ Restart your IDE — project-graph-mcp will be downloaded and started automatically.
127
99
 
128
100
  <details>
129
- <summary>📍 Where is my MCP config file?</summary>
101
+ <summary>Where is my MCP config file?</summary>
130
102
 
131
103
  | IDE | Config path |
132
104
  |-----|------------|
@@ -136,12 +108,12 @@ Restart your IDE — project-graph-mcp will be downloaded and started automatica
136
108
  | Windsurf | `.windsurf/mcp.json` |
137
109
  | Claude Code | Run: `claude mcp add project-graph npx -y project-graph-mcp` |
138
110
 
139
- See **[CONFIGURATION.md](CONFIGURATION.md)** for all supported IDEs.
111
+ See **[CONFIGURATION.md](CONFIGURATION.md)** for all supported IDEs (Antigravity, Gemini CLI, Cursor, VS Code, Zed, Claude Desktop, OpenCode, Jenova, Firebase Genkit, NVIDIA AIQ).
140
112
 
141
113
  </details>
142
114
 
143
115
  <details>
144
- <summary>📦 Alternative: from source</summary>
116
+ <summary>Alternative: from source</summary>
145
117
 
146
118
  ```bash
147
119
  git clone https://github.com/rnd-pro/project-graph-mcp
@@ -152,153 +124,62 @@ cd project-graph-mcp
152
124
 
153
125
  </details>
154
126
 
155
- ## CLI Usage
127
+ ## CLI
156
128
 
157
129
  ```bash
158
- # Get project skeleton (minified graph)
159
- node src/server.js skeleton src/components
160
-
161
- # Expand minified symbol
162
- node src/server.js expand SN
163
-
164
- # Get dependencies
165
- node src/server.js deps SNG
166
-
167
- # List pending tests
168
- node src/server.js pending src/
169
-
170
- # Get test progress summary
171
- node src/server.js summary src/
172
-
173
- # Show filter configuration
174
- node src/server.js filters
175
-
176
- # Show agent instructions
177
- node src/server.js instructions
178
-
179
- # Code Quality Analysis
130
+ node src/server.js skeleton src/ # Project skeleton
131
+ node src/server.js expand SN # Expand minified symbol
132
+ node src/server.js deps SNG # Get dependencies
180
133
  node src/server.js deadcode src/ # Find unused code
181
- node src/server.js jsdoc src/file.js # Generate JSDoc
182
- node src/server.js similar src/ # Find duplicates
183
134
  node src/server.js complexity src/ # Cyclomatic complexity
184
- node src/server.js largefiles src/ # Large files
185
- node src/server.js outdated . # Legacy patterns
186
-
187
- # Show help
188
- node src/server.js help
189
- ```
190
-
191
- ## MCP Configuration
192
-
193
- See **[CONFIGURATION.md](CONFIGURATION.md)** for client-specific setup:
194
- - Antigravity / Gemini CLI
195
- - Cursor / Zed / Continue
196
- - VS Code + Copilot / CodeGPT
197
- - Claude Desktop
198
- - OpenCode / Crush
199
- - Jenova (mobile)
200
- - Firebase Genkit / NVIDIA AIQ
201
-
202
- ## Test Annotations
203
-
204
- Add to your code:
205
- ```javascript
206
- /**
207
- * Create new user via API
208
- *
209
- * @test request: POST /api/users with valid data
210
- * @expect status: 201 Created
211
- * @expect db: User row created
212
- */
213
- async createUser(data) { ... }
214
- ```
215
-
216
- Supported types:
217
- - **Browser**: click, key, drag, type, scroll, hover
218
- - **API**: request, call, invoke, mock
219
- - **CLI**: run, exec, spawn, input
220
- - **Integration**: setup, action, teardown, wait
221
-
222
- Agent workflow:
135
+ node src/server.js similar src/ # Find duplicates
136
+ node src/server.js pending src/ # List pending tests
137
+ node src/server.js help # All commands
223
138
  ```
224
- 1. get_pending_tests("src/")
225
- → [{ id: "createUser.0", type: "request", description: "POST /api/users" }]
226
-
227
- 2. Agent runs the test
228
139
 
229
- 3. mark_test_passed("createUser.0")
140
+ ## MCP Ecosystem
230
141
 
231
- 4. get_test_summary("src/")
232
- → { total: 9, passed: 1, pending: 8, progress: 11 }
233
- ```
234
-
235
- ## .graphignore
142
+ Best used together with [**agent-pool-mcp**](https://www.npmjs.com/package/agent-pool-mcp) — multi-agent task delegation via [Gemini CLI](https://github.com/google-gemini/gemini-cli):
236
143
 
237
- Exclude files from custom rules checking (useful for files containing code examples):
144
+ | Layer | project-graph-mcp | agent-pool-mcp |
145
+ |-------|-------------------|----------------|
146
+ | **Primary IDE agent** | Navigates codebase, runs analysis | Delegates tasks, consults peer |
147
+ | **Gemini CLI workers** | Available as MCP tool inside workers | Executes delegated tasks |
238
148
 
239
- ```
240
- # Comments start with #
241
- instructions.js # Exact filename
242
- outdated-patterns.js # Files with code examples
243
- *.min.js # Glob suffix
244
- dist/* # Glob prefix
149
+ ```json
150
+ {
151
+ "mcpServers": {
152
+ "project-graph": {
153
+ "command": "npx",
154
+ "args": ["-y", "project-graph-mcp"]
155
+ },
156
+ "agent-pool": {
157
+ "command": "npx",
158
+ "args": ["-y", "agent-pool-mcp"]
159
+ }
160
+ }
161
+ }
245
162
  ```
246
163
 
247
- Searches parent directories automatically (like .gitignore).
164
+ > [!IMPORTANT]
165
+ > Each Gemini CLI worker can have its own project-graph-mcp instance — workers navigate the codebase independently, without blocking the primary agent.
248
166
 
249
- ## Architecture
167
+ ## Documentation
250
168
 
251
- ```
252
- project-graph-mcp/
253
- ├── src/
254
- │ ├── server.js # Entry point (CLI/MCP mode switch)
255
- │ ├── mcp-server.js # MCP server + response hints
256
- │ ├── cli.js / cli-handlers.js # CLI commands
257
- │ ├── tool-defs.js # MCP tool schemas
258
- │ ├── tools.js # Graph tools (skeleton, expand, deps)
259
- │ ├── workspace.js # Path resolution + traversal protection
260
- │ ├── parser.js # AST parser (Acorn) + language routing
261
- │ ├── lang-typescript.js # TypeScript/TSX regex parser
262
- │ ├── lang-python.js # Python regex parser
263
- │ ├── lang-go.js # Go regex parser
264
- │ ├── lang-utils.js # Shared: stripStringsAndComments
265
- │ ├── graph-builder.js # Minified graph + legend
266
- │ ├── filters.js # Exclude patterns, .gitignore
267
- │ ├── dead-code.js # Unused code detection
268
- │ ├── complexity.js # Cyclomatic complexity
269
- │ ├── similar-functions.js # Duplicate detection
270
- │ ├── large-files.js # File size analysis
271
- │ ├── outdated-patterns.js # Legacy pattern detection
272
- │ ├── full-analysis.js # Health Score (0-100)
273
- │ ├── undocumented.js # Missing JSDoc finder
274
- │ ├── jsdoc-generator.js # JSDoc template generation
275
- │ ├── custom-rules.js # Configurable lint rules
276
- │ ├── framework-references.js # Framework-specific docs
277
- │ ├── test-annotations.js # @test/@expect parsing
278
- │ └── instructions.js # Agent guidelines
279
- ├── rules/ # Pre-built rule sets (JSON)
280
- ├── references/ # Framework reference docs
281
- ├── vendor/
282
- │ ├── acorn.mjs # AST parser (MIT, vendored)
283
- │ └── walk.mjs # AST walker (MIT, vendored)
284
- └── tests/
285
- ├── parser.test.js
286
- └── mcp.test.js
287
- ```
169
+ - [CONFIGURATION.md](CONFIGURATION.md) — Setup for all supported IDEs
170
+ - [ARCHITECTURE.md](ARCHITECTURE.md) — Source code structure
171
+ - [AGENT_ROLE.md](AGENT_ROLE.md) — Full system prompt for agents
172
+ - [AGENT_ROLE_MINIMAL.md](AGENT_ROLE_MINIMAL.md) Minimal variant (agent self-discovers)
288
173
 
289
- ## Skeleton Example
174
+ ## Related Projects
175
+ - [agent-pool-mcp](https://github.com/rnd-pro/agent-pool-mcp) — Multi-agent orchestration via Gemini CLI
176
+ - [Symbiote.js](https://github.com/symbiotejs/symbiote.js) — Isomorphic Reactive Web Components framework
177
+ - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) — SSG/SSR toolkit for modern web applications
290
178
 
291
- ```json
292
- {
293
- "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
294
- "s": { "files": 23, "classes": 10, "functions": 65 },
295
- "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
296
- "e": 35, "o": 7, "d": 5, "F": 63
297
- }
298
- ```
179
+ ## License
299
180
 
300
- **L** = Legend, **s** = stats, **n** = nodes, **e** = edges, **o** = orphans, **d** = duplicates, **F** = functions
181
+ MIT © [RND-PRO.com](https://rnd-pro.com)
301
182
 
302
- ## License
183
+ ---
303
184
 
304
- MIT
185
+ **Made with ❤️ by the RND-PRO team**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-graph-mcp",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "type": "module",
5
5
  "description": "MCP server for AI agents — multi-language project graph (JS, TS, Python, Go), code quality analysis, and framework-specific lint rules. Zero dependencies.",
6
6
  "main": "src/server.js",
@@ -43,6 +43,7 @@
43
43
  "url": "https://github.com/rnd-pro/project-graph-mcp"
44
44
  },
45
45
  "author": "RND-PRO",
46
+ "homepage": "https://github.com/rnd-pro/project-graph-mcp",
46
47
  "license": "MIT",
47
48
  "engines": {
48
49
  "node": ">=18.0.0"