project-graph-mcp 1.0.0

package/AGENT_ROLE.md

@@ -0,0 +1,126 @@
+# Project Graph MCP - Agent Role
+
+You have access to **Project Graph MCP** — a suite of code analysis and project navigation tools.
+
+## 🧭 Navigation & Understanding
+| Tool | Purpose |
+|------|---------|
+| `get_structure` | Get file/folder tree |
+| `get_skeleton` | Get code structure (classes, functions, exports) |
+| `expand` | Deep dive into a class or function |
+| `get_agent_instructions` | Get project coding guidelines |
+| `get_framework_reference` | Get framework AI reference (auto-detects or explicit) |
+
+## 🧪 Testing System
+
+| Tool | Purpose |
+|------|---------|
+| `get_pending_tests` | List @test/@expect annotations needing verification |
+| `mark_test_passed` / `mark_test_failed` | Track test results |
+| `get_test_summary` | Progress report |
+
+### When to Write @test/@expect
+Add annotations to JSDoc when creating or modifying **interactive methods**:
+- `onclick` / `onchange` / `oninput` event handlers
+- Methods that change DOM state (show/hide, toggle classes/attributes)
+- Navigation and routing methods
+- Form submission and validation handlers
+- Any method with user-visible side effects
+
+### Browser Testing Workflow (VERIFICATION mode)
+After code changes, you MUST verify UI with this flow:
+
+```
+1. get_pending_tests(path)           → see what needs verification
+2. Open browser via browser_subagent → execute each test step
+3. mark_test_passed(testId)          → or mark_test_failed(testId, reason)
+4. get_test_summary(path)            → final report before completing task
+```
+
+**Rule**: If `get_pending_tests()` returns items, they MUST be executed in the browser before the task is marked complete. Never skip browser verification when @test annotations exist.
+
+### Example
+```javascript
+/**
+ * Delete selected persona
+ *
+ * @test click: Click delete button on persona card
+ * @test click: Confirm in dialog
+ * @expect element: Persona removed from list
+ * @expect visual: Toast notification appears
+ */
+async onDeletePersona() { ... }
+```
+
+## 🔍 Code Quality Analysis
+| Tool | Purpose |
+|------|---------|
+| `get_full_analysis` | Run ALL checks + Health Score (0-100) |
+| `get_dead_code` | Find unused functions/classes |
+| `get_undocumented` | Find missing JSDoc |
+| `get_similar_functions` | Detect code duplicates |
+| `get_complexity` | Cyclomatic complexity metrics |
+| `get_large_files` | Files needing split |
+| `get_outdated_patterns` | Legacy patterns + redundant npm deps |
+| `generate_jsdoc` | Auto-generate JSDoc templates |
+
+## 🔧 Custom Rules (Configurable)
+| Tool | Purpose |
+|------|---------|
+| `get_custom_rules` | List all rulesets |
+| `set_custom_rule` | Add/update framework-specific rules |
+| `check_custom_rules` | Run analysis (auto-detects applicable rules) |
+
+### Auto-Detection
+Rules are applied automatically based on:
+- `package.json` dependencies (e.g., `@symbiotejs/symbiote`)
+- Import patterns in source code
+- Code patterns (e.g., `extends Symbiote`)
+
+### Pre-built Rulesets (85 rules)
+| Ruleset | Rules | Framework |
+|---------|-------|-----------|
+| `symbiote-2x` | 12 | Symbiote.js 2.x |
+| `symbiote-3x` | 17 | Symbiote.js 3.x |
+| `react-18` | 6 | React 18 |
+| `react-19` | 5 | React 19 (Server Components) |
+| `vue-3` | 5 | Vue 3 Composition API |
+| `nextjs-15` | 6 | Next.js 15 App Router |
+| `express-5` | 5 | Express.js 5.x |
+| `fastify-5` | 5 | Fastify 5.x |
+| `nestjs-10` | 6 | NestJS 10.x |
+| `typescript-5` | 5 | TypeScript 5.x |
+| `node-22` | 7 | Node.js 22+ |
+
+### Creating New Rules
+Read project workflow docs (e.g., `.agent/workflows/symbiote-audit.md`) and use `set_custom_rule`:
+```json
+{
+  "ruleSet": "framework-2x",
+  "rule": {
+    "id": "framework-no-antipattern",
+    "name": "Avoid antipattern",
+    "pattern": "badCode",
+    "patternType": "string",
+    "replacement": "Use goodCode",
+    "severity": "warning",
+    "filePattern": "*.js",
+    "docs": "https://docs.example.com"
+  }
+}
+```
+
+## ⚙️ Filters
+| Tool | Purpose |
+|------|---------|
+| `get_filters` / `set_filters` | Configure excluded directories |
+| `add_excludes` / `remove_excludes` | Modify exclude list |
+
+## 🚀 Recommended Workflow
+
+1. **Start**: `get_structure` → understand project layout
+2. **Dive**: `get_skeleton` → map code architecture
+3. **Analyze**: `get_full_analysis` → find issues (Health Score)
+4. **Check Rules**: `check_custom_rules` → framework-specific violations
+5. **Fix**: Address issues by severity (error → warning → info)
+6. **Verify**: `get_pending_tests` → execute in browser → `mark_test_passed/failed` → `get_test_summary`

package/AGENT_ROLE_MINIMAL.md

@@ -0,0 +1,54 @@
+# Project Graph MCP
+
+You have **Project Graph MCP** tools available — code analysis, project navigation, and framework-specific linting.
+
+## Quick Start
+
+1. `get_skeleton(path)` — Get code structure (classes, functions, exports)
+2. `get_full_analysis(path)` — Health Score (0-100) with all code quality checks
+3. `get_agent_instructions` — Project coding guidelines and JSDoc format
+
+## Core Tools
+
+### Navigation
+- `get_skeleton` — Compact project overview with symbol legend
+- `expand(symbol)` — Deep dive into class/function (use symbols from skeleton's `L` field)
+- `deps(symbol)` — Dependency tree (imports, usedBy, calls)
+- `usages(symbol)` — Find all usages across project
+
+### Code Quality
+- `get_full_analysis` — Run ALL checks + Health Score
+- `get_dead_code` — Unused functions/classes  
+- `get_undocumented` — Missing JSDoc
+- `get_similar_functions` — Code duplicates
+- `get_complexity` — Cyclomatic complexity (flags >10)
+- `get_large_files` — Files needing split
+- `get_outdated_patterns` — Legacy patterns
+
+### Testing
+- `get_pending_tests` — List @test/@expect annotations
+- `mark_test_passed(testId)` / `mark_test_failed(testId, reason)`
+- `get_test_summary` — Progress report
+
+### Custom Rules
+- `check_custom_rules(path)` — Run framework-specific analysis (auto-detected)
+- `get_custom_rules` — List all rulesets (62 rules across 10 frameworks)
+- `set_custom_rule` — Add/update rules
+
+**Pre-built rulesets:** React 18/19, Vue 3, Next.js 15, Express 5, Fastify 5, NestJS 10, TypeScript 5, Node.js 22, Symbiote 2.x
+
+## Workflow
+
+```
+1. get_skeleton("src/")        → Understand structure
+2. get_full_analysis("src/")   → Find issues (Health Score)
+3. check_custom_rules("src/")  → Framework violations
+4. Fix by severity: error → warning → info
+5. get_pending_tests("src/")   → Verification checklist
+```
+
+## Tips
+
+- Skeleton uses minified symbols (e.g., `SN` = `SymNode`). Check `_keys` and `L` fields for legend.
+- File paths in results are relative to the scanned directory.
+- Use `.graphignore` file to exclude files from custom rules checking.

package/CONFIGURATION.md

@@ -0,0 +1,188 @@
+# MCP Client Configuration
+
+Configuration examples for popular MCP clients (2026).
+
+---
+
+## Desktop & IDE Clients
+
+### Antigravity / Gemini CLI
+```json
+// ~/.gemini/antigravity/mcp_config.json
+{
+  "mcpServers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Cursor
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+### Zed
+```json
+// ~/.config/zed/settings.json
+{
+  "context_servers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+### VS Code + Copilot
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+### Continue
+```yaml
+# ~/.continue/mcpServers/project-graph.yaml
+name: project-graph
+command: node
+args:
+  - /path/to/project-graph-mcp/src/server.js
+```
+
+Or JSON format in `~/.continue/mcpServers/project-graph.json`:
+```json
+{
+  "name": "project-graph",
+  "command": "node",
+  "args": ["/path/to/project-graph-mcp/src/server.js"]
+}
+```
+
+### Sourcegraph Cody
+```json
+// ~/.sourcegraph/cody.json
+{
+  "mcp": {
+    "servers": {
+      "project-graph": {
+        "command": "node",
+        "args": ["/path/to/project-graph-mcp/src/server.js"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## AI Assistants
+
+### Claude Desktop
+```json
+// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+// Windows: %APPDATA%\Claude\claude_desktop_config.json
+{
+  "mcpServers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+### OpenCode / Crush
+```json
+// ~/.config/opencode/config.json
+{
+  "mcp": {
+    "servers": {
+      "project-graph": {
+        "command": "node",
+        "args": ["/path/to/project-graph-mcp/src/server.js"]
+      }
+    }
+  }
+}
+```
+
+### CodeGPT (VS Code / JetBrains)
+```json
+// Extension settings
+{
+  "codegpt.mcp.servers": {
+    "project-graph": {
+      "command": "node",
+      "args": ["/path/to/project-graph-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+---
+
+## Mobile & Cross-Platform
+
+### Jenova (iOS/Android)
+Add via app settings → MCP Servers → Custom:
+- **Name**: project-graph
+- **Command**: node
+- **Args**: /path/to/project-graph-mcp/src/server.js
+
+---
+
+## Enterprise & Frameworks
+
+### Firebase Genkit
+```javascript
+import { mcpClient } from '@genkit-ai/mcp';
+
+const projectGraph = mcpClient({
+  command: 'node',
+  args: ['/path/to/project-graph-mcp/src/server.js'],
+});
+```
+
+### NVIDIA AIQ Toolkit
+```yaml
+# aiq_config.yaml
+mcp_servers:
+  project-graph:
+    command: node
+    args:
+      - /path/to/project-graph-mcp/src/server.js
+```
+
+---
+
+## Any MCP Client
+
+The server uses **stdio transport** — JSON-RPC 2.0 over stdin/stdout.
+
+### Protocol
+- **Methods**: `initialize`, `tools/list`, `tools/call`
+- **Transport**: stdio (no HTTP server)
+
+### Manual Test
+```bash
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node src/server.js
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RND-PRO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# project-graph-mcp
+
+**MCP server for AI agents** — project graph, code quality analysis, and framework-specific lint rules.
+
+> Developed by [RND-PRO](https://rnd-pro.com)
+
+## Why?
+
+AI agents struggle with large codebases:
+- **Context limits** — can't read entire project at once
+- **No architecture awareness** — miss patterns and conventions
+- **Framework blindness** — don't know React vs Vue vs Symbiote best practices
+- **Manual verification** — no structured way to track what's tested
+
+**Project Graph MCP solves this:**
+- 📦 **10-50x compression** — skeleton view fits in context window
+- 🔍 **Code quality analysis** — dead code, complexity, duplicates
+- 🎯 **Framework-specific rules** — auto-detect and apply (React, Vue, Express, Node.js, Symbiote)
+- ✅ **Test checklists** — track @test/@expect annotations
+
+## Features
+
+### 🗺️ Project Graph (10-50x compression)
+- `get_skeleton` — Compact project overview with class/function counts
+- `expand` — Expand minified symbol to full code
+- `deps` — Dependency tree for any symbol
+- `usages` — Find all usages of a symbol
+- `get_focus_zone` — Auto-enriched context from git diff
+
+### 🧪 Test Checklists (Universal)
+- `get_pending_tests` — List tests from `@test/@expect` JSDoc annotations
+- `mark_test_passed` / `mark_test_failed` — Track progress
+- `get_test_summary` — Progress report
+
+Supports: Browser, API, CLI, and Integration tests.
+
+### 🔍 Code Quality Analysis
+- `get_dead_code` — Find unused functions/classes (never called, not exported)
+- `generate_jsdoc` — Auto-generate JSDoc templates with @test/@expect
+- `get_similar_functions` — Detect duplicates (signature + structure similarity)
+- `get_complexity` — Cyclomatic complexity metrics (flags >10)
+- `get_large_files` — Files needing split (lines, functions, exports)
+- `get_outdated_patterns` — Legacy code patterns + redundant npm deps (Node 18+ built-ins)
+- `get_undocumented` — Find missing JSDoc (@test, @param, @returns)
+- `get_full_analysis` — Run ALL checks + Health Score (0-100)
+
+### 🔧 Custom Rules (Configurable)
+- `get_custom_rules` — List all rulesets and rules
+- `set_custom_rule` — Add/update a rule (agent can configure)
+- `check_custom_rules` — Run custom rules analysis
+
+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
+
+### ⚙️ Filter Configuration
+- `get_filters` / `set_filters` — Configure excluded directories and patterns
+- `add_excludes` / `remove_excludes` — Modify exclude list
+- Automatic `.gitignore` parsing
+- **`.graphignore`** — Project-specific ignore file for custom rules (like .gitignore)
+
+### 📚 Framework References
+- `get_framework_reference` — Auto-detect project framework and return AI-optimized docs
+- Includes: React 18/19, Vue 3, Next.js, Express, Node.js, Symbiote.js
+
+### 📘 Agent Instructions
+- `get_agent_instructions` — Get coding guidelines, JSDoc format, architecture standards
+- [AGENT_ROLE.md](AGENT_ROLE.md) — Full system prompt for agents
+- [AGENT_ROLE_MINIMAL.md](AGENT_ROLE_MINIMAL.md) — Minimal variant (agent self-discovers)
+
+### 💡 Response Hints
+Every tool response includes contextual coaching hints:
+- `get_skeleton` → "Use expand() to see code, deps() for architecture"
+- `invalidate_cache` → "Cache cleared. Run get_skeleton() to rebuild"
+- `get_dead_code` → "Review before removing — some may be used dynamically"
+- `get_undocumented` → "Use generate_jsdoc() for auto-generation"
+- Large classes auto-detected → "Run get_complexity() to find refactoring targets"
+
+### 🛡️ Security
+- **Path Traversal Protection** — all tool paths validated to stay within workspace root
+- **Workspace Isolation** — MCP roots set workspace boundary, tools cannot escape it
+
+### 🌐 MCP Ecosystem
+Works alongside [agent-pool-mcp](https://github.com/rnd-pro/agent-pool-mcp) for parallel agent orchestration:
+
+| Layer | project-graph-mcp | agent-pool-mcp |
+|-------|-------------------|----------------|
+| **Primary IDE agent** | Navigates codebase, runs analysis | Delegates tasks, consults peer |
+| **Gemini CLI workers** | Available as MCP tool inside Gemini CLI | Executes delegated tasks |
+
+## Installation
+
+Add to your IDE's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "project-graph": {
+      "command": "npx",
+      "args": ["-y", "project-graph-mcp"]
+    }
+  }
+}
+```
+
+Restart your IDE — project-graph-mcp will be downloaded and started automatically.  
+**Zero dependencies** — only Node.js >= 18 required.
+
+<details>
+<summary>📍 Where is my MCP config file?</summary>
+
+| IDE | Config path |
+|-----|------------|
+| Antigravity | `~/.gemini/antigravity/mcp_config.json` |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `.windsurf/mcp.json` |
+| Claude Code | Run: `claude mcp add project-graph npx -y project-graph-mcp` |
+
+See **[CONFIGURATION.md](CONFIGURATION.md)** for all supported IDEs.
+
+</details>
+
+<details>
+<summary>📦 Alternative: from source</summary>
+
+```bash
+git clone https://github.com/rnd-pro/project-graph-mcp
+cd project-graph-mcp
+# No npm install needed — zero dependencies
+# Use "node /path/to/project-graph-mcp/src/server.js" as the command in MCP config
+```
+
+</details>
+
+## CLI Usage
+
+```bash
+# Get project skeleton (minified graph)
+node src/server.js skeleton src/components
+
+# Expand minified symbol
+node src/server.js expand SN
+
+# Get dependencies
+node src/server.js deps SNG
+
+# List pending tests
+node src/server.js pending src/
+
+# Get test progress summary
+node src/server.js summary src/
+
+# Show filter configuration
+node src/server.js filters
+
+# Show agent instructions
+node src/server.js instructions
+
+# Code Quality Analysis
+node src/server.js deadcode src/       # Find unused code
+node src/server.js jsdoc src/file.js   # Generate JSDoc
+node src/server.js similar src/        # Find duplicates
+node src/server.js complexity src/     # Cyclomatic complexity
+node src/server.js largefiles src/     # Large files
+node src/server.js outdated .          # Legacy patterns
+
+# Show help
+node src/server.js help
+```
+
+## MCP Configuration
+
+See **[CONFIGURATION.md](CONFIGURATION.md)** for client-specific setup:
+- Antigravity / Gemini CLI
+- Cursor / Zed / Continue
+- VS Code + Copilot / CodeGPT
+- Claude Desktop
+- OpenCode / Crush
+- Jenova (mobile)
+- Firebase Genkit / NVIDIA AIQ
+
+## Test Annotations
+
+Add to your code:
+```javascript
+/**
+ * Create new user via API
+ * 
+ * @test request: POST /api/users with valid data
+ * @expect status: 201 Created
+ * @expect db: User row created
+ */
+async createUser(data) { ... }
+```
+
+Supported types:
+- **Browser**: click, key, drag, type, scroll, hover
+- **API**: request, call, invoke, mock
+- **CLI**: run, exec, spawn, input
+- **Integration**: setup, action, teardown, wait
+
+Agent workflow:
+```
+1. get_pending_tests("src/")
+   → [{ id: "createUser.0", type: "request", description: "POST /api/users" }]
+
+2. Agent runs the test
+
+3. mark_test_passed("createUser.0")
+
+4. get_test_summary("src/")
+   → { total: 9, passed: 1, pending: 8, progress: 11 }
+```
+
+## .graphignore
+
+Exclude files from custom rules checking (useful for files containing code examples):
+
+```
+# Comments start with #
+instructions.js          # Exact filename
+outdated-patterns.js     # Files with code examples
+*.min.js                 # Glob suffix
+dist/*                   # Glob prefix
+```
+
+Searches parent directories automatically (like .gitignore).
+
+## Architecture
+
+```
+project-graph-mcp/
+├── src/
+│   ├── server.js             # Entry point (CLI/MCP mode switch)
+│   ├── mcp-server.js         # MCP server + response hints
+│   ├── cli.js / cli-handlers.js  # CLI commands
+│   ├── tool-defs.js          # MCP tool schemas
+│   ├── tools.js              # Graph tools (skeleton, expand, deps)
+│   ├── workspace.js          # Path resolution + traversal protection
+│   ├── parser.js             # AST parser (Acorn)
+│   ├── graph-builder.js      # Minified graph + legend
+│   ├── filters.js            # Exclude patterns, .gitignore
+│   ├── dead-code.js          # Unused code detection
+│   ├── complexity.js         # Cyclomatic complexity
+│   ├── similar-functions.js  # Duplicate detection
+│   ├── large-files.js        # File size analysis
+│   ├── outdated-patterns.js  # Legacy pattern detection
+│   ├── full-analysis.js      # Health Score (0-100)
+│   ├── undocumented.js       # Missing JSDoc finder
+│   ├── jsdoc-generator.js    # JSDoc template generation
+│   ├── custom-rules.js       # Configurable lint rules
+│   ├── framework-references.js # Framework-specific docs
+│   ├── test-annotations.js   # @test/@expect parsing
+│   └── instructions.js       # Agent guidelines
+├── rules/                    # Pre-built rule sets (JSON)
+├── references/               # Framework reference docs
+├── vendor/
+│   ├── acorn.mjs             # AST parser (MIT, vendored)
+│   └── walk.mjs              # AST walker (MIT, vendored)
+└── tests/
+    ├── parser.test.js
+    └── mcp.test.js
+```
+
+## Skeleton Example
+
+```json
+{
+  "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
+  "s": { "files": 23, "classes": 10, "functions": 65 },
+  "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
+  "e": 35, "o": 7, "d": 5, "F": 63
+}
+```
+
+**L** = Legend, **s** = stats, **n** = nodes, **e** = edges, **o** = orphans, **d** = duplicates, **F** = functions
+
+## License
+
+MIT