RealWorldAPIs

RealWorldAPIs MCP

RealWorldAPIs 是一个以证据为先的 API 注册目录，面向连接现实世界的 AI Agent。

现实世界 API 将软件或 AI Agent 连接到代表物理世界的数据、设备、基础设施或服务，包括天气、地图、出行、物流、物联网、能源和机器人技术。

此代码库记录并提供 RealWorldAPIs 的公开可检查 MCP 接口实现。

实时托管的 RealWorldAPIs 服务是当前工具、架构、推荐行为和证据语义的权威来源。 托管服务可能独立于此代码库中可见的代码进行演进。

整项服务遵循一条核心证据规则：

未知仍然是未知，绝不会被视为已确认支持。

公共接口与专有智能

RealWorldAPIs 有意将公共互操作层与专有决策系统分开。

公共／互操作层

以下内容旨在公开发现并用于互操作：

• 远程 MCP 端点和工具架构
• 公共 HTTP 端点和 OpenAPI 描述
• 公共 API 目录和能力／证据输出
• 公共文档和使用示例
• 真实的提供商元数据和证据链接
• 托管服务返回的结构化推荐和验证结果

专有托管系统

以下内容不会通过此代码库发布或授权：

• RealWorldAPIs 的规范推荐和排序引擎
• 自然语言任务解析和任务框架逻辑
• 能力检索、融合和同级能力重新排序逻辑
• 内部评分规则、权重和优化逻辑
• 验证和证据处理实现
• 断言生成和研究流水线
• 基准测试工具、主动使用的私有评估集和留出集
• 内部管理、提案和审批系统

MCP 层会调用托管的 RealWorldAPIs 规范服务，以提供推荐和基于证据的决策支持。发布接口、架构或结果，并不意味着发布底层托管实现。

有关代码库权利声明，请参阅 PROPRIETARY_NOTICE.md。

实时服务

• 网站： https://realworldapis.com
• 远程 MCP 端点： https://mcp.realworldapis.com/mcp
• MCP 健康状态： https://mcp.realworldapis.com/health
• 目录 JSON： https://realworldapis.com/api/catalog.json
• 能力 JSON： https://realworldapis.com/api/capabilities.json
• 需求验证： https://realworldapis.com/api/verify-requirement
• 结构化推荐： https://realworldapis.com/api/recommend
• OpenAPI： https://realworldapis.com/openapi.json
• 完整 LLM 目录： https://realworldapis.com/llms-full.txt
• 研究： https://realworldapis.com/research/state-of-agent-ready-apis-2026

目前，无需 RealWorldAPIs API 密钥即可发现或调用公共 MCP 工具。

MCP 工具

RealWorldAPIs 实时 MCP 服务目前提供六个只读工具：

工具	用途
find_api_for_task	使用规范托管推荐器进行自然语言 API 选择，然后对返回的候选项进行受限比较。
search_apis	根据规范 API 字段进行确定性搜索和筛选。
search_capabilities	直接搜索已验证的能力图谱。
verify_requirement	基于证据，针对特定需求验证某个 API 是否符合要求，结果为 YES / NO / PARTIAL / UNKNOWN。
get_api	根据 slug 或名称检索某个规范 API 决策档案。
compare_apis	对规范字段进行确定性并列比较。

实时工具集和架构具有权威性。此代码库中可见的源代码实现可能落后于托管服务。

我应该使用哪个工具？

如果你需要……	使用
针对开放式自然语言任务或预期结果的建议	find_api_for_task
按类别、能力、协议状态或就绪情况进行精确筛选	search_apis
直接搜索经过验证的任务级能力	search_capabilities
基于证据判定某项确切的 API 要求	verify_requirement
获取某个已知 API 的规范记录	get_api
逐字段比较已知候选项	compare_apis

find_api_for_task

当用户描述的是目标而非特定 API 时使用。

任务示例：

{
  "task": "I need my agent to connect to a car and predict weather on the route"
}

规范托管推荐器返回的结构化候选列表是事实来源。任何 AI 比较都受限于该列表，不得引入列表外的 API。

search_apis

当任务足够明确，可以直接筛选注册表时使用。

示例：

{
  "categories": ["Geospatial"],
  "agent_capabilities": ["locate"],
  "mcp": "Yes",
  "min_readiness": 60,
  "limit": 10
}

只使用明确存储的值。例如，mcp: "Yes" 不能由 MCP 状态为 Unknown 的 API 满足。

search_capabilities

当任务更适合表示为确切的能力或执行要求，而非宽泛的 API 类别时使用。

只要规范证据图中有相关信息，能力结果就可以包含执行、访问、审批、硬件、沙盒、物理后果和可逆性字段。

verify_requirement

当你需要根据一项确切要求判定某个 API 时使用。

示例：

{
  "api": "here-location-services",
  "requirement": "truck routing in Sweden"
}

验证器会返回基于证据的 YES、NO、PARTIAL 或 UNKNOWN 结果。Unknown 绝不会被悄然提升为支持。

get_api

示例：

{
  "identifier": "geoapify"
}

响应是规范的 RealWorldAPIs 决策档案，其中包含提供方元数据、能力、身份验证、协议状态和证据链接。

compare_apis

示例：

{
  "apis": ["Geoapify", "Google Maps Platform", "Mapbox"],
  "fields": [
    "category",
    "capabilities",
    "agent_capabilities",
    "auth_methods",
    "openapi",
    "mcp",
    "agent_readiness_score"
  ]
}

比较结果是确定性的。RealWorldAPIs 不会推断缺失的支持，也不会悄然用猜测取代 Unknown。

连接

任何支持远程 Streamable HTTP 的 MCP 客户端均可连接到：

https://mcp.realworldapis.com/mcp

MCP 配置示例：

{
  "mcpServers": {
    "realworldapis": {
      "url": "https://mcp.realworldapis.com/mcp"
    }
  }
}

Codex 风格的 TOML

[mcp_servers.realworldapis]
url = "https://mcp.realworldapis.com/mcp"

证据模型

RealWorldAPIs 以规范化证据层为基础，而非自由形式的 API 推荐。

规范数据集会追踪以下字段：

• 提供方和类别
• 经过验证的任务级能力
• Agent 操作原语
• 身份验证方法
• OpenAPI
• MCP
• A2A
• x402
• llms.txt
• 公开文档状态
• 身份验证核验
• 访问和设置要求
• 审批要求
• 硬件依赖
• 沙盒可用性
• 物理后果
• 不可逆性
• 直接证据链接

依据规则

1. 规范结构化数据集是事实来源。
2. Unknown 与 No 不同。
3. AI 比较不得引入结构化候选列表之外的 API。
4. 搜索和比较工具使用规范存储的证据。
5. 提供方的关键事实必须符合托管 RealWorldAPIs 证据政策规定的相应证据质量。
6. 投入生产集成前，应检查提供方文档。

RealWorldAPIs 的存在意义

通用 API 目录有助于广泛探索，但 AI Agent 越来越需要一种规范化方式来回答以下问题：

• 哪项确切的 API 能力可以执行此任务？
• 哪些 API 可以定位车辆并为技术人员规划路线？
• 哪些天气 API 既可由 Agent 操作，又可供机器读取？
• 哪些机器人 API 提供机器可用的接口？
• 可以组合哪些 API 来实现现实世界工作流？
• 有哪些访问、审批、硬件或安全限制？
• 在 Agent 依赖某个提供方之前，还存在哪些证据缺口？

RealWorldAPIs 专注于连接软件和 Agent 与现实世界的 API。

研究与数据集

公开研究页面 State of Agent-Ready Real-World APIs 2026 总结了目录快照中关于 Agent 就绪度、协议支持和类别级证据的信息：

https://realworldapis.com/research/state-of-agent-ready-apis-2026

机器可读的研究数据：

https://realworldapis.com/research/state-of-agent-ready-apis-2026.json

公开目录地址：

https://realworldapis.com/api/catalog.json

已验证的能力图谱地址：

https://realworldapis.com/api/capabilities.json

架构

MCP 服务有意设计为规范托管 RealWorldAPIs 服务之上的接口层。

MCP client
   |
   +-- find_api_for_task --------> hosted canonical recommender
   +-- verify_requirement --------> hosted evidence/verifier layer
   +-- search_capabilities -------> canonical capability graph
   +-- search_apis ---------------> canonical API catalog
   +-- get_api -------------------> canonical API decision profile
   +-- compare_apis --------------> canonical evidence fields

这样可以避免在公开 MCP 接口中维护第二套独立的推荐、排名或证据系统。

规范托管推荐、排名、验证和证据处理系统的实现属于专有内容，不包含在此代码仓库中。

更多公开接口详情，请参阅 docs/ARCHITECTURE.md。

仓库布局

src/
  worker.js               Publicly inspectable MCP interface implementation

examples/
  requests.md             Example tool calls and expected semantics

docs/
  ARCHITECTURE.md         Public data flow, grounding and failure behavior
  DATA_MODEL.md           Important catalog fields and evidence semantics

CHANGELOG.md               Release history
CONTRIBUTING.md            Contribution and correction workflow
PROPRIETARY_NOTICE.md      Repository rights and proprietary-service boundary

状态

托管的 RealWorldAPIs 服务独立于此公开仓库持续演进。

如需了解当前生产环境的行为，请使用实时 MCP 端点和规范网站端点。生产环境部署后，第三方目录和此仓库可能会暂时显示较旧的工具数量、描述、实现细节或架构。

贡献

欢迎提交关于公开 API 元数据的更正，但需提供当前服务提供方文档作为依据。请附上证据 URL，并指出需要更改的具体字段。

公开贡献不会授予对 RealWorldAPIs 专有排名、验证、优化、基准测试或研究系统的访问权限，也不意味着这些系统会公开。

请参阅 CONTRIBUTING.md。

权利与许可

此仓库仅公开源代码供查看，并未采用开源许可证发布。

此仓库未授予 MIT、Apache、BSD、GPL 或其他任何开源许可证。

使用托管的 RealWorldAPIs 服务与对仓库源代码的权利相互独立。根据适用条款和法律，可将公开的协议说明、架构和事实输出用于互操作；但此仓库并未对专有的托管 RealWorldAPIs 系统授予许可。

请参阅 PROPRIETARY_NOTICE.md。

版权所有 © 2026 RealWorldAPIs。保留所有权利。