mcpField
A
apifacts

apifacts

本地服务
apifacts.dev开发工具01 天前更新
代码仓库访问官网

关于 apifacts

apifacts 是面向 Agent 和开发者的注册库，记录经验证的 HTTP API、SDK 与 CLI 行为事实，帮助诊断第三方接口错误。其 MCP 工具根据确定性探测返回已知事实和类型化修复方案。

主要功能

  1. 01经验证的 API 行为事实
  2. 02针对已知错误的类型化修复
  3. 03按环境和账户状态区分事实
  4. 04定时执行的确定性探测
  5. 05CLI、pytest 插件和 Agent 技能

适用场景

  1. 01诊断意外的第三方 API 响应
  2. 02检查限流和破坏性变更行为
  3. 03HTTP 测试失败时查看已知事实

MCP 相关

通过 stdio 提供一个 `check(target, method, status, body)` 工具，返回匹配事实、类型化修复方案和探测结果。离线模式使用 wheel 内置的快照。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "illouminus-apifacts": {
      "command": "uvx",
      "args": [
        "apifacts"
      ]
    }
  }
}
启动命令uvx apifacts

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypiapifacts0.2.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

apifacts

面向 AI Agent 的、经过验证的现实变更日志。 一个开放注册库，收录关于第三方机器接口（HTTP API、SDK 包、CLI）实际行为的带类型、注明日期的事实，而非其文档所述内容。

为什么

接口会变，文档会滞后，却没有人告诉 Agent。每次会话都要花费 token 重新发现同样的陷阱：返回 200 和空数组，而不是 429；在响应体中将速率限制报告为 status: 0；SDK 发布版本悄悄移除了某个字段。文档工具会回答“给我正确的文档”；apifacts 则会回答“文档对这个端点的描述现在有误，以下是经过验证的差异”。

安装

pip install apifacts-pytest   # pytest plugin: a test failing on an HTTP error prints the known facts
uvx apifacts check https://api.stripe.com/v1/charges -X GET --status 401   # CLI (and library)
npx skills add Illouminus/apifacts   # agent skill: on an API error, ask the registry first

两个包都发布在 PyPI 上，版本相同，并从同一个标签一起发布 （发布）。插件只有在测试失败后才会发送内容。技能 （skills/apifacts/SKILL.md）会告诉 Claude Code 和其他 Agent 何时调用 apifacts check，以及如何读取结果。

MCP

通过 stdio 调用一个工具 check(target, method, status, body)；没有资源，也没有提示词。Claude Code：

claude mcp add apifacts -- uvx --from 'apifacts[mcp]' apifacts mcp

Claude Desktop、Cursor 和其他客户端（在其 JSON 配置中设置 mcpServers）：

{"mcpServers": {"apifacts": {"command": "uvx", "args": ["--from", "apifacts[mcp]", "apifacts", "mcp"]}}}

apifacts mcp --offline 会根据 wheel 中打包的快照作答，不会发送任何内容。

如何验证事实

  • facts/<service>/ 中每个 YAML 文件记录一条事实，包含类型（error_meaning、rate_limit、 breaking_change 等）、确切的错误信号、一句话声明、维度（env、plan、 region、account_state）和证据。
  • 事实只来自确定性探测：由我们的运行器按计划执行的声明式 HTTP 步骤和断言。验证过程中不会调用任何语言模型。
  • 修复方案是数据，而非建议：从封闭词汇表中选取，并使用带类型的参数（不含自由文本、shell 命令或外部 URL），由我们将其生成一句英文。
  • 在其他环境中进行的探测永远不会推翻事实；它只会增加一个维度。

调用 check()

一个端点既能作答，也能同时学习：请求本身就是贡献。发送目标，并可选地附上遇到的错误；即可收到匹配的事实、带类型的修复方案，以及探测观察到的内容。如果目标匹配已注册的模板，就会存储规范化后的观察结果（不含响应体、标头、查询字符串或原始 IP）。

curl -s https://apifacts.dev/v0/check \
  -H 'Content-Type: application/json' \
  -d '{"target": {"method": "POST", "url": "https://api.stripe.com/v1/payment_intents"},
       "error": {"status": 400, "body_excerpt": "Keys for idempotent requests can only be used with the same parameters they were first used with."}}'

响应永远不会为空：如果没有匹配项，会返回 facts、observed，以及 unknown.reason。

状态

API 已在 https://apifacts.dev 上线（/v0/check、/v0/services、/openapi.json、/healthz； 旧地址 facts.baillot.dev 会重定向至此）。注册库涵盖 apifacts.dev/registry 中列出的服务和事实；每个事实页面都会说明其确立方式；/llms.txt 为 Agent 描述了 API。设计约定位于 docs/specs/。

运行自己的副本：API 会在启动时读取一次 facts/ 和 services/，因此执行 git pull 后需要重启；ops/deploy.sh 可一步完成检出、同步和重启。

贡献

调用 check() 就是在贡献。拉取请求面向人类和 API 提供方：请参阅 CONTRIBUTING.md。提供方签名始终免费。

许可证

代码：MIT。数据（facts/ 和生成的事实页面）：CC BY 4.0。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。