OpenDeviceDB

@opendevicedb/mcp

MCP 服务，让 AI Agent（Claude Code、Codex、Cursor、REA…）在对设备进行逆向工程之前询问 OpenDeviceDB——“这项工作已经有人做过了吗？有人正在做吗？”——并在完成之后记录成果。使用 Stdio 传输，官方 @modelcontextprotocol/sdk。

需要 Node ≥ 22.18（直接运行 .ts 源文件，无需构建步骤），并且已在此仓库根目录运行 npm install。

工具

工具	用途
lookup_device(id?, vendor?, model?, fcc_id?, usb?, ble_name?, zigbee_model?)	查询单个设备：完整记录、有效状态、当前认领情况以及一行建议；明确说明是否没有相关信息
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 issue 链接，由用户自行提交（只读，绝不代为发布）
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 中返回这些信息，并建议 Agent 使用官方指南，引导用户采用最简单的途径（如果必须打开市电设备，绝不提供逐步操作说明）；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_API_URL 设置为网站的基础 URL，而不是设置 ODB_REPO。

Agent 工作流

1. 查找 — 使用标签上的信息调用 lookup_device（FCC ID、lsusb 显示的 USB vid:pid、BLE 名称），或使用厂商 + 型号。遵循建议：如果有开放固件或 SDK，就使用它；如果有人持有有效认领，请联系对方。 如果没有任何已知信息，而用户只是想让设备出现在目录中？向他们提供请求链接（查找结果中的 request / request_url，或 request_device），以便记录这份兴趣。
2. 认领 — 没有已知信息（或信息不完整）？开始前，使用 claim_device 填写认领人、联系方式和范围，然后提交文件并创建 PR，让其他人能看到这项认领。
3. 开展工作 — 逆向工程。切勿触碰 Remote ID、地理围栏或其他安全功能；切勿复制固件映像或厂商代码（POLICY.md）。
4. 发布 — 使用 publish_findings 填写摘要、状态、接口（将协议文档链接设为 spec）、项目（托管在其他地方的代码）、安装途径、验证信息和 provenance.ai_assisted。传入 release_claim_of 以结束认领。
5. PR — 运行结果中的 git / gh pr create 命令。维护者会审核。

SKILL.md 是相同工作流的 Agent 技能版本，可直接放入技能目录（或嵌入其他工具）。

CLI

可在 shell 中调用相同的函数（使用相同的环境变量），并以 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 许可，其他工具可嵌入使用。