project-graph-mcp 1.2.0 → 1.2.2

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 -236
  2. package/package.json +2 -1
package/README.md CHANGED
@@ -1,113 +1,82 @@
1
- # project-graph-mcp
2
-
3
- **MCP server for AI agents** — multi-language project graph, code quality analysis, and framework-specific lint rules.
4
-
5
- > Developed by [RND-PRO](https://rnd-pro.com)
6
-
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)
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)
72
5
 
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"
6
+ # project-graph-mcp
80
7
 
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
8
+ 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.
84
9
 
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:
10
+ > [!TIP]
11
+ > **132 kB, 47 files, zero external dependencies.** Add one line to your MCP config and the server downloads itself on the next IDE restart.
87
12
 
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 |
13
+ ### Project Skeleton (10-50x compression)
92
14
 
93
- Combined config for both:
15
+ 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
16
 
95
17
  ```json
96
18
  {
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
- }
19
+ "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
20
+ "s": { "files": 23, "classes": 10, "functions": 65 },
21
+ "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
22
+ "e": 35, "o": 7, "d": 5, "F": 63
107
23
  }
108
24
  ```
109
25
 
110
- ## Installation
26
+ `L` = legend (actual symbol names), `s` = stats, `n` = nodes with methods/properties, `e` = edges, `o` = orphans, `d` = duplicates, `F` = functions.
27
+
28
+ ### Multi-Language Parsers
29
+
30
+ 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.
31
+
32
+ ```javascript
33
+ // Python — triple quotes, hash comments
34
+ stripStringsAndComments(code, { tripleQuote: true, hashComment: true })
35
+
36
+ // Go — backtick strings without interpolation
37
+ stripStringsAndComments(code, { backtick: true, templateInterpolation: false })
38
+ ```
39
+
40
+ ### Code Quality Analysis
41
+
42
+ - **Dead code detection** — unused functions, classes, exports, variables, and imports
43
+ - **Cyclomatic complexity** — flags functions over threshold, identifies refactoring targets
44
+ - **Duplicate detection** — finds functionally similar functions by signature + structure similarity
45
+ - **Large file analysis** — candidates for splitting by lines, functions, and exports count
46
+ - **Legacy pattern finder** — outdated code patterns and redundant npm deps (built into Node.js 18+)
47
+ - **Health Score (0-100)** — aggregated result from all checks in one call
48
+
49
+ ### Test Checklists
50
+
51
+ JSDoc annotations (`@test` and `@expect`) define test checklists directly in the code:
52
+
53
+ ```javascript
54
+ /**
55
+ * Create new user via API
56
+ *
57
+ * @test request: POST /api/users with valid data
58
+ * @expect status: 201 Created
59
+ */
60
+ async createUser(data) { ... }
61
+ ```
62
+
63
+ The agent calls `get_pending_tests`, runs the test, then `mark_test_passed`. Supports browser, API, CLI, and integration test types.
64
+
65
+ ### Custom Rules & Framework References
66
+
67
+ 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`.
68
+
69
+ Custom project conventions can be added in the `rules/` directory or configured by the agent via `set_custom_rule`.
70
+
71
+ ### Response Hints
72
+
73
+ 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.
74
+
75
+ ### Security
76
+
77
+ **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.
78
+
79
+ ## Quick Start
111
80
 
112
81
  Add to your IDE's MCP configuration:
113
82
 
@@ -122,11 +91,10 @@ Add to your IDE's MCP configuration:
122
91
  }
123
92
  ```
124
93
 
125
- Restart your IDE — project-graph-mcp will be downloaded and started automatically.
126
- **Zero dependencies** — only Node.js >= 18 required.
94
+ Restart your IDE — project-graph-mcp will be downloaded and started automatically.
127
95
 
128
96
  <details>
129
- <summary>📍 Where is my MCP config file?</summary>
97
+ <summary>Where is my MCP config file?</summary>
130
98
 
131
99
  | IDE | Config path |
132
100
  |-----|------------|
@@ -136,12 +104,12 @@ Restart your IDE — project-graph-mcp will be downloaded and started automatica
136
104
  | Windsurf | `.windsurf/mcp.json` |
137
105
  | Claude Code | Run: `claude mcp add project-graph npx -y project-graph-mcp` |
138
106
 
139
- See **[CONFIGURATION.md](CONFIGURATION.md)** for all supported IDEs.
107
+ 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
108
 
141
109
  </details>
142
110
 
143
111
  <details>
144
- <summary>📦 Alternative: from source</summary>
112
+ <summary>Alternative: from source</summary>
145
113
 
146
114
  ```bash
147
115
  git clone https://github.com/rnd-pro/project-graph-mcp
@@ -152,153 +120,62 @@ cd project-graph-mcp
152
120
 
153
121
  </details>
154
122
 
155
- ## CLI Usage
123
+ ## CLI
156
124
 
157
125
  ```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
126
+ node src/server.js skeleton src/ # Project skeleton
127
+ node src/server.js expand SN # Expand minified symbol
128
+ node src/server.js deps SNG # Get dependencies
180
129
  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
130
  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:
131
+ node src/server.js similar src/ # Find duplicates
132
+ node src/server.js pending src/ # List pending tests
133
+ node src/server.js help # All commands
223
134
  ```
224
- 1. get_pending_tests("src/")
225
- → [{ id: "createUser.0", type: "request", description: "POST /api/users" }]
226
-
227
- 2. Agent runs the test
228
135
 
229
- 3. mark_test_passed("createUser.0")
136
+ ## MCP Ecosystem
230
137
 
231
- 4. get_test_summary("src/")
232
- → { total: 9, passed: 1, pending: 8, progress: 11 }
233
- ```
234
-
235
- ## .graphignore
138
+ 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
139
 
237
- Exclude files from custom rules checking (useful for files containing code examples):
140
+ | Layer | project-graph-mcp | agent-pool-mcp |
141
+ |-------|-------------------|----------------|
142
+ | **Primary IDE agent** | Navigates codebase, runs analysis | Delegates tasks, consults peer |
143
+ | **Gemini CLI workers** | Available as MCP tool inside workers | Executes delegated tasks |
238
144
 
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
145
+ ```json
146
+ {
147
+ "mcpServers": {
148
+ "project-graph": {
149
+ "command": "npx",
150
+ "args": ["-y", "project-graph-mcp"]
151
+ },
152
+ "agent-pool": {
153
+ "command": "npx",
154
+ "args": ["-y", "agent-pool-mcp"]
155
+ }
156
+ }
157
+ }
245
158
  ```
246
159
 
247
- Searches parent directories automatically (like .gitignore).
160
+ > [!IMPORTANT]
161
+ > Each Gemini CLI worker can have its own project-graph-mcp instance — workers navigate the codebase independently, without blocking the primary agent.
248
162
 
249
- ## Architecture
163
+ ## Documentation
250
164
 
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
- ```
165
+ - [CONFIGURATION.md](CONFIGURATION.md) — Setup for all supported IDEs
166
+ - [ARCHITECTURE.md](ARCHITECTURE.md) — Source code structure
167
+ - [AGENT_ROLE.md](AGENT_ROLE.md) — Full system prompt for agents
168
+ - [AGENT_ROLE_MINIMAL.md](AGENT_ROLE_MINIMAL.md) Minimal variant (agent self-discovers)
288
169
 
289
- ## Skeleton Example
170
+ ## Related Projects
171
+ - [agent-pool-mcp](https://github.com/rnd-pro/agent-pool-mcp) — Multi-agent orchestration via Gemini CLI
172
+ - [Symbiote.js](https://github.com/symbiotejs/symbiote.js) — Isomorphic Reactive Web Components framework
173
+ - [JSDA-Kit](https://github.com/rnd-pro/jsda-kit) — SSG/SSR toolkit for modern web applications
290
174
 
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
- ```
175
+ ## License
299
176
 
300
- **L** = Legend, **s** = stats, **n** = nodes, **e** = edges, **o** = orphans, **d** = duplicates, **F** = functions
177
+ MIT © [RND-PRO.com](https://rnd-pro.com)
301
178
 
302
- ## License
179
+ ---
303
180
 
304
- MIT
181
+ **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.2",
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"