ellmos CodeCommander

[ellmos CodeCommander MCP emblem]

ellmos CodeCommander MCP Server

English | Deutsch | Español | 简体中文 | 日本語 | Русский | Français | हिन्दी | العربية | বাংলা | Português

The README navigation lists the available documentation languages. Section 11 separately describes the runtime languages used for tool output messages and diagnostics. This does not claim that MCP discovery or schema descriptions, the GUI, CLI, or API are translated.

Part of the ellmos-ai family.

[License: MIT] [npm version] [CI Tests] [Tests] [Node.js] [Platform] [Privacy] [Security] [Security: RunAsInvoker] [Security SLA] [Contributing] [Third-Party Audited] [Marketing Log] [Attribution: NOTICE] [Verified: 2026-10-09] [Ecosystem] [Umbrella] [LLM Indexing]

[!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. Target Personas & Discoverability
3. Comparative Matrix vs. Alternatives
4. Architecture & System Overview
5. Safe Structural Edit Lifecycle
6. Governance & Runtime Invariants
7. Developer Tool Suite (23 Tools)
8. Shared Tools with FileCommander
9. Installation & Quickstart
10. Configuration & MCP Client Setup
11. Multi-Language Support (i18n)
12. Development & Quality Assurance
13. Sibling Ecosystem & Partner Matrix
14. Third-Party Licenses & Transparency
15. Security Policy & Response SLA
16. Changelog & Version History
17. License & Legal Attribution
18. Statutory Notice, Liability Limitation & SLA (§ 521 BGB)

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. Target Personas & Discoverability

CodeCommander MCP is engineered to address key bottlenecks in modern autonomous AI coding, local multi-agent swarms, and safety-compliant developer tooling:

Target Audience & Stakeholder Personas

• [PERSONA-01] ([PERSONA-1]) Autonomous AI Coding Agents & LLM Pair-Programmers

  • Profile: Agents such as Claude Code, Antigravity, Codex, Cursor, and Windsurf performing automated code refactoring, test repair, and feature development.
  • Pain Point: Standard LLM code outputs frequently suffer from hallucinated imports, broken indentation in complex Python control flows, invalid JSON configs, or syntax corruption during naive chunk edits.
  • Solution: Native AST extraction (cc_extract_classes, cc_analyze_methods), preview-safe structural editing with unified diffs (cc_python_structural_edit), automatic indentation checking (cc_check_indentation), and deterministic JSON repair (cc_fix_json).

• [PERSONA-02] ([PERSONA-2]) Full-Stack & Python/TypeScript Software Engineers

  • Profile: Developers maintaining polyglot projects, CLI utilities, and data pipelines requiring cross-language AST analysis and rapid configuration format transitions.
  • Pain Point: Tedious manual format conversions (JSON ↔ YAML ↔ TOML ↔ TOON ↔ XML), broken German umlauts or Mojibake from legacy encodings, and circular runtime imports.
  • Solution: Universal format converter (cc_convert_format), non-destructive encoding and umlaut repair (cc_fix_encoding, cc_fix_umlauts), isolated runtime import diagnostics (cc_runtime_import_diagnose), and interactive regex tester (cc_regex_test).

• [PERSONA-03] ([PERSONA-3]) Enterprise AI Safety, SecOps & Code Governance Officers

  • Profile: Security auditors, compliance engineers, and enterprise architects evaluating MCP toolchains for developer workstations and CI/CD runners.
  • Pain Point: Risk of confidential code leakage via cloud telemetry, unauthorized process elevation, or destructive in-place file overwrites by AI assistants.
  • Solution: 100% Zero-Egress local stdio transport (INV-LOCAL-01), unprivileged user-space execution (INV-SEC-02), mandatory timestamped .bak backups before mutations (INV-BAK-04), dry-run diff preview safety (INV-PREV-03), and isolated subprocess timeouts (INV-ISOL-05).

• [PERSONA-04] ([PERSONA-4]) Open-Source Ecosystem Architects & MCP Tool Developers

  • Profile: Maintainers building, publishing, and indexing MCP servers across Glama, Smithery, npm, and GitHub.
  • Pain Point: Fragmented directory manifests, missing third-party license disclosures, and lack of machine-readable indexing context for AI agents.
  • Solution: 100% manifest parity across package.json, server.json, glama.json, smithery.yaml, and llms.txt, verified by automated contract tests and a complete open-source license audit (THIRD_PARTY_LICENSES.md).

High-Intent Search Queries (SEO & Discoverability)

• mcp code analysis server
• model context protocol python ast tools
• mcp server codecommander
• python structural edit mcp
• claude code developer mcp server
• mcp json repair and encoding fix
• local-first mcp tools for coding
• mcp python runtime import diagnose
• format converter mcp json yaml toml toon
• offline code intelligence mcp server

3. Comparative Matrix vs. Alternatives

The following matrix compares CodeCommander MCP against alternative developer tooling approaches across 10 critical operational dimensions:

4. Architecture & System Overview

+==============================================================================================================+|                            FOUR-VIEW ARCHITECTURAL TOPOLOGY (STANDARDIZED LEVEL-1 SPECIFICATION)             |+==============================================================================================================+| [VIEW 1: CLIENT RUNTIMES, USER INTERFACES & AGENT ENTRYPOINTS]                                               ||  - Stdio JSON-RPC Clients: Claude Desktop, Claude Code CLI, Cursor, Windsurf, Codex, Antigravity, Kimi Code  ||  - MCP Tool Ingestion: 23 Developer Tools via standard Model Context Protocol Specification                  ||  - Runtime locales: DE EN ES ZH JA RU FR HI AR BN PT (INV-I18N-09)                                           |+--------------------------------------------------------------------------------------------------------------+                                          | Stdio Transport (JSON-RPC)                                          v+--------------------------------------------------------------------------------------------------------------+| [VIEW 2: CODECOMMANDER MCP PROTOCOL & TOOL ENGINE]                                                           ||  - Code Intelligence AST: Python AST Class/Method Extractors, Complexity Metrics & Guardrails (INV-GATE-06)   ||  - Structural Refactoring Engine: Preview-Safe Diffs & Dry-Run Syntax Verification (INV-PREV-03)             ||  - Import Diagnostics & Organizer: PEP 8 Cleaners & Subprocess Import Probers (INV-ISOL-05)                  ||  - Universal Format Converter: Lossless Roundtrip across JSON/CSV/INI/YAML/TOML/XML/TOON (INV-FMT-08)         ||  - Text & Encoding Heuristics: 27+ Mojibake & 70+ German Umlaut Restorations, JSON Fixers (INV-ENC-07)       |+--------------------------------------------------------------------------------------------------------------+                                          | Process Isolation & Local I/O                                          v+--------------------------------------------------------------------------------------------------------------+| [VIEW 3: RUNTIME PERSISTENCE, BACKUP VAULTS & ISOLATED SUBPROCESS RUNNERS]                                   ||  - Pre-Mutation Safety Vault: Timestamped `.bak` Disk Backups Before In-Place Modification (INV-BAK-04)       ||  - Ephemeral Python Runner: Isolated Child Processes with Strict Execution Timeout Bounds (INV-ISOL-05)     ||  - Unified Diff Pipeline: LCS Algorithm Unified Diff Generator with Configurable Context Chunks              ||  - Local Document Exporters: Self-Contained Markdown-to-HTML and Print-Safe PDF Artifact Generators          |+--------------------------------------------------------------------------------------------------------------+                                          | Containment & Perimeter Defense                                          v+--------------------------------------------------------------------------------------------------------------+| [VIEW 4: AIR-GAP DEFENSE PERIMETER, ZERO-EGRESS & RUNASINVOKER SECURITY BOUNDARY]                            ||  - Zero-Egress Network Isolation: 100% Offline Local Operation, Zero Sockets, Zero Cloud Telemetry (INV-LOCAL-01)||  - Unprivileged User Mode: Standard RunAsInvoker Execution; Zero Root/Administrator Elevation (INV-SEC-02)  ||  - Supply Chain & License Hygiene: Zero Copyleft, 100% Permissive Open Source Stack (MIT, BSD, Apache)       ||  - Vulnerability Remediation SLA: 48h Response, 5-Day Triage & 30-Day Patch Commitment (INV-SLA-10)          |+==============================================================================================================+

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

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

6. Governance & Runtime Invariants

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

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

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

9. 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.gitcd ellmos-codecommander-mcpnpm installnpm run build

10. 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"    }  }}

11. Multi-Language Support (i18n)

CodeCommander supports these 11 languages for messages returned by tools, including diagnostic messages at runtime:

• de — German (default)
• en — English
• es — Spanish
• zh — Simplified Chinese
• ja — Japanese
• ru — Russian
• fr — French
• hi — Hindi
• ar — Arabic
• bn — Bengali
• pt — Portuguese

These codes select the language of runtime tool output and diagnostic messages. They do not translate MCP discovery or schema descriptions, the GUI, CLI, or API; README navigation lists documentation languages separately.

CC_LANGUAGE selects the initial language when the server starts. During an active MCP session, use cc_set_language to switch languages; cc_get_language reports the active code and supported codes. If CC_LANGUAGE is unset or unsupported, the fallback is German (de). No --lang option is documented.

12. Development & Quality Assurance

npm installnpm run dev               # TypeScript watch modenpm run build             # Compile TypeScript to dist/npm start                 # Run built server via stdionpm test                  # Run Vitest unit & contract suite (205 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 322 automated assertions, 100% green). Contribution workflow and development guidelines are detailed in CONTRIBUTING.md.

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

14. Third-Party Licenses & Transparency

This project strictly adheres to open-source transparency:

• All runtime and development dependencies are audited in THIRD_PARTY_LICENSES.md and plain-text companion THIRD_PARTY_LICENSES.txt.
• The current production dependency audit (npm audit --omit=dev --json, checked 2026-09-20) reports 5 vulnerable package nodes (3 high, 2 moderate); remediation is tracked in TASKPLAN #2198.
• 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.

15. 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 [email protected] and [email protected] with a guaranteed 48-hour initial response SLA and 5-day triage commitment.

16. Changelog & Version History

See CHANGELOG.md for release notes and version history.

17. License & Legal Attribution

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

See NOTICE for open-bricks umbrella attribution, CONTRIBUTING.md for development guidelines, and THIRD_PARTY_LICENSES.md / THIRD_PARTY_LICENSES.txt for the Level 1 SBOM invariant inventory.

18. Statutory Notice, Liability Limitation & SLA (§ 521 BGB)

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB (Gefälligkeitsrecht). Die Haftung des Urhebers und der Mitwirkenden 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.

Sicherheitsrelevante Vorfälle und Schwachstellen werden über das verbindliche 48-Stunden-SLA unter [email protected], [email protected] und [email protected] entgegengenommen und innerhalb von 5 Werktagen triagiert.

This project is an unpaid open-source donation under German law (§§ 516 et seq. BGB). Liability is strictly limited to intent and gross negligence (§ 521 German Civil Code). The MIT license disclaimer applies complementarily. Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.

Security incidents and vulnerabilities are handled under a binding 48-hour response SLA via [email protected], [email protected] and [email protected] with formal triage within 5 business days.