┌────────────┐   OpenAPI 文档   ┌──────────────┐   MCP tools    ┌────────────┐
│  用户/CLI  │ ───────────────> │   Gateway    │ <────────────> │ AI Agent   │
│            │                  │   Server     │                │ (Claude)   │
└────────────┘                  └──────┬───────┘                └────────────┘
                                      │
                               ┌──────▼──────┐
                               │  API 代理层 │ ──HTTP──> 第三方 API
                               └─────────────┘         (GitHub/飞书/Notion...)

┌────────────┐
│ RAG 向量库 │  ← API 文档向量化，Agent 先检索再调用
└────────────┘

api-to-mcp-gateway/
├── packages/
│   ├── core/                # 核心：OpenAPI 解析 → MCP Tool Schema 映射
│   │   ├── parser.ts            # 解析 OpenAPI JSON/YAML，提取 operations
│   │   ├── converter.ts         # operationId → snake_case 工具名 + JSON Schema
│   │   ├── contracts.ts         # 核心接口（IParser/IToolRegistry/IApiProxy/IRagStore）
│   │   └── types.ts             # 全部类型定义
│   │
│   ├── server/              # MCP Server 运行时
│   │   ├── server.ts            # Streamable HTTP 服务（JSON-RPC 2.0，POST /mcp）
│   │   ├── proxy.ts             # API 请求代理（发 HTTP 请求到目标 API）
│   │   ├── auth.ts              # Auth 注入（API Key / Bearer / OAuth2）
│   │   └── index.ts
│   │
│   ├── rag/                 # RAG 文档检索
│   │   ├── indexer.ts           # API 文档切片 + 向量化
│   │   ├── retriever.ts         # 语义搜索
│   │   └── store.ts             # 内存向量存储（余弦相似度）
│   │
│   ├── agent/               # Agent 编排层
│   │   ├── orchestrator.ts      # Agent 主循环（RAG 搜索 → 工具调用 → 迭代）
│   │   └── prompts.ts           # System prompt
│   │
│   └── cli/                 # CLI 命令行入口
│       └── index.ts             # `api2mcp serve --spec ./api.yaml`
│
├── specs/
│   └── petstore.yaml        # 示例 OpenAPI 文档
├── package.json             # pnpm workspace monorepo
└── tsconfig.json

# 克隆仓库
git clone https://github.com/PPACT/api-to-mcp-gateway.git
cd api-to-mcp-gateway

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 使用本地 OpenAPI 文档启动
pnpm start -- --spec ./specs/petstore.yaml

# 使用远程 OpenAPI 文档启动
pnpm start -- --spec https://petstore.swagger.io/v2/swagger.json

# 自定义端口和监听地址
pnpm start -- --spec ./specs/github.openapi.json --port 8080 --host 0.0.0.0

# 多文档聚合（同时暴露多个 API 的工具）
pnpm start -- --spec ./specs/github.yaml --spec ./specs/notion.yaml

# API Key 模式
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Bearer Token 模式
export NOTION_API_KEY=secret_xxxxxxxxxxxx

# 然后启动服务
pnpm start -- --spec ./specs/github.openapi.json

import { AuthManager } from '@api2mcp/server';

const auth = new AuthManager();
auth.register('github', { type: 'bearer', envVar: 'GITHUB_TOKEN' });
auth.register('notion', { type: 'api_key', headerName: 'Notion-Version', envVar: 'NOTION_API_KEY' });

pnpm install      # 安装依赖
pnpm build        # 构建所有包
pnpm test         # 运行全部测试
pnpm test --watch # 监听模式

1. 解析 OpenAPI 文档
   parser.ts 读取 JSON/YAML → 提取全部 operation（operationId、method、path、parameters）

2. 转换为 MCP Tool
   converter.ts 将 operationId 映射为 snake_case 工具名，
   parameters + requestBody → JSON Schema inputSchema

3. 注册工具
   ToolRegistry 存储所有工具及其对应 API 的元数据

4. 启动 MCP Server
   Streamable HTTP 服务监听 /mcp，处理 JSON-RPC 请求：
   - initialize  → 握手
   - tools/list  → 列出所有工具
   - tools/call  → 执行工具 → 代理 HTTP 请求到目标 API

5. AI Agent 连接
   Claude/GPT 通过 MCP 协议连接 → 发现工具 → 调用 API

{
  "error": {
    "code": "API_ERROR",
    "message": "GitHub API 返回 401 —— 请检查 GITHUB_TOKEN",
    "suggestion": "试试 github_list_issues 并传入 owner='octocat'"
  }
}

# 1. 用 Petstore API 启动网关
pnpm start -- --spec ./specs/petstore.yaml

# 2. 在 Claude Desktop 中配置连接（mcp.json）：
{
  "mcpServers": {
    "petstore": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

# 3. 对 Claude 说：
#    "帮我在宠物店添加一只叫 Buddy、状态为 available 的新宠物，
#     然后查出所有状态为 available 的宠物列表。"
#
# Claude 自主完成：
#   - 调用 petstore_add_pet({name: "Buddy", status: "available"})
#   - 调用 petstore_find_pets_by_status({status: "available"})
#   - 汇总结果返回给用户