safe-fix-mcp 0.1.0__tar.gz

safe_fix_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

safe_fix_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pamela-0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

safe_fix_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: safe-fix-mcp
+Version: 0.1.0
+Summary: MCP server: finds real dead code (vulture + deptry) and proposes a branch+PR for the one class safe to auto-remove -- unused imports on a single-name line -- gated on a real full test-suite pass. A human still merges.
+Project-URL: Homepage, https://github.com/pamela-0/safe-fix-mcp
+Project-URL: Repository, https://github.com/pamela-0/safe-fix-mcp
+Project-URL: Issues, https://github.com/pamela-0/safe-fix-mcp/issues
+Author-email: pamela-0 <154478423+pamela-0@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automated-pr,claude,claude-code,code-quality,dead-code,deptry,mcp,model-context-protocol,static-analysis,vulture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: deptry>=0.20
+Requires-Dist: mcp[cli]>=1.26
+Requires-Dist: vulture>=2.11
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# safe-fix-mcp
+
+A real MCP server that finds dead code in a Python repository and proposes a **branch + PR** for the one class of finding that's actually safe to auto-remove: unused imports on a single-name import line. Everything else it finds — unused functions, classes, unused dependencies — stays report-only. A human always merges. This tool never merges anything itself.
+
+## Why this exists
+
+Most "dead code" tools stop at reporting. The ones that go further usually delete with no safety net. This does neither: it drafts a real, minimal, reviewable PR, gated on the target repo's own full test suite actually passing after the removal — not a heuristic, a real `pytest` run. If the suite fails, nothing is committed or pushed; the repo is left exactly as it started.
+
+## Tools
+
+### `scan_dead_code(repo_path=".", min_confidence=60)`
+
+Read-only. Runs [vulture](https://github.com/jendrikseipp/vulture) (dead code) and [deptry](https://github.com/fpgmaas/deptry) (dependency issues) and returns a human-readable list of findings. Never modifies anything.
+
+### `propose_removal_pr(repo_path=".")`
+
+- Refuses on a dirty working tree — never edits on top of uncommitted work.
+- Filters to unused imports at ≥90% vulture confidence, on single-name import lines only (`from x import y, z` is skipped — removing the whole line would silently remove `z` too).
+- Creates a real branch, removes the qualifying imports, runs the repo's real full test suite.
+- Only on a real pass: commits, pushes, and tries to open a PR via `gh pr create`.
+- If `gh` isn't installed/authenticated, the branch is still committed and pushed for real — only PR creation degrades, with the real error returned so you can open it manually.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Add to your MCP client config (e.g. Claude Code):
+
+```bash
+claude mcp add safe-fix-mcp -- safe-fix-mcp
+```
+
+Or run directly for local testing:
+
+```bash
+python -m safe_fix_mcp.server
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- `git` on PATH
+- `gh` (GitHub CLI) on PATH and authenticated, if you want `propose_removal_pr` to actually open the PR — without it, the branch still gets pushed for real, and the tool tells you to open the PR by hand.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Known limitation
+
+`vulture` flags `scan_dead_code`/`propose_removal_pr` themselves as "unused" — a known false-positive class, not a real bug: they're dispatched by the `@mcp.tool()` decorator at runtime, not called directly anywhere in the source, so static call-graph analysis can't see the real caller (the MCP framework itself).
+
+## Verifying it for real
+
+`scripts/verify_real_client.py` launches the packaged server as a real subprocess and talks to it with the real `mcp.client.ClientSession` — the same path a real MCP client uses. Useful as a smoke test after any change:
+
+```bash
+python scripts/verify_real_client.py
+```

safe_fix_mcp-0.1.0/README.md

@@ -0,0 +1,64 @@
+# safe-fix-mcp
+
+A real MCP server that finds dead code in a Python repository and proposes a **branch + PR** for the one class of finding that's actually safe to auto-remove: unused imports on a single-name import line. Everything else it finds — unused functions, classes, unused dependencies — stays report-only. A human always merges. This tool never merges anything itself.
+
+## Why this exists
+
+Most "dead code" tools stop at reporting. The ones that go further usually delete with no safety net. This does neither: it drafts a real, minimal, reviewable PR, gated on the target repo's own full test suite actually passing after the removal — not a heuristic, a real `pytest` run. If the suite fails, nothing is committed or pushed; the repo is left exactly as it started.
+
+## Tools
+
+### `scan_dead_code(repo_path=".", min_confidence=60)`
+
+Read-only. Runs [vulture](https://github.com/jendrikseipp/vulture) (dead code) and [deptry](https://github.com/fpgmaas/deptry) (dependency issues) and returns a human-readable list of findings. Never modifies anything.
+
+### `propose_removal_pr(repo_path=".")`
+
+- Refuses on a dirty working tree — never edits on top of uncommitted work.
+- Filters to unused imports at ≥90% vulture confidence, on single-name import lines only (`from x import y, z` is skipped — removing the whole line would silently remove `z` too).
+- Creates a real branch, removes the qualifying imports, runs the repo's real full test suite.
+- Only on a real pass: commits, pushes, and tries to open a PR via `gh pr create`.
+- If `gh` isn't installed/authenticated, the branch is still committed and pushed for real — only PR creation degrades, with the real error returned so you can open it manually.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Add to your MCP client config (e.g. Claude Code):
+
+```bash
+claude mcp add safe-fix-mcp -- safe-fix-mcp
+```
+
+Or run directly for local testing:
+
+```bash
+python -m safe_fix_mcp.server
+```
+
+## Requirements
+
+- Python ≥ 3.10
+- `git` on PATH
+- `gh` (GitHub CLI) on PATH and authenticated, if you want `propose_removal_pr` to actually open the PR — without it, the branch still gets pushed for real, and the tool tells you to open the PR by hand.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Known limitation
+
+`vulture` flags `scan_dead_code`/`propose_removal_pr` themselves as "unused" — a known false-positive class, not a real bug: they're dispatched by the `@mcp.tool()` decorator at runtime, not called directly anywhere in the source, so static call-graph analysis can't see the real caller (the MCP framework itself).
+
+## Verifying it for real
+
+`scripts/verify_real_client.py` launches the packaged server as a real subprocess and talks to it with the real `mcp.client.ClientSession` — the same path a real MCP client uses. Useful as a smoke test after any change:
+
+```bash
+python scripts/verify_real_client.py
+```

safe_fix_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "safe-fix-mcp"
+version = "0.1.0"
+description = "MCP server: finds real dead code (vulture + deptry) and proposes a branch+PR for the one class safe to auto-remove -- unused imports on a single-name line -- gated on a real full test-suite pass. A human still merges."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "pamela-0", email = "154478423+pamela-0@users.noreply.github.com" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "dead-code",
+    "vulture",
+    "deptry",
+    "code-quality",
+    "automated-pr",
+    "static-analysis",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "mcp[cli]>=1.26",
+    "vulture>=2.11",
+    "deptry>=0.20",
+]
+
+[project.urls]
+Homepage = "https://github.com/pamela-0/safe-fix-mcp"
+Repository = "https://github.com/pamela-0/safe-fix-mcp"
+Issues = "https://github.com/pamela-0/safe-fix-mcp/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+
+[project.scripts]
+safe-fix-mcp = "safe_fix_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/safe_fix_mcp"]
+
+[tool.deptry]
+exclude = [".venv", "tests"]
+
+[tool.deptry.per_rule_ignores]
+# DEP003 "imported but it is a transitive dependency": deptry's real,
+# known limitation with src-layout packages -- it doesn't recognize
+# `safe_fix_mcp` importing its own submodules as the package importing
+# itself, not a real external transitive-dependency risk.
+DEP003 = ["safe_fix_mcp"]
+# DEP002 "defined as a dependency but not used": vulture/deptry are real,
+# load-bearing dependencies invoked as subprocesses (`python -m vulture`),
+# never imported directly, so deptry's static import scan can't see the
+# usage. pytest is a real dev dependency used only from tests/.
+DEP002 = ["vulture", "deptry", "pytest", "pytest-asyncio"]

safe_fix_mcp-0.1.0/scripts/verify_real_client.py

@@ -0,0 +1,32 @@
+"""Throwaway real-client verification, not a deliverable: launches
+safe-fix-mcp as a REAL subprocess over stdio and talks to it with the
+real mcp.client.ClientSession -- the exact path a real MCP client
+(Claude Code, Claude Desktop, Cursor) uses. Proves the packaged
+`safe-fix-mcp` console script actually works as a standalone server
+process, not just as in-process Python calls.
+"""
+
+import asyncio
+import sys
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+
+async def main() -> None:
+    params = StdioServerParameters(command=sys.executable, args=["-m", "safe_fix_mcp.server"])
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            init = await session.initialize()
+            print(f"Real handshake OK -- server: {init.server_info.name} v{init.server_info.version}")
+
+            tools = await session.list_tools()
+            print(f"Real tools advertised: {[t.name for t in tools.tools]}")
+
+            result = await session.call_tool("scan_dead_code", {"repo_path": "."})
+            print("Real scan_dead_code call result:")
+            print(result.content[0].text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

safe_fix_mcp-0.1.0/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.pamela-0/safe-fix-mcp",
+  "description": "Finds real dead code (vulture + deptry) in a Python repo and proposes a branch+PR for the one class safe to auto-remove: unused imports on a single-name line, gated on the target repo's own real full test-suite pass. A human always merges.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/pamela-0/safe-fix-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "identifier": "safe-fix-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

safe_fix_mcp-0.1.0/src/safe_fix_mcp/bloat_check.py

@@ -0,0 +1,143 @@
+"""Real dead-code/dependency-bloat detection — runs vulture and deptry
+(real static-analysis tools, not a hand-rolled heuristic) and returns a
+structured report of real candidates. Deliberately a *report*, not an
+autonomous deleter — see bloat_pr.py for the narrow, safety-gated subset
+that IS auto-proposed as a branch+PR.
+
+Both tools are invoked as real subprocesses (`python -m vulture`/`python
+-m deptry`), not imported — so this module's own imports of them never
+count against it.
+
+Unlike a project with a fixed `src`/`tests` layout, this is a
+general-purpose tool meant to scan an arbitrary caller's repository —
+`paths` defaults to `["."]` (the whole target repo) rather than assuming
+any particular directory convention.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_VULTURE_LINE_RE = re.compile(
+    r"^(?P<file>.+):(?P<line>\d+): (?P<message>.+) \((?P<confidence>\d+)% confidence\)$"
+)
+
+# Real bug found live scanning this project's own repo: paths=None -> ["."]
+# with no exclusions walks straight into .venv/site-packages, turning a
+# handful of real findings into 30,000+ noise findings from third-party
+# packages that were never this repo's own code. Every general-purpose
+# Python project layout puts one of these inside the repo root, so
+# excluding them isn't optional for a tool meant to scan "." by default.
+DEFAULT_EXCLUDE = ".venv,venv,.git,__pycache__,build,dist,*.egg-info,node_modules"
+
+
+@dataclass(frozen=True)
+class BloatFinding:
+    tool: str  # "vulture" | "deptry"
+    file: str
+    line: int | None
+    message: str
+    confidence: int | None = None  # vulture only; deptry findings have no confidence score
+
+
+def run_vulture(
+    paths: list[str] | None = None,
+    min_confidence: int = 60,
+    cwd: str = ".",
+    exclude: str = DEFAULT_EXCLUDE,
+) -> list[BloatFinding]:
+    """Real dead-code candidates: unused functions, classes, variables,
+    imports. `paths` defaults to `["."]` — the whole target repo, since
+    this tool can't assume any particular directory layout — with
+    `exclude` defaulting to skip `.venv`/`.git`/build artifacts, which are
+    routinely inside a real project's repo root and are never the
+    caller's own code (see DEFAULT_EXCLUDE for why this isn't optional)."""
+    targets = paths or ["."]
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "vulture",
+            *targets,
+            "--min-confidence",
+            str(min_confidence),
+            *(["--exclude", exclude] if exclude else []),
+        ],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    findings = []
+    for line in result.stdout.strip().splitlines():
+        match = _VULTURE_LINE_RE.match(line)
+        if not match:
+            continue  # vulture prints nothing else on stdout in normal operation, but don't crash if it ever does
+        findings.append(
+            BloatFinding(
+                tool="vulture",
+                file=match.group("file"),
+                line=int(match.group("line")),
+                message=match.group("message"),
+                confidence=int(match.group("confidence")),
+            )
+        )
+    return findings
+
+
+def run_deptry(cwd: str = ".") -> list[BloatFinding]:
+    """Real unused/missing/transitive dependency issues, via deptry's own
+    `--json-output` (structured, not text-scraped). Returns an empty list,
+    not an error, when the target repo has no `pyproject.toml` at all —
+    deptry can't run without one, and a repo with no Python packaging
+    metadata simply has nothing for it to check."""
+    import json
+    import tempfile
+
+    if not (Path(cwd) / "pyproject.toml").exists():
+        return []
+
+    with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as tmp:
+        output_path = tmp.name
+
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "deptry", ".", "--json-output", output_path],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+        )
+        raw = Path(cwd, output_path).read_text(encoding="utf-8")
+        issues = json.loads(raw) if raw.strip() else []
+    finally:
+        Path(output_path).unlink(missing_ok=True)
+
+    findings = []
+    for issue in issues:
+        location = issue.get("location", {})
+        findings.append(
+            BloatFinding(
+                tool="deptry",
+                file=location.get("file", "pyproject.toml"),
+                line=location.get("line"),
+                message=f"{issue.get('error', {}).get('code', '?')}: "
+                f"{issue.get('error', {}).get('message', issue)}",
+            )
+        )
+    return findings
+
+
+def run_bloat_check(
+    cwd: str = ".",
+    min_confidence: int = 60,
+    vulture_paths: list[str] | None = None,
+    vulture_exclude: str = DEFAULT_EXCLUDE,
+) -> list[BloatFinding]:
+    """Both tools together, as one flat list of real candidates — the
+    single entry point the MCP server (and any other caller) should use."""
+    return run_vulture(
+        paths=vulture_paths, min_confidence=min_confidence, cwd=cwd, exclude=vulture_exclude
+    ) + run_deptry(cwd=cwd)

safe_fix_mcp-0.1.0/src/safe_fix_mcp/bloat_pr.py

@@ -0,0 +1,217 @@
+"""Autonomous branch+PR proposal for bloat_check's SAFEST finding class
+only: unused imports on a single-name import line. A human still clicks
+merge — this automates *drafting* the removal, not *approving* it.
+
+Deliberately does NOT auto-remove anything else bloat_check finds:
+
+- Unused functions/classes/variables/attributes (vulture): a well-known
+  false-positive class lives here, not in unused imports — Pydantic/
+  dataclass field declarations, framework fixtures, and anything accessed
+  via reflection/dynamic attribute access can't be traced by vulture's
+  static analysis. An unused *import* has no equivalent escape hatch: if
+  nothing in the scanned tree references the name, removing the import
+  line is safe by construction.
+- Unused dependencies (deptry DEP002): real removal means editing
+  `pyproject.toml`'s dependency arrays correctly (project deps vs.
+  optional extras vs. tool-specific tables) — that needs a real
+  TOML-structure-aware rewrite, not blind line deletion.
+
+A multi-name import line (`from x import y, z` where only `y` is
+unused) is also excluded even though vulture flags it: deleting the
+whole line would silently remove `z` too. `_is_safe_single_import_line`
+gates on this before a finding is ever added to the auto-remove set.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from safe_fix_mcp.bloat_check import BloatFinding, run_bloat_check
+
+AUTO_PR_MIN_CONFIDENCE = 90  # higher bar than run_bloat_check's own 60% default report threshold — this path commits and pushes without a per-finding human review, so the bar for what qualifies is deliberately stricter.
+
+_SIMPLE_IMPORT_RE = re.compile(
+    r"^\s*(import\s+[\w.]+(\s+as\s+\w+)?|from\s+[\w.]+\s+import\s+\**\w+(\s+as\s+\w+)?)\s*$"
+)
+
+
+@dataclass(frozen=True)
+class BloatPrResult:
+    status: str  # "nothing_to_propose" | "dirty_worktree" | "tests_failed" | "opened" | "pr_creation_failed"
+    branch: str | None = None
+    pr_url: str | None = None
+    removed: tuple[BloatFinding, ...] = field(default_factory=tuple)
+    needs_manual_review: tuple[BloatFinding, ...] = field(default_factory=tuple)
+    detail: str = ""
+
+
+def _run_git(args: list[str], cwd: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
+
+
+def _is_safe_single_import_line(file_path: Path, line_no: int) -> bool:
+    try:
+        lines = file_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return False
+    if not (1 <= line_no <= len(lines)):
+        return False
+    return bool(_SIMPLE_IMPORT_RE.match(lines[line_no - 1]))
+
+
+def _auto_removable_imports(findings: list[BloatFinding], cwd: str) -> list[BloatFinding]:
+    return [
+        f
+        for f in findings
+        if f.tool == "vulture"
+        and f.message.startswith("unused import ")
+        and f.confidence is not None
+        and f.confidence >= AUTO_PR_MIN_CONFIDENCE
+        and _is_safe_single_import_line(Path(cwd, f.file), f.line)
+    ]
+
+
+def _remove_import_lines(removals: list[BloatFinding], cwd: str) -> None:
+    """Groups by file, removes highest line number first per file so an
+    earlier removal never shifts the line numbers of ones still pending."""
+    by_file: dict[str, list[int]] = {}
+    for finding in removals:
+        by_file.setdefault(finding.file, []).append(finding.line)
+
+    for rel_path, line_numbers in by_file.items():
+        target = Path(cwd, rel_path)
+        lines = target.read_text(encoding="utf-8").splitlines(keepends=True)
+        for line_no in sorted(line_numbers, reverse=True):
+            del lines[line_no - 1]
+        target.write_text("".join(lines), encoding="utf-8")
+
+
+def _default_run_tests(cwd: str) -> bool:
+    result = subprocess.run([sys.executable, "-m", "pytest", "-q"], cwd=cwd)
+    return result.returncode == 0
+
+
+def _default_push_branch(branch: str, cwd: str) -> None:
+    result = _run_git(["push", "-u", "origin", branch], cwd)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "git push failed")
+
+
+def _default_open_pr(branch: str, title: str, body: str, cwd: str) -> str:
+    result = subprocess.run(
+        ["gh", "pr", "create", "--title", title, "--body", body, "--head", branch],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "gh pr create failed")
+    return result.stdout.strip()
+
+
+def _pr_body(removed: list[BloatFinding], manual: list[BloatFinding]) -> str:
+    lines = [
+        "Automated by `safe-fix-mcp` — removes only unused imports at "
+        f">= {AUTO_PR_MIN_CONFIDENCE}% vulture confidence, on single-name "
+        "import lines only. Nothing else was touched.",
+        "",
+        "## Removed",
+    ]
+    lines += [f"- `{f.file}:{f.line}` — {f.message} ({f.confidence}%)" for f in removed]
+    if manual:
+        lines += [
+            "",
+            "## Found but NOT auto-removed — needs manual review",
+        ]
+        lines += [f"- `{f.file}:{f.line}` ({f.tool}) — {f.message}" for f in manual]
+    return "\n".join(lines)
+
+
+def propose_bloat_removal_pr(
+    cwd: str = ".",
+    vulture_paths: list[str] | None = None,
+    run_tests: Callable[[str], bool] = _default_run_tests,
+    push_branch: Callable[[str, str], None] = _default_push_branch,
+    open_pr: Callable[[str, str, str, str], str] = _default_open_pr,
+) -> BloatPrResult:
+    """The real workflow: scan -> filter to the safe subset -> branch ->
+    remove -> run the REAL full test suite as the safety gate -> only
+    commit/push/PR if it still passes. Any failure at any step leaves the
+    working tree exactly as it started."""
+    status = _run_git(["status", "--porcelain"], cwd)
+    if status.stdout.strip():
+        return BloatPrResult(status="dirty_worktree", detail="uncommitted changes present — commit or stash first")
+
+    findings = run_bloat_check(cwd=cwd, vulture_paths=vulture_paths)
+    removable = _auto_removable_imports(findings, cwd)
+    manual = [f for f in findings if f not in removable]
+
+    if not removable:
+        return BloatPrResult(status="nothing_to_propose", needs_manual_review=tuple(manual))
+
+    original_branch = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd).stdout.strip()
+    branch = f"safe-fix-mcp/auto-unused-imports-{uuid.uuid4().hex[:8]}"
+    _run_git(["checkout", "-b", branch], cwd)
+
+    _remove_import_lines(removable, cwd)
+
+    if not run_tests(cwd):
+        _run_git(["checkout", "--", "."], cwd)
+        _run_git(["checkout", original_branch], cwd)
+        _run_git(["branch", "-D", branch], cwd)
+        return BloatPrResult(
+            status="tests_failed",
+            branch=branch,
+            removed=tuple(removable),
+            needs_manual_review=tuple(manual),
+            detail="full test suite failed after removing the flagged imports — nothing committed or pushed",
+        )
+
+    commit_lines = [f"- {f.file}:{f.line} — {f.message} ({f.confidence}%)" for f in removable]
+    _run_git(["add", "-A"], cwd)
+    _run_git(
+        [
+            "commit",
+            "-m",
+            "chore: remove unused imports flagged by vulture (auto-proposed)\n\n" + "\n".join(commit_lines),
+        ],
+        cwd,
+    )
+
+    try:
+        push_branch(branch, cwd)
+    except Exception as exc:  # noqa: BLE001 — real network/auth/remote failure, not a code bug
+        return BloatPrResult(
+            status="pr_creation_failed",
+            branch=branch,
+            removed=tuple(removable),
+            needs_manual_review=tuple(manual),
+            detail=f"committed to {branch!r} locally, but push failed: {exc}",
+        )
+
+    title = f"chore: remove {len(removable)} unused import(s) flagged by vulture"
+    body = _pr_body(removable, manual)
+    try:
+        pr_url = open_pr(branch, title, body, cwd)
+    except Exception as exc:  # noqa: BLE001 — e.g. `gh` not installed/authenticated
+        return BloatPrResult(
+            status="pr_creation_failed",
+            branch=branch,
+            removed=tuple(removable),
+            needs_manual_review=tuple(manual),
+            detail=f"pushed {branch!r}, but PR creation failed: {exc} — open it manually",
+        )
+
+    return BloatPrResult(
+        status="opened",
+        branch=branch,
+        pr_url=pr_url,
+        removed=tuple(removable),
+        needs_manual_review=tuple(manual),
+    )

safe_fix_mcp-0.1.0/src/safe_fix_mcp/server.py

@@ -0,0 +1,112 @@
+"""safe-fix-mcp: real MCP server exposing bloat_check/bloat_pr as tools
+any MCP client (Claude Code, Claude Desktop, Cursor, etc.) can call
+against any target repository — not tied to any one project.
+
+    safe-fix-mcp                      # stdio, the real entry point clients use
+    python -m safe_fix_mcp.server     # same, for local testing
+"""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from safe_fix_mcp.bloat_check import run_bloat_check
+from safe_fix_mcp.bloat_pr import propose_bloat_removal_pr
+
+mcp = MCPServer(
+    name="safe-fix-mcp",
+    title="Safe Fix",
+    version="0.1.0",
+    instructions=(
+        "Finds real dead code (vulture) and dependency issues (deptry) in a "
+        "Python repository. `scan_dead_code` is read-only and always safe to "
+        "call. `propose_removal_pr` goes further: it creates a real git "
+        "branch, removes only unused imports on single-name import lines at "
+        ">= 90% vulture confidence, runs the target repo's own full test "
+        "suite as a safety gate, and only commits/pushes/opens a PR if that "
+        "suite still passes. A human still has to merge the PR — this tool "
+        "never merges anything itself."
+    ),
+)
+
+
+def _format_findings(findings) -> str:
+    if not findings:
+        return "No real candidates found."
+    lines = [f"{len(findings)} real candidate(s):"]
+    for f in findings:
+        confidence = f" ({f.confidence}% confidence)" if f.confidence is not None else ""
+        location = f"{f.file}:{f.line}" if f.line else f.file
+        lines.append(f"- [{f.tool}] {location} — {f.message}{confidence}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def scan_dead_code(repo_path: str = ".", min_confidence: int = 60) -> str:
+    """Scan a Python repository for real dead code (vulture) and dependency
+    issues (deptry). Read-only — never modifies anything. Returns a
+    human-readable list of findings, or "No real candidates found."
+
+    repo_path: path to the repository to scan (must contain a
+      pyproject.toml for the dependency checks to run; dead-code scanning
+      works regardless).
+    min_confidence: vulture's own confidence threshold (0-100). Lower
+      values surface more candidates but more false positives.
+    """
+    try:
+        findings = run_bloat_check(cwd=repo_path, min_confidence=min_confidence)
+    except FileNotFoundError as exc:
+        return f"vulture/deptry not available in this environment: {exc}"
+    return _format_findings(findings)
+
+
+@mcp.tool()
+def propose_removal_pr(repo_path: str = ".") -> str:
+    """Propose a real branch+PR removing only unused imports (single-name
+    import lines, >= 90% vulture confidence) from a Python repository. Runs
+    the repo's own full test suite as a safety gate before ever committing
+    or pushing — a failure there reverts everything and nothing is
+    committed or pushed. If `gh` isn't available or PR creation otherwise
+    fails, the branch is still committed and pushed for real; only the PR
+    itself needs opening manually. A human always merges — this never
+    merges anything itself.
+
+    repo_path: path to a real git repository with a clean working tree
+      (uncommitted changes are refused, not overwritten).
+    """
+    result = propose_bloat_removal_pr(cwd=repo_path)
+
+    if result.status == "dirty_worktree":
+        return f"Refused: {result.detail}"
+    if result.status == "nothing_to_propose":
+        extra = f" ({len(result.needs_manual_review)} other finding(s) need manual review.)" if result.needs_manual_review else ""
+        return "No unused imports qualified for automatic removal." + extra
+    if result.status == "tests_failed":
+        return (
+            f"Removed {len(result.removed)} import(s), but the real test suite "
+            f"failed afterward — reverted, nothing committed or pushed. {result.detail}"
+        )
+    if result.status == "pr_creation_failed":
+        return (
+            f"Branch {result.branch!r} committed and pushed, but PR creation "
+            f"failed — open it manually. {result.detail}"
+        )
+    # "opened"
+    manual_note = (
+        f" {len(result.needs_manual_review)} other finding(s) need manual review."
+        if result.needs_manual_review
+        else ""
+    )
+    return (
+        f"Opened: {result.pr_url}\n"
+        f"Removed {len(result.removed)} unused import(s) on branch {result.branch!r}."
+        f"{manual_note}"
+    )
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

safe_fix_mcp-0.1.0/tests/test_bloat_check.py

@@ -0,0 +1,91 @@
+"""Real tests against the actual vulture/deptry subprocesses, not mocked
+output.
+"""
+
+from safe_fix_mcp.bloat_check import (
+    _VULTURE_LINE_RE,
+    BloatFinding,
+    run_bloat_check,
+    run_deptry,
+    run_vulture,
+)
+
+
+class TestVultureLineParsing:
+    def test_parses_a_real_vulture_output_line(self):
+        line = "src/app.py:12: unused function 'helper' (60% confidence)"
+
+        match = _VULTURE_LINE_RE.match(line)
+
+        assert match.group("file") == "src/app.py"
+        assert match.group("line") == "12"
+        assert match.group("message") == "unused function 'helper'"
+        assert match.group("confidence") == "60"
+
+    def test_does_not_match_an_unrelated_line(self):
+        assert _VULTURE_LINE_RE.match("Scanning 82 files...") is None
+
+
+class TestRunVultureReal:
+    def test_finds_a_real_genuinely_unused_function(self, tmp_path):
+        (tmp_path / "sample.py").write_text(
+            "def used():\n"
+            "    return 1\n"
+            "\n"
+            "\n"
+            "def totally_unused_helper():\n"
+            "    return 2\n"
+            "\n"
+            "\n"
+            "used()\n",
+            encoding="utf-8",
+        )
+
+        findings = run_vulture(paths=["sample.py"], min_confidence=60, cwd=str(tmp_path))
+
+        assert any(f.tool == "vulture" and "totally_unused_helper" in f.message for f in findings)
+        assert not any("'used'" in f.message for f in findings)
+
+    def test_finds_nothing_when_everything_is_used(self, tmp_path):
+        (tmp_path / "sample.py").write_text("def used():\n    return 1\n\n\nused()\n", encoding="utf-8")
+
+        findings = run_vulture(paths=["sample.py"], min_confidence=60, cwd=str(tmp_path))
+
+        assert findings == []
+
+    def test_defaults_to_scanning_the_whole_target_repo(self, tmp_path):
+        # No fixed src/tests layout assumed -- paths=None must scan "."
+        (tmp_path / "sample.py").write_text(
+            "def totally_unused_here():\n    return 1\n", encoding="utf-8"
+        )
+
+        findings = run_vulture(paths=None, min_confidence=60, cwd=str(tmp_path))
+
+        assert any("totally_unused_here" in f.message for f in findings)
+
+
+class TestRunDeptryReal:
+    def test_returns_empty_when_no_pyproject_toml_exists(self, tmp_path):
+        assert run_deptry(cwd=str(tmp_path)) == []
+
+    def test_returns_a_list_of_findings_or_empty_for_a_clean_project(self, tmp_path):
+        (tmp_path / "pyproject.toml").write_text(
+            '[project]\nname = "tmp"\nversion = "0.0.0"\ndependencies = []\n', encoding="utf-8"
+        )
+
+        findings = run_deptry(cwd=str(tmp_path))
+
+        assert isinstance(findings, list)
+        assert all(isinstance(f, BloatFinding) and f.tool == "deptry" for f in findings)
+
+
+class TestRunBloatCheck:
+    def test_combines_both_tools_real_output(self, tmp_path):
+        (tmp_path / "sample.py").write_text("def totally_unused_again():\n    return 1\n", encoding="utf-8")
+        (tmp_path / "pyproject.toml").write_text(
+            '[project]\nname = "tmp"\nversion = "0.0.0"\ndependencies = []\n', encoding="utf-8"
+        )
+
+        findings = run_bloat_check(cwd=str(tmp_path), vulture_paths=["sample.py"])
+
+        assert any(f.tool == "vulture" for f in findings)

safe_fix_mcp-0.1.0/tests/test_bloat_pr.py

@@ -0,0 +1,145 @@
+"""Real tests: unit coverage for the safe-removal filtering/editing logic,
+plus a full end-to-end run against a real git repo (real branch, real
+commit, real push to a local bare remote) with only `gh pr create` faked
+-- there's no way to test against a real GitHub repo locally.
+"""
+
+import subprocess
+
+import pytest
+
+from safe_fix_mcp.bloat_check import BloatFinding
+from safe_fix_mcp.bloat_pr import (
+    AUTO_PR_MIN_CONFIDENCE,
+    _auto_removable_imports,
+    _is_safe_single_import_line,
+    _remove_import_lines,
+    propose_bloat_removal_pr,
+)
+
+
+class TestIsSafeSingleImportLine:
+    def test_plain_import_is_safe(self, tmp_path):
+        f = tmp_path / "m.py"
+        f.write_text("import os\n")
+        assert _is_safe_single_import_line(f, 1) is True
+
+    def test_multi_name_import_is_not_safe(self, tmp_path):
+        f = tmp_path / "m.py"
+        f.write_text("from pathlib import Path, PurePath\n")
+        assert _is_safe_single_import_line(f, 1) is False
+
+    def test_non_import_line_is_not_safe(self, tmp_path):
+        f = tmp_path / "m.py"
+        f.write_text("x = 1\n")
+        assert _is_safe_single_import_line(f, 1) is False
+
+
+class TestAutoRemovableImports:
+    def _finding(self, **overrides):
+        defaults = dict(tool="vulture", file="m.py", line=1, message="unused import 'os'", confidence=95)
+        return BloatFinding(**{**defaults, **overrides})
+
+    def test_includes_a_qualifying_finding(self, tmp_path):
+        (tmp_path / "m.py").write_text("import os\n")
+        findings = [self._finding()]
+
+        assert _auto_removable_imports(findings, str(tmp_path)) == findings
+
+    def test_excludes_low_confidence(self, tmp_path):
+        (tmp_path / "m.py").write_text("import os\n")
+        findings = [self._finding(confidence=AUTO_PR_MIN_CONFIDENCE - 1)]
+
+        assert _auto_removable_imports(findings, str(tmp_path)) == []
+
+    def test_excludes_multi_name_import_lines(self, tmp_path):
+        (tmp_path / "m.py").write_text("from pathlib import Path, PurePath\n")
+        findings = [self._finding()]
+
+        assert _auto_removable_imports(findings, str(tmp_path)) == []
+
+
+class TestRemoveImportLines:
+    def test_removes_the_exact_line(self, tmp_path):
+        f = tmp_path / "m.py"
+        f.write_text("import os\nx = 1\n")
+        finding = BloatFinding(tool="vulture", file="m.py", line=1, message="unused import 'os'", confidence=95)
+
+        _remove_import_lines([finding], str(tmp_path))
+
+        assert f.read_text() == "x = 1\n"
+
+    def test_a_removal_above_does_not_corrupt_a_kept_line_below(self, tmp_path):
+        f = tmp_path / "m.py"
+        f.write_text("import os\ny = 2\nimport sys\n")
+        findings = [BloatFinding(tool="vulture", file="m.py", line=1, message="unused import 'os'", confidence=95)]
+
+        _remove_import_lines(findings, str(tmp_path))
+
+        assert f.read_text() == "y = 2\nimport sys\n"
+
+
+def _run_git(args, cwd, **kw):
+    return subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True, text=True, **kw)
+
+
+@pytest.fixture
+def bloat_repo(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _run_git(["init"], repo)
+    _run_git(["config", "user.email", "test@example.com"], repo)
+    _run_git(["config", "user.name", "Test"], repo)
+
+    (repo / "pyproject.toml").write_text(
+        '[project]\nname = "tmp"\nversion = "0.0.0"\ndependencies = []\n', encoding="utf-8"
+    )
+    (repo / "mod.py").write_text("import os\n\n\ndef used():\n    return 1\n\n\nused()\n", encoding="utf-8")
+    (repo / "test_mod.py").write_text("def test_ok():\n    assert True\n", encoding="utf-8")
+
+    _run_git(["add", "-A"], repo)
+    _run_git(["commit", "-m", "initial commit"], repo)
+    return repo
+
+
+class TestProposeBloatRemovalPr:
+    def test_dirty_worktree_is_refused_without_touching_anything(self, bloat_repo):
+        (bloat_repo / "mod.py").write_text("import os\nos.getcwd()\n", encoding="utf-8")
+
+        result = propose_bloat_removal_pr(cwd=str(bloat_repo))
+
+        assert result.status == "dirty_worktree"
+
+    def test_opens_a_real_pr_when_tests_pass(self, bloat_repo, tmp_path):
+        bare_remote = tmp_path / "bare_remote.git"
+        _run_git(["init", "--bare", str(bare_remote)], bloat_repo)
+        _run_git(["remote", "add", "origin", str(bare_remote)], bloat_repo)
+
+        opened_prs = []
+
+        def fake_open_pr(branch, title, body, cwd):
+            opened_prs.append((branch, title, body))
+            return "https://github.com/fake/fake/pull/1"
+
+        result = propose_bloat_removal_pr(
+            cwd=str(bloat_repo),
+            run_tests=lambda cwd: True,
+            open_pr=fake_open_pr,
+        )
+
+        assert result.status == "opened"
+        assert result.pr_url == "https://github.com/fake/fake/pull/1"
+        assert len(result.removed) == 1
+        remote_branches = _run_git(["ls-remote", "--heads", "origin"], bloat_repo).stdout
+        assert result.branch in remote_branches
+        assert (bloat_repo / "mod.py").read_text() == "\n\ndef used():\n    return 1\n\n\nused()\n"
+
+    def test_aborts_cleanly_and_leaves_no_branch_when_tests_fail(self, bloat_repo):
+        original_branch = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], bloat_repo).stdout.strip()
+
+        result = propose_bloat_removal_pr(cwd=str(bloat_repo), run_tests=lambda cwd: False)
+
+        assert result.status == "tests_failed"
+        assert _run_git(["rev-parse", "--abbrev-ref", "HEAD"], bloat_repo).stdout.strip() == original_branch
+        assert _run_git(["status", "--porcelain"], bloat_repo).stdout.strip() == ""
+        assert result.branch not in _run_git(["branch"], bloat_repo).stdout

safe_fix_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,97 @@
+"""Real MCP-protocol-level tests: calls go through `mcp.call_tool()` --
+the actual dispatch path a real MCP client uses -- not the underlying
+Python functions directly. Proves the MCP wrapping itself works, not
+just the ported logic (already covered in test_bloat_check.py/
+test_bloat_pr.py).
+
+`propose_removal_pr`'s "opened" (real PR) happy path can't be tested
+through the public tool interface -- it has no injection point by
+design, and there's no real GitHub repo to test against locally. The
+"pr_creation_failed but branch really pushed" path IS fully real and
+testable here: `gh` genuinely isn't installed in this environment
+(confirmed live), so a real scratch repo with a real local bare remote
+exercises the complete real chain -- vulture scan, branch, removal, real
+pytest run, commit, real push -- through nothing but the public MCP tool
+call, with only the final `gh pr create` failing for a real reason.
+"""
+
+import subprocess
+
+import pytest
+
+from safe_fix_mcp.server import mcp
+
+
+def _text(result) -> str:
+    return result.content[0].text
+
+
+class TestScanDeadCodeTool:
+    @pytest.mark.asyncio
+    async def test_reports_no_candidates_for_a_clean_repo(self, tmp_path):
+        (tmp_path / "clean.py").write_text("def used():\n    return 1\n\n\nused()\n", encoding="utf-8")
+
+        result = await mcp.call_tool("scan_dead_code", {"repo_path": str(tmp_path)})
+
+        assert _text(result) == "No real candidates found."
+
+    @pytest.mark.asyncio
+    async def test_reports_a_real_finding(self, tmp_path):
+        (tmp_path / "dirty.py").write_text("def totally_unused_xyz():\n    return 1\n", encoding="utf-8")
+
+        result = await mcp.call_tool("scan_dead_code", {"repo_path": str(tmp_path)})
+
+        assert "totally_unused_xyz" in _text(result)
+
+
+def _run_git(args, cwd, **kw):
+    return subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True, text=True, **kw)
+
+
+@pytest.fixture
+def bloat_repo(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _run_git(["init"], repo)
+    _run_git(["config", "user.email", "test@example.com"], repo)
+    _run_git(["config", "user.name", "Test"], repo)
+    (repo / "pyproject.toml").write_text(
+        '[project]\nname = "tmp"\nversion = "0.0.0"\ndependencies = []\n', encoding="utf-8"
+    )
+    (repo / "mod.py").write_text("import os\n\n\ndef used():\n    return 1\n\n\nused()\n", encoding="utf-8")
+    (repo / "test_mod.py").write_text("def test_ok():\n    assert True\n", encoding="utf-8")
+    _run_git(["add", "-A"], repo)
+    _run_git(["commit", "-m", "initial commit"], repo)
+    return repo
+
+
+class TestProposeRemovalPrTool:
+    @pytest.mark.asyncio
+    async def test_refuses_a_dirty_worktree_through_the_real_tool_call(self, bloat_repo):
+        (bloat_repo / "mod.py").write_text("import os\nos.getcwd()\n", encoding="utf-8")
+
+        result = await mcp.call_tool("propose_removal_pr", {"repo_path": str(bloat_repo)})
+
+        assert _text(result).startswith("Refused:")
+
+    @pytest.mark.asyncio
+    async def test_real_end_to_end_through_the_public_tool_gh_missing_in_this_environment(
+        self, bloat_repo, tmp_path
+    ):
+        # No mocks anywhere in this test: real vulture scan, real branch,
+        # real file edit, real pytest run against the scratch repo's own
+        # test_mod.py, real commit, real push to a real local bare
+        # remote -- only gh pr create fails, because gh really isn't
+        # installed here (confirmed live before writing this test).
+        bare_remote = tmp_path / "bare_remote.git"
+        _run_git(["init", "--bare", str(bare_remote)], bloat_repo)
+        _run_git(["remote", "add", "origin", str(bare_remote)], bloat_repo)
+
+        result = await mcp.call_tool("propose_removal_pr", {"repo_path": str(bloat_repo)})
+
+        text = _text(result)
+        assert "committed and pushed" in text
+        assert "PR creation failed" in text
+        remote_branches = _run_git(["ls-remote", "--heads", "origin"], bloat_repo).stdout
+        assert remote_branches.strip() != ""
+        assert (bloat_repo / "mod.py").read_text() == "\n\ndef used():\n    return 1\n\n\nused()\n"