project-graph-mcp：AI 导航图

project-graph-mcp：AI智能体代码导航的依赖图谱

多智能体开发系统需要精准地在代码库中导航。project-graph-mcp 服务器提供了一个MCP接口，用于构建依赖图谱，并将其压缩为精简的JSON格式。这使得智能体能够在不消耗令牌解析源文件的情况下理解项目架构。

该服务器分析文件，提取类、方法、导入信息，并返回一个压缩比达10–50倍的结构化数据。支持JavaScript、TypeScript、Python和Go语言，可无缝运行于多语言混合项目中。

压缩格式下的项目骨架

核心功能是生成项目的“骨架”结构。解析器扫描源文件，输出包含图例、统计信息和节点图的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 — 缩写名称的图例
• s — 统计信息（文件数、类数、函数数）
• n — 节点及其方法（m）和属性（$）
• e, o, d, F — 边、对象、目录、文件

如需深入探索，可使用 expand 和 deps 方法动态扩展图谱。

无需AST的多语言解析

最初基于Acorn构建用于JavaScript解析。1.1版本新增了TypeScript、Python和Go的正则表达式解析器。该方案无需外部依赖，同时保留各语言的语法特性。

共享工具 stripStringsAndComments 可移除代码中的字符串与注释：

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

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

// TypeScript（默认）
stripStringsAndComments(code)

所有解析器统一输出 ParseResult：类、函数、导入、调用。正则模式可根据项目风格自动适配。

代码分析与健康评分

服务器内置质量指标：

• get_dead_code — 检测未使用的代码
• get_complexity — 计算圈复杂度
• get_large_files — 识别需重构的大文件
• get_call_chain — 追踪调用链（authMiddleware → validateToken → renderDashboard）

命令示例：

# 旧版本与依赖检查
npx project-graph-mcp outdated .

# 复杂度分析
npx project-graph-mcp complexity src/

结果汇总生成健康评分（0–100）。响应提示建议下一步操作，例如审查高复杂度函数。

通过JSDoc实现测试清单

支持 @test 和 @expect 注解来记录测试用例：

/**
 * 通过API创建新用户
 * 
 * @test request: POST /api/users with valid data
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — 列出未完成的测试
• mark_test_passed — 标记测试通过

支持API、CLI、集成及浏览器测试场景。

框架定制化规则

内置针对React 18/19、Vue 3、Express 5、TypeScript 5、Symbiote.js的规则集（共11套，86条规则）。可通过 get_framework_reference 自动检测项目框架。

自定义约定时：

• 将规则添加至 rules/ 目录
• 使用智能体中的 set_custom_rule 方法配置

与智能体池的集成

在分形编排架构中，IDE智能体请求项目骨架，并将任务委派给工作节点（如Gemini等）。每个工作节点运行本地MCP实例，利用 expand/deps 实现导航。

仅132 KB大小，零外部依赖。适用于VS Code、Cursor、Zed的配置如下：

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

安全性与路径遍历防护

路径验证采用 resolve + startsWith 机制，限制访问范围仅限于工作目录。expand、deps 和 get_skeleton 等方法均继承此保护机制——例如请求 ../../etc/passwd 将返回错误。

核心亮点：

• 压缩后的依赖图谱显著提升AI智能体导航效率
• 无外部库的正则解析器支持JS/TS/Python/Go
• 健康评分与调用链分析助力精准重构
• JSDoc清单自动化测试文档编写
• 内置86条预设规则，开箱即用支持主流框架

— Editorial Team