safe-fix-mcp

一个真正的 MCP 服务器，用于在 Python 仓库中查找死代码，并针对唯一一类可以安全自动移除的发现提出 分支 + PR 建议：单名称导入行上的未使用导入。它发现的其余内容——未使用的函数、类、未使用的依赖——仅保留在报告中。合并始终由人工完成。此工具本身从不合并任何内容。

为什么存在

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

Related MCP server: code-review-mcp-server

工具

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 -e .

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

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

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

python -m safe_fix_mcp.server

要求

• Python ≥ 3.10

• git 已加入 PATH

• gh（GitHub CLI）已加入 PATH 并完成认证，如果你希望 propose_removal_pr 真正打开 PR——如果没有，分支仍然会被真实推送，工具会告诉你手动打开 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