project-graph-mcp helps AI agents see project architecture without extra tokens

A new way has emerged for AI agents to quickly navigate unfamiliar code: project-graph-mcp builds a structural graph of the project and returns it as compressed JSON. Instead of reading dozens of files in sequence, an agent receives an architecture map, sees dependencies, and then dives deeper into the necessary areas.

How the server works

The key idea behind project-graph-mcp is the so-called project skeleton. The server parses source code, collects information about files, classes, functions, imports, and calls, then returns all of this in a compact structure. According to the author, compression reaches 10–50x, allowing the model to understand the overall architecture without consuming enormous context. This approach is especially useful for agent IDEs and orchestrators that need to quickly decide which file to read, where to delegate subtasks, and how modules relate to each other.

Compression achieves 10–50x.

Initially, the tool only worked with JavaScript through the Acorn AST parser, but in version 1.1 it gained support for TypeScript, Python, and Go. For the new languages, the author chose a regex-based approach: it's simpler, lighter, and doesn't require pulling in heavy external libraries for basic code navigation. At the same time, all parsers are standardized to the same output — lists of classes, functions, imports, and calls — so the agent works with the same project model regardless of the tech stack.

What problems it solves

The project doesn't end with a single graph. The server includes built-in analysis tools that enable not only navigation but also rapid identification of problem areas. The agent can understand which code sections are potentially dead, where a function has grown to unwieldy size, and what call chain a request follows from middleware to rendering or API handler. This makes the server more than just a project map — it's a tool for initial technical diagnosis.

• `get_dead_code` finds unused functions and modules
• `get_complexity` evaluates cyclomatic complexity
• `get_large_files` identifies files as refactoring candidates
• `get_call_chain` shows the path between related functions
• Health Score aggregates check results into a score from 0 to 100

Additionally, project-graph-mcp includes test checklists via JSDoc annotations `@test` and `@expect`. An agent can receive a list of open checks, write code, then mark tests as passing. This acts as a bridge between project navigation and the actual development cycle: first the model understands the application structure, then makes changes and immediately verifies against expected behavior. For typical stacks there are also built-in rules: 11 sets with 86 conventions for React, Vue, Express, TypeScript, and Symbiote.js.

Integration and security

The tool is designed as part of a broader agent framework. The author describes a scenario where the main agent in the IDE first requests the project skeleton, then delegates individual tasks to background workers via agent-pool-mcp. Each worker runs the same server locally and invokes `expand`, `deps`, and other methods for specific code sections. This way the orchestrator doesn't pull unnecessary files into context and can distribute work faster among models with different specializations.

From an implementation perspective, the barrier to entry is low: Node.js 18+ is required, the server runs via `npx`, weighs 132 KB, consists of 47 files, and has no external dependencies. Version 1.2.0 is already available on npm. The authors also specifically addressed security. All paths pass validation through `resolve` and `startsWith`, so the agent cannot escape the working directory. Attempting to access something like `../../etc/passwd` returns an error. For MCP tools that read files and dependencies, such protection is critical.

What it means

AI agents are gradually moving from simple autocompletion to understanding the architecture of entire projects. project-graph-mcp is interesting because it solves a practical context problem: instead of hundreds of lines of code, the model gets a compact system map and works more accurately. For teams building their own AI agents for development, this is no longer an experiment but a practical infrastructure layer. If such MCP servers become standard, agent-based development will face fewer token limits and more often be limited by the quality of the engineering logic itself.