v8unpack-mcp

MCPサーバー (stdio) は、1С のバイナリファイル (.cf / .cfe / .epf / .erf) を 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): 1回のセッションでは、整理されたレイヤー (コード/フォーム) の編集か、raw レイヤー (help/バイトコード) の編集のどちらか一方のみで、両方はできません。オブジェクト単位のマージは別タスクです。

search_code で検索されるもの

• .bsl — モジュールのソースコード;

• .json — オブジェクトのヘッダー、属性、フォーム要素ツリー;

• .txt / .html — テキストおよび HTML レイアウト;

• .bin (СКД) — データ構成スキーマ: バイナリプレフィックス + クエリテキストを含む XML。

layers パラメータで検索範囲を制限できます: modules (.bsl)、forms (.json)、templates_text (.txt)、templates_html (.html)、dcc (.bin-СКД)。空 = すべて。各一致には layer フィールドが含まれます。

検索されないもの (バイナリ): .mxl (表計算ドキュメント)、画像、ロール (.c1brace)、暗号化モジュール。MXL パーサーは別のリサーチタスクです (.ai/ 参照)。

比較 (diff)

diff(dir_a, dir_b, full=true) は展開済みの2つのディレクトリをオブジェクト単位で比較します:

• オブジェクトのディレクトリを列挙します (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 を無効にし (シリアルプール)、stdio プロトコルを 壊さないよう stdout/stderr を抑制します。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 (設定 → 開発者 → Edit Config);

• 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" キーで指定し、コマンドは1つの配列として渡します (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 は個別のディレクトリへの完全な展開を行います。オブジェクト単位のインデックス (完全な展開なしで1つのオブジェクトを読む) は次のステップです。

• 表形式レイアウト (.mxl) はまだ検索対象外です — バイナリ形式のため、パーサーは TODO です。

• 保護 (暗号化) されたモジュール: パスワードなしではソースを復元できませんが、read_bytecode がコンパイル済みバイトコードを解析し、decompiler.py がそれを BSL にデコンパイルできます (decompile ツールは計画中)。

• 整理されたレイヤーと raw レイヤー (help/バイトコード) の編集は、1回のセッションではマージされません (all-or-nothing の use_raw)。

借用コンポーネント

プロジェクトはコミュニティのオープンソース成果を再利用しています:

saby v8unpack は src/v8unpack/ としてパッケージに含まれています (MIT ライセンスは src/v8unpack/LICENSE に保持されています)。decompiler.py は 1C-inversion のアルゴリズムの移植です。bytecode.py は v8asm の形式を使用しています。

⚠️ 法的注意事項。 DISCLAIMER.md と LICENSE を参照してください:

• 本プロジェクトは MIT ライセンスの下で「現状のまま」、保証なしで配布されます。使用は自己責任です。

• 「1С:Предприятия 8」のライセンスは、非標準的な手段による製品のコード/データの変更と、システムのソフトウェア部分の逆コンパイルを禁止しています。この制限は、プラットフォームと 1С の標準構成を保護するものです。独自の構成、拡張、外部処理/レポートには適用されません — 自分のオブジェクトに対してのみ作業してください。

• クローズド (パスワード保護された) モジュールの逆コンパイルは研究目的で実装されており、他人の構成をクラッキングしたり保護を解除したりするために使用してはなりません (ロシア連邦刑法第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