v8unpack-mcp

Servidor MCP (stdio) para trabajar con los binarios de 1С (.cf / .cfe / .epf / .erf) sin importarlos a un proyecto EDT:

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

El único punto de desempaquetado — unpack. Todas las demás herramientas aceptan dir_path — un directorio creado por unpack — y no realizan desempaquetado implícito.

Características

La búsqueda de binarios .cf/.cfe/.epf/.erf en el disco se realiza con las herramientas estándar de archivos del cliente (glob/list).

Ciclo de trabajo

1. unpack(file_path) → {status, dir, file, kind}. El directorio dir contiene:

   • árbol organizado (Тип/Имя + .json / .obj.bsl / formularios / plantillas): lectura y edición de código, formularios, plantillas, atributos;

   • capa raw .v8unpack_raw/ (archivos brace: text/image/help) — para read_bytecode/set_help.

2. Lectura — list_objects / get_metadata / read_module / read_bytecode / search_code; edición — mediante archivos en dir (o set_help).

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

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

Los errores (archivo o directorio inexistente, tipo incorrecto) lanzan excepciones. El directorio no se elimina automáticamente después de repack; se puede reutilizar para varias compilaciones.

Esquema repack

repack ensambla a través de v8unpack.build(use_raw=True):

• el árbol organizado no se editó → la capa raw se restaura byte a byte (se conservan help, bytecode, módulos cifrados);

• el árbol organizado se editó → reensamblaje desde el árbol organizado.

Limitación (all-or-nothing): en una misma sesión se pueden aplicar ediciones del árbol organizado (código/formularios) o de la capa raw (help/bytecode), pero no ambas a la vez. La fusión por objeto es una tarea aparte.

Qué busca search_code

• .bsl — código fuente de los módulos;

• .json — encabezados de objetos, atributos y árbol de elementos de formularios;

• .txt / .html — plantillas de texto y HTML;

• .bin (СКД) — esquema de composición de datos: prefijo binario + XML con el texto de la consulta.

El parámetro layers limita las áreas de búsqueda: modules (.bsl), forms (.json), templates_text (.txt), templates_html (.html), dcc (.bin-СКД). Vacío = todas. Cada coincidencia contiene el campo layer.

No se busca (binario): .mxl (documento tabular), imágenes, roles (.c1brace), módulos cifrados. El parser MXL es una tarea de investigación aparte (ver .ai/).

Comparación (diff)

diff(dir_a, dir_b, full=true) compara dos directorios desempaquetados objeto por objeto:

• enumera los directorios de objetos (Тип/Имя para cf/cfe, raíz para epf/erf);

• reúne los archivos de cada objeto (sin el .id.json de servicio);

• estados: changed / added / removed / unchanged;

• para los modificados se genera un unified diff, recortado por límites (MAX_DIFF_LINES=400, MAX_DIFF_FILES=20);

• full=false — solo el hecho del cambio, sin construir el diff.

Related MCP server: 1C MCP Server

Arquitectura

• Núcleo de desempaquetado — saby v8unpack (Python, MIT). Vendored en src/v8unpack/ con parches locales (keep_raw/use_raw, detect_format para 8.3.24+, tolerancia a grupos de metadatos desconocidos).

• Wrapper propio — src/v8unpack_mcp: core.py (lógica), textlayers.py (extracción de capas de texto), server.py (servidor MCP).

• Desempaquetado — en un directorio temporal aparte %TEMP%\v8unpack_unpack_* en cada llamada a unpack; no hay caché común (el agente gestiona el ciclo de vida mediante cleanup).

• Para MCP desactivamos el multiprocessing de v8unpack (pool en serie) y silenciamos stdout/stderr para no romper el protocolo stdio; OrganizerFile.pack/unpack omiten .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

Instalación y ejecución

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

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

Conexión al cliente (MCP)

El servidor funciona por stdio: cada cliente lo lanza como un proceso separado con un único comando. Todas las herramientas aceptan rutas absolutas a los archivos, por lo que el directorio de trabajo del proceso no importa. Los directorios temporales de desempaquetado se crean en el %TEMP% del sistema con el prefijo v8unpack_unpack_.

El comando recomendado es el script de consola v8unpack-mcp (se crea con pip install) o python -m v8unpack_mcp. Para clientes GUI que no heredan tu PATH, es más seguro usar una ruta absoluta al intérprete.

Formato MCP estándar (command + args)

Claude Desktop, Claude Code, Cline, Continue, Roo, VS Code (.mcp.json) y otros usan un formato común con los campos command y args:

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

O con un intérprete explícito:

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

Dónde colocarlo:

• Claude Desktop — claude_desktop_config.json (Ajustes → Desarrollador → Edit Config);

• Claude Code — ~/.claude.json o el .mcp.json del proyecto;

• Cline / Continue / Roo — .mcp.json del proyecto (se comparte entre los participantes) o la configuración del usuario;

• VS Code — .vscode/mcp.json (para el servidor del proyecto) o la configuración de usuario.

Kilo Code / Kilo CLI (kilo.json, el comando es un arreglo)

El formato de Kilo es distinto: los servidores se definen en kilo.json bajo la clave "mcp", y el comando se pasa en un único arreglo (sin separar en command+args). El archivo es ./kilo.json / .kilo/kilo.json del proyecto, o el global ~/.config/kilo/kilo.json.

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

O mediante python -m:

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

El servidor se enciende/apaga en TUI con el comando /mcps. Un servidor heredado se puede desactivar: { "v8unpack": { "enabled": false } }.

Los permisos de las herramientas del servidor — mediante claves v8unpack_* (glob; se aplica la última coincidencia de arriba hacia abajo):

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

Recomendaciones para varios clientes

• Instalación: una vez con pip install -e . (para desarrollo) o pip install dist/v8unpack_mcp-0.2.0-py3-none-any.whl (desde el wheel construido); la dependencia v8unpack se instalará automáticamente desde pyproject.toml.

• Intérprete único: usa el comando de consola v8unpack-mcp (entra en el PATH de la instalación) o la misma ruta absoluta a python.exe en todas las configuraciones; así cualquier cliente usará la misma instalación.

• Clientes independientes: cada cliente mantiene su propio proceso stdio; el único estado compartido son los directorios temporales de desempaquetado en el disco. Puedes conectar el mismo servidor a varios clientes a la vez sin problema.

• Rutas con espacios/letras cirílicas: en las configuraciones JSON encierra las rutas entre comillas; en el arreglo command (Kilo) los elementos se escapan automáticamente.

• Inicio silencioso: el servidor silencia el progreso desempaquetado y solo usa stdio: no tienes que añadir salida interactiva en las configuraciones.

Construcción

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

Pruebas

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

Las pruebas usan archivos de ../testdata (archivos personales, no están en el registro git — coloca los tuyos).

Limitaciones

• .cf grandes (cientos de MB — GB): unpack hace una extracción completa en un directorio separado. Un índice por objeto (leer un objeto sin extracción completa) es el siguiente paso.

• Las plantillas tabulares (.mxl) todavía no se buscan — es un formato binario, el parser está en TODO.

• Módulos protegidos (cifrados): el código fuente no se puede recuperar sin contraseña, pero read_bytecode analiza el bytecode compilado, y decompiler.py puede descompilarlo a BSL (la herramienta decompile está planeada).

• Las ediciones del árbol organizado y de la capa raw (help/bytecode) en una misma sesión no se combinan (all-or-nothing de use_raw).

Componentes reutilizados

El proyecto reutiliza desarrollos abiertos de la comunidad:

saby v8unpack se incluye en el paquete como src/v8unpack/ (la licencia MIT está en src/v8unpack/LICENSE). decompiler.py es un port del algoritmo de 1C-inversion; bytecode.py usa el formato de v8asm.

⚠️ Aviso legal. Ver DISCLAIMER.md y LICENSE:

• El proyecto se distribuye bajo la licencia MIT «tal cual», sin garantías — usar bajo tu propio riesgo.

• La licencia de «1С:Предприятия 8» prohíbe modificar el código/datos del producto por medios no previstos y descompilar la parte de software del sistema. Esta restricción protege a la plataforma y las configuraciones estándar/típicas de 1C; no se aplica a las configuraciones propias, extensiones y procesos/informes externos — trabaja solo con tus propios objetos.

• La descompilación de módulos cerrados (protegidos por contraseña) se implementó con fines de investigación y no debe utilizarse para vulnerar o eliminar la protección de configuraciones ajenas (stказ. 146 del Código Penal de la Federación de Rusia). Usarlo solo para recuperar tus propios módulos.

Enlaces útiles

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

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

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

• Formato MXL8 (especificación): https://github.com/azubar/SpreadSheet/blob/main/docs/format-mxl.md