ast-impact-mapper-mcp

🗺️ ast-impact-mapper-mcp ✨

“别试图面面俱到。只运行真正受你所做更改影响的测试。” 🐸

ast-impact-mapper-mcp 是一款先进的 Model Context Protocol（MCP）服务，它通过 AST 解析（ts-morph）和依赖图追踪来分析 TypeScript/JavaScript 代码库。它可以帮助 AI Agent（例如 Claude 或 Cursor）只针对相关测试、查找死代码、识别循环导入依赖，并追踪 API 变更。

---

🧐 为什么要用导入图？

根据文件名匹配来猜测受影响的测试（例如 auth.ts -> auth.test.ts）非常不准确。每次细微更改都运行整个测试套件，速度会非常慢。

导入图不会说谎。 如果某个测试文件传递性地导入了修改过的源文件，就必须运行该测试。ast-impact-mapper-mcp 会构建双向文件依赖图，并在毫秒内回答“我应该运行哪些测试？”

---

💡 快速演示（真实端到端工作流）

假设 AI Agent 修改了一个共享辅助工具：src/utils/auth.ts。Agent 不会盲目运行所有测试，也不会根据名称猜测，而是使用此 MCP 服务：

1. 找出受影响的测试

Agent 使用更改的文件调用 get_affected_tests：

// Tool Call: get_affected_tests({ changed_files: ["src/utils/auth.ts"] })
{
  "changed_files": ["/project/src/utils/auth.ts"],
  "affected_tests": ["/project/tests/checkout.spec.ts"],
  "total_affected": 1
}

2. 解释关联关系

要了解 checkout.spec.ts 为何依赖于 auth.ts，Agent 会调用 explain_impact：

// Tool Call: explain_impact({ changed_file: "src/utils/auth.ts", test_file: "tests/checkout.spec.ts" })
{
  "found": true,
  "import_chain": [
    "/project/tests/checkout.spec.ts",
    "/project/src/fixtures/user-fixture.ts",
    "/project/src/utils/auth.ts"
  ]
}

原来如此！checkout 测试导入了 user-fixture，而它又导入了 auth！

3. 检查运行时影响

如果 auth.ts 中的更改只是添加了一个 TypeScript 接口（仅类型更改），调用 differentiate_type_impact 会告诉 Agent：

{
  "files": [{ "file": "/project/src/utils/auth.ts", "runtime_impact": false }],
  "total_tests_must_run": 0,
  "total_tests_skippable": 1
}

成功！由于这只是类型更改，Agent 可以完全跳过测试运行，节省宝贵的 CPU 资源和时间。

4. 运行最少的测试

如果更改_确实_包含运行时变更，Agent 会请求执行命令：

// Tool Call: generate_test_command({ changed_files: ["src/utils/auth.ts"], runner: "vitest" })
{
  "command": "npx vitest run tests/checkout.spec.ts"
}

---

🛠️ MCP 工具参考

所有工具都采用一致且类型安全的架构配置（参数使用 snake_case）。

1. 影响映射与追踪

• get_affected_tests

  查找所有传递导入了已更改源文件的测试文件。

  • 参数：
    • project_root（string，必填）：TypeScript 项目的绝对路径。
    • changed_files（string[]，可选）：已修改文件的路径。
    • git_diff（string，可选）：git diff --name-only 的原始标准输出。
  • **返回：**已更改文件、受影响测试和总数的详细映射。

• get_affected_tests_by_branch

  使用 git 自动将当前状态与基分支进行比较，以查找受影响的测试。

  • 参数：
    • project_root（string，必填）
    • base_branch（string，默认值："main"）：要进行比较的分支。

• get_rename_aware_diff

  高度稳健的分支影响分析，可追踪文件移动／重命名（通过 git diff -M），并忽略格式／空白字符更改。

  • 参数：
    • project_root（string，必填）
    • base_branch（string，默认值："main"）
    • similarity_threshold（number，默认值：90）：判定为移动的相似度阈值（%）。

• explain_impact

  追踪并解释精确的导入链，说明已更改的源文件为何会影响特定测试。

  • 参数：
    • project_root（string，必填）
    • changed_file（string，必填）
    • test_file（string，必填）

• generate_test_command

  为测试运行器（vitest、jest 或 playwright）构造与受影响测试子集匹配的 CLI 命令。

  • 参数：
    • project_root（string，必填）
    • changed_files（string[]，必填）
    • runner（enum：jest、vitest、playwright，默认值：vitest）

---

2. TypeScript 专项深度代码分析

• differentiate_type_impact

  检查导入和类型，以隔离仅涉及类型的更改（接口、类型或 import type 导出）。如果更改不会影响运行时包，便可完全跳过测试执行！

  • 参数：
    • project_root（string，必填）
    • changed_files（string[]，必填）

• analyze_api_surface_mutation

  将文件与其 HEAD 版本进行比较，判断它是否修改了公共 API（breaking_api_change），或仅包含内部实现编辑（internal_refactor）。

  • 参数：
    • project_root（string，必填）
    • file_path（string，必填）

• generate_skeleton_view

  通过移除函数和方法主体，生成经过 Token 优化的文件骨架，仅保留签名、JSDoc 和行号。

  • 参数：
    • project_root（string，必填）
    • file_path（string，必填）
    • include_jsdoc（boolean，默认值：true）
    • include_private_members（boolean，默认值：false）

• get_symbol_dependency_graph

  追踪跨文件的声明级依赖（函数、类、变量），查找内部声明的使用情况。

  • 参数：
    • project_root（string，必填）
    • file_path（string，必填）
    • symbol_name（string，可选）：要映射的特定导出符号。
    • direction（enum：forward、reverse、bidirectional，默认值：bidirectional）

---

3. 代码库健康状况与图谱洞察

• identify_unreachable_modules

  查找没有任何传入导入的孤立源文件（可安全清理的死代码）。自动识别标准入口点。

  • 参数：
    • project_root（字符串，必填）
    • entry_points（字符串[]，可选）：明确指定不发出警告的入口点。
    • limit（数字，默认值：50）

• detect_architectural_cycles

  查找循环依赖（例如 A → B → C → A），此类依赖会导致模块初始化顺序不可预测。

  • 参数：
    • project_root（字符串，必填）

• get_dependency_graph

  以 JSON 格式或可视化的 Mermaid TD 流程图，返回文件的直接导入项和导入者。

  • 参数：
    • project_root（字符串，必填）
    • file_path（字符串，必填）
    • format（枚举：json、mermaid，默认值：json）

• get_coverage_gaps

  查找导入覆盖率为零的文件，即从未被任何测试文件导入的文件。

  • 参数：
    • project_root（字符串，必填）
    • source_dirs（字符串[]，可选）
    • limit（数字，默认值：50）

• get_test_summary

  概览测试覆盖率、最深导入链，以及风险较高且被导入次数最多的模块。

  • 参数：
    • project_root（字符串，必填）

• refresh_project

  使 AST 和依赖图缓存失效。在切换分支或拉取远程 Git 更新后运行。

  • 参数：
    • project_root（字符串，必填）

---

🚀 安装与设置

1. 全局安装

npm install -g ast-impact-mapper-mcp

2. 配置编辑器 / Agent 客户端

VS Code / Cursor

将以下内容添加到 .cursor/mcp.json 或 .vscode/mcp.json：

{
  "mcpServers": {
    "ast-impact-mapper": {
      "command": "npx",
      "args": ["-y", "ast-impact-mapper-mcp"]
    }
  }
}

Claude Code CLI

claude mcp add ast-impact-mapper npx -- -y ast-impact-mapper-mcp

---

💬 示例场景

假设你修改了一个共享页面组件：src/pages/login-page.ts。

1. AI Agent 运行 get_rename_aware_diff： 它检测到只有 tests/auth.spec.ts 会传递性地导入该页面对象。
2. AI Agent 运行 differentiate_type_impact： 它发现你只添加了一个类型定义接口，并将其归类为 type_only_change -> 因此完全跳过测试执行，节省开发时间！
3. AI Agent 运行 explain_impact： 如果有人询问 tests/auth.spec.ts 为什么依赖它，该工具会显示路径： tests/auth.spec.ts → src/fixtures/app.ts → src/pages/login-page.ts。

---

🔗 生态系统

• ast-impact-mapper-mcp 解答："我的更改会影响哪些测试？" 🗺️
• flakiness-graph-mcp 解答："在这些受影响的测试中，哪些历来不稳定？" 📊
• 二者共同构成完美的反馈闭环，用于运行优先级明确、稳定且精简的测试套件。

---

🛠️ CLI 开发

npm run build        # Compile TypeScript to dist/
npm run lint         # Run ESLint validation
npm run format       # Format files via Prettier
npm test             # Run unit tests via Vitest

---

📄 许可证

MIT © vola-trebla 🐸