apifable

阅读规范。理解 API。自信地进行集成。

English | 繁體中文

概述

apifable 是一个 MCP 服务器，旨在帮助 AI 更顺畅地将 API 集成到 TypeScript 前端项目中。它使探索 API 结构、搜索端点和生成 TypeScript 类型变得简单，从而为您的 AI 代理提供编写准确集成代码所需的上下文。

Related MCP server: openapi-mcp-proxy

✨ 特性

• 📦 AI 就绪的 API 上下文 — 为 AI 提供理解和使用您的 API 所需的结构

• 📘 支持 OpenAPI 3.0 / 3.1 — 作为可靠的事实来源，适用于标准规范

• 🤖 面向 AI 代理的 MCP 服务器 — 可接入 Claude、Cursor 和 Windsurf

• 🔍 API 探索工具 — 浏览端点、按关键字搜索并检查完整的请求/响应详情

• 🏷️ TypeScript 类型生成 — 生成可直接在前端代码中使用的 TypeScript 类型定义

入门指南

安装

运行 apifable init 来设置您的项目配置：

npx apifable@latest init

这将在您的项目根目录中创建 apifable.config.json。该配置文件应提交到版本控制中，以便与团队共享规范路径。

命令启动后，您可以选择 手动文件 (Manual file) 或 远程 URL (Remote URL)。

1. 手动文件

如果您的 OpenAPI 规范已经存在于项目中，或者您想自己管理规范更新，请使用此模式。

init 将询问本地文件路径，例如 openapi.yaml。

然后，您需要手动将 OpenAPI 规范放置在该路径下。当后端 API 发生变化时，您也需要手动更新该文件。

2. 远程 URL

如果您的 OpenAPI 规范可以通过稳定的远程 URL 获取（例如后端 API 文档提供的 OpenAPI 规范端点），请使用此模式。

init 将首先询问远程 URL（例如 https://api.example.com/openapi.yaml），然后询问本地输出路径（例如 ./openapi.yaml）。

[!NOTE] 在此模式下，init 还会自动将下载的本地规范路径添加到 .gitignore 中，因为该文件旨在从远程源刷新。

然后，您可以运行以下命令将 OpenAPI 规范从远程 URL 下载到本地路径（spec.url → spec.path）。每当规范发生变化时，只需再次运行它即可刷新：

npx apifable@latest fetch

请求头 (Headers)

对于可以与团队共享的非敏感请求头，请将 spec.headers 添加到 apifable.config.json 中：

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

认证请求头 (Secret Tokens)

如果下载远程 OpenAPI 规范需要身份验证（私有 API），请将秘密请求头存储在 .apifable/auth.json 中。此文件不应提交到版本控制中：

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

apifable.config.json 和 .apifable/auth.json 都支持在请求头值中使用 ${ENV_VAR} 语法。

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

请求头优先级（从高到低）

1. .apifable/auth.json 中的请求头（覆盖同名键）

2. apifable.config.json 中的 spec.headers

Claude Code

将以下内容添加到您的 .mcp.json 中：

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

对于 Cursor 和 Windsurf 等其他 AI 代理，您可以按照相同的方法将 apifable 配置为 MCP 服务器。

使用方法

以下是一些可用于探索 API 和构建功能的示例提示词。

探索 API

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

构建功能

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] 在编写构建功能的提示词时，请包含相关上下文：页面路径、组件位置、相关 API 以及任何需要遵循的模式或示例。

AI 代理指南

将以下内容添加到项目的 AGENTS.md 中，以帮助 AI 代理更有效地使用 apifable：

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

以上是推荐的起点。请根据您的项目随意调整端点列表列和类型文件夹路径。

MCP 工具参考

get_spec_info

返回 API 标题、版本、描述、服务器以及所有带有端点计数的标签。从这里开始了解陌生规范的结构。

list_endpoints_by_tag

输入：

• tag (string): 要过滤的标签名称

• limit (number, 可选): 返回的最大端点数

• offset (number, 可选): 跳过的端点数（默认值：0）

返回属于给定标签的所有端点。响应包含用于分页的 total、offset 和 hasMore 字段。当结果超过 30 项且未指定 limit 时，包含警告。

search_endpoints

输入：

• query (string): 要搜索的关键字

• tag (string, 可选): 将搜索限制在特定标签内

• limit (number, 可选): 返回的最大结果数（默认值：10）

跨 operationId、路径、摘要和描述进行关键字搜索。结果按相关性排序。如果未找到精确匹配，则自动回退到模糊搜索。响应包含 matchType 字段（"exact" 或 "fuzzy"）；模糊搜索结果还包含每个结果的 score 字段。

get_endpoint

输入（二选一）：

• method (string) + path (string): HTTP 方法和端点路径（例如 get + /users/{id}）

• operationId (string): 操作 ID（例如 listUsers）

返回完整的端点对象，包括参数、requestBody 和响应，并解析内联支持的内部组件 $ref。

search_schemas

输入：

• query (string): 要搜索的关键字

• limit (number, 可选): 返回的最大结果数（默认值：10）

跨模式名称和描述进行关键字搜索。结果按相关性排序。如果未找到精确匹配，则自动回退到模糊搜索。响应包含 matchType 字段（"exact" 或 "fuzzy"）；模糊搜索结果还包含每个结果的 score 字段。空结果可能还包含带有下一步指导的 message 字段。

get_schema

输入：

• name (string): 来自 components/schemas 的模式名称

返回解析了支持的内部组件 $ref 的完整模式。

get_types

输入（选择一种模式）：

• schemas (string[]): 来自 components/schemas 的模式名称数组

• method (string) + path (string): HTTP 方法和端点路径

• operationId (string): 操作 ID（例如 listUsers）

生成独立的 TypeScript 声明作为代码文本。在端点模式下，它会在收集模式依赖项之前跟踪支持的内部组件 $ref。它会自动包含传递依赖项，且不包含 import 语句。

模式规则：

• 每次调用仅使用一种模式：schemas、method + path 或 operationId

• 不要在同一次调用中混合使用模式

限制

• 不支持外部 $ref（例如对其他文件或 URL 的引用）。

• 不支持 OpenAPI 2.0 (Swagger)。仅支持 OpenAPI 3.0 和 3.1 规范。

赞助

如果您认为此包对您有帮助，请考虑 成为赞助者 以支持我的工作~ 您的头像将显示在我的主要项目中。

致谢

• @reapi/mcp-openapi — 感谢最初的灵感来源

许可证

MIT LICENSE

Star 历史