v8unpack-mcp

MCP server (stdio) for the full lifecycle of working with 1C binary files (.cf / .cfe / .epf / .erf) without importing into an EDT project:

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

The single unpacking point is unpack. All other tools accept dir_path — a directory created by unpack — and do not perform implicit unpacking.

Features

Searching for .cf/.cfe/.epf/.erf binaries on disk is done with standard client file tools (glob/list).

Workflow

1. unpack(file_path) → {status, dir, file, kind}. The dir directory contains:

   • organized tree (Type/Name + .json / .obj.bsl / forms / layouts) — reading and editing code, forms, layouts, attributes;

   • raw layer .v8unpack_raw/ (brace files: text/image/help) — for read_bytecode/set_help.

2. Reading — list_objects / get_metadata / read_module / read_bytecode / search_code; editing — via files in dir (or set_help).

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

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

Errors (missing file/directory, wrong type) are raised as exceptions. The directory after repack is not deleted automatically — it can be reused for multiple assemblies.

repack scheme

repack assembles via v8unpack.build(use_raw=True):

• organized tree not modified → the raw layer is restored byte-for-byte (help, bytecode, encrypted modules are preserved);

• organized tree modified → reassembly from the organized tree.

Limitation (all-or-nothing): in one session, either organized-layer edits (code/forms) or raw-layer edits (help/bytecode) — not both. Per-object merging is a separate task.

What search_code looks for

• .bsl — module sources;

• .json — object headers, attributes, and form element trees;

• .txt / .html — text and HTML layouts;

• .bin (SKD) — data composition schema: binary prefix + XML with query text.

The layers parameter restricts search areas: modules (.bsl), forms (.json), templates_text (.txt), templates_html (.html), dcc (.bin-SKD). Empty = all. Each match contains a layer field.

Not searched (binary): .mxl (tabular document), images, roles (.c1brace), encrypted modules. The MXL parser is a separate research task (see .ai/).

Comparison (diff)

diff(dir_a, dir_b, full=true) compares two unpacked directories object-by-object:

• enumerates object directories (Type/Name for cf/cfe, root for epf/erf);

• collects each object's files (excluding the service .id.json);

• statuses: changed / added / removed / unchanged;

• for changed objects, a unified diff is built, truncated by limits (MAX_DIFF_LINES=400, MAX_DIFF_FILES=20);

• full=false — only the change fact, without building the diff.

Related MCP server: 1C MCP Server

Architecture

• Unpacking core — saby v8unpack (Python, MIT). Vendored into src/v8unpack/ with local patches (keep_raw/use_raw, detect_format for 8.3.24+, tolerance to unknown metadata groups).

• Own wrapper — src/v8unpack_mcp: core.py (logic), textlayers.py (text layer extraction), server.py (MCP server).

• Unpacking goes into a separate temporary directory %TEMP%\v8unpack_unpack_* for each unpack call; no shared cache (the agent manages the lifecycle itself via cleanup).

• For MCP, we disable v8unpack multiprocessing (serial pool) and silence stdout/stderr so as not to break the stdio protocol; OrganizerFile.pack/unpack skip .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 and launch

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

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

Connecting to a client (MCP)

The server works over stdio: each client launches it as a separate process with a single command. All tools accept absolute paths to files, so the process working directory does not matter. Temporary unpacking directories are created in the system %TEMP% with the v8unpack_unpack_ prefix.

The recommended launch command is the console script v8unpack-mcp (created during pip install) or python -m v8unpack_mcp. For GUI clients that do not inherit your PATH, it is safer to specify the absolute path to the interpreter.

Standard MCP format (command + args)

Claude Desktop, Claude Code, Cline, Continue, Roo, VS Code (.mcp.json) and others use a common format with command and args fields:

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

Or with an explicit interpreter:

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

Where to place it:

• Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config);

• Claude Code — ~/.claude.json or project .mcp.json;

• Cline / Continue / Roo — project .mcp.json (shared between team members) or user settings;

• VS Code — .vscode/mcp.json (for the project server) or user settings.

Kilo Code / Kilo CLI (kilo.json, command is an array)

The Kilo format differs: servers are specified in kilo.json under the "mcp" key, and the command is passed as a single array (without splitting into command+args). The file is the project-level ./kilo.json / .kilo/kilo.json or the global ~/.config/kilo/kilo.json.

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

Or via python -m:

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

The server is enabled/disabled in the TUI with the /mcps command. An inherited server can be disabled: { "v8unpack": { "enabled": false } }.

Server tool permissions are set by v8unpack_* keys (glob, the last match from top to bottom takes effect):

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

Recommendations for multiple clients

• Installation: once pip install -e . (for development) or pip install dist/v8unpack_mcp-0.2.0-py3-none-any.whl (from a built wheel); the v8unpack dependency is pulled automatically from pyproject.toml.

• Single interpreter: use the console command v8unpack-mcp (it lands in the installation PATH) or the same absolute path to python.exe in all configs — then any client will pick up the same installation.

• Clients are independent: each client holds its own stdio process; the only shared state is the temporary unpack directories on disk. You can safely connect the same server to multiple clients simultaneously.

• Paths with spaces/Cyrillic: quote paths in JSON configs; in the command array (Kilo), elements are escaped automatically.

• Quiet launch: the server silences unpacking progress and works only over stdio — no interactive output needs to be added to configs.

Build

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

Tests use files from ../testdata (personal files, not included in git — place your own).

Limitations

• Large .cf files (hundreds of MB — GB): unpack performs a full extract into a separate directory. A per-object index (reading one object without a full extract) is the next step.

• Tabular layouts (.mxl) are not searched yet — binary format, parser is in the TODO.

• Protected (encrypted) modules: the source cannot be recovered without the password, but read_bytecode parses the compiled bytecode, and decompiler.py can decompile it into BSL (the decompile tool is planned).

• Edits to the organized layer and the raw layer (help/bytecode) are not merged in one session (all-or-nothing use_raw).

Borrowed components

The project reuses open community developments:

saby v8unpack is included in the package as src/v8unpack/ (the MIT license is preserved in src/v8unpack/LICENSE). decompiler.py is a port of the 1C-inversion algorithm; bytecode.py uses the v8asm format.

⚠️ Legal notice. See DISCLAIMER.md and LICENSE:

• The project is distributed under the MIT license "as is", without warranties — use at your own risk.

• The "1C:Enterprise 8" license prohibits modifying the product's code/data with non-standard means, as well as decompiling the software part of the system. This restriction protects the platform and standard 1C configurations; it does not apply to your own configurations, extensions, and external reports/processing — work only with your own objects.

• Decompilation of closed (password-protected) modules is implemented for research purposes and must not be used to crack or remove protection from others' configurations (Article 146 of the Russian Criminal Code). Use it only to recover your own modules.

Useful 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 (spec): https://github.com/azubar/SpreadSheet/blob/main/docs/format-mxl.md