project-graph-mcp: graph for AI navigation

project-graph-mcp: Dependency Graph for AI Agent Navigation in Code

Multi-agent development systems require precise navigation through codebases. The project-graph-mcp server provides an MCP interface to build a dependency graph, compressed into a minified JSON format. This allows agents to understand project architecture without consuming tokens on parsing source files.

The server analyzes files, extracts classes, methods, imports, and returns a structure with 10–50x compression. Support for JavaScript, TypeScript, Python, and Go enables seamless operation across polyglot projects.

Project Skeleton in Compressed Format

The core function is generating a "skeleton" of the project. The parser scans source files and produces a JSON output containing legends, statistics, and a node graph.

Example output:

{
  "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 of abbreviated names
• s — statistics (files, classes, functions)
• n — nodes with methods (m) and properties ($)
• e, o, d, F — edges, objects, directories, files

For deeper exploration, use expand and deps methods to dynamically extend the graph.

Multi-Language Parsing Without AST

Initially built with Acorn for JavaScript. Version 1.1 added parsers for TypeScript, Python, and Go using regular expressions. This approach eliminates external dependencies while respecting language-specific nuances.

A shared utility stripStringsAndComments removes strings and comments from code:

// Python
stripStringsAndComments(code, { tripleQuote: true, hashComment: true })

// Go
stripStringsAndComments(code, { backtick: true, templateInterpolation: false })

// TypeScript (default)
stripStringsAndComments(code)

All parsers unify under ParseResult: classes, functions, imports, calls. Regex patterns adapt to project style.

Code Analysis and Health Score

The server includes quality metrics:

• get_dead_code — detects unused code
• get_complexity — measures cyclomatic complexity
• get_large_files — identifies files needing refactoring
• get_call_chain — traces call chains (authMiddleware → validateToken → renderDashboard)

Commands:

# Legacy and dependency checks
npx project-graph-mcp outdated .

# Complexity analysis
npx project-graph-mcp complexity src/

Results aggregate into a Health Score (0–100). Response Hints suggest next steps, such as reviewing complex functions.

Test Checklists via JSDoc

Support for @test and @expect annotations to document tests:

/**
 * Create new user via API
 * 
 * @test request: POST /api/users with valid data
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — lists incomplete tests
• mark_test_passed — marks test completion

Supports API, CLI, integration, and browser testing.

Customization for Frameworks

Built-in rule sets for React 18/19, Vue 3, Express 5, TypeScript 5, Symbiote.js (11 sets, 86 rules total). Automatic project detection via get_framework_reference.

For custom conventions:

• Add rules to rules/
• Use set_custom_rule from the agent

Integration with Agent Pools

In fractal orchestration, the IDE agent requests the skeleton and delegates tasks to workers (Gemini, etc.). Each worker runs a local MCP instance for navigation using expand/deps.

Only 132 KB in size, zero external dependencies. Config for VS Code, Cursor, Zed:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

Security and Path Traversal Protection

Path validation uses resolve + startsWith to restrict access to the working directory. Methods like expand, deps, and get_skeleton inherit this protection — a request like ../../etc/passwd returns an error.

Key Highlights:

• Compressed dependency graphs speed up AI agent navigation
• Regex-based parsers for JS/TS/Python/Go with no external libraries
• Health Score and call chain analysis for targeted refactoring
• JSDoc checklists automate test documentation
• 86 pre-built rules for popular frameworks out of the box

— Editorial Team