ellmos CodeCommander MCP Server

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.

Architecture Overview

mermaid

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

Code Intelligence & Safe Structural Edit Lifecycle

mermaid

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

Why CodeCommander?

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 - 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)
Umlaut Repair - Fix broken German characters (70+ patterns)
Format Conversion - Convert between JSON, CSV, INI, YAML, TOML, XML, and TOON
File Diff - Compare two files with unified diff output (LCS algorithm)
Regex Tester - Test regular expressions with match details, groups, and replace preview
Markdown Export - Convert Markdown to professional HTML/PDF with code blocks, tables, nested lists, blockquotes
Cross-platform - Works on Windows, macOS, and Linux

Installation

Prerequisites

Node.js 20 or higher

Option 1: Install from NPM

Terminal

npm install -g ellmos-codecommander-mcp

Option 2: Install from Source

bash

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

Configuration

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

If installed globally via NPM:

config.json

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

If installed from source:

config.json

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

Using Both Servers Together

FileCommander and CodeCommander are designed to work side by side:

config.json

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

Tools Overview

Code Analysis (3 tools)

Tool	Description
`cc_analyze_code`	Full code analysis: classes, functions, imports, LOC, complexity
`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 (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)

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

Total: 23 developer tools (including cc_set_language and cc_get_language for runtime language management)

Shared Tools

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

Tool Prefix

All tools use the cc_ prefix (CodeCommander) to avoid conflicts with FileCommander's fc_ prefix and other MCP servers.

Security

See SECURITY.md for detailed security information.

Key points:

File-modifying tools support preview/dry-run modes where applicable
Backup creation is enabled by default for destructive operations
Pure stdio JSON-RPC transport with Zero-Egress guarantees
Designed for local development use with standard unprivileged user permissions

Development

Terminal

npm install
npm run dev    # Watch mode
npm run build  # One-time build
npm start      # Start server
npm test       # Run test suite (vitest)
npm run test:integration  # 35 real MCP stdio assertions (after build)
npm run test:i18n         # 43 translation assertions

Testing

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

Terminal

npm test                  # Run Vitest unit tests (187 tests)
npm run test:integration  # Real MCP stdio test (35 assertions, build first)
npm run test:i18n         # i18n assertions (43 assertions)
npm run test:all          # Run full test suite (build + vitest + integration + i18n)

Tests are verified on Windows, macOS, and Linux.

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

Changelog

See CHANGELOG.md for the full version history.

License

MIT - Lukas Geiger (ellmos-ai)

History

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

The legacy package name bach-codecommander-mcp is deprecated. Please use ellmos-codecommander-mcp instead:

Terminal

npm uninstall -g bach-codecommander-mcp
npm install -g ellmos-codecommander-mcp

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent 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, JSON repair, imports, diffs, 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

AI Infrastructure

Project	Description
BACH	Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory
open-compute	Model-agnostic computer-use core powering Open Compute MCP
clutch	Provider-neutral LLM orchestration with auto-routing and budget tracking
rinnsal	Lightweight agent memory, connectors, and automation infrastructure
ellmos-stack	Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest)
MarbleRun	Autonomous agent chain framework for Claude Code
gardener	Minimalist database-driven LLM OS prototype (4 functions, 1 table)
ellmos-tests	Testing framework for LLM operating systems (7 dimensions)

Desktop Software

Our partner organization 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.

Liability

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.