ESP32-S3 ハードウェア知識MCPサーバー

ESP32-S3 の PIE（Processor Instruction Extensions, EE.* 命令）・レジスタ特性・パフォーマンス チューニングに関する知識を、MCP（Model Context Protocol）経由でエージェントに提供するための サーバー。回答は推測ではなく Espressif 公式PDFのページ番号付き引用で返すことを設計の前提にする。

公開: https://github.com/dj-oyu/esp32s3-hw-mcp

動かし方（uvx：クローン不要）

uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp          # MCP（stdio）として起動
uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --list   # ツール面を人向けに表示
uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --paths  # どの写しの知識が答えたか

抽出済みの知識（data/）は wheel に同梱されるので、クローンも PDF も追加設定も無しに 18 ツール中 12 ツールがそのまま答える （符号化を確かめる4つは Espressif の binutils が、本文検索の2つは下記のコーパスが要る。無い環境では「無い」と理由を返す）。

マニュアル本文のページ検索（search_manual / get_page）だけは本文を再配布できないため、初回に一度だけ:

uvx --with pymupdf --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --fetch-corpus

sha256 を検証して PDF を取得し（16MB）、~/.cache/esp32s3-hw-mcp/ にTRM 1531ページ＋Datasheet 87ページの コーパスを作る。以後は同じ uvx 起動がそこを見つけるので、環境変数は要らない。

MCP クライアントへの登録（クライアントの流儀に従う。hermes mcp add は有効化するツールを対話で聞く）:

claude mcp add esp32s3-hw -- uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp
hermes mcp add esp32s3-hw --command uvx --args --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp

{ "mcpServers": { "esp32s3-hw": { "command": "uvx",
  "args": ["--from", "git+https://github.com/dj-oyu/esp32s3-hw-mcp", "esp32s3-hw-mcp"] } } }

短い別名 esp32-hw-mcp も同じサーバーを起動する（どちらの名前も同じ main を指す）。

Related MCP server: SheetsData MCP

公開・ライセンス方針

• ライセンスは付与しない（All rights reserved）。 事実の出所が Espressif Systems の著作物である 派生データを含むため、明示的な利用許諾は与えない立場を取る。詳細は NOTICE.md。

• 公式PDFは同梱しない（git 管理外）。tools/fetch_sources.sh が配布元から取得し sha256 で検証する。

• 抽出データには常に出所（文書・版・ページ）を持たせる。ページを出せない値はデータに入れない。

• CI（.github/workflows/verify.yml）が一次情報を再取得して全派生ファイルを再生成し、 コミット済みの data/ とバイト一致することを要求する。抽出の静かな変化・上流の改版はここで落ちる。

• CI はさらに wheel を組んで配布物を検査する（tools/check_wheel.py。レジストリが「同梱する」と宣言した 成果物が実際に入っているか、件数・entry point・登録ツールの実体まで）、素の環境にインストールした同じ サーバーを stdio 越しの E2E 88項目に通す。同梱物が1つ欠けてもツールは起動してしまい、何も無いところから 答えるので、そこを門にしている。

• .github/workflows/uvx.yml が公開経路そのものを検査する: uvx --from <repo> で起動してツール一覧を 読み戻す（テキストの --list と、MCP クライアントとしての initialize → tools/list → 各ツール呼び出しの 両方）。検査対象はそのコミット（パス指定と git+file://）と、PR 以外では公開 main の git+https://github.com/dj-oyu/esp32s3-hw-mcp。ツール一覧の期待値は esp32s3_hw_mcp/registry.py から 読むので、索引と実装が食い違えば落ちる（tools/check_uvx.py）。

一次情報ポリシー

• 収録する事実は Espressif 公式ドキュメントのみ。本リポジトリは PDF を再配布せず、 tools/fetch_sources.sh で取得し sha256 をピン留めして検証する。

• 一次情報の格は3段階で管理し、回答に必ず出所を添える。

  1. PDF（一次）: TRM / Datasheet。ページ番号で引用する。

  2. 公式HTML（準一次）: errata、チップリビジョン、ESP-IDF の cache/perf 記述。現状未収録。

  3. SDKソース（突き合わせ用）: ESP-IDF の soc/esp32s3/include/soc/*_reg.h。現状未収録。

• 抽出値には source_page を必ず持たせる。ページを出せない値はデータに入れない。

収録済みの一次情報（M0時点）

• どちらも 印字ページ＝PDFページ（tools/build_corpus.py がビルド時に検査）。引用のオフセット計算は不要。

• Xtensa 基本ISA のリファレンスマニュアルは Espressif 配布のPDFが存在しない。 documentation.espressif.com/*.pdf の未知URLは HTTP 200 で SPA の HTML（約13KB）を返すため、 存在確認はステータスコードでは不可。サイズと sha256 で判定すること。 → 基本ISA（パイプライン段の一般論、命令スケジューリング、hwloop 等）は PDF では裏が取れない。 TRM 1.7 に書かれている範囲だけを一次情報として扱う。

知識レジストリ（data/ とルート）

集めた知識は「成果物 → 層 → それを提供するツール/リソース → 生成元 → 門」の1枚の表で管理している （実体は esp32s3_hw_mcp/registry.py の ARTIFACTS。表と実装が食い違えば CI が落ちる）。 規模は表の数字ではなく、サーバーがその場でファイルを開いて数えた値を knowledge_routes が返す。

pie_pipeline.json が本プロジェクトの中核データで、これがあると 「この命令列は何サイクルストールするか」を決定論的に計算できる（LLMの推定に頼らない）。

ルートの解決（どの写しが答えるか）

同じ知識が「wheel の中」「クローンの data/」「環境変数が指す先」にあり得るので、順番と根拠を1か所に決めている （esp32s3_hw_mcp/registry.py）。最初に見つかったものが勝ち、探索の履歴ごと報告する:

1. ESP32S3_DATA_DIR（ESP32S3_CORPUS_DIR / ESP32S3_SOURCES_DIR / ESP32S3_POCKETJS_DOC も同様）— 明示指定が最優先。

2. wheel 同梱の写し（uvx --from git+… の既定）。

3. クローンの data/（python server/esp32s3_mcp.py のとき）。

4. ~/.cache/esp32s3-hw-mcp/（--fetch-corpus が作った PDF とコーパス。ESP32S3_CACHE_DIR で変更可）。

esp32s3-hw-mcp --paths       # どのルートがどこに解決したか（探索履歴つき）＋成果物の有無
esp32s3-hw-mcp --registry    # レジストリ全体を JSON で（MCP の knowledge_routes と同じ内容）

MCP 経由では knowledge_routes（ツール）と esp32s3://registry（リソース）が同じ索引を返す。 索引には「どの写しから答えたか」「何件あったか」が入るので、corpus_missing や no_measurements のような 返事が出たときに、ルートとインストールのどちらが悪いのかを切り分けられる。必須の成果物が1つでも欠けていれば、 サーバーは黙って空を返さず起動を拒否する（--paths が原因を出す）。

アセンブラ照合（マニュアルの読み取りは信用しない）

TRM の命令語はビットフィールド図で書かれており、これを目で読むと1ビットの取り違えが 「それらしい別の命令」として通ってしまう。そこでファームを実際にビルドするのと同じ Espressif binutils に答えさせ、図から再構成した命令語と突き合わせる（tools/asm_toolchain.py）。

.venv/bin/python tools/asm_toolchain.py --check-asm "ld.qr q0, a3, 0"   # 符号化をアセンブラに答えさせる
.venv/bin/python tools/asm_toolchain.py --decode cd2034                 # 命令語 → ニーモニック
.venv/bin/python tools/asm_toolchain.py --check-instruction EE.ANDQ     # 図 vs アセンブラ
.venv/bin/python tools/asm_toolchain.py --check-all                     # 全220命令
.venv/bin/python tools/asm_toolchain.py --errata data/pie_encoding_errata.json
.venv/bin/python tools/selftest_asm_toolchain.py                        # 門の自己検査（ツールチェーンが無ければ skip）

結果は 220命令中 214命令がビット単位で一致。残り6件が不一致で、それが成果物 （data/pie_encoding_errata.json、詳細と解釈は notes/06-encoding-verification.md）:

即値の「刻み」はマニュアルの範囲幅とフィールド幅から出る（LD.QR の -128..112 ÷ 4ビット = 16刻み、 -128 は −8 の2の補数で 1000）。この規則もアセンブラ出力と突き合わせて検証している。

検証

.venv/bin/python tools/verify_pie.py        # PIE:  0 failure / 2 warning で緑
.venv/bin/python tools/verify_registers.py  # レジスタ: 0 failure / 0 warning で緑（pypdfとの突き合わせで数分）

再現性の門: tools/extract_pie.py を流し直した結果が data/ と一致すること（CI でも検査している）。

.venv/bin/python tools/extract_pie.py && git diff --exit-code -- data/

6つの検査を、抽出器とは独立の情報源（1.8 のアセンブラ構文、Table 1.7-1 の段番号、印字ページの目視、 コーパス統計）で行う。片方の抽出器だけを信じない方針で、表のセルは pypdf と PyMuPDF の 両方で取り、両者が一致することを確認済み。

既知の限界（レジスタ側）

1. I2S 章はアドレス列を2本（I2S0 / I2S1）持つ（p1059 のヘッダは "I2S0 Ad-" + "dress" にハイフネーション される）。抽出は左の列を採用しており、両インスタンスでオフセットが一致することを前提にしている。

2. RNG 章はオフセットでなく絶対アドレス（0x6003_507C）を印字する。address_is_absolute: true を 付けて区別してある。オフセットとして解釈してはならない。

3. メモリブロック表（20.4, p878）はレジスタ表ではないため収録しない（"Starting/Ending Address" を 持つヘッダを弾いている）。

4. 抽出したのは Register Summary 表のみ。各レジスタのフィールド（ビット範囲）は図版 （ビットマップ図）に描かれており、テキスト層には説明文しかない。フィールドの抽出は次の段階で、 図形の座標からビット範囲を復元するか、ESP-IDF の soc/*_reg.h と突き合わせる必要がある。

5. オフセットの一意性検査は「同一節かつ同一レジスタファミリ（先頭トークン）」に限定している。章をまたいで 同じ番地に別ペリフェラルのレジスタが並ぶのは正常（別ベースアドレス）。

既知の限界（PIE側）

1. LD.QR / ST.QR / MV.QR（p301-303）は Table 1.7-2 に載っていない。ハザード段の情報が 一次情報に存在しないので、これら3命令のスケジューリングは「未検証」として扱う。

2. EE.BITREV は表と構文が食い違う。Table 1.7-2 は use=ax、1.8 のアセンブラ構文は qa, as （p66 と p77、両抽出器で同じ）。どちらが正かは一次情報では決まらない → 手当てで確定する。

3. EE.FFT.AMS.S16.ST.INCP は表が as0 を挙げるが構文には as しかない。添字付き サブレジスタ（as0/as1, qz1, fu0〜）の扱いは未整理。

4. EE.VMULAS.S8.QACC.LD.IP（p228）に Description 節が無い（マニュアル側の欠落）。

5. Table 1.7-2 のセルは PDFのテキスト層でスペースが落ちる（qv2,as01,as1, = "qv 2, as0 1, as 1"）。 パーサは貪欲マッチで復元し、復元できなかった残りは raw として残す（黙って切り捨てない）。

ディレクトリ

sources/          取得したPDF（git管理外。tools/fetch_sources.sh で再取得）
corpus/           ページ単位JSONL＋ブックマーク（git管理外。tools/build_corpus.py で再生成）
data/             抽出済み知識（git管理。wheel に同梱され、MCPサーバーが読む）
esp32s3_hw_mcp/   配布するパッケージ（レジストリ＝ルート索引、wheel に同梱されるサーバー/橋/生成器）
examples/         PIE実用サンプル（手書きアセンブリ＋自己採点。examples/README.md）
experiments/      実機実験（段・ハザードの測定、flash退避）
server/           サーバー本体（wheel では esp32s3_hw_mcp/server.py として入る）
tools/            取得・コーパス・抽出・検証・ビルド・実機実行のスクリプト
notes/            調査メモ（08 に Cardputer ADV のメディア/3D 性能の物差しと量産リスト）
pyproject.toml    配布の宣言（依存・entry point・wheel に入れるもの）。tools/check_wheel.py が検査する

PIE 実用サンプル（examples/）

data/ の知識だけを使って書いた手書き PIE アセンブリの例題集。どの例も「手書き asm / ファーム内 C 参照 / ホスト側 Python 参照」の三重で答え合わせをし、マニュアルとアセンブラが食い違う箇所はどちらの文書に シリコンが従ったかを判定して出す。詳細と例題一覧は examples/README.md。

bash tools/build_examples.sh                                        # ビルド
bash tools/host_flash_and_log.sh --examples                         # 焼く＋ログ＋自動判定（ホスト側）
.venv/bin/python tools/check_examples_log.py /workspace/backups/pie-examples-<stamp>.log
.venv/bin/python tools/selftest_examples_checker.py                 # チェッカー自身の検査

第1回ラン（pie-examples-20260914T174138Z.log）で ex01/ex02/ex04/ex05 と ex06 の測定済みレーンは一致し、 失敗した2件はどちらもこちら側の思い違いが原因と判明した（ex03 は 2 バイトずつ滑らせた窓が 8サンプル連続で同じ16バイトを読んでいた＝TRM p49 の丸めを実機が実演、ex06 は sel2=1 のフィールド並びが MSB 先だった）。詳細は examples/README.md と data/pie_examples_measured.json。

使い方（クローンして開発・抽出・実機検証する場合）

上の uvx 経路が利用者の既定で、こちらは抽出を作り直す／検証する／実機で測るための経路。

uv sync --extra dev                                           # 依存（pypdf / pymupdf / mcp）
bash tools/fetch_sources.sh                                   # PDF取得＋sha256検証
.venv/bin/python tools/build_corpus.py sources/esp32-s3_technical_reference_manual_en.pdf --out corpus/trm-s3
.venv/bin/python tools/extract_pie.py                         # data/*.json を生成
.venv/bin/python tools/verify_pie.py                          # 検証（緑になること）

uv を使わない場合は python3 -m venv .venv && .venv/bin/pip install -r requirements.txt で同じ。

コーパスへの問い合わせは skill 付属の tools/pdf_corpus.py（toc / find / text / grep）が使える。

MCPサーバー（server/esp32s3_mcp.py / パッケージ名 esp32s3_hw_mcp）

uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp              # 利用者（uvx）
uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --list       # ツール面
uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --paths      # ルートの解決結果
uvx --with pymupdf --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp --fetch-corpus

.venv/bin/python server/esp32s3_mcp.py                                              # 同じサーバー（クローンから）
.venv/bin/python tools/test_mcp_server.py                                            # stdio越しに88項目のE2E
.venv/bin/python tools/verify_measured_costs.py                                      # ④層のデータと出典文書の突き合わせ
uv build --wheel && .venv/bin/python tools/check_wheel.py dist/*.whl                 # 配布物の門（中身・件数・entry point・ツール面）

実装済みツール（18ツール）。4つの層を混ぜない: ①一次情報（PDF）は必ず文書・版・印字ページを添える、 ②ツールチェーン（アセンブラ）は「実際に何に符号化されるか」を答える、③実機の計測（段・ストール）は測った値と その有効性検査の結果を返す、④実機の意味とコストは測定条件と一緒に返す。④には2種類あり、 このリポジトリで測ったもの（data/pie_examples_measured.json、data/pie_timing_measured.json）と 兄弟プロジェクト cardputer-adv-pocketjs で測られたもの（data/pie_measured_costs.json）を provenance.measured_in_this_repository で必ず区別する。両者を混ぜたり平均したりしない。

リソース（5つ）: esp32s3://registry（上記レジストリの索引そのもの）、esp32s3://trm/pie-hazards（1.7 の原文）、 esp32s3://trm/review（マニュアル自身が食い違う行）、esp32s3://docs/sources（出所とsha256。兄弟プロジェクトの 文書は一次情報と別枠で digest 付きに列挙）、esp32s3://pocketjs/pie-costs（④層のデータ本体）。

設計上の約束:

• マニュアルに書かれていないことは**「無い」と言う**。例: LD.QR のハザード段は Table 1.7-2 に無いので 推定せず absent を返す。フィールドのビット範囲も未抽出なので返さない。

• 推定値（レジスタのベースアドレス）は confidence: heuristic と候補列を付けて返す。

• 応答に必ず citation（文書名・版・ページ・sha256）を付ける。

• マニュアルの図と実際のアセンブラ出力が違うときは、両方をそのまま返す（どちらが正かを勝手に決めない）。 その一覧が manual_errata。

ストール見積りの中身（analyze_sequence）

• 規則: D = max(SA - SB + 1, 0)（SA=書く段, SB=読む段）／インターロックは D - 1 = max(SA - SB, 0)。

• マニュアル自身の矛盾を記録: p65 の計算例は SA=W を 2 として D=max(2-1+1,0)=2 と書くが、 Table 1.7-1 は W=3。ただし Table 1.7-2 は use/def とも 1(E)/2(M) しか使わず W は現れないため、 表から駆動する計算には波及しない（応答の rule.manual_inconsistency にも明記して返す）。

• 表から導かれる「1ストールを生みうるレジスタ」は ACCX / QACC_H / QACC_L / UA_STATE / as0 / qs の6つ。

• ハードウェア資源ハザード（1.7.2）と制御ハザード（1.7.3）は表から計算できないので計算せず、根拠ページ付きで 「未モデル」として返す。

予定している MCP のサーフェス（未実装分の設計案）

上の表にあるものは実装済み。ここに残るのは未実装の設計案だけ（すべて回答に TRM/Datasheet のページを付ける）:

• list_instructions(class?) — 1.6 の分類（Read/Write/DataExchange/Arithmetic/Comparison/…）で絞る

• get_section(ref) — 節単位の取得（現状は search_manual + get_page）

• get_field(reg, field) — レジスタのビット範囲。一次情報では図版に描かれているため、図形座標からの 復元か ESP-IDF soc/*_reg.h との突き合わせが要る（未実装）

• memory_map() / clock_tree() — Ch.4 (p400-409) / Ch.7 (p526-533)

• perf_checklist(topic) — チューニング項目の整理（根拠ページ付き）

リソースとして TRM のページとセクションを trm://page/65 のように公開し、プロンプトで 「PIEで書かれたカーネルのストール解析」を定型化する。

決定事項（2026-09-14、ユーザー判断）

1. 実装言語: Python 一本。uv / uvx で動かせることを必須要件とする。 pyproject.toml に [project.scripts] と依存を宣言し、uvx --from <path|repo> esp32s3-hw-mcp で起動できる形にする（uv run も同じ宣言から動く）。python3 -m venv の手順は補助に落とす。 → 実装済み（2026-09-15）: pyproject.toml（hatchling）＋ esp32s3_hw_mcp/ パッケージ。 uvx --from git+https://github.com/dj-oyu/esp32s3-hw-mcp esp32s3-hw-mcp が最短経路で、知識は wheel に 同梱。uvx からは取れない成果物（PDF・コーパス）は --fetch-corpus が ~/.cache/esp32s3-hw-mcp に作る。

2. 知識の持ち方: 構造化KB＋ページ全文検索（ベクトルRAG・埋め込みは入れない）。 値（オフセット・段数・ハザード・集約）は構造化データから、記述はページ全文検索から引く。 どちらの経路でも回答に文書名・版・ページを付ける。

3. 収録範囲: PDF中核（TRM/Datasheet）＋ SDK突き合わせ。 ESP-IDF の soc/esp32s3/include/soc/*_reg.h 等を照合専用データとして収録し、 PDF の値との一致・不一致の両方を返せるようにする（PDFを一次、SDKは突き合わせ用と区別する）。 公式HTML（errata 等）は補助で、PDFと同格には扱わない。

4. リポジトリ: GitHub public（dj-oyu/esp32s3-hw-mcp、現行のまま）。 著作権の免責（出所は Espressif 著作物、非公式、PDF非同梱、引用は技術仕様を伝えるのに必要な 最小限）を NOTICE.md に明記する。MCP の応答にも免責と出所を必ず載せる。