
> 研究对象：Mastouri, Ksontini & Kessentini, *Making REST APIs Agent-Ready: From OpenAPI to Model Context Protocol Servers for Tool-Augmented LLMs*, arXiv:2507.16044v1（2025-07）
> 论文地址：https://arxiv.org/abs/2507.16044
> 复现包与数据集：https://sites.google.com/view/automcp
> 研究焦点：OpenAPI 规范能否直接“编译”成 MCP 服务器，以及是什么在阻挡自动化。
>
> **研究路径**：本文采取“论文为主、代码为辅”的解读顺序——先梳理论文对 MCP 生态的实证画像与 AutoMCP 编译器设计（第 1、2 节），再聚焦实验证据与失败根因（第 3 节），最后回到与先前 RestGPT 工作的对比与启示（第 4 节）。

---

## 0. 一句话结论

在 AutoMCP 的语境里，**通往 agent-ready 的最快路径不是写更多胶水代码，而是写一份足够完整、准确、可机器消费的 OpenAPI 契约**。只要契约正确，REST API 可以在一次编译中变成 LLM 可动态发现、可 JSON-RPC 调用的 MCP 工具；反之，所有失败都追溯到 OpenAPI 规范自身的五类缺陷。因此，**OpenAPI 从“文档格式”进一步升级为“自动化集成基础设施”**。

---

## 1. 为什么需要 AutoMCP？MCP 生态的实证画像

### 1.1 MCP 的承诺与现实的落差

Anthropic 在 2024 年底推出 **Model Context Protocol（MCP）**，目标是让 LLM 客户端与工具实现解耦：工具以 MCP 服务器形式注册 schema，客户端动态发现、调用，无需手工写提示词或硬编码。但论文指出，**MCP 的协议层虽已标准化，服务器层仍高度手工化**：开发者仍需把每个 REST 端点翻译成 handler、定义输入/输出 schema、处理认证、再按 MCP 约定暴露。

这与 MCP 想要消除的集成成本本质上重复。论文背景部分直接点明：当前工具集成仍是“人工把 API 描述塞进 prompt 或硬编码到初始化逻辑”，缺乏规模化方案。

### 1.2 GitHub 上的 MCP 采用现状：热闹但落地稀疏

论文 RQ1 对 2024-10 至 2025-04 的 GitHub 进行了一次大样本挖掘：

| 指标 | 数值 | 含义 |
| --- | --- | --- |
| MCP 标签仓库 | 22,722 个 | 含 `model-context-protocol` 字符串 |
| 含可运行服务器 | 1,164 个 | 仅约 **5.1%** |
| 服务器中位代码规模 | 920 SLOC | 非空非注释源码行 |
| 中位贡献者 | 1 人 | 50% 服务器单人维护 |
| 主作者提交占比 | 82% | 工作量高度集中 |
| 中位代码变更强度 | 31 LoC/月 | 演化缓慢 |

> **Finding-1**：MCP 讨论度很高，但真正的服务器实现稀少、规模小、单人维护、变化慢——说明当前 MCP 开发成本主要耗在重复样板代码上，而不是业务逻辑。

这也为“自动化”提供了直接动机：既然 95% 的 MCP 项目没有服务器，且已有服务器多半是相似的胶水代码，何不直接由 OpenAPI 规范生成？

---

## 2. AutoMCP：把 OpenAPI 编译成 MCP 服务器

### 2.1 整体定位：协议层之后的服务器层自动化

AutoMCP 与此前工作的核心差异在于：**它不关心 LLM 怎么规划或选工具，只关心“如何把一份真实 REST API 的规范，变成一份可部署的 MCP 服务器”**。这与 RestGPT（客户端规划/调用）正好互补。

论文 Table 1 给出了直接对比：

| 维度 | REST-GPT [3] | AutoMCP |
| --- | --- | --- |
| MCP 兼容 | 否 | **是** |
| 支持 API 范围 | ~100 个声明，仅评估 2 个（TMDB、Spotify） | **任意带 OpenAPI 的 API；评估 50 个** |
| 可扩展性 | 手动集成 | **全自动** |
| 对 OpenAPI 的依赖 | 部分（需人工预处理） | **完整（输入即规范）** |
| 关注层面 | 客户端调用/规划 | 服务端基础设施生成 |

> 注：RestGPT 是北大论文，也是本系列前文的研究对象；AutoMCP 在参考文献 [3] 中明确引用并对比了它。

### 2.2 编译流程（六步）

AutoMCP 是一个静态编译器，输入 OpenAPI 2.0/3.0 规范，输出一个可运行的 Python MCP 服务器。论文 Algorithm 1 与第 3.3 节描述如下流程：

1. **输入解析与方言识别**：自动检测 YAML/JSON 与 OpenAPI 2.0/3.0，确定 base URL（2.0 用 `schemes+host+basePath`，3.0 用 `servers[0]`）。
2. **规范归一化与内联**：递归解析 `$ref`、合并版本差异、清洗标识符、修复重复 `operationId` 等。
3. **认证分析与 `.env` 生成**：识别 `apiKey`、`http basic`、`bearer`、`oauth2` 等安全方案，生成环境变量模板；OAuth2 还额外生成 `oauth_login_server.py` 处理登录回调。
4. **Handler 合成**：每个端点生成一个 Python 函数，用 `@mcp.tool(...)` 装饰，负责输入校验、注入认证、发起 `requests` HTTP 调用、返回解析后的响应。
5. **输出布局**：输出 `server_stub.py`、`.env`、可选的 OAuth 服务器，默认用 `fastmcp.run(transport="stdio")` 运行。

> **关键设计点**：AutoMCP 不生成“智能规划”，只生成“协议翻译层”。LLM 客户端（如 Claude）负责选工具、填参数；AutoMCP 负责把参数正确变成 HTTP 请求。

下图是论文 Figure 2 的**研究方案总览**，把上面六步流程与三个研究问题（RQ1 绿 / RQ2 蓝 / RQ3 红）叠在一起：左侧“OpenAPI 规范”经编译流水线产出 MCP 服务器（RQ2），右上角 GitHub 实证刻画了当前 MCP 生态的手工现状（RQ1），右下角失败根因分析指向“规范质量”这一瓶颈（RQ3）。

![automcp_fig2_approach.png](https://developer.qcloudimg.com/http-save/yehe-11563618/5d1c8995a740e01e5979f83636d5c8d7.png)

### 2.3 端到端示例：Trello 的 create_card

论文用 Trello 展示了一次完整往返（Figure 1）：

- 输入 Trello 的 OpenAPI 规范 → AutoMCP 输出 `server_stub.py` + `.env`。
- `.env` 中自动出现 `TRELLO_API_KEY` 与 `TRELLO_API_TOKEN`（因为规范声明了 API key + token 认证）。
- Claude 作为 MCP 客户端，启动 stub 后调用 `get_capabilities`，拿到所有工具 schema；当用户说“在 Trello 创建 bug 卡片”时，Claude 选择 `create_card` 工具，填入 board ID、list ID、卡片名，通过 JSON-RPC 发送 `tool_call`。
- Stub 从 `.env` 读取凭证，向 `POST /1/cards` 发起签名请求，返回卡片 URL；Claude 再把它翻译成人话反馈给用户。

![automcp_fig1_trello_flow.png](https://developer.qcloudimg.com/http-save/yehe-11563618/1d02626dbd5ccf20522aa01294ee3227.png)

---

## 3. 实验证据：自动化行得通，但规范质量是瓶颈

### 3.1 数据集与评估方法

论文从 APIs.guru 与 Konfig 数据集中抽取 3,784 份有效 OpenAPI 规范，按 **认证方案 × 规模** 分层抽样，最终得到 50 个 API，覆盖 5,066 个端点、超过 10 个领域。由于人工测试无法穷尽 5,066 次调用，采用两阶段采样：

- **Stage 1**：17 个小型/中型 API（端点数 ≤20），穷举所有端点 → 148 次可执行请求。
- **Stage 2**：33 个大型 API，按资源组划分，用多样性分数（新 verb / 新认证 / 新参数形态）贪婪采样 → 875 次可执行请求。
- 合计 **1,023 次**工具调用作为评估集。

评估使用 Claude 作为 MCP 客户端。成功标准：manifest 能加载、工具能成功执行并返回上游 API 成功状态、结果可验证。

### 3.2 结果：开箱即用已接近 8 成，修复后接近 100%

| 结果 | 数值 |
| --- | --- |
| 50 个 API 生成服务器 | 全部成功 |
| 采样工具调用 | 1,023 次 |
| 开箱成功 | **783/1023（76.5%）** |
| 41/50 个 API | 100% 成功 |
| 失败调用 | 240 次，集中在 **9 个 API** |
| 应用最小规范补丁后 | **1022/1023（99.9%）** |
| 平均每个 API 补丁 | 约 **19 行** |

> **Finding-2**：AutoMCP 能在不手写代码的前提下，为 50 个真实 API 生成可运行 MCP 服务器；41 个 API 开箱即达 100% 工具调用成功率。

### 3.3 与官方手写服务器的覆盖度与代码量对比

论文选取了 17 个已有厂商维护的 MCP 服务器，对比 AutoMCP 生成版本：

| API | 官方端点数 | AutoMCP 端点数 | 官方 SLOC | AutoMCP SLOC |
| --- | --- | --- | --- | --- |
| Brave | 2 | 1 | — | 79 |
| Firecrawl | 8 | 5 | 8,656 | 161 |
| Exa | 8 | 7 | 12,061 | 571 |
| Huggingface | 7 | 12 | 18,063 | 377 |
| Notion | 19 | 19 | 10,592 | 609 |
| GitLab | 60 | 73 | 13,068 | 2,420 |
| Elasticsearch | 5 | 102 | 1,569 | 2,793 |
| Redis | 13 | 132 | 13,832 | 4,869 |
| Render | 18 | 166 | 36,098 | 5,515 |
| Sentry | 11 | 183 | 43,880 | 6,419 |
| GitHub | 73 | 1,038 | 10,488 | 46,135 |

> 14/17 个 API 中，AutoMCP 匹配或超过官方工具覆盖度；GitHub 上因为官方只覆盖精选子集，而 AutoMCP 直接继承完整 OpenAPI 规范，端点数多出 **1,025** 个。手写服务器的代码量从 1.5k 到 704k 不等，而生成代码全为机器胶水，中位数约 0.7k。

### 3.4 什么会破坏自动化？五类 OpenAPI 规范缺陷

RQ3 对 240 次失败做了人工根因分析（Cohen κ=0.84，一致性高），所有失败都归因于 OpenAPI 规范本身，而非 AutoMCP 或 MCP 运行时。五类缺陷如下：

| 类别 | 缺陷描述 | 占比（失败中） | 典型示例 |
| --- | --- | --- | --- |
| **A. 安全方案缺失/错误** | `securitySchemes`/`securityDefinitions` 未声明或类型错误 | 62% | GitHub 官方 spec 完全遗漏 security scheme；Apaleo 的 OAuth2 缺 `tokenUrl` |
| **B. base URL 畸形或相对** | `servers.url` 用模板变量或未解析的相对路径 | 41% | ADP 写 `{{service-root}}`，需替换为 `https://api.adp.com` |
| **C. 未文档化的运行期 header/token 前缀** | 规范没写实际 API 必需的 header 或 token 格式 | 47% | Notion 要求 `Notion-Version` 头，但 spec 缺失 |
| **E. 端点级认证缺失** | 全局有安全方案，但具体端点没标 `security` | 10% | OpenRoute 24 个端点只有 5 个标了 API key，其余 401 |
| **D. 参数类型不匹配** | 声明类型与真实 API 期望不一致 | 2% | GitLab `project_id` 声明为 integer，实际为 string |

> **Finding-3**：所有失败都可由小幅度规范修复解决。9 份问题 spec 共改 174 行，平均每个 API 19 行，即可把成功率从 76.5% 提升到 99.9%。唯一未修复的是 OpenRoute 一个健康检查端点，依赖本地引擎，属环境问题而非规范问题。

### 3.5 GitHub 案例：23 行补丁换 100% 覆盖

论文用 GitHub 官方 MCP 服务器作为最详尽的质性案例。官方手写 `list_branches` 工具需要：命名工具、写描述、声明参数、启用分页、手写 handler（认证、请求、解析、错误处理）。同一段语义在 OpenAPI 中只是一个声明式片段：`/repos/{owner}/{repo}/branches` 的 `get` 操作 + `parameters` + `responses.200`。

下面是**我从 GitHub 官方 OpenAPI 描述库（`github/rest-api-description`，即 AutoMCP 论文评估语料中 GitHub 这一份规范）直接抓取的该端点真实定义**——它正是 AutoMCP 会编译成 `list_branches` MCP 工具的源片段：

```yaml
  "/repos/{owner}/{repo}/branches":
    get:
      summary: List branches
      description: ''
      tags:
      - repos
      operationId: repos/list-branches
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/rest/branches/branches#list-branches
      parameters:
      - "$ref": "#/components/parameters/owner"
      - "$ref": "#/components/parameters/repo"
      - name: protected
        description: >-
          Setting to `true` returns only branches protected by branch
          protections or rulesets. When set to `false`, only unprotected
          branches are returned. Omitting this parameter returns all branches.
        in: query
        required: false
        schema:
          type: boolean
      - "$ref": "#/components/parameters/per-page"
      - "$ref": "#/components/parameters/page"
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/short-branch"
              examples:
                default:
                  "$ref": "#/components/examples/short-branch-with-protection-items"
          headers:
            Link:
              "$ref": "#/components/headers/link"
        '404':
          "$ref": "#/components/responses/not_found"
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: branches
        subcategory: branches
```

注意三点，它们正好呼应前文“写好契约”的主题：
1. **声明即接口**：路径模板、`get` 动作、参数列表、成功响应 schema 全部机器可读、自洽；AutoMCP 消费这一段一次，就能合成 JSON-Schema 输入、自动接线认证、生成 handler。
2. **`$ref` 到 components**：`owner`/`repo`/`per-page`/`page` 参数与 `short-branch` 响应都靠 `$ref` 复用——这正是 AutoMCP 编译流程里“递归内联 `$ref`”那一步要处理的内容（见第 2.2 节）。
3. **缺的就是 security**：这段片段里你找不到任何 `security` 标注——这正是论文指出的 GitHub 官方 spec 的“已知限制”（公开 issue #237），也正是那 23 行补丁要补的东西。

GitHub 官方 OpenAPI 规范自己承认遗漏了 security scheme（公开 issue）。作者补了 23 行安全方案后，AutoMCP 对 GitHub 全部 1,038 个操作达到 100% 覆盖。这再次印证：**复杂工具的手写成本与规范覆盖度之间的差距，不是来自技术难度，而是来自规范不完整**。

---

## 4. 与 RestGPT 的对比与后续启示

### 4.1 两篇论文其实站在同一根“OpenAPI”枝干上

前文研究的 **RestGPT**（Song et al., 2023）证明：OpenAPI 规范里的字段可以分发给 Planner / API Selector / Caller / Parser，让 LLM 在有限上下文里选对 API、填对参数、从复杂 JSON 中抽值。RestGPT 的“利用规范”发生在 **LLM 客户端侧**。

**AutoMCP**（2025）则证明：同一份 OpenAPI 规范可以静态编译成 **MCP 服务器侧**的可运行基础设施。它把 RestGPT 时代“人工写 handler”的工作也自动化了。

两者共同说明：OpenAPI 规范作为“通用语义接口契约”的价值，正在从**“被 LLM 读取的文档”**扩展到**“被编译器消费的自动化源文件”**。

### 4.2 对实践的启示

1. **对 API 提供者**：维护一份准确、完整、可机器消费的 OpenAPI 规范，正在成为“让 AI  agent 能调用我”的最低成本路径。规范缺失的认证、错误的类型、未声明的 header，都会直接变成自动化的失败点。
2. **对 agent/LLM 开发者**：构建 agent 时，优先检查 OpenAPI 规范质量；如果规范干净，AutoMCP 这类工具可以替代大量手工服务器开发。
3. **对研究方向**：
   - 自动检测并修复 OpenAPI 规范中的五类缺陷（安全方案、base URL、header、端点级认证、参数类型）。
   - 把 RestGPT 的“客户端规划”与 AutoMCP 的“服务器生成”结合，形成端到端 OpenAPI → agent 工具生态。

### 4.3 局限

论文自身也指出：
- 评估仅覆盖 50 个 API，虽经分层抽样，但存在外部效度边界。
- 部分 API 的运行期行为（如未文档化的 header、私有认证流）无法被规范捕获。
- 手写服务器可能故意省略不稳定或内部端点，并加入自定义 convenience action，这些是自动生成无法替代的。

---

## 5. 结论

AutoMCP 这篇论文的实质贡献是：**把 OpenAPI 从“文档格式”重新定义为“可编译的集成契约”**。它用 50 个真实 API、5,066 个端点、1,023 次工具调用的证据说明：只要 OpenAPI 规范足够准确，MCP 服务器的代码生成可以接近完全自动化；而失败几乎全部来自规范质量，而非生成器本身。这直接指向一句可操作的结论——

> **通往 agent-ready 的最快路径，不是写更多代码，而是写好契约。**

一份完整声明了认证、base URL、参数类型、响应 schema 的 OpenAPI 规范，就是通往 LLM 原生工具生态的通行证。

---

## 附：论文 ↔ 工程要点 速查

| 论文要点 | 工程含义 |
| --- | --- |
| MCP 服务器仍手写、重复、样板化 | 5% GitHub 仓库有服务器，且多为单人 920 SLOC 小项目 |
| AutoMCP 编译 OpenAPI → MCP server | 一次命令行即可生成 `server_stub.py` + `.env` + OAuth 登录服务器 |
| 每个端点 → 一个 `@mcp.tool` handler | 输入/输出 schema 直接来自 OpenAPI parameters / responses |
| 开箱 76.5% → 修规范后 99.9% | 失败根因全部在规范：安全方案、base URL、header、端点认证、参数类型 |
| 手写 vs 生成：14/17 覆盖度持平或超越，代码量少 1–4 个数量级 | 手写服务器往往只覆盖精选端点，且需要大量重复胶水代码 |
| 与 RestGPT 的关系 | RestGPT 用 OpenAPI 做客户端规划；AutoMCP 用 OpenAPI 做服务端生成，互补 |


研究对象：Mastouri, Ksontini & Kessentini, Making REST APIs Agent-Ready: From OpenAPI to Model Context Protocol Servers for Tool-Augmented LLMs, arXiv:2507.16044v1（2025-07） 论文地址：https://arxiv.org/abs/2507.16044 复现包与数据集：https://sites.google.com/view/automcp 研究焦点：OpenAPI 规范能否直接“编译”成 MCP 服务器，以及是什么在阻挡自动化。

论文研究：通往 agent-ready 的最快路径是写好契约

AutoMCP 这篇论文的实质贡献是：把 OpenAPI 从“文档格式”重新定义为“可编译的集成契约”。

编程语言

人工智能

后端

AutoMCP研究将OpenAPI规范编译为MCP服务器，实现REST API自动化集成。实验证明76.5%调用成功率，修复规范后达99.9%。关键发现：OpenAPI规范质量是自动化瓶颈，五类缺陷影响集成。研究显示写好OpenAPI契约比编写胶水代码更高效，为LLM工具生态提供自动化解决方案。

代码解释

服务器

编译器

Python

GitHub

OAuth

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

论文研究：通往 agent-ready 的最快路径是写好契约-腾讯云开发者社区-腾讯云

论文研究：通往 agent-ready 的最快路径是写好契约

论文研究：通往 agent-ready 的最快路径是写好契约

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐