App Index

面向接入 OpenBot 客户端或扩展服务端的开发者。示例需要本页说明的访问权限。从开发者手册开始。

App Index（App 索引）是一个公开的 App 列表。任何人都可以搜索它。你不需要登录，也不需要发送用户令牌。Index 只保存公开的 App 描述。它永远不保存账号、设置、登录信息或结果。

Bot 通过 openbot_search_apps 和 openbot_app_details 工具使用同一个 Index。参见 App。

来源

一个 Index 可以从多个来源读取。列出它们：

curl https://api.example.com/v1/app-index/sources

[
  {
    "id": "openbot",
    "name": "OpenBot Index",
    "url": "https://api.example.com/v1/app-index/apps",
    "simulated": false
  }
]

openbot 来源是这台 OpenBot 服务器的 Index。部署所有者可以在代码中加入其他 OpenBot 服务器的 Index。OpenBot 读取它们时不使用用户凭据。在开发模式下，来源名称是 OpenBot Development Index，simulated 为 true。

搜索

curl "https://api.example.com/v1/app-index/apps?query=calendar&limit=10"

参数	说明
`query`	最多 200 个字符。它匹配 App 的名称和标题、描述，或发布者的主机名。不区分大小写。不填则列出所有 App。
`source`	只搜索一个来源，按它的 `id`。
`limit`	1 到 50 之间的数字。默认是 20。
`cursor`	上一页的 `nextCursor` 值。

响应是一页结果：

{
  "apps": [
    {
      "entry": {
        "cardUrl": "https://apps.example.com/mcp/server-card",
        "card": {
          "name": "com.example/calendar",
          "title": "Calendar",
          "description": "...",
          "remotes": []
        },
        "evidence": [
          {
            "publisherUrl": "https://apps.example.com",
            "catalogUrl": "https://apps.example.com/.well-known/ai-catalog.json",
            "cardUrl": "https://apps.example.com/mcp/server-card",
            "association": "CardOrigin"
          }
        ],
        "checkedAt": 1792454400000,
        "validators": { "etag": "\"v1\"" }
      },
      "sources": [
        {
          "id": "openbot",
          "name": "OpenBot Index",
          "url": "https://api.example.com/v1/app-index/apps",
          "simulated": false
        }
      ],
      "matches": ["name"],
      "check": { "_tag": "Indexed", "attemptedAt": 1792454400000 }
    }
  ],
  "nextCursor": null,
  "issues": []
}

entry.card 是完整的公开 Server Card，带有图标和用法示例。
entry.evidence 显示发布者在哪里列出了这个 Card。
matches 说明哪些字段匹配了你的查询。
check 是最近一次索引检查。参见 App 如何被收录。
当本部署屏蔽了这个 App 时，会出现 restriction。参见宿主限制。

结果先按 Card 名称排序，再按 Card URL 排序。当同一个 App 出现在多个来源中时，它只出现一次，并带有它所有的 sources。

分页

当 nextCursor 不是 null 时，还有更多结果。再次发送同样的 query 和 source，并把 cursor 设为这个值。

如果搜索条件或它的来源在两页之间发生了变化，你会得到 400 IndexInputInvalid。请从第一页重新开始。

部分结果

当一个来源失败时，你仍然会得到其他来源的结果。issues 列表会指出每个失败的来源，并给出一条 message。请把这些问题展示给用户，让他们知道列表可能不完整。

当所有来源都失败时，你会得到 503 IndexUnavailable 和 issues。

App 详情

通过 Card URL 读取一个 App：

curl "https://api.example.com/v1/app-index/app?cardUrl=https%3A%2F%2Fapps.example.com%2Fmcp%2Fserver-card"

响应的结构和 apps 中的一项相同。你可以加上 source，只从一个来源读取。

状态	错误	含义
400	`IndexInputInvalid`	输入无效。
403	`IndexRestricted`	本部署屏蔽了这个 App。
404	`IndexNotFound`	Index 中没有这个 App 或这个来源。
503	`IndexUnavailable`	没有任何来源可以读取。

App 如何被收录

任何人都不需要注册 App。App 在有用户连接它之后加入 Index：

用户保存一个到该 App 的连接。手动连接不会被收录。
OpenBot 把 Card URL 放入一个队列。连接不会等待这一步。即使 Index 不可用，连接也能工作。
一个后台 worker 在没有用户数据、没有凭据的情况下再次读取 Card。它检查：
- Card 是公开且有效的，并且有一个支持该协议的端点；
- robots.txt 允许 OpenBot 用户代理；
- Card 没有 noindex 规则；
- 有一个发布者 Catalog 列出了同一个 Card URL。
如果所有检查都通过，OpenBot 会保存这个公开条目。

发布者 Catalog 可以位于 Card 自身来源下的 /.well-known/ai-catalog.json，也可以是 Card 响应中的 ai-catalog 链接，或者是 Card 的 websiteUrl 指向的页面。别人的 Catalog 中有一份 Card 的副本是不够的。

OpenBot 大约每小时重新检查一次每个 App。检查失败或结果不确定后，它会在大约一分钟后重试。

`check._tag`	含义
`Pending`	等待第一次检查。
`Indexed`	App 已在 Index 中。
`Excluded`	App 不允许进入 Index。它不会出现在搜索中。`reason` 说明原因。
`Withdrawn`	App 曾在 Index 中，现在已被移除。
`Unconfirmed`	某项必要的检查没有完成。已有的条目会保留。
`Failed`	检查无法运行。

发布者也可以在开发者工具中请求一次检查。

每次检查最多运行四分钟。只有仍持有任务的工作进程才能写入结果。旧工作进程迟到的结果不能覆盖当前条目。读取来源列表时，如果 OpenBot 无法读取平台设置，会返回 503 SettingsUnavailable。

发布者撤回与 noindex

发布者可以控制自己的 App 是否在 Index 中：

noindex。 在 Card 响应中发送 X-Robots-Tag: noindex。你也可以发送 X-Robots-Tag: OpenBot: noindex，只针对这个爬虫。在下次检查时，OpenBot 会移除这个条目，或者根本不添加它。
从你的 Catalog 中移除 Card。 在下次检查时，OpenBot 会撤回这个条目。
robots.txt。 屏蔽 OpenBot 用户代理。在下次检查时，OpenBot 会排除这个 App，它不会再出现在搜索中。

如果你的 Catalog 无法访问，这不算撤回。检查结果为 Unconfirmed，条目会保留。

移除 Index 条目永远不会移除任何人的连接。用户仍然可以使用不在 Index 中的 App。

宿主限制

参见 App Index 设置.