ellmos CodeCommander

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

Dimension / Capability	Generic File MCP	Raw Shell / Ad-Hoc Scripts	Heavyweight Cloud LLMOps	Traditional IDE Plugins	ellmos CodeCommander MCP
1. AST Code Intelligence	None (raw text reads)	Requires custom python scripts	Cloud parser required	Built-in (GUI only)	Native AST & regex JS/TS (cc_analyze_code)
2. Safe Structural Edit Preview	None (blind overwrite)	High risk (sed/awk)	Cloud gateway dependent	Interactive dialog	Preview-safe diffs (mode: "preview")
3. Mandatory Pre-Mutation Backups	None	Manual scripting	None	Local history (opaque)	Automatic .bak creation (INV-BAK-04)
4. Runtime Import Diagnostics	None	Unsafe direct execution	None	Partial / static only	Isolated subprocess + timeout (INV-ISOL-05)
5. Encoding & Mojibake Recovery	None	Fragile iconv calls	None	Basic encoding switch	27+ Mojibake, 70+ Umlauts (cc_fix_encoding)
6. Universal Format Conversion	None	Multiple disparate CLI tools	SaaS conversion API	Multi-plugin setup	Lossless 7 formats (JSON/YAML/TOML/XML/TOON)
7. Diff Engine & Regex Workbench	None	Basic diff/grep	None	GUI panel only	LCS Unified Diff & Regex with groups/replace
8. Local-First & Zero-Egress	Host-dependent	Local	Cloud egress / telemetry	Often connects to cloud	100% Offline Stdio JSON-RPC (INV-LOCAL-01)
9. Multi-Language (i18n) Support	English only	None	English only	Language packs	Dynamic 6 languages (cc_set_language)
10. Registry & Manifest Parity	Minimal	None	Proprietary	Marketplace specific	npm, Glama, Smithery, MCP Registry, llms.txt

---

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

---

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:

Invariant ID	Classification	Architectural Guarantee & Verification Mechanism
INV-LOCAL-01	Zero-Egress Privacy	Pure local stdio JSON-RPC transport; zero network telemetry, cloud beacons, or remote egress.
INV-SEC-02	Unprivileged Security	Standard user-space execution (RunAsInvoker) requiring zero root or administrative elevation.
INV-PREV-03	Preview Safety	Structural edits default to non-mutating preview mode (mode: "preview") with unified diff generation.
INV-BAK-04	Automatic Backups	File modifications automatically generate timestamped .bak files before in-place disk writes.
INV-ISOL-05	Subprocess Isolation	Python runtime import diagnosis executes in isolated, timeout-bounded child processes.
INV-GATE-06	Explicit Language Gates	Python-specific path tools reject non-.py files explicitly; JS/TS analysis is read-only and regex-based.
INV-ENC-07	Non-Destructive Encoding	Repaired text restores 27+ Mojibake and 70+ German umlaut patterns without loss or binary corruption.
INV-FMT-08	Format Interchange Parity	Lossless format conversions across JSON, CSV, INI, YAML, TOML, XML, and TOON with schema preservation.
INV-I18N-09	Runtime Multi-Language	Dynamic runtime language switching across 6 languages (EN, DE, ES, ZH, JA, RU) via cc_set_language.
INV-SLA-10	48h Security Response SLA	Verified across Ubuntu, Windows, macOS on Node 20, 22, 24 with public 48h response / 5-day triage commitment.

---

7. Developer Tool Suite (23 Tools)

Code Analysis (3 tools)

Tool	Description
cc_analyze_code	Read-only Python or regex-based JavaScript/TypeScript analysis: classes, functions, imports, LOC, complexity
cc_analyze_methods	Read-only Python or regex-based JavaScript/TypeScript method analysis; Python retains its BACH guardrails
cc_extract_classes	Extract Python classes/functions as separate text blocks, optionally including pycutter-style inline content

Import Management (3 tools)

Tool	Description
cc_organize_imports	Sort & deduplicate Python imports per PEP 8
cc_diagnose_imports	Read-only Python or regex-based JavaScript/TypeScript import diagnostics
cc_runtime_import_diagnose	Run isolated Python runtime imports with timeouts, __init__.py analysis, and circular-import hints

JSON Tools (2 tools)

Tool	Description
cc_fix_json	Repair broken JSON (BOM, trailing commas, comments, single quotes)
cc_validate_json	Validate JSON with detailed error position and context

Encoding & Text (3 tools)

Tool	Description
cc_fix_encoding	Fix Mojibake / double-encoded UTF-8 (27+ patterns)
cc_cleanup_file	Remove BOM, NUL bytes, trailing whitespace, normalize line endings
cc_fix_umlauts	Repair broken German umlauts (70+ patterns, HTML entities, escapes)

Scanning (1 tool)

Tool	Description
cc_scan_emoji	Scan files for emojis with codepoint info

Format & Documentation (2 tools)

Tool	Description
cc_convert_format	Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON formats
cc_generate_licenses	Generate third-party license file (npm/pip)

Developer Utilities (2 tools)

Tool	Description
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 (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)

Tool	Description
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

Runtime Language Management (2 tools)

Tool	Description
cc_set_language	Switch active runtime language (en, de, es, zh, ja, ru)
cc_get_language	Query currently active language and supported locale codes

Total: 23 developer tools available under the cc_ prefix.

---

8. Shared Tools with FileCommander

7 tools exist in both FileCommander and CodeCommander for convenience:

FileCommander	CodeCommander	Function
fc_fix_json	cc_fix_json	JSON repair
fc_validate_json	cc_validate_json	JSON validation
fc_fix_encoding	cc_fix_encoding	Encoding repair
fc_cleanup_file	cc_cleanup_file	File cleanup
fc_convert_format	cc_convert_format	Format conversion (JSON/CSV/INI/YAML/TOML/XML/TOON)
fc_md_to_html	cc_md_to_html	Markdown to HTML export
fc_md_to_pdf	cc_md_to_pdf	Markdown to PDF export

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.git
cd ellmos-codecommander-mcp
npm install
npm 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 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.

---

12. 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 (201 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 296 automated assertions, 100% green).

---

13. Sibling Ecosystem & Partner Matrix

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

MCP Server Family

Server	Tools	Focus	npm
FileCommander	50	Filesystem, process management, interactive sessions, cloud-lock-safe operations	ellmos-filecommander-mcp
CodeCommander	23	Code analysis, AST edits, JSON repair, diff, regex	ellmos-codecommander-mcp
Clatcher	12	File repair, format conversion, batch operations	ellmos-clatcher-mcp
n8n Manager	19	n8n workflow management via AI assistants	n8n-manager-mcp
ControlCenter	34	MCP stack discovery, profile management, control plane	ellmos-controlcenter-mcp
Homebase	51	Local-first LLM memory, knowledge, state, routing, swarm orchestration	ellmos-homebase-mcp (alpha)
ServerCommander	8	Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics	ellmos-servercommander-mcp (alpha)
Blender Use	4	Headless Blender asset QA and FBX reimport verification	ellmos-blender-use-mcp (alpha)
Open Compute	16	Model-agnostic computer use: capture, safety-gated actions, Windows UIA	open-compute-mcp (alpha)

Sibling Developer, File & Document Tools

Ecosystem	Tool / Project	Focus & Capabilities
ellmos-ai	sqlite-transit-sync	Offline SQLite change distribution with HMAC verification
ellmos-ai	policy-registry	Cryptographically signed delegation policies for AI agents
ellmos-ai	clutch	Provider-neutral LLM orchestration with auto-routing and budget tracking
ellmos-ai	BACH	Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools
dev-bricks	DevCenter	PySide6 Developer Desktop Suite & offline secret vault
dev-bricks	CodeBox	Fast desktop code snippet manager & local AST indexing
dev-bricks	MethodenAnalyser	Method flow & complexity diagnostic engine
doc-bricks	PDFtoPDFocr	Desktop OCR pipeline for searchable PDFs with Tesseract
doc-bricks	DokuReader	Multi-format document workspace & offline PDF export
file-bricks	ProFiler	Multi-pane file management & bulk batch operations
open-bricks	open-bricks	Umbrella organization for AI-native desktop applications

---

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.
• 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 security@ellmos.ai and support@lukasgeiger.com 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 and THIRD_PARTY_LICENSES.md 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 security@open-bricks.org, security@ellmos.ai und support@lukasgeiger.com 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 security@open-bricks.org, security@ellmos.ai and support@lukasgeiger.com with formal triage within 5 business days.