v8unpack-mcp

用于完整处理 1C 二进制文件（.cf / .cfe / .epf / .erf）的 MCP 服务器（stdio），无需导入 EDT 项目：

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

唯一的解包入口是 unpack。所有其他工具都接受 dir_path —— 即由 unpack 创建的目录，并且不会进行隐式解包。

功能

在磁盘上搜索 .cf/.cfe/.epf/.erf 二进制文件 —— 使用客户端的标准文件工具（glob/list）。

工作流程

1. unpack(file_path) → {status, dir, file, kind}。dir 目录包含：

   • 组织化目录树（类型/名称 + .json / .obj.bsl / 表单 / 布局）—— 用于读取和编辑代码、表单、布局、属性；

   • raw 层 .v8unpack_raw/（brace 文件：text/image/help）—— 用于 read_bytecode/set_help。

2. 读取 —— list_objects / get_metadata / read_module / read_bytecode / search_code；编辑 —— 通过 dir 中的文件（或 set_help）。

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

4. cleanup(dir_path)（或 cleanup(all=true)）。

错误（文件/目录不存在、类型错误）通过异常抛出。repack 后目录不会自动删除 —— 可重复用于多次组装。

repack 方案

repack 通过 v8unpack.build(use_raw=True) 进行组装：

• 组织化目录树未修改 → raw 层逐字节恢复（保留 help、字节码、加密模块）；

• 组织化目录树已修改 → 从组织化目录树重新组装。

限制（all-or-nothing）：在同一会话中，要么修改组织化层（代码/表单），要么修改 raw 层（help/字节码）—— 不能同时进行。按对象合并是单独的任务。

search_code 搜索的内容

• .bsl —— 模块源码；

• .json —— 对象标题、属性及表单元素树；

• .txt / .html —— 文本和 HTML 布局；

• .bin（SKD）—— 数据组合方案：二进制前缀 + 带查询文本的 XML。

layers 参数限制搜索范围：modules（.bsl）、forms（.json）、templates_text（.txt）、templates_html（.html）、dcc（.bin-SKD）。空 = 全部。每个匹配项包含 layer 字段。

不搜索（二进制）：.mxl（表格文档）、图片、角色（.c1brace）、加密模块。MXL 解析器是单独的研究任务（参见 .ai/）。

比较（diff）

diff(dir_a, dir_b, full=true) 按对象比较两个解包目录：

• 枚举对象目录（cf/cfe 为 类型/名称，epf/erf 为根目录）；

• 收集每个对象的文件（不含服务文件 .id.json）；

• 状态：changed / added / removed / unchanged；

• 对已更改的文件构建 unified diff，按限制截断（MAX_DIFF_LINES=400，MAX_DIFF_FILES=20）；

• full=false —— 仅返回变更事实，不构建差异。

Related MCP server: 1C MCP Server

架构

• 解包核心 —— saby v8unpack（Python，MIT）。内置在 src/v8unpack/ 中，带有本地补丁（keep_raw/use_raw、针对 8.3.24+ 的 detect_format、对未知元数据组的容错）。

• 自有封装 —— src/v8unpack_mcp：core.py（逻辑）、textlayers.py（文本层提取）、server.py（MCP 服务器）。

• 解包 —— 每次调用 unpack 时解包到独立的临时目录 %TEMP%\v8unpack_unpack_*；无共享缓存（代理通过 cleanup 自行管理生命周期）。

• 对于 MCP，我们禁用 v8unpack 的多进程（串行池）并静默 stdout/stderr，以免破坏 stdio 协议；OrganizerFile.pack/unpack 跳过 .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

安装与启动

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

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

连接到客户端（MCP）

服务器通过 stdio 工作：每个客户端通过一条命令以独立进程方式自行启动它。所有工具都接受文件的绝对路径，因此进程的工作目录无关紧要。解包临时目录在系统 %TEMP% 中创建，前缀为 v8unpack_unpack_。

推荐的启动命令是控制台脚本 v8unpack-mcp（在 pip install 时创建）或 python -m v8unpack_mcp。对于不继承您的 PATH 的 GUI 客户端，更可靠的做法是指定解释器的绝对路径。

标准 MCP 格式（command + args）

Claude Desktop、Claude Code、Cline、Continue、Roo、VS Code（.mcp.json）等使用带有 command 和 args 字段的通用格式：

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

或使用显式解释器：

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

放置位置：

• Claude Desktop —— claude_desktop_config.json（设置 → 开发者 → 编辑配置）；

• Claude Code —— ~/.claude.json 或项目级 .mcp.json；

• Cline / Continue / Roo —— 项目级 .mcp.json（在成员之间共享）或用户设置；

• VS Code —— .vscode/mcp.json（用于项目服务器）或用户设置。

Kilo Code / Kilo CLI（kilo.json，命令为数组）

Kilo 的格式不同：服务器在 kilo.json 的 "mcp" 键下配置，命令以单个数组传递（不拆分为 command+args）。文件为项目级 ./kilo.json / .kilo/kilo.json 或全局 ~/.config/kilo/kilo.json。

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

或通过 python -m：

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

服务器在 TUI 中通过 /mcps 命令启用/禁用。可禁用继承的服务器：{ "v8unpack": { "enabled": false } }。

服务器工具权限 —— 通过 v8unpack_* 键（glob，自上而下匹配最后一个）：

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

多客户端建议

• 安装：一次 pip install -e .（用于开发）或 pip install dist/v8unpack_mcp-0.2.0-py3-none-any.whl（从构建的 wheel）；依赖 v8unpack 将从 pyproject.toml 自动拉取。

• 统一解释器：使用控制台命令 v8unpack-mcp（位于安装的 PATH 中）或在所有配置中使用相同的 python.exe 绝对路径 —— 这样任何客户端都会使用同一安装。

• 客户端相互独立：每个客户端持有自己的 stdio 进程；共享状态仅为磁盘上的 unpack 临时目录。可以放心地将同一服务器同时连接到多个客户端。

• 含空格/西里尔字母的路径：在 JSON 配置中将路径用引号括起来；在 command 数组（Kilo）中，元素会自动转义。

• 静默启动：服务器静默解包进度，仅通过 stdio 工作 —— 无需在配置中添加交互式输出。

构建

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   # установка из колеса

测试

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

测试使用 ../testdata 中的文件（个人文件，不包含在 git 中 —— 请放入您自己的文件）。

限制

• 大型 .cf（数百 MB 至 GB）：unpack 会完整提取到独立目录。按对象索引（无需完整提取即可读取单个对象）是下一步计划。

• 表格布局（.mxl）暂不搜索 —— 二进制格式，解析器在 TODO 中。

• 受保护（加密）模块：没有密码无法恢复源码，但 read_bytecode 可解析编译后的字节码，decompiler.py 可将其反编译为 BSL（decompile 工具在计划中）。

• 组织化层和 raw 层（help/字节码）的修改在同一会话中不会合并（all-or-nothing use_raw）。

借用的组件

项目复用了社区的开源成果：

saby v8unpack 作为 src/v8unpack/ 包含在包中（MIT 许可证保留在 src/v8unpack/LICENSE 中）。decompiler.py 是 1C-inversion 算法的移植；bytecode.py 使用 v8asm 的格式。

⚠️ 法律声明。 参见 DISCLAIMER.md 和 LICENSE：

• 本项目按 MIT 许可证“按原样”分发，不提供任何保证 —— 使用风险自负。

• “1C:Enterprise 8”许可证禁止以非标准方式修改产品的代码/数据，也禁止反编译系统的软件部分。该限制保护平台和 1C 的标准配置；不适用于自有配置、扩展和外部处理/报表 —— 请仅处理您自己的对象。

• 反编译受保护（加密）模块仅用于研究目的，不得用于破解或解除他人配置的保护（俄罗斯联邦刑法典第 146 条）。仅用于恢复您自己的模块。

有用链接

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

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

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

• MXL8 格式（规范）：https://github.com/azubar/SpreadSheet/blob/main/docs/format-mxl.md