chore(conductor): Add new track 'Add Python structural MCP tools'

conductor/tracks.md

@@ -260,3 +260,7 @@ This file tracks all major tracks for the project. Each track has its own detail
 
 - [x] **Track: I started to do a large cleanup to ./src/gui_2.py. I want you to study it and derive more information on how to maintain and write code for the python codebase. Please update product guidlines or the python code_styleguidleines based on what you discover. Also we may need to make some changes the mcp_tools for better structural awareness of annotations or other conventions with these python files. There is still more orgnaizatoin to be done like annotation/organizing the __init__ method's declarations, among other nitpicks.**
 *Link: [./tracks/gui_2_cleanup_20260513/](./tracks/gui_2_cleanup_20260513/)*
+---
+
+- [ ] **Track: Add Python structural MCP tools (py_remove_def, py_add_def, py_move_def, py_region_wrap)**
+*Link: [./tracks/python_structural_mcp_tools_20260513/](./tracks/python_structural_mcp_tools_20260513/)*

conductor/tracks/python_structural_mcp_tools_20260513/index.md

@@ -0,0 +1,5 @@
+# Track python_structural_mcp_tools_20260513 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/tracks/python_structural_mcp_tools_20260513/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "python_structural_mcp_tools_20260513",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-05-13T21:00:00Z",
+  "updated_at": "2026-05-13T21:00:00Z",
+  "description": "Add Python structural MCP tools (py_remove_def, py_add_def, py_move_def, py_region_wrap) with AST-aware slicing and strict 1-space indentation preservation."
+}

conductor/tracks/python_structural_mcp_tools_20260513/plan.md

@@ -0,0 +1,22 @@
+# Implementation Plan: Python Structural MCP Tools
+
+## Phase 1: Core Logic Implementation
+- [ ] Task: Create `scripts/py_struct_tools.py` to house shared AST and regex manipulation logic.
+- [ ] Task: Implement the "Surgical Indentation Shifter" utility to enforce 1-space indentation context without destructive full-file formatting.
+- [ ] Task: Implement `py_remove_def` core logic.
+- [ ] Task: Implement `py_add_def` core logic.
+- [ ] Task: Implement `py_move_def` core logic.
+- [ ] Task: Implement `py_region_wrap` core logic.
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Core Logic Implementation' (Protocol in workflow.md)
+
+## Phase 2: MCP Client Integration
+- [ ] Task: Register JSON schemas for `py_remove_def`, `py_add_def`, `py_move_def`, and `py_region_wrap` in `src/mcp_client.py`.
+- [ ] Task: Implement dispatch handlers in `src/mcp_client.py` to bridge the native tool calls to the `./scripts/py_struct_tools.py` logic.
+- [ ] Task: Update the `TOOL_NAMES` and `MUTATING_TOOLS` constants to include the new capabilities.
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: MCP Client Integration' (Protocol in workflow.md)
+
+## Phase 3: Testing & Validation
+- [ ] Task: Create `tests/test_py_struct_tools.py` and write unit tests for the indentation shifter and AST extraction logic.
+- [ ] Task: Write integration tests verifying the execution of the new tools via the MCP dispatcher.
+- [ ] Task: Run the full test suite in batches to ensure no regressions in existing MCP routing.
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Testing & Validation' (Protocol in workflow.md)

conductor/tracks/python_structural_mcp_tools_20260513/spec.md

@@ -0,0 +1,21 @@
+# 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).