v8unpack-mcp

1C 바이너리 파일(.cf / .cfe / .epf / .erf)을 EDT 프로젝트로 가져오지 않고 전체 작업 주기를 처리하는 MCP 서버(stdio):

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 — diff 없이 변경 사실만.

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의 multiprocessing(직렬 풀)을 비활성화하고 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(빌드된 휠에서); 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