# Specification: Python Structural MCP Tools

## Overview
The current MCP toolset relies heavily on arbitrary line slicing (`set_file_slice`) for Python implementation changes, which is prone to errors and indentation drift. This track introduces a suite of AST-aware Python structural manipulation tools designed to act on semantic boundaries (definitions, regions) rather than raw line numbers.

## Functional Requirements
1. **`py_remove_def`**: Excises a specific class or function definition from a Python file using AST-derived line ranges, preserving surrounding formatting and comments.
2. **`py_add_def`**: Inserts a new definition into a specific context (module level or within a specific class).
3. **`py_move_def`**: Relocates a definition within a file or across different Python files.
4. **`py_region_wrap`**: Wraps a specified block of code (e.g., a set of methods) in `#region: Name` and `#endregion: Name` tags to support the project's structural guidelines.

## Technical Requirements
- **Mechanism (Regex + AST Hybrid)**: Tools must use the `ast` module to accurately identify start and end lines of target definitions, then perform string-based manipulation on the source text to ensure existing stylistic choices, blank lines, and comments are perfectly preserved.
- **Surgical Indentation Correction**: When adding or moving definitions, the tools must automatically adjust the base indentation of the incoming payload to adhere to the project's strict 1-space rule. **Crucially, this must be a targeted indentation shift (e.g., stripping existing leading whitespace and prepending the correct number of spaces based on context depth). It must NOT invoke a full code formatter (like `ai_style_formatter.py`) that might destroy custom internal formatting.**
- **Integration & Modularity**:
  - The tools will be registered as native capabilities in `src/mcp_client.py`.
  - To maintain clean architecture, the underlying logic for complex manipulations will be modularized into dedicated helper scripts within `./scripts/` (e.g., `scripts/tool_py_add_def.py` or a consolidated structural utility module).

## Out of Scope
- Full-file automated formatting.
- Structural tools for non-Python languages (C/C++ tree-sitter tools are handled separately).