OpenDeviceDB

@opendevicedb/mcp

AI エージェント（Claude Code、Codex、Cursor、REA…）がデバイスをリバースエンジニアリングする前に OpenDeviceDB に問い合わせ、「すでに調査されていますか？　誰かが取り組んでいますか？」と確認し、作業後に結果を記録できる MCP サーバーです。Stdio トランスポートを使用し、公式の @modelcontextprotocol/sdk を利用します。

Node ≥ 22.18（ビルド手順なしで .ts ソースを直接実行します）と、ルートで npm install を実行済みのこのリポジトリのチェックアウトが必要です。

ツール

ツール	用途
lookup_device(id?, vendor?, model?, fcc_id?, usb?, ble_name?, zigbee_model?)	デバイスを1台確認します。完全なレコード、有効なステータス、現在の作業申告、1行の推奨事項を返し、情報がない場合はその旨を明示します
search_devices(query, category?, status?, limit?)	名前、別名、識別子を対象に、一致度順で検索して候補を調べます（該当する場合は最も簡単な install の難易度も表示します）
claim_device(id? | vendor+model, category?, who, contact, scope, days=30)	作業中であることを申告します（最長90日）。必要に応じて仮レコードを作成します
publish_findings(id, patch, allow_downgrade?, release_claim_of?)	検証済みの結果をレコードに統合します（ステータスは前進のみ、ポリシー審査あり）
request_device(vendor, model, fcc_id?, usb?, ble_name?, zigbee_model?, goal?)	ユーザーがデバイスを使いたいものの、自分ではリバースエンジニアリングしない場合に、既存のリクエストへの👍の追加方法、またはユーザー自身が送信する新しい公開 GitHub イシューの事前入力済みリンクを提示します（読み取り専用で、投稿は行いません）
list_sources()	ライセンス、スナップショットの日付、レコード数を含むインポート済みデータベースと、キュレーション済みレコード数を表示します

インストール方法。 レコードには、オープンなファームウェアやソフトウェアをデバイスに導入する方法を示す install を含められます（web-serial、ota-exploit、usb-bootloader、pairing などの方法、プロジェクト公式の guide と installer、difficulty、tools、opens_device、mains_powered、brick_risk、reversible／revert、firmware_constraints）。lookup_device は record.install にこれらを返し、推奨事項では公式ガイドを使って最も簡単な方法をユーザーに案内するようエージェントに伝えます（商用電源で動作するデバイスを開ける必要がある場合、手順を一つずつ案内することはありません）。search_devices は最も簡単な difficulty を install として返します。publish_findings は patch.install のインストール方法を受け付け、方法とガイドをキーとして統合します。ここでファームウェアの書き込みやホスティングは行いません。

書き込み先は、ローカルのチェックアウト内にある data/devices/<vendor>/<model>.yaml です。サーバーは git を実行しません。各書き込み結果には変更されたファイル名と、次の手順（git checkout -b … && git add … && git commit … && gh pr create --fill）が示されます。

バックエンド（環境変数）

変数	動作
ODB_REPO=/path/to/opendevicedb	ローカルチェックアウトを使用します。キュレーション済みレコードとインポート済みレコードを読み取り、書き込みが可能です
ODB_API_URL=https://…	読み取り専用です。サイトの静的 API（/api/index.json、/api/devices/<id>.json）を使い、10分間キャッシュします。claim／publish は ODB_REPO を指定するよう求めるエラーを返します
どちらも未設定	このパッケージが置かれているチェックアウトを使用します（ODB_REPO にそのパスを指定した場合と同じです）

両方を設定した場合は、ODB_REPO が優先されます。

登録

/path/to/opendevicedb をご自身のチェックアウトのパスに置き換えてください。

Claude Code

claude mcp add opendevicedb -e ODB_REPO=/path/to/opendevicedb -- node /path/to/opendevicedb/packages/mcp/src/server.ts

（すべてのプロジェクトで使うには --scope user を指定します。）

Codex（~/.codex/config.toml、または codex mcp add opendevicedb -- node …/server.ts）

[mcp_servers.opendevicedb]
command = "node"
args = ["/path/to/opendevicedb/packages/mcp/src/server.ts"]
env = { ODB_REPO = "/path/to/opendevicedb" }

Cursor（プロジェクト内の .cursor/mcp.json、または ~/.cursor/mcp.json）

{
  "mcpServers": {
    "opendevicedb": {
      "command": "node",
      "args": ["/path/to/opendevicedb/packages/mcp/src/server.ts"],
      "env": { "ODB_REPO": "/path/to/opendevicedb" }
    }
  }
}

ご自身のデータのチェックアウトなしで読み取り専用として使う場合は、ODB_REPO の代わりにサイトのベース URL を ODB_API_URL に設定してください。

エージェントのワークフロー

1. lookup — ラベルに記載されている情報（FCC ID、lsusb の USB vid:pid、BLE 名）、またはベンダーとモデルを指定して lookup_device を実行します。推奨事項に従ってください。オープンファームウェアや SDK がある場合はそれを使用し、現在対応中の人がいる場合はその人に連絡します。 何もわからず、ユーザーがデバイスを登録したいだけの場合は、リクエストリンク（検索結果の request／request_url、または request_device）を案内して、関心が記録されるようにします。
2. claim — 情報がない（または一部しかない）場合は、作業を始める前に担当者／連絡先／対象範囲を指定して claim_device を実行します。その後、ファイルをコミットして PR を作成し、他の人にも担当がわかるようにします。
3. work — リバースエンジニアリングを行います。Remote ID、ジオフェンシング、その他の安全機能には絶対に触れないでください。ファームウェアイメージやベンダーコードをコピーしてはいけません（POLICY.md）。
4. publish — 概要、ステータス、インターフェース（プロトコルのドキュメントを spec としてリンク）、プロジェクト（他の場所でホストされている自分のコード）、インストール方法、検証情報、provenance.ai_assisted を指定して publish_findings を実行します。担当を終了するには release_claim_of を渡します。
5. PR — 結果に含まれる git／gh pr create コマンドを実行します。メンテナーがレビューします。

SKILL.md は同じワークフローをエージェントスキルとしてまとめたもので、スキルディレクトリにそのまま配置するか、別のツールに埋め込めます。

CLI

同じ環境変数を使い、シェルから同じ関数を実行して、ツールの結果を JSON として出力します。

node src/cli.ts lookup --vendor DJI --model "Neo 2"
node src/cli.ts lookup --usb 2ca3:001f
node src/cli.ts search tello --category drone
node src/cli.ts claim --vendor Acme --model "X1" --category toy --who alice --contact @alice --scope "BLE control" --days 30
node src/cli.ts publish acme/x1 --patch '{"status":"partial-protocol","summary":"…"}'   # or --patch-file findings.json
node src/cli.ts sources

開発

npm test -w @opendevicedb/mcp   # node:test; uses temporary fake repositories, plus a stdio end-to-end test
npm run mcp                     # from the repo root: start the server on stdio

コード：AGPL-3.0-or-later（リポジトリの LICENSE を参照）。SKILL.md のみ CC0-1.0 で、他のツールに埋め込めます。