agentify

agentify

将任意 OpenAPI / Swagger 规范转换为适用于 Agent 的 MCP 服务。

已列入 官方 MCP Registry（io.github.sani-savaliya/agentify）和 Smithery。

指定一个规范——URL、文件、OpenAPI 3.x 或 Swagger 2.0 均可——其中的每个操作 都会变成 AI Agent 可调用的工具。无需生成代码，无需为每个 API 编写样板代码，也无需 托管。只需一条命令。

npx agentify-openapi https://petstore3.swagger.io/api/v3/openapi.json --list

Swagger Petstore - OpenAPI 3.0 v1.0.27
Base URL: https://petstore3.swagger.io/api/v3
Tools: 19

  getPetById
    Find pet by ID.
  findPetsByStatus
    Finds Pets by status.
  ...

为什么选择它

“如今，Agent 必须操作为人类设计的软件。未来的接口将为 Agent 构建——API、MCP、CLI——并将 Agent 视为一等公民。” — YC RFS：面向 Agent 的软件

数以万计的 API 已经通过 OpenAPI 文档描述自身。agentify 能立即让它们都适用于 Agent，无需任何人 手写集成代码。

与 Claude、Cursor、Windsurf 和任意 MCP 客户端搭配使用

将它添加到客户端的 MCP 配置中。相同的 command/args 格式适用于 Claude Desktop、Claude Code（claude mcp add）、Cursor （.cursor/mcp.json）、Windsurf、Cline 以及其他所有支持 MCP 的产品：

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": ["-y", "agentify-openapi", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

现在，Agent 为每个 API 操作都配备了一个工具。调用工具会构建 HTTP 请求 （路径参数、查询字符串、标头、JSON 正文），并返回实时响应。

API 很庞大？只选择需要的工具

如果直接指定 GitHub（1000 多个操作）或 Stripe（400 多个操作），Agent 会被数百个工具淹没， 工具选择准确率也会大幅下降。你可以按标签、HTTP 方法或名称 glob 筛选出需要的工具， 并限制工具总数：

# GitHub, read-only, just the repo endpoints
npx agentify-openapi https://api.github.com/openapi.json --tag repos --read-only

# Stripe customer endpoints only, hard cap at 25 tools
npx agentify-openapi ./stripe.json --include "*Customer*" --max-tools 25

{
  "mcpServers": {
    "github-repos": {
      "command": "npx",
      "args": ["-y", "agentify-openapi", "https://api.github.com/openapi.json",
               "--tag", "repos", "--read-only", "--max-tools", "30"],
      "env": { "AGENTIFY_BEARER_TOKEN": "ghp_your_token" }
    }
  }
}

--read-only（GET/HEAD/OPTIONS）也是一种简单的安全防护措施——可以向 Agent 开放大型 API， 同时避免暴露任何可能更改状态的操作。

身份验证

通过环境变量提供凭据——agentify 会读取规范中声明的安全方案，并在可能的情况下找到相应的标头名称：

变量	作用
AGENTIFY_BEARER_TOKEN	Authorization: Bearer <token>
AGENTIFY_BASIC_USER / AGENTIFY_BASIC_PASS	HTTP 基本身份验证
AGENTIFY_API_KEY	API 密钥（默认通过标头发送）
AGENTIFY_API_KEY_HEADER	覆盖 api-key 标头名称
AGENTIFY_API_KEY_QUERY	改为将 API 密钥作为查询参数发送

也可以通过 CLI 注入原始标头：--header "X-Org-Id: 42"（可重复使用）。

CLI

agentify <spec-url-or-file> [options]

  --base-url <url>     Override the API base URL from the spec
  --header "K: V"      Add a raw header to every request (repeatable)
  --name <name>        Override the MCP server name
  --list               Print the discovered tools and exit (no server)
  -h, --help           Show help

  Tool selection (keep big APIs from flooding the agent's context):
  --tag <tag>          Keep only operations with this tag (repeatable)
  --exclude-tag <tag>  Drop operations with this tag (repeatable)
  --method <verb>      Keep only this HTTP method, e.g. GET (repeatable)
  --read-only          Shorthand: keep only GET/HEAD/OPTIONS operations
  --include <glob>     Keep only tools matching this glob (repeatable)
  --exclude <glob>     Drop tools matching this glob (repeatable)
  --max-tools <n>      Hard cap on tool count (warns when it truncates)

工作原理

一个精简的纯流水线——每个阶段都经过独立的单元测试：

spec ──▶ operations ──▶ tool defs ──▶ http request ──▶ response
 │           │              │              │              │
load &    one tool       JSON Schema   path/query/    fetch + surface
deref     per op         for inputs    header/body    status & body
$refs                                  + auth

只有 HTTP 执行和 MCP 传输会接触外部环境；其余部分都是确定性的，并经过测试。

以编程方式使用

import { loadSpec, extractOperations, resolveBaseUrl, createServer } from "agentify-openapi";

const spec = await loadSpec("./openapi.yaml");
const tools = extractOperations(spec);
const baseUrl = resolveBaseUrl(spec);
// ...build your own MCP server, or just inspect the generated tool defs

局限性

• JSON 请求/响应正文是一等支持项；multipart/表单正文会尽力传递。
• 尚未处理 cookie 参数和 OAuth2 流程（目前可使用 --header）。
• 每个规范对应一个服务。多规范聚合已列入路线图。

开发

npm install
npm test          # vitest, 80%+ coverage enforced
npm run build     # tsc -> dist/
node scripts/smoke.mjs   # end-to-end MCP client smoke test (network)

许可证

MIT