feat: add codecommander structural python tools

Author: Lukas Geiger

CHANGELOG.md

@@ -2,14 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## [1.3.13] - 2026-06-22
 
 ### Added
 - Add BACH-derived `cc_check_indentation` for Python indentation diagnostics.
 - Add BACH-derived `cc_generate_python_code` for template-based Python code snippets.
+- Extend `cc_extract_classes` with optional pycutter-style inline class/helper content for LLM context packaging.
+- Extend `cc_analyze_methods` with BACH-derived guardrails for missing signal callbacks, self-attributes used before definition, and underscore method mismatches.
+- Add BACH-derived `cc_runtime_import_diagnose` for isolated Python runtime import checks, `__init__.py` analysis, and circular-import hints.
+- Add BACH-derived `cc_python_structural_edit` for structural Python edits with preview, test-file, syntax-check and backup safety modes.
 - Replace Spanish, Simplified Chinese, Japanese, and Russian i18n fallbacks with maintained CodeCommander translations.
-- Update README, README_de, llms.txt, server metadata, i18n and security notes for 19 developer tools.
-- Extend the local Vitest suite to 154 tests.
+- Update README, README_de, llms.txt, server metadata, i18n and security notes for 21 developer tools.
+- Extend the local Vitest suite to 167 tests.
 
 ## [1.3.12] - 2026-06-17
 

README.md

@@ -12,9 +12,9 @@
 [![CodeCommander tests](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-A developer-focused **Model Context Protocol (MCP) server** that gives AI assistants code analysis, JSON repair, encoding fix, import organization, format conversion, file diff, and regex testing capabilities.
+A developer-focused **Model Context Protocol (MCP) server** that gives AI assistants code analysis, structural Python editing, JSON repair, encoding fix, import organization, format conversion, file diff, and regex testing capabilities.
 
-**19 tools** optimized for developers - the coding companion to [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp).
+**21 tools** optimized for developers - the coding companion to [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp).
 
 **Discoverability:** Published on [npm](https://www.npmjs.com/package/ellmos-codecommander-mcp) as `ellmos-codecommander-mcp`, visible on [Glama](https://glama.ai/mcp/servers/b9kjs4uaav), and prepared for the official MCP Registry with [`server.json`](server.json) under `io.github.ellmos-ai/ellmos-codecommander-mcp`.
 
@@ -25,7 +25,7 @@ A developer-focused **Model Context Protocol (MCP) server** that gives AI assist
 While FileCommander handles filesystem operations, CodeCommander focuses on **code intelligence**:
 
 - **Python Code Analysis** - AST-based class/method extraction, complexity metrics, import analysis
-- **BACH-derived Python Helpers** - indentation diagnostics and template-based code generation
+- **BACH-derived Python Helpers** - runtime import diagnostics, structural edits, indentation checks, and template-based code generation
 - **JSON Repair** - Fix broken JSON automatically (trailing commas, single quotes, BOM, comments)
 - **Import Organization** - Sort and deduplicate Python imports per PEP 8
 - **Encoding Fix** - Repair Mojibake and double-encoded UTF-8 (27+ patterns)
@@ -121,15 +121,16 @@ FileCommander and CodeCommander are designed to work side by side:
 | Tool | Description |
 |------|-------------|
 | `cc_analyze_code` | Full code analysis: classes, functions, imports, LOC, complexity |
-| `cc_analyze_methods` | Detailed method analysis: params, decorators, visibility, data flow |
-| `cc_extract_classes` | Extract Python classes/functions as separate text blocks |
+| `cc_analyze_methods` | Detailed method analysis: params, decorators, visibility, data flow, BACH guardrails |
+| `cc_extract_classes` | Extract Python classes/functions as separate text blocks, optionally including pycutter-style inline content |
 
-### Import Management (2 tools)
+### Import Management (3 tools)
 
 | Tool | Description |
 |------|-------------|
 | `cc_organize_imports` | Sort & deduplicate Python imports per PEP 8 |
 | `cc_diagnose_imports` | Detect unused imports, duplicates, circular import risks |
+| `cc_runtime_import_diagnose` | Run isolated Python runtime imports with timeouts, __init__.py analysis, and circular-import hints |
 
 ### JSON Tools (2 tools)
 
@@ -166,12 +167,13 @@ FileCommander and CodeCommander are designed to work side by side:
 | `cc_diff_files` | Compare two files with unified diff output (configurable context lines) |
 | `cc_regex_test` | Test regex patterns against text/files with match details, groups, and replace preview |
 
-### Python Assistance (2 tools)
+### Python Assistance (3 tools)
 
 | Tool | Description |
 |------|-------------|
 | `cc_check_indentation` | Detect missing colons, unindented return/yield statements, and mixed tab/space indentation |
 | `cc_generate_python_code` | Generate Python functions, classes, dataclasses, CLI stubs, tests, exceptions, and modules from templates |
+| `cc_python_structural_edit` | Inspect and apply structural Python edits with preview, test-file, syntax-check and backup modes |
 
 ### Export (2 tools)
 
@@ -180,7 +182,7 @@ FileCommander and CodeCommander are designed to work side by side:
 | `cc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |
 | `cc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |
 
-**Total: 19 developer tools** (`cc_set_language` is also available for runtime language switching)
+**Total: 21 developer tools** (`cc_set_language` is also available for runtime language switching)
 
 ---
 
@@ -211,7 +213,7 @@ All tools use the `cc_` prefix (CodeCommander) to avoid conflicts with FileComma
 See [SECURITY.md](SECURITY.md) for detailed security information.
 
 Key points:
-- All file-modifying tools support `dry_run` mode
+- File-modifying tools support preview/dry-run modes where applicable
 - Backup creation is enabled by default for destructive operations
 - No built-in sandboxing - security is delegated to the MCP client
 - Designed for local development use via stdio transport
@@ -230,7 +232,7 @@ npm test       # Run test suite (vitest)
 
 ### Testing
 
-The project includes a comprehensive test suite with **154 tests** covering all 19 developer tools and i18n behavior.
+The project includes a comprehensive test suite covering all 21 developer tools and i18n behavior.
 
 ```bash
 npm test              # Run all tests

README_de.md

@@ -13,9 +13,9 @@
 [![CodeCommander tests](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/ellmos-codecommander-mcp/actions/workflows/tests.yml)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-Ein entwicklerfokussierter **Model Context Protocol (MCP) Server**, der KI-Assistenten Fähigkeiten für Code-Analyse, JSON-Reparatur, Encoding-Korrektur, Import-Organisation, Formatkonvertierung, Datei-Vergleich und Regex-Tests verleiht.
+Ein entwicklerfokussierter **Model Context Protocol (MCP) Server**, der KI-Assistenten Fähigkeiten für Code-Analyse, strukturelles Python-Editing, JSON-Reparatur, Encoding-Korrektur, Import-Organisation, Formatkonvertierung, Datei-Vergleich und Regex-Tests verleiht.
 
-**19 Tools** optimiert für Entwickler – das Coding-Gegenstück zu [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp).
+**21 Tools** optimiert für Entwickler – das Coding-Gegenstück zu [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp).
 
 **Auffindbarkeit:** Veröffentlicht auf [npm](https://www.npmjs.com/package/ellmos-codecommander-mcp) als `ellmos-codecommander-mcp`, auf [Glama](https://glama.ai/mcp/servers/b9kjs4uaav) sichtbar und mit [`server.json`](server.json) für die offizielle MCP Registry unter `io.github.ellmos-ai/ellmos-codecommander-mcp` vorbereitet.
 
@@ -26,7 +26,7 @@ Ein entwicklerfokussierter **Model Context Protocol (MCP) Server**, der KI-Assis
 Während FileCommander Dateisystem-Operationen übernimmt, konzentriert sich CodeCommander auf **Code-Intelligenz**:
 
 - **Python Code-Analyse** – AST-basierte Klassen-/Methodenextraktion, Komplexitätsmetriken, Import-Analyse
-- **BACH-abgeleitete Python-Helfer** – Einrückungsdiagnose und Template-basierte Codegenerierung
+- **BACH-abgeleitete Python-Helfer** – Runtime-Importdiagnose, strukturelle Edits, Einrückungsprüfung und Template-basierte Codegenerierung
 - **JSON-Reparatur** – Automatische Korrektur von fehlerhaftem JSON (Trailing Commas, einfache Anführungszeichen, BOM, Kommentare)
 - **Import-Organisation** – Python-Imports sortieren und deduplizieren gemäß PEP 8
 - **Encoding-Korrektur** – Reparatur von Mojibake und doppelt kodiertem UTF-8 (27+ Muster)
@@ -122,15 +122,16 @@ FileCommander und CodeCommander sind für den parallelen Einsatz konzipiert:
 | Tool | Beschreibung |
 |------|-------------|
 | `cc_analyze_code` | Vollständige Code-Analyse: Klassen, Funktionen, Imports, LOC, Komplexität |
-| `cc_analyze_methods` | Detaillierte Methodenanalyse: Parameter, Decorators, Sichtbarkeit, Datenfluss |
-| `cc_extract_classes` | Python-Klassen/-Funktionen als separate Textblöcke extrahieren |
+| `cc_analyze_methods` | Detaillierte Methodenanalyse: Parameter, Decorators, Sichtbarkeit, Datenfluss, BACH-Prüfungen |
+| `cc_extract_classes` | Python-Klassen/-Funktionen als separate Textblöcke extrahieren, optional mit pycutter-artigem Inline-Inhalt |
 
-### Import-Verwaltung (2 Tools)
+### Import-Verwaltung (3 Tools)
 
 | Tool | Beschreibung |
 |------|-------------|
 | `cc_organize_imports` | Python-Imports sortieren & deduplizieren gemäß PEP 8 |
 | `cc_diagnose_imports` | Ungenutzte Imports, Duplikate und zirkuläre Import-Risiken erkennen |
+| `cc_runtime_import_diagnose` | Python-Runtime-Imports isoliert mit Timeouts, __init__.py-Analyse und Zirkularitäts-Hinweisen prüfen |
 
 ### JSON-Tools (2 Tools)
 
@@ -167,12 +168,13 @@ FileCommander und CodeCommander sind für den parallelen Einsatz konzipiert:
 | `cc_diff_files` | Zwei Dateien vergleichen mit Unified-Diff-Ausgabe (konfigurierbare Kontextzeilen) |
 | `cc_regex_test` | Regex-Muster gegen Text/Dateien testen mit Match-Details, Gruppen und Ersetzungsvorschau |
 
-### Python-Assistenz (2 Tools)
+### Python-Assistenz (3 Tools)
 
 | Tool | Beschreibung |
 |------|-------------|
 | `cc_check_indentation` | Fehlende Doppelpunkte, unindentierte return/yield-Zeilen und gemischte Tab-/Leerzeichen-Einrückung erkennen |
 | `cc_generate_python_code` | Python-Funktionen, Klassen, Dataclasses, CLI-Stubs, Tests, Exceptions und Module aus Templates erzeugen |
+| `cc_python_structural_edit` | Strukturelle Python-Edits mit Vorschau, Testdatei, Syntaxprüfung und Backup-Modus prüfen und anwenden |
 
 ### Export (2 Tools)
 
@@ -181,7 +183,7 @@ FileCommander und CodeCommander sind für den parallelen Einsatz konzipiert:
 | `cc_md_to_html` | Markdown zu eigenständigem HTML mit CSS-Styling (Überschriften, Code-Blöcke, Tabellen, verschachtelte Listen, Zitate, Bilder, Checkboxen) |
 | `cc_md_to_pdf` | Markdown zu PDF über Headless-Browser (Edge/Chrome). Fallback auf HTML wenn kein Browser verfügbar |
 
-**Gesamt: 19 Entwickler-Tools** (`cc_set_language` ist zusätzlich für Sprachumschaltung verfügbar)
+**Gesamt: 21 Entwickler-Tools** (`cc_set_language` ist zusätzlich für Sprachumschaltung verfügbar)
 
 ---
 
@@ -212,7 +214,7 @@ Alle Tools verwenden das Präfix `cc_` (CodeCommander), um Konflikte mit dem `fc
 Siehe [SECURITY.md](SECURITY.md) für detaillierte Sicherheitsinformationen.
 
 Wichtige Punkte:
-- Alle dateiverändernden Tools unterstützen den `dry_run`-Modus
+- Dateiverändernde Tools unterstützen Vorschau-/Dry-run-Modi, wo anwendbar
 - Backup-Erstellung ist standardmäßig bei destruktiven Operationen aktiviert
 - Kein integriertes Sandboxing – die Sicherheit wird an den MCP-Client delegiert
 - Konzipiert für die lokale Entwicklungsnutzung über stdio-Transport
@@ -231,7 +233,7 @@ npm test       # Tests ausführen (vitest)
 
 ### Tests
 
-Das Projekt enthält eine umfassende Test-Suite mit **154 Tests** für alle 19 Entwickler-Tools und i18n-Verhalten.
+Das Projekt enthält eine umfassende Test-Suite für alle 21 Entwickler-Tools und i18n-Verhalten.
 
 ```bash
 npm test              # Alle Tests ausführen

SECURITY.md

@@ -17,13 +17,19 @@ ellmos CodeCommander MCP Server is a developer tool that analyzes and modifies s
 | `cc_convert_format` | Creates files | Converts between formats |
 | `cc_md_to_html` | Creates files | Generates HTML output |
 | `cc_md_to_pdf` | Creates files | Generates PDF output |
+| `cc_python_structural_edit` | Modifies Python source when `mode=apply` | Defaults to preview; supports syntax checks, test-file output and backups |
+
+### Runtime Diagnostic Tools
+| Tool | Risk | Description |
+|------|------|-------------|
+| `cc_runtime_import_diagnose` | Executes target-project imports in isolated Python subprocesses | CodeCommander writes no files, but imported Python modules may run top-level side effects; use explicit `modules`, short timeouts and trusted project paths |
 
 ### Low Risk Tools (Read-Only)
 | Tool | Description |
 |------|-------------|
 | `cc_analyze_code` | Reads and analyzes code |
-| `cc_analyze_methods` | Reads and analyzes methods |
-| `cc_extract_classes` | Reads and extracts class info |
+| `cc_analyze_methods` | Reads and analyzes methods, callbacks and self-attribute order |
+| `cc_extract_classes` | Reads and extracts class info; creates files only when `output_dir` is set |
 | `cc_diagnose_imports` | Reads and diagnoses imports |
 | `cc_check_indentation` | Reads and checks Python indentation |
 | `cc_generate_python_code` | Generates text output only |
@@ -36,8 +42,9 @@ ellmos CodeCommander MCP Server is a developer tool that analyzes and modifies s
 
 ## Recommendations
 
-- All file-modifying tools support `dry_run` and/or `create_backup` options
-- Use `dry_run=true` to preview changes before applying
+- File-modifying tools support `dry_run`, `mode=preview` and/or `create_backup` options
+- Preview changes before applying (`dry_run=true` or `mode=preview`)
+- Treat runtime import diagnostics as code execution of the inspected project
 - Review changes before deploying to production
 - This server is designed for local development use via stdio transport
 

llms.txt

@@ -1,8 +1,8 @@
 # ellmos-codecommander-mcp - MCP Server for Code Intelligence
 
-> CodeCommander is a developer-focused MCP (Model Context Protocol) server that gives AI assistants code analysis, JSON repair, encoding fix, import organization, Python indentation checks, code generation, format conversion, file diff, and regex testing capabilities. 19 tools optimized for developers -- the coding companion to FileCommander in the ellmos MCP family.
+> CodeCommander is a developer-focused MCP (Model Context Protocol) server that gives AI assistants code analysis, pycutter-style Python context extraction, JSON repair, encoding fix, import organization, Python runtime import diagnostics, structural Python editing, indentation checks, code generation, format conversion, file diff, and regex testing capabilities. 21 tools optimized for developers -- the coding companion to FileCommander in the ellmos MCP family.
 
-Core capabilities: Python AST-based class/method extraction with complexity metrics and import analysis, BACH-derived indentation diagnostics and Python code generation templates, JSON repair (trailing commas, single quotes, BOM, comments), PEP 8 import sorting and deduplication, Mojibake/double-encoded UTF-8 repair (27+ patterns), German umlaut repair (70+ patterns), format conversion across JSON / CSV / INI / YAML / TOML / XML / TOON, unified diff output (LCS algorithm), regex tester with match details and replace preview, Markdown-to-HTML/PDF export with code blocks, tables, nested lists, and blockquotes. Cross-platform: Windows, macOS, Linux.
+Core capabilities: Python AST-based class/method extraction with complexity metrics, BACH-derived method guardrails, import analysis, runtime import diagnostics in isolated Python subprocesses, structural Python edits with preview/test/apply modes, optional inline class/helper blocks for LLM context packaging, BACH-derived indentation diagnostics and Python code generation templates, JSON repair (trailing commas, single quotes, BOM, comments), PEP 8 import sorting and deduplication, Mojibake/double-encoded UTF-8 repair (27+ patterns), German umlaut repair (70+ patterns), format conversion across JSON / CSV / INI / YAML / TOML / XML / TOON, unified diff output (LCS algorithm), regex tester with match details and replace preview, Markdown-to-HTML/PDF export with code blocks, tables, nested lists, and blockquotes. Cross-platform: Windows, macOS, Linux.
 
 Node.js >= 18, MIT. Published as `ellmos-codecommander-mcp` on npm. Visible on Glama at `https://glama.ai/mcp/servers/b9kjs4uaav`. MCP Registry metadata is provided in `server.json` for the namespace `io.github.ellmos-ai/ellmos-codecommander-mcp`.
 
@@ -46,7 +46,7 @@ Python AST class method extraction MCP
 JSON repair encoding fix MCP server
 ellmos-ai MCP developer tools
 Claude Code MCP code analysis import organization
-BACH Python indentation checker code generator MCP
+BACH Python runtime import diagnose structural edit indentation checker code generator MCP
 regex tester format conversion markdown PDF MCP
 ```