code-impact-mcp

CodeImpact MCP

面向 AI 辅助代码修改的快速提交前依赖检查。 几秒内给出 PASS/WARN/BLOCK 判定，回答“这样提交安全吗？”，让你在不良提交发生前，而不是发生后，发现高风险影响范围。无需数据库，也无需繁琐配置。

日本語 | 中文 | Русский | Español

收录状态：awesome-mcp-servers 的提交内容已准备就绪；Official MCP Registry 的软件包元数据已通过 server.json 发布；Smithery 已将此服务列为上线；Glama 的收录也已恢复，地址为 https://glama.ai/mcp/servers/vk0dev-code-impact-mcp。Glama 的恢复情况已在工厂指标中体现，但公开的规范徽章就绪路径仍未解决，因此 PR punkpeye/awesome-mcp-servers#5907 已存在，不应重复提交，目前也无法使用稳定的徽章 URL 完成收录。Cline 市场条目（cline/mcp-marketplace#1486）仍处于开放状态，尚未获接受；MCP Hive 仍是一个待人工提交的后续操作，而非目前已确认上线的收录。本 README 不宣称已具备徽章就绪状态或已完成 awesome-listing 收录。

最适合

• 提交前重构检查： 修改共享文件、路由或模块之前，需要快速获得 PASS/WARN/BLOCK 答复时。
• Agent 多文件编辑，包括单体仓库： AI Agent 即将修改多个文件或工作区范围内的软件包，而你希望在提交前通过依赖感知的检查进行风险控制时。
• 无需基础设施的影响范围评估： 需要快速获取风险评分和受影响文件摘要，又不想配置数据库、图服务或繁重的治理层时。

不适合

这不是完整的策略平台、合规检查套件或重度依赖可视化的代码图谱产品。

它专为快速的本地提交时安全检查而构建，并非用于全仓库治理工作流、持久化图谱探索或高管报告。

为什么／何时使用

在以下情况下使用此 MCP 服务：

• 用户询问：“如果我修改这个文件，哪些内容会出问题？”
• 用户询问：“这个重构提交安全吗？”
• 用户询问：“推送之前检查一下影响范围。”
• 用户询问：“有哪些内容依赖这个模块？”
• Agent 在修改多个文件之前需要快速的提交前检查
• Agent 希望为拟议的修改获取数值风险评分（0-1）
• 你需要依赖分析，但不想配置数据库或 tree-sitter

CodeImpact MCP 会构建轻量级的本地依赖图，并提供有界的判定：PASS、WARN 或 BLOCK。无需云服务，无需 API 密钥，本地优先。目前，这意味着全面支持 TypeScript/JavaScript；而 Python 仍仅支持范围较窄的文件级路径，用于 analyze_impact 和 gate_check，无法覆盖完整的 TS/JS 图谱功能。

如果用户需要的是针对 AI 生成代码修改的快速、有界的提交前检查，而非重量级代码治理平台，那么这是首选 MCP 服务。无需云服务，无需 API 密钥，本地优先。

安装

Claude Code

claude mcp add code-impact-mcp -- npx -y @vk0/code-impact-mcp

如果 Windows 用户在 Claude Code shell 中无法顺利解析普通的 npx 命令，可以通过 cmd /c 包装该命令。

其他 stdio MCP 客户端（包括 OpenClaw Tasks）

如果客户端要求提供普通的 stdio 命令，而不是 claude mcp add ... 包装命令，请直接使用相同的服务入口：

npx -y @vk0/code-impact-mcp

此服务采用本地优先模式，会从客户端启动时所在的工作目录读取目标仓库。

面向 stdio 客户端的 JSON 配置示例

如果你的 MCP 客户端需要 JSON，而不是 shell 包装脚本，Claude Desktop 在 macOS 上使用 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上使用 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "code-impact-mcp": {
      "command": "npx",
      "args": ["-y", "@vk0/code-impact-mcp"]
    }
  }
}

保存 claude_desktop_config.json 后，完全退出并重启 Claude Desktop，使其重新加载 MCP 服务配置。

使用工作区或项目专属的启动目录，这样服务就能读取你想要分析的代码库。

可选的 pre-commit 钩子辅助工具

运行 npm run demo:install-hook，即可预览受管理的 Husky 代码片段，而不会写入 .husky 文件。 这是已发布辅助工具的 dry-run 演示，并非 Husky 脚手架。

需要有关 install-hook 辅助工具、受限的 Python gate 嵌入方案，或已发布的 gate_check / analyze_impact 演示的快速示例？请参阅 docs/README.md。

最新变更请参阅 CHANGELOG.md。

教程

• Claude Desktop 快速入门
• 如何解读 analyze_impact 和 gate_check 的输出
• Pre-commit gate 方案

v1.6.0 中发布：一个安全的、仅适用于 Husky 的辅助工具，可在无需手动编辑 pre-commit 钩子的情况下接入受限的 gate runner。

如果你已经在使用 Husky，code-impact-mcp install-hook 是接入 pre-commit 钩子的直接方式，可直接添加受限的 gate runner，而不必手动配置钩子：

npx -y @vk0/code-impact-mcp install-hook

规范的三件套演示请参阅录制的终端会话 docs/demo-install-hook.cast、渲染后的预览 docs/demo-install-hook.gif，以及可复现的分镜脚本 scripts/demo-install-hook.mjs。

这是一个仅适用于 Husky 的辅助工具。如果 .husky/pre-commit 已包含无关内容，且没有受管理的 code-impact-mcp 区块，该命令会拒绝执行并保持钩子不变。如果受管理的区块已存在，重复运行时只会在该管理区块内操作，并保持幂等。如果 Husky 尚未初始化，该命令会停止并给出可执行的提示，而不会替你搭建钩子基础设施。它不会初始化 Husky、重写任意钩子逻辑，也不会替你管理非 pre-commit 钩子文件。

工具

核心工具界面的已发布演示素材可通过 scripts/demo-tool.mjs 复现，因此下方示例始终与当前工具行为保持一致，不会变成一次性的截图。

gate_check

Pre-commit 安全 gate。分析指定的变更，并给出附带原因的 PASS/WARN/BLOCK 判定。可在提交多文件变更前用作受限的决策辅助工具，包括 pnpm/package.json 工作区和 Lerna 风格单体仓库中的工作区感知检查。BLOCK 表示风险超过阈值，或有变更文件参与了检测到的循环依赖。WARN 表示建议人工审核，包括图中其他位置存在循环依赖的情况。PASS 表示基于依赖图的风险较低。

detect_cycles

返回当前 TS/JS 依赖图中的紧凑强连通分量，用于识别循环依赖。在重构或发布 gate 检查前，如果你需要一份简短的循环热点列表，而非完整的依赖图可视化，请使用此工具。

analyze_impact

分析更改特定文件所产生的影响范围。返回会受到直接和传递影响的文件，以及风险评分（0-1）。在提交涉及多个文件的更改之前使用，以了解可能出现的问题。不会修改任何文件。

还会返回 depthHistogram，即按 BFS 深度级别统计受影响文件数量（从更改的文件开始计算）（例如，{ "1": 5, "2": 12 }），以便了解影响是集中在更改附近，还是会扩散到多个跳转层级。

get_dependencies

获取特定文件的 import 和 importedBy 关系。显示此文件依赖什么，以及哪些文件依赖它。重构文件之前使用，以了解耦合情况。

refresh_graph

从头重建依赖图。在大量新增或删除文件后，或结果似乎已过时时调用。返回图统计信息，包括文件数量、边数量、构建时间和检测到的循环依赖。

还会返回 topHotFiles，即整个图中被导入次数最多的前 20 个文件，按导入者数量排序（例如，{ "file": "src/shared/config.ts", "importers": 14 }），以便在不对每个文件运行 get_dependencies 的情况下发现结构性热点。

对话示例

用户：“我想重构 src/routes.ts——这样安全吗？”

Agent 调用 gate_check：

{
  "projectRoot": "/Users/you/projects/my-app",
  "files": ["src/routes.ts"],
  "threshold": 0.5
}

结果：

{
  "verdict": "BLOCK",
  "scanSummary": "BLOCK, 8 affected across src/routes (4), src/pages (2), src (2)",
  "recommendation": "Refactor the circular dependency before shipping this change.",
  "riskScore": 0.35,
  "reasons": [
    "Changed files participate in a circular dependency. Example: src/router.ts → src/routes.ts"
  ],
  "affectedFiles": 8,
  "circularDependencies": 1,
  "affectedCycles": [["src/router.ts", "src/routes.ts"]]
}

Agent：“门禁检查返回了 BLOCK——routes.ts 属于一个循环依赖，因此我应该先理清该循环，再进行更多更改。”

Agent 调用 detect_cycles：

{
  "projectRoot": "/Users/you/projects/my-app"
}

结果：

{
  "cycleCount": 2,
  "hotspots": ["src/router.ts", "src/routes.ts"],
  "cycles": [
    ["src/router.ts", "src/routes.ts"],
    ["src/cache/index.ts", "src/cache/store.ts"]
  ]
}

工作原理

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Agent asks  │────▶│  ts-morph     │────▶│  In-memory    │
│  "safe to    │     │  parses       │     │  dependency   │
│   change?"   │     │  imports      │     │  graph        │
└─────────────┘     └──────────────┘     └──────┬───────┘
                                                 │
                    ┌──────────────┐     ┌───────▼───────┐
                    │  PASS/WARN/  │◀────│  BFS traverse  │
                    │  BLOCK       │     │  reverse deps  │
                    │  + risk 0-1  │     │  + risk score  │
                    └──────────────┘     └───────────────┘

1. **解析：**ts-morph 扫描项目中的 ESM 导入、重新导出和 CommonJS require
2. **构图：**在内存中构建依赖图（无数据库，不持久化）
3. **分析：**从更改的文件开始，对反向依赖进行 BFS 遍历
4. **评分：**风险 = 受影响文件数 / 文件总数（0-1）
5. **判定：**PASS（低于阈值的 60%）、WARN（阈值的 60-100%）、BLOCK（高于阈值）

支持：ESM 导入、ESM 重新导出、CommonJS require()、NodeNext 风格的 .js → .ts 解析。

对比

如果你正在为 Agent 或审查者选择工具，关键问题其实很简单：你需要探索依赖图、获取更广泛的仓库上下文，或为市场打包，还是需要在本地提交时，对已知的变更文件进行检查，并给出 PASS/WARN/BLOCK 判定？CodeImpact MCP 专为第二种任务打造。

替代方案	最擅长的方面	当前优势	CodeImpact MCP 的优势
CodeImpact MCP	针对拟议的 TS/JS 变更（包括单体仓库）进行以决策为先的依赖检查	在提交时立即对已知的变更文件给出 PASS/WARN/BLOCK 输出；内置 detect_cycles；支持工作区感知的门禁检查、文件级影响范围分类、适用于 analyze_impact 和 gate_check 的有限 Python 支持、零网络的本地优先工作流，以及直接提供 Husky 安装钩子辅助工具	当任务是“这样提交安全吗？”，而不是“帮我探索整个仓库”时最合适
code-graph-mcp	通过 MCP 接口托管或预构建代码图的检查	当 Agent 需要图遍历、语义图查询，以及通过现有 DeepGraph 或 CodeGPT 工作流访问公开/私有图，而不是使用本地门禁优先的 CLI 时，更合适	当你想要一个有限范围的提交前判定和受影响文件分类，而不是一场图探索会话时更合适
Depwire	覆盖更广泛语言和工具链的依赖情报及架构工作流	当你需要符号级分析、浏览器可视化、安全或健康工作流，或 CodeImpact 有意不涵盖的多语言平台时，更合适	当你想要一个小巧的 MIT 工具、保持本地优先、已上线 Official MCP Registry，并能快速回答范围明确的门禁问题时更合适
RepoGraph	面向 SWE 风格上下文收集的仓库级图检索	当工作流侧重研究或检索时更合适，尤其适用于更大型的仓库理解循环中的行级仓库上下文，而非轻量级的提交时检查	当已知涉及哪些文件，而你只需要有限范围的影响分类和门禁结果时更合适
CodeGraphContext	通过 CLI 和 MCP 双入口提供更全面的本地代码图与上下文平台	当 Agent 需要可查询的本地图索引工作流，以及针对本地代码库进行更长篇幅的仓库推理，而不是对已知变更文件给出一次提交时判定时，更合适	当你想要针对已知文件变更快速进行本地 PASS/WARN/BLOCK 门禁检查，并获得有限范围的影响分类，而不是更广泛的图/上下文工作流时更合适
MCP Hive 风格的市场后续流程	仓库内容稳定后，手动提交至市场/发现目录	当任务是为目录工作流准备市场打包、截图和运营文案，而不是进行技术门禁检查时，更合适	当你需要先推出产品核心价值时更合适：本地判定、安装钩子接入，以及已交付的有限范围 Python 影响检查，无需等待任何手动目录提交后续流程

**选择 CodeImpact MCP 的情况：**你已知道涉及哪些文件，并希望在提交前快速获得本地的 MIT 许可判定，其中包含风险评分、明确显示循环依赖、文件级影响范围输出、支持单体仓库的检查、已提供的 Husky 安装钩子辅助工具，以及清晰的 PASS/WARN/BLOCK 结果。

**选择其他替代方案的情况：**主要任务是访问托管/公开图、探索图、理解仓库、覆盖更广泛的依赖工作流、通过图数据库检索上下文以支持更长的推理循环，或在核心仓库内容已确定后手动进行市场打包。

常见问题

问：它会访问网络吗？ 答：不会。CodeImpact MCP 完全以本地为先。它通过 ts-morph 读取项目文件，绝不会发起网络请求。无需 API 密钥、云服务，也不会收集遥测数据。

问：它会修改我的代码吗？ 答：不会。所有 5 个工具均为只读（标注为 readOnlyHint: true）。它们只进行分析，绝不写入。

问：风险评分有多准确？ 答：风险评分是一种基于图的启发式指标（受影响的文件数 / 文件总数）。它不了解运行时行为、测试或数据迁移。请将其视为分流信号，而非保证。

问：它目前支持哪些语言？ 答：全面支持仍主要集中在 TypeScript 和 JavaScript 文件（.ts、.tsx、.js、.jsx、.mts、.cts、.mjs、.cjs）。当变更文件为 .py 时，analyze_impact 和 gate_check 也提供有限的 Python 支持，但仅限于文件/模块级别的影响分析，不涵盖广泛的多语言平台支持或整个代码库范围的图探索。

问：它有多快？ 答：构建图通常需要 1-5 秒，具体取决于项目规模。针对缓存图的单次工具调用几乎瞬间完成。

问：它会缓存图吗？ 答：会，图会按 (projectRoot, tsconfigPath) 对缓存在内存中。重大变更后，可使用 refresh_graph 重新构建。

局限性

• 全面图深度分析目前仍以 TypeScript/JavaScript 为主；Python 支持有意限定为本地文件/模块级别的影响分析，并非完整的多语言平台。
• 无法区分运行时导入和仅类型导入
• 图仅存储在内存中（服务重启后不会保留）
• 风险评分反映的是结构，而非语义——它不知道哪些文件“重要”
• 不提供可视化输出（仅文本/JSON）

更新日志

请参阅 CHANGELOG.md 了解发布历史。

许可证

MIT — 可免费用于任何项目，无论是商业用途还是个人用途。

贡献

欢迎通过 github.com/vk0dev/code-impact-mcp 提交问题和 PR。