v8unpack-mcp

MCP-Server (stdio) für den vollständigen Arbeitszyklus mit 1C-Binärdateien (.cf / .cfe / .epf / .erf) ohne Import in ein EDT-Projekt:

unpack → чтение/правка → repack → cleanup

Der einzige Entpackungspunkt ist unpack. Alle anderen Werkzeuge akzeptieren dir_path — ein Verzeichnis, das von unpack erstellt wurde, und führen keine implizite Entpackung durch.

Funktionen

Suche nach Binärdateien .cf/.cfe/.epf/.erf auf der Festplatte — mit den Standard-Datei- werkzeugen des Clients (glob/list).

Arbeitszyklus

1. unpack(file_path) → {status, dir, file, kind}. Das Verzeichnis dir enthält:

   • organisierten Baum (Typ/Name + .json / .obj.bsl / Formulare / Layouts) — Lesen und Bearbeiten von Code, Formularen, Layouts, Attributen;

   • raw-Ebene .v8unpack_raw/ (Brace-Dateien: text/image/help) — für read_bytecode/set_help.

2. Lesen — list_objects / get_metadata / read_module / read_bytecode / search_code; Bearbeiten — per Dateien in dir (oder set_help).

3. repack(dir_path, output_path) → {status, output, bytes}.

4. cleanup(dir_path) (oder cleanup(all=true)).

Fehler (keine Datei/kein Verzeichnis, falscher Typ) — als Ausnahmen. Das Verzeichnis wird nach repack nicht automatisch gelöscht — es kann für mehrere Zusammenbauten wiederverwendet werden.

Schema von repack

repack baut über v8unpack.build(use_raw=True) zusammen:

• organisierter Baum nicht bearbeitet → raw-Ebene wird byteweise wiederhergestellt (Hilfen, Byte-Code, verschlüsselte Module bleiben erhalten);

• organisierter Baum bearbeitet → Neuzusammenbau aus dem organisierten Baum.

Einschränkung (Alles-oder-nichts): In einer Sitzung entweder Bearbeitungen der organisierten Ebene (Code/Formulare) oder der raw-Ebene (Hilfe/Byte-Code) — nicht beides gleichzeitig. Objektweise Zusammenführung — separate Aufgabe.

Was in search_code gesucht wird

• .bsl — Quellcode der Module;

• .json — Objektköpfe, Attribute und Elementbaum der Formulare;

• .txt / .html — Text- und HTML-Layouts;

• .bin (SKD) — Datenkompositionsschema: binäres Präfix + XML mit Abfragetext.

Der Parameter layers begrenzt die Suchbereiche: modules (.bsl), forms (.json), templates_text (.txt), templates_html (.html), dcc (.bin-SKD). Leer = alle. Jede Übereinstimmung enthält ein Feld layer.

Nicht gesucht wird (binär): .mxl (Tabellendokument), Bilder, Rollen (.c1brace), verschlüsselte Module. Der MXL-Parser — separate Research-Aufgabe (siehe .ai/).

Vergleich (diff)

diff(dir_a, dir_b, full=true) vergleicht zwei entpackte Verzeichnisse objektweise:

• listet die Objektverzeichnisse auf (Typ/Name für cf/cfe, Wurzel für epf/erf);

• sammelt die Dateien jedes Objekts (ohne Dienstdatei .id.json);

• Status: changed / added / removed / unchanged;

• für geänderte wird ein unified diff erstellt, begrenzt durch Limits (MAX_DIFF_LINES=400, MAX_DIFF_FILES=20);

• full=false — nur die Tatsache der Änderung, ohne Diff-Erstellung.

Related MCP server: 1C MCP Server

Architektur

• Entpackungskern — saby v8unpack (Python, MIT). Vendored in src/v8unpack/ mit lokalen Patches (keep_raw/use_raw, detect_format für 8.3.24+, Toleranz gegenüber unbekannten Metadatengruppen).

• Eigener Wrapper — src/v8unpack_mcp: core.py (Logik), textlayers.py (Extraktion von Textebenen), server.py (MCP-Server).

• Entpackung — in ein separates temporäres Verzeichnis %TEMP%\v8unpack_unpack_* bei jedem Aufruf von unpack; kein gemeinsamer Cache (der Agent verwaltet den Lebenszyklus selbst über cleanup).

• Für MCP deaktivieren wir Multiprocessing von v8unpack (serieller Pool) und unterdrücken stdout/stderr, um das stdio-Protokoll nicht zu stören; OrganizerFile.pack/unpack überspringen .v8unpack_raw.

v8unpack-mcp/
├── src/
│   ├── v8unpack/            # вендоренное ядро saby v8unpack (MIT) + патчи
│   └── v8unpack_mcp/
│       ├── __init__.py
│       ├── __main__.py     # python -m v8unpack_mcp
│       ├── core.py         # инструменты: unpack/чтение/правка/repack/cleanup
│       ├── textlayers.py   # извлечение текстовых слоёв (поиск)
│       ├── bytecode.py     # чтение байт-кода закрытых модулей (из raw-слоя)
│       ├── decompiler.py   # декомпилятор байт-кода → BSL
│       ├── diffing.py      # сравнение распакованных каталогов
│       └── server.py       # MCP-сервер (stdio)
├── tests/
│   ├── test_core.py
│   └── test_server_e2e.py
└── pyproject.toml

Installation und Start

# MCP-сервер (вендоренное ядро v8unpack входит в пакет)
pip install -e .

# запуск (stdio)
python -m v8unpack_mcp
# или консольная команда
v8unpack-mcp

Verbindung zum Client (MCP)

Der Server arbeitet über stdio: Jeder Client startet ihn selbst als separaten Prozess über einen einzigen Befehl. Alle Werkzeuge akzeptieren absolute Pfade zu Dateien, daher ist das Arbeitsverzeichnis des Prozesses nicht wichtig. Temporäre Entpackungsverzeichnisse werden im System-%TEMP% mit dem Präfix v8unpack_unpack_ erstellt.

Der empfohlene Startbefehl ist das Konsolenskript v8unpack-mcp (wird bei pip install erstellt) oder python -m v8unpack_mcp. Für GUI-Clients, die Ihr PATH nicht erben, ist es zuverlässiger, den absoluten Pfad zum Interpreter anzugeben.

Standardformat von MCP (command + args)

Claude Desktop, Claude Code, Cline, Continue, Roo, VS Code (.mcp.json) und andere verwenden ein gemeinsames Format mit den Feldern command und args:

{
  "mcpServers": {
    "v8unpack": {
      "command": "v8unpack-mcp",
      "args": []
    }
  }
}

Oder mit explizitem Interpreter:

{
  "mcpServers": {
    "v8unpack": {
      "command": "~/путь/к/python.exe",
      "args": ["-m", "v8unpack_mcp"]
    }
  }
}

Wo platzieren:

• Claude Desktop — claude_desktop_config.json (Einstellungen → Entwickler → Edit Config);

• Claude Code — ~/.claude.json oder Projekt-.mcp.json;

• Cline / Continue / Roo — Projekt-.mcp.json (wird zwischen Teilnehmern geteilt) oder Benutzereinstellungen;

• VS Code — .vscode/mcp.json (für den Projekt-Server) oder Benutzereinstellungen.

Kilo Code / Kilo CLI (kilo.json, Befehl — Array)

Das Kilo-Format unterscheidet sich: Server werden in kilo.json unter dem Schlüssel "mcp" angegeben, und der Befehl wird als ein einziges Array übergeben (ohne Trennung in command+args). Die Datei — Projekt- ./kilo.json / .kilo/kilo.json oder global ~/.config/kilo/kilo.json.

// kilo.json (проект)
{
  "mcp": {
    "v8unpack": {
      "type": "local",
      "command": ["v8unpack-mcp"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

Oder über python -m:

{
  "mcp": {
    "v8unpack": {
      "type": "local",
      "command": ["python", "-m", "v8unpack_mcp"],
      "enabled": true
    }
  }
}

Der Server wird in der TUI mit dem Befehl /mcps ein-/ausgeschaltet. Ein geerbter Server kann deaktiviert werden: { "v8unpack": { "enabled": false } }.

Rechte auf die Server-Werkzeuge — über Schlüssel v8unpack_* (glob, die letzte Übereinstimmung von oben nach unten gewinnt):

{
  "permission": {
    "v8unpack_*": "allow"
  }
}

Empfehlungen für mehrere Clients

• Installation: einmal pip install -e . (für Entwicklung) oder pip install dist/v8unpack_mcp-0.2.0-py3-none-any.whl (aus dem gebauten Wheel); die Abhängigkeit v8unpack wird automatisch aus pyproject.toml nachgezogen.

• Einheitlicher Interpreter: Verwenden Sie den Konsolenbefehl v8unpack-mcp (gelangt in den PATH der Installation) oder denselben absoluten Pfad zu python.exe in allen Konfigurationen — dann übernimmt jeder Client dieselbe Installation.

• Clients sind unabhängig: Jeder Client hält seinen eigenen stdio-Prozess; gemeinsamer Zustand — nur die temporären unpack-Verzeichnisse auf der Festplatte. Sie können denselben Server bedenkenlos gleichzeitig mit mehreren Clients verbinden.

• Pfade mit Leerzeichen/Kyrillisch: In JSON-Konfigurationen Pfade in Anführungszeichen setzen; im Array command (Kilo) werden Elemente automatisch maskiert.

• Stiller Start: Der Server unterdrückt den Entpackungsfortschritt und arbeitet nur über stdio — interaktive Ausgabe muss nicht zu den Konfigurationen hinzugefügt werden.

Zusammenbau

pip install build wheel          # инструменты сборки
python -m build                  # создаст dist/v8unpack_mcp-<ver>-py3-none-any.whl и .tar.gz
pip install dist/v8unpack_mcp-0.2.0-py3-none-any.whl   # установка из колеса

Tests

python tests/test_core.py          # юнит-смоук ядра
python tests/test_server_e2e.py    # end-to-end через stdio

Die Tests verwenden Dateien aus ../testdata (persönliche Dateien, gehören nicht zu git — legen Sie Ihre eigenen hinein).

Einschränkungen

• Große .cf (Hunderte MB — GB): unpack macht eine vollständige Extraktion in ein separates Verzeichnis. Objektweiser Index (Lesen eines Objekts ohne vollständige Extraktion) — nächster Schritt.

• Tabellenlayouts (.mxl) werden vorerst nicht durchsucht — binäres Format, Parser in TODO.

• Geschützte (verschlüsselte) Module: Quellcode ohne Passwort nicht wiederherstellbar, aber read_bytecode analysiert den kompilierten Byte-Code, und decompiler.py kann ihn in BSL dekompilieren (Werkzeug decompile — geplant).

• Bearbeitungen der organisierten Ebene und der raw-Ebene (Hilfe/Byte-Code) werden in einer Sitzung nicht zusammengeführt (Alles-oder-nichts use_raw).

Übernommene Komponenten

Das Projekt verwendet offene Entwicklungen der Community wieder:

saby v8unpack ist als src/v8unpack/ im Paket enthalten (MIT-Lizenz in src/v8unpack/LICENSE erhalten). decompiler.py — Port des 1C-inversion-Algorithmus; bytecode.py verwendet das Format aus v8asm.

⚠️ Rechtlicher Hinweis. Siehe DISCLAIMER.md und LICENSE:

• Das Projekt wird unter der MIT-Lizenz „wie besehen", ohne Garantien, verbreitet — Nutzung auf eigenes Risiko.

• Die Lizenz von „1C:Enterprise 8" verbietet, Code/Daten des Produkts mit nicht standardmäßigen Mitteln zu ändern sowie den Softwareteil des Systems zu dekompilieren. Diese Einschränkung schützt die Plattform und die Standard-Konfigurationen von 1C; auf eigene Konfigurationen, Erweiterungen und externe Verarbeitungen/Berichte erstreckt sie sich nicht — arbeiten Sie nur mit Ihren eigenen Objekten.

• Die Dekompilierung geschlossener (passwortgeschützter) Module ist zu Forschungszwecken implementiert und darf nicht zum Knacken oder Entfernen des Schutzes fremder Konfigurationen verwendet werden (Art. 146 StGB der RF). Verwenden Sie sie nur zur Wiederherstellung eigener Module.

Nützliche Links

• saby v8unpack: https://github.com/saby-integration/v8unpack

• EvilBeaver/v8asm: https://github.com/EvilBeaver/v8asm

• 1C-inversion: https://github.com/ProhorP/1C-inversion

• MXL8-Format (Spezifikation): https://github.com/azubar/SpreadSheet/blob/main/docs/format-mxl.md