<p align="center"> <img src="assets/codecommander_banner.jpg" alt="CodeCommander banner" width="700"> </p>

ellmos CodeCommander MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family.

A developer-focused Model Context Protocol (MCP) server that gives AI assistants code analysis, JSON repair, encoding fix, import organization, format conversion, file diff, and regex testing capabilities.

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

---

Why CodeCommander?

While FileCommander handles filesystem operations, CodeCommander focuses on code intelligence:

• Python Code Analysis - AST-based class/method extraction, complexity metrics, import analysis
• 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 18 or higher

Option 1: Install from NPM

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

---

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:

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

If installed from source:

{
  "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:

{
  "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
cc_extract_classes	Extract Python classes/functions as separate text blocks

Import Management (2 tools)

Tool	Description
cc_organize_imports	Sort & deduplicate Python imports per PEP 8
cc_diagnose_imports	Detect unused imports, duplicates, circular import risks

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

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: 17 tools

---

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:

• All file-modifying tools support dry_run mode
• Backup creation is enabled by default for destructive operations
• No built-in sandboxing - security is delegated to the MCP client
• Designed for local development use via stdio transport

---

Development

npm install
npm run dev    # Watch mode
npm run build  # One-time build
npm start      # Start server

---

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 old npm package bach-codecommander-mcp is deprecated. Please use ellmos-codecommander-mcp instead:

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	43	Filesystem, process management, interactive sessions	ellmos-filecommander-mcp
CodeCommander	17	Code analysis, AST parsing, import management	ellmos-codecommander-mcp
Clatcher	12	File repair, format conversion, batch operations	ellmos-clatcher-mcp
n8n Manager	13	n8n workflow management via AI assistants	n8n-manager-mcp

AI Infrastructure

Project	Description
BACH	Text-based OS for LLMs — 109+ handlers, 373+ tools, 932+ skills
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.

---

Haftung / 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 gelten die Haftungsausschlüsse aus GPL-3.0 / MIT / Apache-2.0 §§ 15–16 (je nach gewählter 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. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.