跳转到内容
OpenBot

开发者工具

这些工具面向发布 App 的人。你可以检查你的 App、证明你控制它、与团队共享访问权限、运行私密测试、请求收录，以及在出现问题时收到通知。

只有检查调用是公开的。其他所有调用都需要用户令牌或 session cookie，以及 apps.publish 权限。参见身份验证。

检查 App

任何人都可以检查 App。你不需要登录。检查只读取公开的文档。它不保存任何东西，也不连接 App。

Terminal window
curl -X POST https://api.example.com/v1/developer/inspect \
  -H "Content-Type: application/json" \
  -d '{ "input": "apps.example.com" }'

input 可以是一个域名或一个 HTTPS 链接，最多 8192 个字符。报告包含：

字段 说明
apps 找到的每个 App。对于公开的 Index，eligibility 为 Eligible、Excluded 或 Unconfirmed。stored 显示最近一次保存的索引检查（如果有）。
issues 需要修复的问题。每个问题都有一个 code、一个 stage、一个 severity（blocking 或 suggestion）、一个 message 和一个 repair 提示。
stages 每个检查步骤：Input、Discovery、CardRead、CardSchema、Compatibility、PublisherAssociation 和 Eligibility。每个都是 Passed、Failed、Unconfirmed 或 NotChecked。

Eligible 结果并不表示 App 已经在 Index 中。参见 App Index。

证明你控制 App

大多数工具需要证明你控制这个 App。你可以用两种方式证明：

范围 覆盖什么 令牌放在哪里
PublisherHostname Card 位于这个主机名上、并且被同一主机名上的 Catalog 列出的所有 App。 一条 DNS TXT 记录
AppCard 一个 App，按它确切的 Card URL。 Server Card

发起声明

Terminal window
curl -X POST https://api.example.com/v1/developer/claims \
  -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "_tag": "PublisherHostname", "hostname": "apps.example.com" }'

对于单个 App，发送 { "_tag": "AppCard", "cardUrl": "https://apps.example.com/mcp/server-card" }。主机名必须是一个确切的公开名称，不能带端口、路径或通配符。

响应中有一个 id 和一个形如 openbot-verification=... 的 token。声明保留 24 小时。

发布令牌

对于主机名，在 _openbot-verification.<hostname> 添加一条 DNS TXT 记录。用完整的令牌作为值：

_openbot-verification.apps.example.com.  TXT  "openbot-verification=abc123..."

对于单个 Card，把令牌加到 Card 中：

{
  "_meta": {
    "openbot/developer-verification": {
      "version": 1,
      "tokens": ["openbot-verification=abc123..."]
    }
  }
}

OpenBot 在 Card 确切的 URL 读取它，不跟随重定向。你的 robots.txt 必须允许 OpenBot 用户代理。

验证

Terminal window
curl -X POST https://api.example.com/v1/developer/claims/<claim id>/verify \
  -H "Authorization: Bearer $OPENBOT_TOKEN"

成功时，你会得到一份证明（proof）。你会成为这个范围的 administrator。失败时，你会得到 409 DeveloperConflict。它的 reason 可能是 ProofMismatch、ClaimExpired、VerificationUnavailable、RobotsDenied、RobotsUnconfirmed 或 CardUnconfirmed。

请保留令牌。证明的有效期是 7 天，OpenBot 每天都会重新检查它：

  • 如果令牌不见了，证明会立刻变成 Suspended。
  • 如果检查无法运行，证明会变成 Unconfirmed。在到期之前它仍然有效。OpenBot 会在大约一分钟后重试。
  • Suspended 的证明不提供任何访问权限。

要立刻检查，请调用 POST /v1/developer/proofs/:id/verify。要放弃一份证明，请调用 POST /v1/developer/proofs/:id/relinquish。要取消一个声明，请调用 POST /v1/developer/claims/:id/revoke。

GET /v1/developer 返回你的 App、你的证明，以及你的访问授权 grants。

成员和角色

管理员可以邀请其他账号。

角色 能做什么
administrator 做出证明的账号。可以做所有事，并管理成员。
maintainer 保存报告、运行测试和请求收录。
viewer 读取 App、报告和收录请求。不能修改。
  1. 邀请：POST /v1/developer/proofs/:id/invitations，带上 { "role": "maintainer" } 或 "viewer"。邀请保留 7 天。
  2. 把邀请的 id 发给对方。对方用 GET /v1/developer/invitations/:id 读取它，用 POST /v1/developer/invitations/:id/accept 接受它。
  3. 管理：GET /v1/developer/proofs/:id/members、带新 role 的 PUT /v1/developer/members/:id，以及 DELETE /v1/developer/members/:id。成员也可以移除自己。

要取消邀请，请调用 POST /v1/developer/invitations/:id/revoke。证明结束时，它的成员也会失去访问权限。

报告

报告是一次保存下来的检查。用报告查看你的 App 随时间如何变化。

任务 请求
保存一份新报告 POST /v1/developer/reports，带上 { "cardUrl" }
列出某个 App 的报告 GET /v1/developer/reports?cardUrl=...（最新的在前，每页 50 条，用 before 翻页）
读取一份报告 GET /v1/developer/reports/:id
比较两份报告 GET /v1/developer/reports/:id/compare?other=<id>
删除你保存的一份报告 DELETE /v1/developer/reports/:id
列出你保存的报告 GET /v1/developer/personal-reports

比较结果会列出 introduced（新出现）、resolved（已解决）和 persisting（仍存在）的问题。

私密连接测试

测试会像用户一样从 OpenBot 连接你的 App。它是私密的。它不保存用户连接，也不把 App 加入 Index。测试在一小时后结束。

  1. 用你自己的 UUID 创建一个测试：POST /v1/developer/tests，带上 { "id", "cardUrl", "remoteIndex" }。
  2. 如果端点需要设置，就发送它们：PUT /v1/developer/tests/:id/configuration，带上一个由键和值组成的对象。键和连接中的相同。
  3. 运行它：POST /v1/developer/tests/:id/run。用 GET /v1/developer/tests/:id 读取结果。

每次运行都有 stages：configuration、negotiation、tools、resources、resourceTemplates 和 prompts。每个阶段都是 Passed、Failed、NotAdvertised 或 NotChecked。测试的 status 最终为 Succeeded 或 Failed。

在测试中登录

当 App 需要账号时，测试状态会变成 AwaitingAuthorization。

  1. 开始登录：POST /v1/developer/tests/:id/authorization，带上 { "scopes": [] }。如果 App 有多个提供方，请加上 issuer。
  2. 在浏览器中打开 authorization.authorizationUrl 并登录。
  3. 提供方把你跳转到 /auth/developer/apps/callback。OpenBot 再把你跳转到 /?developerTest=<testId>。
  4. 完成：POST /v1/developer/tests/:id/authorization/complete。然后再次运行测试。

完成后，请调用 POST /v1/developer/tests/:id/cleanup。在提供方允许的情况下，OpenBot 会撤销测试中的登录，并删除保存的令牌。你也可以 cancel 一个正在运行的测试，或者 DELETE 它。

请求收录

你不必等用户来连接你的 App。可以让 OpenBot 检查它：

Terminal window
curl -X POST https://api.example.com/v1/developer/indexing \
  -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cardUrl": "https://apps.example.com/mcp/server-card" }'

OpenBot 会先检查这个 App。如果它不符合条件，你会得到 409 和 reason。如果本部署屏蔽了这个 App，你会得到 403 DeveloperRestricted。

请求的 status 从 Accepted 依次变为 Waiting、Verifying 和 Completed。完成后，check 中有结果。用 GET /v1/developer/indexing 列出请求，或用 GET /v1/developer/indexing/:id 读取一个请求。

通知

OpenBot 大约每小时检查一次你管理的 App。有变化时，它会给你发送通知。

类型 何时
IssueAppeared 出现了一个新的阻塞问题。
IssueResolved 一个阻塞问题消失了。
AccessChanged 某份证明的状态变了，或者你失去了成员权限。

用 GET /v1/developer/notifications 读取通知。用 before 读取更早的页面。用 POST /v1/developer/notifications/:id/read 把一条通知标记为已读。

问题通知对每个 App 默认打开。要为某个 App 关闭它们，请发送 PUT /v1/developer/subscriptions，带上 { "cardUrl": "...", "enabled": false }。用 GET /v1/developer/subscriptions 列出你的设置。

在 API 参考中查看完整的结构。