revise-mcp copilot-instructions.md

Project Guidelines

Overview

Revise MCP is an MCP (Model Context Protocol) server providing code refactoring tools that use substring matching with a ⬥ marker instead of line numbers — solving the problem of AI agents being unable to reliably count characters or coordinates. See doc/DESIGN.md for architecture and design principles.

Build and Test

poetry install              # Create/update .venv
poetry run pytest tests/    # Run all tests
poetry run python -m revise # Run server (stdio mode)

Requires Python 3.14+ and Poetry.

Architecture

• src/revise/server.py — Creates FastMCP instance; tools auto-register via @mcp.tool() decorators on import
• src/revise/tools/ — One file per tool (move_string_in_file.py, indent_dedent.py)
• src/revise/match.py — Shared ⬥-marker matching logic (parse, find, validate, expand context)
• src/revise/indent.py — Indent style auto-detection
• src/revise/__main__.py — CLI entrypoint; dispatches to mcp.run()

Conventions

Typing

Full type hints on all functions. Tool parameters use Annotated[type, "description"] — FastMCP parses these for schema generation.

Tool functions

• Must be async def (FastMCP requirement)
• Return JSON strings: {"success": true, ...} or {"success": false, "message": ...}
• Never raise exceptions to the caller — encode errors in the JSON response
• All boundary inputs are matched against the pre-edit file state

Error responses

Return rich error objects with disambiguation hints:

• matchingLines: {line_num: context} when multiple matches found
• subContextMatchingLines for partial sub-context fallback hints

Naming

• snake_case functions; internal helpers prefixed with _
• Test classes: class TestModuleName
• Test helpers: _write(tmp_path, name, content) for temp files, _call(...) wraps tool call + JSON parse

Tests

• Framework: pytest + pytest-asyncio
• Pattern: create temp file → call tool → assert JSON response + file content
• All test methods are async def with @pytest.mark.asyncio