PCILeech用MCPサーバー

English

DMAベースのメモリオペレーションのためにPCILeechへの標準化されたインターフェースを提供するModel Context Protocol (MCP) サーバーです。これにより、MCPクライアント（例：Claude Code）がツール呼び出しを通じてメモリ/デバッグワークフローを実行できるようになります。

著者: EVAN & MOER サポート: Discordに参加

機能

19個のMCPツール（機能別にグループ化）:
- コアメモリ: memory_read, memory_write, memory_format
- システム: system_info, memory_probe, memory_dump, memory_search, memory_patch, process_list
- アドレス変換: translate_phys2virt, translate_virt2phys, process_virt2phys
- カーネルモジュール (KMD): kmd_load, kmd_exit, kmd_execute, kmd_list_scripts_list
- 高度な機能/FPGA: benchmark, tlp_send, fpga_config
仮想アドレスモード: メモリツールは pid または process_name をサポート（相互排他）
ノンブロッキングサーバー: PCILeechの呼び出しは asyncio.to_thread を介して実行されます
出力ヘルパー: 分析用のhexdump + ASCII + バイト/DWORDビュー

前提条件

Windows 10/11 (x64)
Python 3.10+
PCILeechハードウェア（適切に構成され動作していること）
PCILeechバイナリ (pcileech/ 配下にバンドル)

クイックスタート

1. クローン

git clone https://github.com/Evan7198/mcp_server_pcileech
cd mcp_server_pcileech
// download release in https://github.com/ufrisk/pcileech for using the latest pcileech

2. 依存関係のインストール

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

MCPのインポートやバージョンに関する問題が発生した場合は、代わりに pyproject.toml からインストールしてください:

pip install -e .

3. PCILeechの検証

cd pcileech
pcileech.exe probe

4. Claude Code (MCP) の設定

サーバーエントリを追加します（パスは適宜調整してください）:

"mcpServers": {
  "pcileech": {
    "command": "C:\\path\\to\\mcp_server_pcileech\\.venv\\Scripts\\python.exe",
    "args": [
      "C:\\path\\to\\mcp_server_pcileech\\main.py"
    ],
    "cwd": "C:\\path\\to\\mcp_server_pcileech",
    "env": {}
  }
}

MCP設定を編集した後、Claude Codeを再起動してください。

設定

config.json でPCILeechの実行可能パスとタイムアウトを制御します:

{
  "pcileech": {
    "executable_path": "pcileech\\pcileech.exe",
    "timeout_seconds": 30
  },
  "server": {
    "name": "mcp-server-pcileech",
    "version": "1.0.0"
  }
}

使用例

設定が完了すると、自然言語でアクションを要求できます。クライアントがそれをツール呼び出しに変換します:

Read 256 bytes from address 0x1000

Write the hex data 48656c6c6f to address 0x2000

Show me a formatted view of 64 bytes at address 0x1000

MCPツール（概要）

注意:

仮想メモリモード: メモリツールでは pid または process_name を使用してください（両方は不可）。
FPGA専用: 一部の操作（memory_probe, tlp_send など）にはFPGAベースのデバイスが必要です。

コアメモリ

memory_read(address, length, pid?, process_name?) → 16進データ + メタデータ
memory_write(address, data, pid?, process_name?) → 成功/確認
memory_format(address, length, formats?, pid?, process_name?) → hexdump/ASCII/配列/raw

システム

system_info(verbose?) → ターゲットシステム + デバイス情報
memory_probe(min_address?, max_address?) → 読み取り可能な領域 (FPGA専用)
memory_dump(min_address, max_address, output_file?, force?) → ダンプファイルのパス/結果
memory_search(pattern? | signature?, min_address?, max_address?, find_all?) → 一致箇所
memory_patch(signature, min_address?, max_address?, patch_all?) → パッチ適用結果
process_list() → PID/PPID/名前リスト

アドレス変換

translate_phys2virt(physical_address, cr3) → 変換詳細
translate_virt2phys(virtual_address, cr3) → 変換詳細
process_virt2phys(pid, virtual_address) → 変換詳細

カーネルモジュール (KMD)

kmd_load(kmd_type, use_pt?, cr3?) → ロード結果（KMDアドレスをキャッシュ）
kmd_exit(kmd_address?) → アンロード結果（省略時はキャッシュされたアドレスを使用）
kmd_execute(script_name, kmd_address?, input_file?, output_file?, parameter_string?, parameter_int0?, parameter_int1?)
kmd_list_scripts(platform?) → プラットフォーム別にグループ化された利用可能な .ksh スクリプト

高度な機能 / FPGA

benchmark(test_type?, address?) → MB/sの結果（ハードウェアに依存）
tlp_send(tlp_data?, wait_seconds?, verbose?) → 送信/受信されたTLP (FPGA専用)
fpga_config(action?, address?, data?, output_file?) → 設定の読み取り/書き込み (FPGA専用)

アーキテクチャ

2層設計

MCPサーバー層 (main.py)
- Stdioトランスポート、ツールスキーマ、検証、フォーマット
- イベントループをブロックしないように asyncio.to_thread() を使用
PCILeechラッパー (pcileech_wrapper.py)
- pcileech.exe へのサブプロセス呼び出し
- アドレスアライメント + 256バイト単位のチャンク処理 (PCILeechの display 動作)
- 出力解析、タイムアウト、エラーマッピング

トラブルシューティング

PCILeechが見つからない

エラー: PCILeech executable not found 修正: config.json → pcileech.executable_path を確認してください

ハードウェアが接続されていない

警告: PCILeech connection verification failed 修正: pcileech\pcileech.exe probe を実行し、ドライバーとケーブル接続を検証してください

メモリアクセス失敗

エラー: Memory read/write failed 修正: まずCLIでアドレス/範囲を検証してから、MCP経由で再試行してください

タイムアウト

エラー: PCILeech command timed out 修正: config.json の pcileech.timeout_seconds を増やしてください

プロジェクト構造

mcp_server_pcileech/
├── main.py
├── pcileech_wrapper.py
├── config.json
├── pyproject.toml
├── requirements.txt
├── README.md
├── README_CN.md
└── pcileech/
    ├── pcileech.exe
    └── LICENSE.txt

制限事項

Windowsのみ (このリポジトリのPCILeechはWindowsに特化しています)
実際のメモリオペレーションには互換性のあるPCILeechハードウェアが必要です
読み取りサイズの制限:
- memory_read: 最大1MB
- memory_format: 最大4KB (読み取り可能な出力)
一部のツールは FPGA専用 です (probe/TLP/config)
PCILeechコマンドは順次実行されます (サブプロセス呼び出しごと)

セキュリティと法的注意

このツールは、許可されたデバッグ、セキュリティ研究、教育を目的としています。不正アクセスや悪意のある活動には使用しないでください。適用される法律および規制を遵守する責任はユーザーにあります。

ライセンス

このプロジェクトはPCILeechをラップしており、PCILeechには独自のライセンスがあります。pcileech/LICENSE.txt を参照してください。

クレジット

PCILeech: Ulf Frisk
Model Context Protocol: Anthropic
著者: EVAN & MOER

バージョン

このリポジトリのツールセットには、現在19個のツールが含まれています。パッケージ/設定のバージョンについては以下を参照してください:

pyproject.toml ([project].version)
config.json (server.version)

サポート

Discord: Discordに参加
Issues: このリポジトリでIssueを開いてください
PCILeechドキュメント: PCILeech GitHub
MCPドキュメント: MCP Documentation

変更履歴

v1.0.0 (2025-12-16)

PCILeechの全機能をカバーする19個のMCPツールに拡張
メモリツールに仮想アドレスモード (pid / process_name) を追加
アドレス変換、KMD、FPGA/高度なツールを追加
検証とエラー処理を強化。ノンブロッキングサーバー実行

v0.1.0 (2025-12-10)

初回リリース
3つのMCPツール: memory_read, memory_write, memory_format

PCILeech MCP Server