vk0dev/code-impact-mcp

# CodeImpact MCP [](https://www.npmjs.com/package/@vk0/code-impact-mcp) [](./LICENSE) [](https://github.com/vk0dev/code-impact-mcp/actions/workflows/ci.yml) **专为 AI 辅助代码更改打造的快速预提交依赖门禁。** 在几秒钟内以 PASS/WARN/BLOCK（通过/警告/阻止）判定回答“这个提交安全吗？”，让您能在不良提交产生之前而非之后发现潜在的爆炸半径。无需数据库，无需繁琐设置。 [日本語](./README.ja.md) | [中文](./README.zh-CN.md) | [Русский](./README.ru.md) | [Español](./README.es.md) ## 最佳适用场景 - **预提交重构检查：** 在更改共享文件、路由或模块之前，需要快速的 PASS/WARN/BLOCK 判定。 - **Agent 多文件编辑（包括 monorepo）：** 当 AI agent 准备修改多个文件或工作区范围内的包时，您希望在提交前有一个有边界的、具备依赖感知的门禁。 - **无基础设施的爆炸半径分类：** 当您需要快速的风险评分和受影响文件摘要，又不想搭建数据库、图服务或沉重的治理层时。 ## 不适用场景 这**不是**一个完整的策略平台、合规门禁套件或可视化浓厚的代码图谱产品。 它专为快速的本地提交时安全检查而构建，不适用于全仓库治理工作流、持久化图谱探索或高管报告。 ## 为什么 / 何时使用 在以下情况下使用此 MCP server： - 用户询问：**“如果我更改这个文件，什么会崩溃？”** - 用户询问：**“这个重构可以安全提交吗？”** - 用户询问：**“在我 push 之前检查一下爆炸半径”** - 用户询问：**“什么依赖于这个模块？”** - Agent 在修改多个文件之前需要一个**快速的预提交门禁** - Agent 想要为提议的更改获取一个**数字风险评分 (0-1)** - 您需要进行依赖分析，但**不想搭建数据库或 tree-sitter** CodeImpact MCP 构建了一个轻量级的本地依赖图，并为您提供一个有边界的答案：PASS、WARN 或 BLOCK。零云端，无需 API key，本地优先。目前，这意味着完整的 TypeScript/JavaScript 支持，以及针对 `analyze_impact` 和 `gate_check` 提供有限的文件级 Python 路径，包括导入图爆炸半径和相同的门禁判定框架，但并不声称支持广泛的多语言。 如果用户需要的是**一个针对 AI 生成代码更改的快速、有边界的预提交门禁**，而不是一个沉重的代码治理平台，那么这就是为此量身定制的 MCP server。零云端，无需 API key，本地优先。 ## 安装 ### Claude Code ``` claude mcp add code-impact-mcp -- npx -y @vk0/code-impact-mcp ``` ### 可选的 pre-commit hook 辅助工具 如果您已经在使用 Husky，您可以直接植入这个有边界的门禁运行器，而无需手动配置 hook： ``` npx -y @vk0/code-impact-mcp install-hook ```  这是一个仅限 Husky 的辅助工具。如果 `.husky/` 已经存在，它只会创建或更新 `.husky/pre-commit` 中被标记的 `code-impact-mcp` 代码块，并保留不相关的 hook 内容。如果 Husky 尚未初始化，该命令将停止并给出可操作的信息，而不是为您搭建 hook 基础设施。 ### Claude Desktop 添加到 `claude_desktop_config.json`： ``` { "mcpServers": { "code-impact-mcp": { "command": "npx", "args": ["-y", "@vk0/code-impact-mcp"] } } } ``` ### Cursor 添加到 `.cursor/mcp.json`： ``` { "mcpServers": { "code-impact-mcp": { "command": "npx", "args": ["-y", "@vk0/code-impact-mcp"] } } } ``` ### Cline 添加到 Cline MCP 设置中： ``` { "mcpServers": { "code-impact-mcp": { "command": "npx", "args": ["-y", "@vk0/code-impact-mcp"] } } } ``` ## 工具 ### `gate_check` 预提交安全门禁。分析指定的更改并返回一个带有原因的 **PASS/WARN/BLOCK 判定**。在提交多文件更改之前用作有边界的决策辅助，包括 pnpm/package.json 工作区和 lerna 风格 monorepo 中的工作区感知检查。BLOCK 意味着风险超过阈值或更改的文件参与了检测到的循环依赖。WARN 意味着建议人工审查，包括图谱的其他部分包含循环依赖的情况。PASS 意味着基于图谱的风险较低。 ### `detect_cycles` 返回当前 TS/JS 图中循环依赖的紧凑强连通分量。当您需要一个简短的循环热点列表而不是完整的图谱可视化时，请在重构或发布门禁之前使用。 ### `analyze_impact` 分析更改特定文件的爆炸半径。返回哪些文件将受到直接和传递影响，以及风险评分 (0-1)。在提交多文件更改之前使用，以了解哪些可能会崩溃。不会修改任何文件。  ### `get_dependencies` 获取特定文件的 import 和 importedBy 关系。显示此文件依赖于什么以及什么依赖于它。用于在重构文件之前了解耦合情况。 ### `refresh_graph` 从头开始重建依赖图。在大量添加/删除文件后，或者如果结果似乎过时，请调用此工具。返回图谱统计信息，包括文件数量、边数量、构建时间以及检测到的循环依赖。 ## 示例对话 **用户：** “我想重构 `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 import、re-export 和 CommonJS require 2. **建图：** 构建内存中的依赖图（无数据库，无持久化） 3. **分析：** 从更改的文件进行 BFS 遍历反向依赖 4. **评分：** 风险 = 受影响文件 / 总文件数 (0-1) 5. **判定：** PASS（低于阈值的 60%），WARN（60-100%），BLOCK（超过阈值） 支持：ESM import、ESM re-export、CommonJS `require()`、NodeNext 风格的 `.js` → `.ts` 解析。 ## 对比 如果您正在为 agent 或审阅者选择工具，关键问题很简单：您是需要**探索图谱**，还是需要**对一项提议的更改进行门禁**？ | 替代方案 | 最擅长 | 它的优势 | CodeImpact MCP 的优势 | | --- | --- | --- | --- | | **CodeImpact MCP** | 对 TS/JS 仓库进行快速单判定依赖门禁 | 即时的 PASS/WARN/BLOCK 决策，本地优先的工作流，零设置 | 当任务是“这个提交安全吗？”而不是“帮我探索整个仓库”时的最佳选择 | | **code-graph-mcp** | 通过 MCP 工具界面进行更广泛的图谱检查 | 当 agent 想要从多个角度遍历关系并检查代码图谱时更好 | 当您想要一个有边界的预提交判定，而不是一次图谱探索会话时更好 | | **Depwire** | 在更大的依赖工作流中提供更广泛的依赖智能 | 当您需要更重的平台视图、更深入的依赖管理或更广泛的语言覆盖时更好 | 当您想要一个在本地运行并快速回答门禁问题的小型 MIT 工具时更好 | | **RepoGraph** | 图谱优先的浏览和仓库发现 | 当用户仍在学习代码库并希望交互式地检查结构时更好 | 当涉及的文件已知，并且您只需要爆炸半径分类加上门禁结果时更好 | | **CodeGraphContext** | 为较长形式的 agent 推理提供仓库上下文检索 | 当 agent 需要广泛的代码上下文来进行规划、综合或解释时更好 | 当您需要决策优先的输出，而不是通用的上下文提供者时更好 | **在以下情况选择 CodeImpact MCP：** 您已经知道涉及的文件，并希望获得一个带有风险评分和明确 PASS/WARN/BLOCK 判定的、快速、本地、MIT 许可的答案。 **在以下情况选择替代方案之一：** 主要任务是图谱探索、仓库理解、更广泛的依赖工作流覆盖，或为更长的推理循环提供上下文检索。 ## 常见问题 **问：它会访问网络吗？** 答：不会。CodeImpact MCP 是 100% 本地优先的。它通过 ts-morph 读取您的项目文件，从不发起网络请求。无需 API key，无云端，无遥测。 **问：它会修改我的代码吗？** 答：不会。所有 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 支持是有意限定于本地文件/模块级别的影响，而不是一个完整的多语言平台。 - 不区分运行时 import 和仅类型 import - 图谱仅在内存中（服务器重启后不会持久化） - 风险评分是结构性的，而非语义性的 —— 它不知道哪些文件是“重要的” - 无可视化输出（仅限 text/JSON） ## 更新日志 有关发布历史，请参阅 [CHANGELOG.md](./CHANGELOG.md)。 ## 许可证 [MIT](./LICENSE) —— 可免费用于任何项目，无论是商业还是个人用途。 ## 贡献 欢迎在 [github.com/vk0dev/code-impact-mcp](https://github.com/vk0dev/code-impact-mcp) 提交 Issue 和 PR。

标签：AI代码助手, AI编程, DevSecOps, MCP Server, MITM代理, Model Context Protocol, NPM包, OSV-Scalibr, Pre-commit, TypeScript, 上游代理, 代码安全检查, 代码审查, 代码重构, 依赖图分析, 依赖管理, 安全插件, 安全门禁, 影响范围分析, 无损检测, 暗色界面, 爆炸半径分析, 自动化攻击, 错误基检测, 静态代码分析