ellmos CodeCommander MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

[!NOTE] For AI Assistants & LLMs: Machine-readable indexing documentation for this repository is available at llms.txt. The server exposes 23 specialized tools under the cc_ prefix.

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.

23 tools optimized for developers - the coding companion to FileCommander.

Discoverability: Published on npm as ellmos-codecommander-mcp, visible on Glama, and prepared for the official MCP Registry with server.json under io.github.ellmos-ai/ellmos-codecommander-mcp. Registry and directory manifests server.json, glama.json, smithery.yaml, and llms.txt are maintained in full parity.

Quick Navigation

1. Overview & Highlights
2. Architecture & System Overview
3. Safe Structural Edit Lifecycle
4. Governance & Runtime Invariants
5. Developer Tool Suite (23 Tools)
6. Shared Tools with FileCommander
7. Installation & Quickstart
8. Configuration & MCP Client Setup
9. Multi-Language Support (i18n)
10. Development & Quality Assurance
11. Sibling Ecosystem & Partner Matrix
12. Third-Party Licenses & Transparency
13. Security Policy & Response SLA
14. Changelog & Version History
15. License & Liability Notice

1. Overview & Highlights

While FileCommander handles filesystem operations and system processes, CodeCommander focuses specifically on code intelligence and developer precision:

• Python, JavaScript & TypeScript Analysis — Extension-dispatched classes, methods, functions, complexity metrics, and import analysis; JS/TS analysis is regex-based and read-only.
• BACH-derived Python Helpers — Runtime import diagnostics, structural edits, indentation checks, and template-based code generation.
• Explicit Language Gates — Python-only path tools reject non-.py files explicitly instead of producing Python-shaped false findings.
• JSON Repair & Validation — Automatically repair broken JSON (trailing commas, single quotes, BOM, comments) with precise error locations.
• PEP 8 Import Organization — Sort and deduplicate Python imports per PEP 8 guidelines.
• Encoding & Mojibake Repair — Fix Mojibake and double-encoded UTF-8 (27+ patterns) and broken German characters (70+ umlaut patterns).
• Universal Format Conversion — Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats losslessly.
• Unified File Diff — Compare two files with LCS unified diff output and configurable context lines.
• Regex Testing Workbench — Test regular expressions with match details, capturing groups, and replace previews.
• Markdown Export — Convert Markdown to standalone HTML or PDF with syntax-styled code blocks, tables, and blockquotes.
• Cross-Platform Native — Full support on Windows, macOS, and Linux.

2. Architecture & System Overview

graph TD
    Client["MCP Clients<br/>(Claude Desktop / Claude Code / Cursor / Windsurf)"]
    Server["ellmos CodeCommander MCP Server<br/>(stdio transport • Node.js)"]

    subgraph Tools["Developer Tool Suites (23 Tools)"]
        subgraph CodeIntel["Code & Python Intelligence"]
            C1["cc_analyze_code"]
            C2["cc_analyze_methods"]
            C3["cc_extract_classes"]
            C4["cc_check_indentation"]
            C5["cc_generate_python_code"]
            C6["cc_python_structural_edit"]
        end

        subgraph Imports["Import Management"]
            I1["cc_organize_imports"]
            I2["cc_diagnose_imports"]
            I3["cc_runtime_import_diagnose"]
        end

        subgraph Repair["Text, JSON & Encoding Repair"]
            R1["cc_fix_json"]
            R2["cc_validate_json"]
            R3["cc_fix_encoding"]
            R4["cc_cleanup_file"]
            R5["cc_fix_umlauts"]
        end

        subgraph Utility["Utilities & Conversion"]
            U1["cc_convert_format (JSON/CSV/YAML/TOML/XML/TOON)"]
            U2["cc_diff_files (Unified Diff)"]
            U3["cc_regex_test (Regex Tester)"]
            U4["cc_scan_emoji"]
            U5["cc_generate_licenses"]
        end

        subgraph Export["Export & i18n"]
            E1["cc_md_to_html"]
            E2["cc_md_to_pdf"]
            E3["cc_set_language"]
            E4["cc_get_language"]
        end
    end

    Client -->|Stdio JSON-RPC| Server
    Server --> CodeIntel
    Server --> Imports
    Server --> Repair
    Server --> Utility
    Server --> Export

3. Safe Structural Edit Lifecycle

sequenceDiagram
    autonumber
    actor Developer as Developer / LLM Client
    participant Stdio as CodeCommander Server (stdio)
    participant Core as AST & Code Intelligence Core
    participant Disk as Local Filesystem

    Developer->>Stdio: cc_python_structural_edit (mode: "preview" / "apply")
    Stdio->>Core: Parse Python AST & Validate Syntax
    alt Validation Failed
        Core-->>Stdio: Syntax / Parsing Diagnostics
        Stdio-->>Developer: Error Diagnostics & Line References
    else Validation Passed
        Core->>Disk: Read Original File
        Core->>Core: Compute Unified Structural Diff
        alt Mode == "preview"
            Core-->>Stdio: Return Diff Preview (Zero File Mutations)
            Stdio-->>Developer: Structural Diff Preview
        else Mode == "apply"
            Core->>Disk: Create .bak Backup File
            Core->>Disk: Write Modified AST Code In-Place
            Core-->>Stdio: Confirmation with Applied Diff & Backup Path
            Stdio-->>Developer: Success Payload
        end
    end

4. Governance & Runtime Invariants

ellmos-codecommander-mcp guarantees 10 core architectural and runtime invariants across all platforms:

5. Developer Tool Suite (23 Tools)

Code Analysis (3 tools)

Import Management (3 tools)

JSON Tools (2 tools)

Encoding & Text (3 tools)

Scanning (1 tool)

Format & Documentation (2 tools)

Developer Utilities (2 tools)

Python Assistance (3 tools)

Export (2 tools)

Runtime Language Management (2 tools)

Total: 23 developer tools available under the cc_ prefix.

6. Shared Tools with FileCommander

7 tools exist in both FileCommander and CodeCommander for convenience:

All tools in CodeCommander use the cc_ prefix to guarantee seamless coexistence with FileCommander's fc_ namespace.

7. Installation & Quickstart

Prerequisites

• Node.js 20 or higher
• npm 9 or higher

Option 1: Install from NPM (Recommended)

npm install -g ellmos-codecommander-mcp

Option 2: Install from Source

git clone https://github.com/ellmos-ai/ellmos-codecommander-mcp.git
cd ellmos-codecommander-mcp
npm install
npm run build

8. Configuration & MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Global NPM Install:

{
  "mcpServers": {
    "codecommander": {
      "command": "ellmos-codecommander"
    }
  }
}

From Source Build:

{
  "mcpServers": {
    "codecommander": {
      "command": "node",
      "args": ["/absolute/path/to/ellmos-codecommander-mcp/dist/index.js"]
    }
  }
}

Coexistence with FileCommander

FileCommander and CodeCommander are designed to run concurrently:

{
  "mcpServers": {
    "filecommander": {
      "command": "ellmos-filecommander"
    },
    "codecommander": {
      "command": "ellmos-codecommander"
    }
  }
}

9. Multi-Language Support (i18n)

CodeCommander natively supports 6 languages for all tool descriptions, output notices, and diagnostic messages:

• en — English (Default)
• de — Deutsch (German)
• es — Español (Spanish)
• zh — 简体中文 (Chinese Simplified)
• ja — 日本語 (Japanese)
• ru — Русский (Russian)

Use cc_get_language to check the current language or cc_set_language to dynamically change it during an active MCP session.

10. Development & Quality Assurance

npm install
npm run dev               # TypeScript watch mode
npm run build             # Compile TypeScript to dist/
npm start                 # Run built server via stdio
npm test                  # Run Vitest unit suite (196 tests)
npm run test:integration  # Real MCP stdio test suite (52 assertions, build first)
npm run test:i18n         # Translation parity test suite (43 assertions)
npm run test:all          # Run full QA pipeline (build + vitest + integration + i18n)

The test gates are deliberately separated and automated in CI across Ubuntu, macOS, and Windows on Node.js 20, 22, and 24 (totaling 292 automated assertions, 100% green).

11. Sibling Ecosystem & Partner Matrix

Part of the ellmos-ai and open-bricks family of local-first tools:

MCP Server Family

Sibling Developer, File & Document Tools

12. Third-Party Licenses & Transparency

This project strictly adheres to open-source transparency:

• All runtime and development dependencies are audited in THIRD_PARTY_LICENSES.md.
• Distributed exclusively under permissive open-source licenses (MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0).
• Comprehensive discoverability, personas, and marketing metrics are documented in MARKETING-LOG.txt.
• Zero proprietary tracking, zero telemetric beacons, and zero viral copyleft dependencies.

13. Security Policy & Response SLA

Please review SECURITY.md for full vulnerability disclosure procedures.

• Zero-Egress Guarantee: Completely local execution over stdio.
• Preview & Backup Safety: Destructive operations create .bak backups and support non-mutating preview.
• Unprivileged User Mode: Runs under standard unprivileged user permissions (RunAsInvoker).
• Dedicated Response Channels: Contact security@ellmos.ai and support@lukasgeiger.com with a guaranteed 48-hour initial response SLA and 5-day triage commitment.

14. Changelog & Version History

See CHANGELOG.md for release notes and version history.

15. License & Liability Notice

This project is licensed under the MIT License — Copyright © 2026 Lukas Geiger (ellmos-ai).

Dieses 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. Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.

This 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.