safe-fix-mcp

safe-fix-mcp

一个真正的 MCP 服务，可在 Python 仓库中查找死代码，并针对唯一一种可以安全自动删除的问题提出 分支 + PR：位于仅导入一个名称的导入行中的未使用导入。它发现的其他问题——未使用的函数、类和依赖项——都只会报告，不会修改。始终由人来合并。此工具绝不会自行合并任何内容。

为什么要开发这个工具

大多数“死代码”工具只会报告。更进一步的工具通常会在没有安全保障的情况下直接删除。本工具两者都不做：它会起草一个真实、精简、可审查的 PR，并以目标仓库完整测试套件在删除后通过为前提——不是启发式判断，而是真正运行 pytest。如果测试套件失败，就不会提交或推送任何内容；仓库会保持原样。

工具

scan_dead_code(repo_path=".", min_confidence=60)

只读。运行 vulture（死代码）和 deptry（依赖项问题），并返回易于阅读的问题列表。绝不会修改任何内容。

propose_removal_pr(repo_path=".")

• 如果工作树不干净，则拒绝执行——绝不会在未提交的工作上进行修改。
• 仅筛选 vulture 置信度 ≥90% 的未使用导入，且仅限每行只导入一个名称的导入语句（会跳过 from x import y, z——删除整行会连 z 也一并悄悄删除）。
• 创建真实分支，删除符合条件的导入，并运行仓库的完整测试套件。
• 只有测试真正通过后，才会提交、推送，并尝试通过 gh pr create 创建 PR。
• 如果未安装 gh 或未完成身份验证，分支仍会真实提交并推送——只有 PR 创建步骤会降级处理，并返回实际错误，以便你手动创建 PR。

安装

pip install safe-fix-mcp

添加到 MCP 客户端配置中（例如 Claude Code）：

claude mcp add safe-fix-mcp -- safe-fix-mcp

或者直接运行以进行本地测试：

python -m safe_fix_mcp.server

如果要从源代码而非 PyPI 安装：

pip install -e .

技能

同一软件包内附带 SKILL.md——无需单独下载——它会教 Claude 何时以及如何正确使用这两个工具（例如，propose_removal_pr 只会自动删除仅导入一个名称的未使用导入，绝不会删除函数、类或依赖项）。将其安装到项目中：

safe-fix-mcp-install-skill

在希望启用该技能的项目根目录中运行——它会相对于当前目录写入 .claude/skills/safe-fix-mcp/SKILL.md。

要求

• Python ≥ 3.10
• PATH 中有 git
• 如果希望 propose_removal_pr 实际创建 PR，则需在 PATH 中安装并完成身份验证的 gh（GitHub CLI）——没有它，分支仍会真实推送，工具会提示你手动创建 PR。

开发

pip install -e ".[dev]"
pytest

已知限制

vulture 会将 scan_dead_code/propose_removal_pr 标记为“未使用”——这是已知的一类误报，并非真正的 bug：它们会在运行时通过 @mcp.tool() 装饰器进行分发，而不会在源代码中的任何位置被直接调用，因此静态调用图分析无法发现真正的调用方（MCP 框架本身）。

真实验证

scripts/verify_real_client.py 会将打包后的服务作为真实子进程启动，并使用真实的 mcp.client.ClientSession 与其通信——这与真实 MCP 客户端使用的路径相同。每次修改后都可以用它进行冒烟测试：

python scripts/verify_real_client.py