{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ellmos-ai/.github/master/profile/logo-ellmos-codecommander.jpg\" alt=\"ellmos CodeCommander MCP emblem\" width=\"400\">\n</p>\n\n# ellmos CodeCommander MCP Server\n**🇩🇪 [Deutsche Version](README_de.md)**\n\n*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm version](https://img.shields.io/npm/v/ellmos-codecommander-mcp.svg)](https://www.npmjs.com/package/ellmos-codecommander-mcp)\n[![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)\n[![Vitest](https://img.shields.io/badge/Vitest-187%20passed-brightgreen.svg)](https://vitest.dev/)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://nodejs.org/)\n[![Privacy](https://img.shields.io/badge/Privacy-100%25%20Offline%20%7C%20Zero--Egress-success.svg)](SECURITY.md)\n[![Security](https://img.shields.io/badge/Security-Local--First%20%7C%20Preview--Safe-blue.svg)](SECURITY.md)\n[![Ecosystem](https://img.shields.io/badge/ellmos--ai-Ecosystem-blue.svg)](https://github.com/ellmos-ai)\n[![Umbrella](https://img.shields.io/badge/open--bricks-Umbrella-purple.svg)](https://github.com/open-bricks)\n[![LLM Indexing](https://img.shields.io/badge/LLM--Ready-llms.txt-blue.svg)](llms.txt)\n\n> [!NOTE]\n> **For AI Assistants & LLMs:** Machine-readable indexing documentation for this repository is available at [`llms.txt`](llms.txt). The server exposes 23 specialized tools under the `cc_` prefix.\n\nA 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.\n\n**23 tools** optimized for developers - the coding companion to [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp).\n\n**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`. Registry and directory manifests [`server.json`](server.json), [`glama.json`](glama.json), [`smithery.yaml`](smithery.yaml), and [`llms.txt`](llms.txt) are maintained in full parity.\n\n---\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n    Client[\"MCP Clients<br/>(Claude Desktop / Claude Code / Cursor / Windsurf)\"]\n    Server[\"ellmos CodeCommander MCP Server<br/>(stdio transport • Node.js)\"]\n\n    subgraph Tools[\"Developer Tool Suites (23 Tools)\"]\n        subgraph CodeIntel[\"Code & Python Intelligence\"]\n            C1[\"cc_analyze_code\"]\n            C2[\"cc_analyze_methods\"]\n            C3[\"cc_extract_classes\"]\n            C4[\"cc_check_indentation\"]\n            C5[\"cc_generate_python_code\"]\n            C6[\"cc_python_structural_edit\"]\n        end\n\n        subgraph Imports[\"Import Management\"]\n            I1[\"cc_organize_imports\"]\n            I2[\"cc_diagnose_imports\"]\n            I3[\"cc_runtime_import_diagnose\"]\n        end\n\n        subgraph Repair[\"Text, JSON & Encoding Repair\"]\n            R1[\"cc_fix_json\"]\n            R2[\"cc_validate_json\"]\n            R3[\"cc_fix_encoding\"]\n            R4[\"cc_cleanup_file\"]\n            R5[\"cc_fix_umlauts\"]\n        end\n\n        subgraph Utility[\"Utilities & Conversion\"]\n            U1[\"cc_convert_format (JSON/CSV/YAML/TOML/XML/TOON)\"]\n            U2[\"cc_diff_files (Unified Diff)\"]\n            U3[\"cc_regex_test (Regex Tester)\"]\n            U4[\"cc_scan_emoji\"]\n            U5[\"cc_generate_licenses\"]\n        end\n\n        subgraph Export[\"Export & i18n\"]\n            E1[\"cc_md_to_html\"]\n            E2[\"cc_md_to_pdf\"]\n            E3[\"cc_set_language\"]\n            E4[\"cc_get_language\"]\n        end\n    end\n\n    Client -->|Stdio JSON-RPC| Server\n    Server --> CodeIntel\n    Server --> Imports\n    Server --> Repair\n    Server --> Utility\n    Server --> Export\n```\n\n### Code Intelligence & Safe Structural Edit Lifecycle\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor Developer as Developer / LLM Client\n    participant Stdio as CodeCommander Server (stdio)\n    participant Core as AST & Code Intelligence Core\n    participant Disk as Local Filesystem\n\n    Developer->>Stdio: cc_python_structural_edit (mode: \"preview\" / \"apply\")\n    Stdio->>Core: Parse Python AST & Validate Syntax\n    alt Validation Failed\n        Core-->>Stdio: Syntax / Parsing Diagnostics\n        Stdio-->>Developer: Error Diagnostics & Line References\n    else Validation Passed\n        Core->>Disk: Read Original File\n        Core->>Core: Compute Unified Structural Diff\n        alt Mode == \"preview\"\n            Core-->>Stdio: Return Diff Preview (Zero File Mutations)\n            Stdio-->>Developer: Structural Diff Preview\n        else Mode == \"apply\"\n            Core->>Disk: Create .bak Backup File\n            Core->>Disk: Write Modified AST Code In-Place\n            Core-->>Stdio: Confirmation with Applied Diff & Backup Path\n            Stdio-->>Developer: Success Payload\n        end\n    end\n```\n\n---\n\n## Why CodeCommander?\n\nWhile FileCommander handles filesystem operations, CodeCommander focuses on **code intelligence**:\n\n- **Python Code Analysis** - AST-based class/method extraction, complexity metrics, import analysis\n- **BACH-derived Python Helpers** - runtime import diagnostics, structural edits, indentation checks, and template-based code generation\n- **JSON Repair** - Fix broken JSON automatically (trailing commas, single quotes, BOM, comments)\n- **Import Organization** - Sort and deduplicate Python imports per PEP 8\n- **Encoding Fix** - Repair Mojibake and double-encoded UTF-8 (27+ patterns)\n- **Umlaut Repair** - Fix broken German characters (70+ patterns)\n- **Format Conversion** - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON\n- **File Diff** - Compare two files with unified diff output (LCS algorithm)\n- **Regex Tester** - Test regular expressions with match details, groups, and replace preview\n- **Markdown Export** - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes\n- **Cross-platform** - Works on Windows, macOS, and Linux\n\n---\n\n## Installation\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) 20 or higher\n\n### Option 1: Install from NPM\n\n```bash\nnpm install -g ellmos-codecommander-mcp\n```\n\n### Option 2: Install from Source\n\n```bash\ngit clone https://github.com/ellmos-ai/ellmos-codecommander-mcp.git\ncd ellmos-codecommander-mcp\nnpm install\nnpm run build\n```\n\n---\n\n## Configuration\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### If installed globally via NPM:\n\n```json\n{\n  \"mcpServers\": {\n    \"codecommander\": {\n      \"command\": \"ellmos-codecommander\"\n    }\n  }\n}\n```\n\n#### If installed from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"codecommander\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/ellmos-codecommander-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Using Both Servers Together\n\nFileCommander and CodeCommander are designed to work side by side:\n\n```json\n{\n  \"mcpServers\": {\n    \"filecommander\": {\n      \"command\": \"ellmos-filecommander\"\n    },\n    \"codecommander\": {\n      \"command\": \"ellmos-codecommander\"\n    }\n  }\n}\n```\n\n---\n\n## Tools Overview\n\n### Code Analysis (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_analyze_code` | Full code analysis: classes, functions, imports, LOC, complexity |\n| `cc_analyze_methods` | Detailed method analysis: params, decorators, visibility, data flow, BACH guardrails |\n| `cc_extract_classes` | Extract Python classes/functions as separate text blocks, optionally including pycutter-style inline content |\n\n### Import Management (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_organize_imports` | Sort & deduplicate Python imports per PEP 8 |\n| `cc_diagnose_imports` | Detect unused imports, duplicates, circular import risks |\n| `cc_runtime_import_diagnose` | Run isolated Python runtime imports with timeouts, __init__.py analysis, and circular-import hints |\n\n### JSON Tools (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_fix_json` | Repair broken JSON (BOM, trailing commas, comments, single quotes) |\n| `cc_validate_json` | Validate JSON with detailed error position and context |\n\n### Encoding & Text (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_fix_encoding` | Fix Mojibake / double-encoded UTF-8 (27+ patterns) |\n| `cc_cleanup_file` | Remove BOM, NUL bytes, trailing whitespace, normalize line endings |\n| `cc_fix_umlauts` | Repair broken German umlauts (70+ patterns, HTML entities, escapes) |\n\n### Scanning (1 tool)\n\n| Tool | Description |\n|------|-------------|\n| `cc_scan_emoji` | Scan files for emojis with codepoint info |\n\n### Format & Documentation (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_convert_format` | Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats |\n| `cc_generate_licenses` | Generate third-party license file (npm/pip) |\n\n### Developer Utilities (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_diff_files` | Compare two files with unified diff output (configurable context lines) |\n| `cc_regex_test` | Test regex patterns against text/files with match details, groups, and replace preview |\n\n### Python Assistance (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_check_indentation` | Detect missing colons, unindented return/yield statements, and mixed tab/space indentation |\n| `cc_generate_python_code` | Generate Python functions, classes, dataclasses, CLI stubs, tests, exceptions, and modules from templates |\n| `cc_python_structural_edit` | Inspect and apply structural Python edits with preview, test-file, syntax-check and backup modes |\n\n### Export (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `cc_md_to_html` | Markdown to standalone HTML with CSS styling (headers, code blocks, tables, nested lists, blockquotes, images, checkboxes) |\n| `cc_md_to_pdf` | Markdown to PDF via headless browser (Edge/Chrome). Falls back to HTML if no browser is available |\n\n**Total: 23 developer tools** (including `cc_set_language` and `cc_get_language` for runtime language management)\n\n---\n\n## Shared Tools\n\n7 tools exist in both FileCommander and CodeCommander for convenience:\n\n| FileCommander | CodeCommander | Function |\n|---------------|---------------|----------|\n| `fc_fix_json` | `cc_fix_json` | JSON repair |\n| `fc_validate_json` | `cc_validate_json` | JSON validation |\n| `fc_fix_encoding` | `cc_fix_encoding` | Encoding repair |\n| `fc_cleanup_file` | `cc_cleanup_file` | File cleanup |\n| `fc_convert_format` | `cc_convert_format` | Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON) |\n| `fc_md_to_html` | `cc_md_to_html` | Markdown to HTML export |\n| `fc_md_to_pdf` | `cc_md_to_pdf` | Markdown to PDF export |\n\n---\n\n## Tool Prefix\n\nAll tools use the `cc_` prefix (CodeCommander) to avoid conflicts with FileCommander's `fc_` prefix and other MCP servers.\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\nKey points:\n- File-modifying tools support preview/dry-run modes where applicable\n- Backup creation is enabled by default for destructive operations\n- Pure stdio JSON-RPC transport with Zero-Egress guarantees\n- Designed for local development use with standard unprivileged user permissions\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run dev    # Watch mode\nnpm run build  # One-time build\nnpm start      # Start server\nnpm test       # Run test suite (vitest)\nnpm run test:integration  # 35 real MCP stdio assertions (after build)\nnpm run test:i18n         # 43 translation assertions\n```\n\n### Testing\n\nThe supported gates are deliberately separated: `npm test` runs the 187-test Vitest suite, `npm run test:integration` runs 35 real MCP stdio assertions against `dist/index.js`, and `npm run test:i18n` runs 43 translation assertions (265 automated test assertions total).\n\n```bash\nnpm test                  # Run Vitest unit tests (187 tests)\nnpm run test:integration  # Real MCP stdio test (35 assertions, build first)\nnpm run test:i18n         # i18n assertions (43 assertions)\nnpm run test:all          # Run full test suite (build + vitest + integration + i18n)\n```\n\nTests are verified on **Windows**, **macOS**, and **Linux**.\n\nGitHub Actions runs the build, all three test gates (187 Vitest, 35 MCP stdio, 43 i18n assertions — 265 assertions total), and npm package check on Node.js 20, 22, and 24.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n---\n\n## License\n\n[MIT](LICENSE) - Lukas Geiger ([ellmos-ai](https://github.com/ellmos-ai))\n\n---\n\n## History\n\nThis project was originally developed as **BACH CodeCommander** (`bach-codecommander-mcp`). It has been renamed to **ellmos CodeCommander** (`ellmos-codecommander-mcp`) as part of the [ellmos-ai](https://github.com/ellmos-ai) organization.\n\nThe legacy package name `bach-codecommander-mcp` is deprecated. Please use [`ellmos-codecommander-mcp`](https://www.npmjs.com/package/ellmos-codecommander-mcp) instead:\n\n```bash\nnpm uninstall -g bach-codecommander-mcp\nnpm install -g ellmos-codecommander-mcp\n```\n\n---\n\n## ellmos-ai Ecosystem\n\nThis MCP server is part of the **[ellmos-ai](https://github.com/ellmos-ai)** ecosystem — AI infrastructure, MCP servers, and intelligent tools.\n\n### MCP Server Family\n\n| Server | Tools | Focus | npm |\n|--------|-------|-------|-----|\n| [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | 50 | Filesystem, process management, interactive sessions, cloud-lock-safe operations | [`ellmos-filecommander-mcp`](https://www.npmjs.com/package/ellmos-filecommander-mcp) |\n| **[CodeCommander](https://github.com/ellmos-ai/ellmos-codecommander-mcp)** | **23** | **Code analysis, JSON repair, imports, diffs, regex** | **[`ellmos-codecommander-mcp`](https://www.npmjs.com/package/ellmos-codecommander-mcp)** |\n| [Clatcher](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | 12 | File repair, format conversion, batch operations | [`ellmos-clatcher-mcp`](https://www.npmjs.com/package/ellmos-clatcher-mcp) |\n| [n8n Manager](https://github.com/ellmos-ai/n8n-manager-mcp) | 19 | n8n workflow management via AI assistants | [`n8n-manager-mcp`](https://www.npmjs.com/package/n8n-manager-mcp) |\n| [ControlCenter](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | 34 | MCP stack discovery, profile management, control plane | [`ellmos-controlcenter-mcp`](https://www.npmjs.com/package/ellmos-controlcenter-mcp) |\n| [Homebase](https://github.com/ellmos-ai/ellmos-homebase-mcp) | 51 | Local-first LLM memory, knowledge, state, routing, swarm orchestration | [`ellmos-homebase-mcp`](https://www.npmjs.com/package/ellmos-homebase-mcp) (alpha) |\n| [ServerCommander](https://github.com/ellmos-ai/ellmos-servercommander-mcp) | 8 | Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics | [`ellmos-servercommander-mcp`](https://www.npmjs.com/package/ellmos-servercommander-mcp) (alpha) |\n| [Blender Use](https://github.com/ellmos-ai/ellmos-blender-use-mcp) | 4 | Headless Blender asset QA and FBX reimport verification | [`ellmos-blender-use-mcp`](https://www.npmjs.com/package/ellmos-blender-use-mcp) (alpha) |\n| [Open Compute](https://github.com/ellmos-ai/open-compute-mcp) | 16 | Model-agnostic computer use: capture, safety-gated actions, Windows UIA | [`open-compute-mcp`](https://www.npmjs.com/package/open-compute-mcp) (alpha) |\n\n### Sibling Developer, File & Document Tools\n\n| Ecosystem | Tool / Project | Focus & Capabilities |\n|---|---|---|\n| **ellmos-ai** | [sqlite-transit-sync](https://github.com/ellmos-ai/sqlite-transit-sync) | Offline SQLite change distribution with HMAC verification |\n| **ellmos-ai** | [policy-registry](https://github.com/ellmos-ai/policy-registry) | Cryptographically signed delegation policies for AI agents |\n| **ellmos-ai** | [clutch](https://github.com/ellmos-ai/clutch) | Provider-neutral LLM orchestration with auto-routing and budget tracking |\n| **ellmos-ai** | [BACH](https://github.com/ellmos-ai/bach) | Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools |\n| **dev-bricks** | [DevCenter](https://github.com/dev-bricks/DevCenter) | PySide6 Developer Desktop Suite & offline secret vault |\n| **dev-bricks** | [CodeBox](https://github.com/dev-bricks/CodeBox) | Fast desktop code snippet manager & local AST indexing |\n| **dev-bricks** | [MethodenAnalyser](https://github.com/dev-bricks/MethodenAnalyser) | Method flow & complexity diagnostic engine |\n| **doc-bricks** | [PDFtoPDFocr](https://github.com/doc-bricks/PDFtoPDFocr) | Desktop OCR pipeline for searchable PDFs with Tesseract |\n| **doc-bricks** | [DokuReader](https://github.com/doc-bricks/DokuReader) | Multi-format document workspace & offline PDF export |\n| **file-bricks** | [ProFiler](https://github.com/file-bricks/ProFiler) | Multi-pane file management & bulk batch operations |\n| **open-bricks** | [open-bricks](https://github.com/open-bricks) | Umbrella organization for AI-native desktop applications |\n\n### AI Infrastructure\n\n| Project | Description |\n|---------|-------------|\n| [BACH](https://github.com/ellmos-ai/bach) | Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory |\n| [open-compute](https://github.com/ellmos-ai/open-compute) | Model-agnostic computer-use core powering Open Compute MCP |\n| [clutch](https://github.com/ellmos-ai/clutch) | Provider-neutral LLM orchestration with auto-routing and budget tracking |\n| [rinnsal](https://github.com/ellmos-ai/rinnsal) | Lightweight agent memory, connectors, and automation infrastructure |\n| [ellmos-stack](https://github.com/ellmos-ai/ellmos-stack) | Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest) |\n| [MarbleRun](https://github.com/ellmos-ai/MarbleRun) | Autonomous agent chain framework for Claude Code |\n| [gardener](https://github.com/ellmos-ai/gardener) | Minimalist database-driven LLM OS prototype (4 functions, 1 table) |\n| [ellmos-tests](https://github.com/ellmos-ai/ellmos-tests) | Testing framework for LLM operating systems (7 dimensions) |\n\n### Desktop Software\n\nOur partner organization **[open-bricks](https://github.com/open-bricks)** bundles AI-native desktop applications — a modern, open-source software suite built for the age of AI. Categories include file management, document tools, developer utilities, and more.\n\n## Liability\n\nDieses Projekt ist eine **unentgeltliche Open-Source-Schenkung** im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß **§ 521 BGB** auf **Vorsatz und grobe Fahrlässigkeit** beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.\n\nNutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.\n\nThis project is an unpaid open-source donation under German law. Liability is limited to intent and gross negligence (§ 521 German Civil Code), supplemented by the MIT License warranty disclaimer. Use at your own risk.\n",
  "bytes": 19576,
  "sha": "344173d47c2747dcd4250098fde1d575c313c60d11cec16ddf0af8ef0ba9e6d6",
  "repo_slug": "ellmos-ai/ellmos-codecommander-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ellmos_ai_ellmos_codecommander_c8e5f5c5/readme"
}