reforge-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for working in this repository.

What this is

An MCP server that exposes a codebase to Claude Code as structured tools so it can scan, plan and apply refactors with rollback. Python 3.11+, tree-sitter for parsing, FastMCP for the tool surface. Pre-1.0 and honestly alpha.

Commands

uv run pytest -q            # the test suite — plain `python -m pytest` has no pytest installed
uv run pytest tests/test_fix.py -q
uv run reforge-mcp          # start the server (stdio)

Self-scan — the fastest way to see whether a scanner change actually works:

uv run python -c "import sys,json; sys.path.insert(0,'src'); \
from reforge_mcp.tools.scan import scan_repo; \
print(json.dumps(scan_repo('.'), indent=1))"

Layout

src/reforge_mcp/
  server.py          FastMCP entry point — registers all tools, thin wrappers only
  tools/             one file per MCP tool: scan, chunk, fix, git
  scanner/           analysis: parser (tree-sitter), dead_code, duplicates, risk, architecture
  scanner/adapters/  per-language stubs (currently 7 lines each; see R20)
  utils/             security (path + command validation), diff, state
tests/               one file per module, pytest, no fixtures framework beyond tmp_path

Invariants — do not break these

• Every path from a tool argument goes through utils.security.validate_path before any read or write. It is the only thing standing between a caller and the rest of the filesystem. Same for validate_test_command before any subprocess.
• server.py stays thin. Tool functions there wrap an implementation in tools/ or scanner/ and do nothing else. Logic in server.py is untestable.
• State writes are .tmp -> rename. See utils/state.py:save_state. Never write reforge-state.json in place.
• write_fix must leave the file either correctly changed or byte-identical, on every path. The backup is a byte copy under a unique tempfile name, so restoring it is a no-op even where nothing needed restoring; if a new early-return is added, check it goes through _restore or unlinks the copy. Never read or write a patched file with read_text/write_text: that translates line endings and was R37.
• Scanner output is a public contract. scan_repo's return shape is consumed by get_health_score, score_risk and infer_architecture. Changing a key means changing all three.