Ellmos Clatcher MCP

ellmos-clatcher-mcp

🇩🇪 Deutsche Version | 🤝 Contributing | 🛡️ Security Policy | 📜 Licenses | 📝 Changelog | 📋 llms.txt

Claude Patcher -- an MCP server that extends AI coding agents with utility tools they don't have natively. File repair, format conversion, duplicate detection, batch operations, and more.

Use Clatcher when your agent needs reliable local maintenance tools for text files, data files, and project folders: repair invalid JSON, normalize encodings, convert formats, compare folders, rename files safely, and verify checksums without leaving the MCP workflow.

[!NOTE] AI / LLM Integration Note: All destructive operations (e.g. batch_rename, cleanup_file, fix_json, fix_encoding, fix_umlauts) default to dry-run mode (dry_run: true). Autonomous agents must explicitly specify dry_run: false to execute mutations on disk.

Highlights & Value Proposition

• 12 Specialized Agent Tools: Extends Claude Code, Cursor, and MCP agents with utilities they lack out-of-the-box (JSON repair, encoding normalization, format conversion, diffing, deduplication, regex batch renaming).
• Default Dry-Run Guard: Mutating tools run in preview mode (dry_run: true) by default. Agents must pass dry_run: false to write to disk.
• 100% Local-First & Zero-Egress: Pure local execution over stdio JSON-RPC. No network calls, no cloud telemetry, zero remote attack surface.
• Atomic File Operations: All disk modifications write to temporary staging buffers before replacement, preventing corrupt or truncated files.
• Lossless Encoding Preservation: Eliminates Windows cp1252 artifacts, BOM headers, and German umlaut Mojibake (ä, ö, ü, ß) while guaranteeing pristine UTF-8 bytes.
• Universal Multi-OS Parity: Tested continuously across Ubuntu, Windows, and macOS with native path handling and line endings.

🧭 Quick Navigation

Target Personas & Discoverability

Comparative Matrix & Alternatives

System Architecture & Data Flow

ASCII Four-View Architectural Topology

+--------------------------------------------------------------------------------------------------+
|                              ELLMOS CLATCHER MCP ARCHITECTURAL TOPOLOGY                          |
+--------------------------------------------------------------------------------------------------+
| [VIEW 1: CALLER RUNTIMES & AGENT CLIENTS]                                                        |
|   * Autonomous Agents   : Claude Code, OpenAI Codex, Antigravity / Gemini, Kimi, Cursor          |
|   * Agent Frameworks    : AutoGen, CrewAI, LangChain, LlamaIndex, Custom Python / TS Clients    |
|   * Transport Protocols : Model Context Protocol (MCP stdio), JSON-RPC 2.0 Framing               |
|   * Tool Surface        : 12 Specialized Agent Tools (file repair, formatting, hash & archives)  |
|   * Schema Contract     : Stdio transport, dynamic runtime Zod schema validation & parameter guards|
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 2: CLATCHER MCP CORE ENGINE & TOOL DISPATCH ORCHESTRATOR]                                  |
|   * Protocol Dispatch   : ESM stdio router with Zod schema validation & parameter checking      |
|   * Safety Interceptor  : Built-in Dry-Run Guard (INV-DRYRUN-01) defaulting mutating tools to preview|
|   * Fault Diagnostics   : Multi-pass JSON syntax linter & self-healing AST repair pipeline       |
|   * Encoding Resolver   : Lossless UTF-8 normalization, BOM stripper & German umlaut Mojibake fix|
|   * Format Converter    : Bi-directional translation across 6 formats (JSON, YAML, TOML, XML...)|
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 3: RUNTIME UTILITIES, FORMAT CONVERTERS & ATOMIC REPAIR PIPELINE]                          |
|   * Atomic File Ops     : Staged temporary buffer writes before replacement (INV-ATOMIC-04)      |
|   * Traversal Guard     : Archive extraction & batch rename strictly bounded to root trees       |
|   * Duplication Analysis: Collision-resistant SHA-256 cluster detection across workspace files   |
|   * Cryptographic Hashes: Native multi-algorithm digest verification (SHA-256, SHA-512, MD5, SHA-1)|
|   * Directory Diffs     : Fast recursive folder structural and content delta comparison engine   |
|   * In-Memory Archives  : Streamlined ZIP creation, inspection, and extraction with adm-zip      |
+--------------------------------------------------------------------------------------------------+
|                                                |                                                 |
|                                                v                                                 |
+--------------------------------------------------------------------------------------------------+
| [VIEW 4: AIR-GAP DEFENSE PERIMETER, RUNASINVOKER & ZERO-EGRESS GOVERNANCE]                       |
|   * Execution Privilege : RunAsInvoker unprivileged user-mode (Zero administrative elevation)    |
|   * Transport Boundary  : 100% Local stdio transport, zero telemetry, zero open listening ports  |
|   * Air-Gap Isolation   : 100% Offline execution, zero outbound network sockets, zero egress     |
|   * Statutory Protection: § 521 BGB gratuitous open-source liability disclaimer & 48h SLA        |
|   * Governance & Supply : Level 1 SBOM, 100% permissive runtime (MIT/BSD), NOTICE attribution    |
+--------------------------------------------------------------------------------------------------+

Component Data Flow Diagram

graph TD
    Agent["AI Agent / Claude Code / Cursor / IDE"] -->|"MCP JSON-RPC Protocol over Stdio"| Transport["MCP Stdio Transport Layer"]
    Transport --> Server["Clatcher MCP Server Runtime"]
    Server --> Dispatcher{"Tool Dispatcher"}

    Dispatcher -->|"fix_json / cleanup_file"| JsonEngine["JSON Linter & Auto-Fix Engine"]
    Dispatcher -->|"fix_encoding / fix_umlauts"| EncodingEngine["Encoding Normalizer & Mojibake Resolver"]
    Dispatcher -->|"convert_format"| FormatEngine["Format Converter: JSON/YAML/TOML/XML/CSV/INI"]
    Dispatcher -->|"detect_dupes / checksum"| HashEngine["SHA-256 / Multi-Hash Content Engine"]
    Dispatcher -->|"folder_diff / batch_rename"| FileOpsEngine["Folder Diff & Regex Batch Renamer"]
    Dispatcher -->|"archive / zip"| ArchiveEngine["AdmZip Compression Handler"]
    Dispatcher -->|"scan_emoji / regex_test"| RegexEngine["Emoji Scanner & Regex Debugger"]

    JsonEngine --> DryRunGuard{"Dry-Run Guard"}
    EncodingEngine --> DryRunGuard
    FormatEngine --> DryRunGuard
    FileOpsEngine --> DryRunGuard
    ArchiveEngine --> DryRunGuard

    DryRunGuard -->|"dry_run: true (default)"| PreviewReport["Detailed Dry-Run Preview Diff & Status"]
    DryRunGuard -->|"dry_run: false (explicit)"| DiskWrite["Safe Atomic Filesystem Write"]

End-to-End Execution Sequence

sequenceDiagram
    autonumber
    actor User as Developer / Agent Orchestrator
    participant Agent as AI Coding Agent (Claude Code / Cursor)
    participant Stdio as MCP Stdio Protocol (JSON-RPC)
    participant Clatcher as Clatcher MCP Server
    participant Validator as Zod Schema Validator
    participant Engine as Dedicated Tool Engine
    participant Guard as Dry-Run Safety Guard
    participant FS as Local Filesystem

    User->>Agent: Prompt: "Fix broken encoding and trailing commas in config.json"
    Agent->>Stdio: CallTool(name="fix_json", args={path: "config.json", dry_run: true})
    Stdio->>Clatcher: Dispatch JSON-RPC Request
    Clatcher->>Validator: Validate arguments (Zod schema)
    Validator-->>Clatcher: Validated inputs

    Clatcher->>Engine: Run JSON repair pipeline
    Engine->>FS: Read target file content (UTF-8)
    FS-->>Engine: Raw file bytes / string
    Engine->>Engine: Strip comments, trailing commas, single quotes, NULs
    Engine->>Guard: Submit repaired AST / string

    alt dry_run == true (Default Mode)
        Guard->>Guard: Generate diff & mutation preview
        Guard-->>Clatcher: Return diff preview without disk write
    else dry_run == false (Explicit Agent Mutation)
        Guard->>FS: Atomic write to target file via temp buffer
        FS-->>Guard: Write successful
        Guard-->>Clatcher: Return success receipt + bytes written
    end

    Clatcher-->>Stdio: JSON-RPC ToolResult (diff, stats, safety report)
    Stdio-->>Agent: Formatted MCP response
    Agent-->>User: Synthesized result & proposed next steps

Core Invariants & Safety Guarantees

Tools

All destructive tools default to dry-run mode and require explicit dry_run: false to write changes.

Installation

Claude Code CLI

claude mcp add ellmos-clatcher-mcp -- npx ellmos-clatcher-mcp

Claude Desktop / Cursor Configuration

Add Clatcher to your claude_desktop_config.json or Cursor MCP settings:

{
  "mcpServers": {
    "clatcher": {
      "command": "npx",
      "args": ["-y", "ellmos-clatcher-mcp"]
    }
  }
}

npm (global)

npm install -g ellmos-clatcher-mcp
claude mcp add ellmos-clatcher-mcp -- ellmos-clatcher

From source

git clone https://github.com/ellmos-ai/ellmos-clatcher-mcp.git
cd ellmos-clatcher-mcp
npm install
npm run build
node dist/index.js

Practical Usage Workflows

Clatcher provides deterministic, single-step utility actions tailored for AI coding workflows:

1. JSON Auto-Repair (fix_json)

Autonomous agent runs often stumble upon configuration files with trailing commas, single-quoted keys, or inline JavaScript comments:

{
  "name": "fix_json",
  "arguments": {
    "path": "tsconfig.json",
    "dry_run": false
  }
}

Result: Comments and trailing commas are parsed and stripped, producing strict, spec-compliant JSON with verifiable bytes written.

2. Lossless Character Encoding Normalization (fix_encoding / fix_umlauts)

Fixes Windows cp1252 artifacts, BOM headers, and double-encoded UTF-8 sequences without data loss:

{
  "name": "fix_umlauts",
  "arguments": {
    "path": "docs/Anleitung.md",
    "dry_run": false
  }
}

Result: Corrupted sequences like ä, ö, ü, ß are converted back to clean UTF-8 ä, ö, ü, ß.

3. Multi-Format Configuration Conversion (convert_format)

Converts structured data between JSON, YAML, TOML, XML, CSV, and INI in a single pass:

{
  "name": "convert_format",
  "arguments": {
    "source_path": "config.yaml",
    "target_format": "json",
    "dry_run": false
  }
}

4. Duplicate Detection & Cryptographic Hashing (detect_dupes / checksum)

Scans target directory trees to identify identical content using SHA-256 hash clustering without transmitting data over the network:

{
  "name": "detect_dupes",
  "arguments": {
    "directory": "src/assets"
  }
}

5. Safe Regex Batch Renaming (batch_rename)

Preview and stage batch file renames with regex patterns:

{
  "name": "batch_rename",
  "arguments": {
    "directory": "reports",
    "pattern": "^draft_(.*)\\.txt$",
    "replacement": "final_$1.txt",
    "dry_run": true
  }
}

Dry-Run Protocol & Safety Verification

All mutating tools in ellmos-clatcher-mcp enforce a preview-first contract (dry_run: true by default):

1. Safety Preview: Invoking fix_json, cleanup_file, batch_rename, fix_encoding, or archive without arguments returns a detailed unified diff and mutation preview without touching the disk.
2. Explicit Opt-In: Filesystem writes occur only when the agent explicitly supplies dry_run: false.
3. Fail-Closed Argument Validation: Path parameters are strictly sanitized against path traversal (.. escapes) and bounded by project directory constraints.
4. Receipt Generation: Every modifying run produces an authoritative JSON receipt detailing bytes read, bytes written, and cryptographic verification status.

Encoding, Mojibake & Format Conversion

Clatcher incorporates specialized string manipulation primitives to resolve cross-platform text corruption:

• BOM Stripping: Automatically removes UTF-8 BOM headers (0xEF, 0xBB, 0xBF) that break legacy CLI parsers and CI linters.
• Mojibake Resolution: Reconstructs corrupted multi-byte sequences resulting from ISO-8859-1 or Windows-1252 interpretations of UTF-8 text.
• Line Ending Standardization: Converts mixed Windows CRLF (\r\n) and Unix LF (\n) files into consistent line feeds.
• NUL-Byte Removal: Sanitizes accidental binary NUL characters injected by interrupted network streams or corrupted disk blocks.

Multi-OS Support & Windows Path Robustness

Cross-platform parity is verified continuously on Linux, macOS, and Windows:

• Path Normalization: Resolves backslashes (\) and forward slashes (/) transparently using native Node.js path modules.
• Long Path Support: Safely operates on Windows deep nested structures without MAX_PATH (260 character) truncation.
• Unprivileged Execution: Operates under standard user rights (RunAsInvoker), requiring no administrative elevation or root access.

ellmos MCP Family & Sibling Matrix

Part of the ellmos MCP family:

Each server covers a different domain. Use one server, a focused pair, or the full family depending on your workflow.

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

AI Infrastructure

Desktop Software & Sibling Ecosystem

Our partner organization open-bricks and sister suites bundle AI-native applications and developer tooling:

Security Policy

For security vulnerability disclosure channels, supported versions, and our 48-hour response SLA, refer to SECURITY.md. For development guidelines, quality gates, and invariant contracts, see CONTRIBUTING.md.

Machine-Readable Context (llms.txt)

This repository provides a standardized machine-readable context file for AI agents, crawlers, and RAG indexers:

• llms.txt: Concise manifest of all 12 tools, dry-run safety invariants, sibling MCP tool counts, and CLI invocation examples.

Testing

npm test

172 tests covering all 12 tools, i18n language packs, repository hygiene, and metadata consistency (vitest). The GitHub Actions workflow runs npm ci, TypeScript build, Vitest, and an npm package dry-run on Node.js 20, 22, and 24.

Requirements

• Node.js >= 20

License

MIT

Third-Party Licenses & Transparency

ellmos-clatcher-mcp adheres strictly to open-bricks and ellmos-ai open-source governance standards. All 7 direct runtime dependencies and 5 development dependencies are 100% permissively licensed (MIT, BSD-3-Clause, BSD-2-Clause, Apache-2.0) with zero copyleft (0% GPL/AGPL) and zero cloud telemetry.

Formal copyright notice and ecosystem attribution are codified in NOTICE. For the comprehensive dependency inventory, SPDX identifiers, Level 1 SBOM cross-reference matrix, and full license texts, see THIRD_PARTY_LICENSES.md and the plain-text companion THIRD_PARTY_LICENSES.txt.

Discoverability

• npm: ellmos-clatcher-mcp
• GitHub: ellmos-ai/ellmos-clatcher-mcp
• MCP Registry metadata: server.json declares the official io.github.ellmos-ai/ellmos-clatcher-mcp package identity.
• Glama.ai Registry: glama.json manifest for Glama MCP ecosystem.
• LLM index: llms.txt summarizes the tool surface for agents and registry crawlers.

Primary search terms: ellmos-clatcher-mcp, clatcher mcp, claude patcher, mcp json repair server, mcp encoding fix, model context protocol file repair, claude code utility tools, format conversion mcp tool, duplicate file detection mcp, batch rename mcp, checksum mcp, zip archive mcp.

Changelog

For the complete release evolution, version notes, and hygiene audits, see CHANGELOG.md.

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 gilt der Gewährleistungsausschluss 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). The MIT License warranty disclaimer applies.

Use at your own risk. No warranty, no maintenance guarantee, no availability guarantee, and no fitness-for-purpose assumed.