semantic-edit-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP (Model Context Protocol) server for AST-aware code editing. Instead of line/character edits, edits target tree-sitter AST nodes located by a short text anchor, then the whole file is reformatted with the language's native formatter and re-parsed to guarantee the result is still syntactically valid before anything touches disk.

Commands

cargo build                          # build
cargo test                           # run all tests (the snapshot suite + unit tests)
cargo fmt --all -- --check           # formatting check (CI gate)
cargo clippy                         # lint (CI gate)
cargo run -- serve                   # run the MCP stdio server locally

Snapshot tests (the main test surface)

Most behavior is covered by data-driven snapshot tests under tests/snapshots/, discovered and run by src/tests/snapshot_runner.rs via the single run_snapshot_tests Rust test. Each test is a directory containing args.json (one tool call or an array of them), an optional input.<ext>, and the expected response.txt / output.<ext>.

TEST_FILTER=rust cargo test                    # run a category (prefix match)
TEST_FILTER=rust::attributes cargo test        # run one test (exact, "::"-joined path)
TEST_FILTER=json,rust cargo test               # multiple, comma-separated
UPDATE_SNAPSHOTS=1 cargo test                  # regenerate all expected files
UPDATE_SNAPSHOTS=1 TEST_FILTER=rust::attributes cargo test   # regenerate one

When a snapshot fails, the summary prints the exact TEST_FILTER=... and UPDATE_SNAPSHOTS=1 ... commands to reproduce or accept it. Always review a diff before accepting it with UPDATE_SNAPSHOTS=1 — the whole point of the suite is to catch unintended formatting/targeting changes.

External formatter dependencies

Editing relies on language-native formatters being on PATH; an edit fails (and is reported as unsafe) if its formatter is missing or errors: