diff --git a/conductor/tracks.md b/conductor/tracks.md index 3975a50..631b033 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -259,4 +259,8 @@ 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/)* \ No newline at end of file +*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/)* diff --git a/conductor/tracks/python_structural_mcp_tools_20260513/index.md b/conductor/tracks/python_structural_mcp_tools_20260513/index.md new file mode 100644 index 0000000..5918c79 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/conductor/tracks/python_structural_mcp_tools_20260513/metadata.json b/conductor/tracks/python_structural_mcp_tools_20260513/metadata.json new file mode 100644 index 0000000..a6fe235 --- /dev/null +++ b/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." +} diff --git a/conductor/tracks/python_structural_mcp_tools_20260513/plan.md b/conductor/tracks/python_structural_mcp_tools_20260513/plan.md new file mode 100644 index 0000000..dd30cef --- /dev/null +++ b/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) \ No newline at end of file diff --git a/conductor/tracks/python_structural_mcp_tools_20260513/spec.md b/conductor/tracks/python_structural_mcp_tools_20260513/spec.md new file mode 100644 index 0000000..dc45034 --- /dev/null +++ b/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). \ No newline at end of file