Openapi®

---

概览

欢迎使用 openapi-mcp-sdk，这是官方的 openapi.com MCP SDK。 它以 Python 软件包的形式发布在 PyPI 上， 并可通过两种方式使用：

• 开箱即用的服务 — 直接通过一条命令运行软件包中的 MCP 网关， 无需克隆或设置。
• Python 库 — 在自己的项目中导入 openapi_mcp_sdk，构建自定义 MCP 服务， 在其基础上通过自定义逻辑、工具或认证层封装 openapi.com API。

环境变量

所有配置均通过环境变量完成。启动服务不需要设置任何变量——默认值适用于本地使用。

核心

变量	默认值	描述
MCP_PORT	8080	服务监听的 HTTP 端口
MCP_ENV	production	运行环境：dev | staging | production
MCP_BASE_URL	http://localhost:8080	此服务的公开 URL（用于构建回调和文件下载 URL）
MCP_CALLBACK_URL	$MCP_BASE_URL/callbacks	发送给异步 API 的显式回调 URL
MCP_OPENAPI_ENV	(empty)	Openapi 环境：dev、test、sandbox（test 的别名），或留空以使用生产环境

存储

对于返回二进制文档的 API（例如公司官方文件），服务需要存储文件。存储后端可配置：

变量	默认值	描述
MCP_STORAGE_BACKEND	local	local | gcs | s3
MCP_STORAGE_PATH	./openapi_storage	local 后端的本地路径
MCP_STORAGE_BUCKET	(cloud 环境必填)	gcs 或 s3 的存储桶名称
MCP_STORAGE_REGION	(s3 必填)	S3 存储桶的 AWS 区域

缓存

用于在多个服务实例之间共享异步回调结果。

变量	默认值	说明
MCP_CACHE_BACKEND	none	none（进程内字典）| memcached | redis
MCP_CACHE_URL	(none)	Redis 连接 URL（MCP_CACHE_BACKEND=redis），例如 redis://host:6379
MCP_CACHE_HOST	(none)	Memcached 主机（MCP_CACHE_BACKEND=memcached）
MCP_CACHE_PORT	11211	Memcached 端口

有关各环境的配置指南（本地、Docker、AWS、GCP、Kubernetes），请参阅 docs/env/。

功能

• 安全代理：透传客户端提供的 Bearer Token，无需直接处理敏感凭据。
• 可扩展：在 /apis/ 中创建模块，即可轻松添加新工具/API。
• 兼容 MCP：按照 MCP 协议最佳实践设计。
• 模块化：所有 API 调用逻辑和工具注册均集中在 mcp_core.py 中。

快速开始 — 从 PyPI 运行（推荐）

无需克隆，无需虚拟环境。只需一条命令即可启动服务：

uvx openapi-mcp-sdk server

服务会立即在 http://localhost:8080 启动。

其他运行环境

# pipx (ephemeral run, no install needed — similar to uvx)
pipx run openapi-mcp-sdk server

# pip (installs the package, then run the command)
pip install openapi-mcp-sdk && openapi-mcp-sdk server

# pip3 on systems where python3 is the default
pip3 install openapi-mcp-sdk && openapi-mcp-sdk server

CLI 参考

openapi-mcp-sdk <command>

Commands:
  server   Start the MCP server (HTTP/SSE, default port 8080)
  ping     Ping the openapi.com APIs and report latency       [coming soon]
  token    Generate or inspect an openapi.com Bearer token    [coming soon]

使用 Docker 运行

项目提供了一个包含 mcp 服务的 compose.yml。

# Build and start (production-like image)
docker compose up --build

# Run in background
docker compose up --build -d

# Follow logs
docker compose logs -f mcp

服务可通过 http://localhost:8080 访问。

调试与开发

本地开发（不使用 Docker）

最快的迭代方式是直接使用 uvicorn 运行服务：

make start

这会设置 PYTHONPATH=src 并启动禁用自动重载的 uvicorn。服务监听 http://0.0.0.0:8080。

手动测试端点：

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080

服务会将请求标头和参数打印到 stdout——无需额外配置。

使用 VS Code 和 Docker 进行远程调试（一键操作）

此代码库已预先配置好一键调试体验。 无需手动操作，无需编辑 compose 文件，也无需使用终端命令。

工作原理

文件	作用
docker/dev/Dockerfile	调试镜像 — 添加 debugpy，开放端口 5678
compose.yml	Compose 配置 — 开发镜像、调试端口、绑定挂载
.vscode/tasks.json	VS Code 任务 — 自动启动/停止容器
.vscode/launch.json	启动配置 — 按下 F5 即可完成所有设置

工作流

1. 在 src/ 中的任意位置设置断点。
2. 打开“运行和调试”（Ctrl+Shift+D / ⌘+Shift+D）。
3. 从下拉菜单中选择 MCP: Debug (Docker)。
4. 按下 F5。

VS Code 会：

• 如有需要，构建调试镜像（docker/dev/Dockerfile）。
• 通过 compose.yml 启动容器（调试镜像 + 绑定挂载）。
• 自动等待 debugpy 在端口 5678 上接受连接。
• 附加 debugpy——此时断点已生效。

按下 ⇧F5（停止）时，VS Code 会断开连接并销毁容器。

断开调试后仍要保持容器运行？ 从 .vscode/launch.json 中移除 "postDebugTask" 这一行。此后无需重新构建，再次按 F5 即可随时重新附加。

实时代码重载

compose.yml 会将 ./src 绑定挂载到容器内的 /app/src。 对 src/ 下文件的修改会立即生效——无需重新构建镜像。只需发送新请求，即可运行更新后的代码。

路径映射参考

	主机	容器
源代码	./src	/app/src
MCP 服务	localhost:8080	0.0.0.0:8080
debugpy 监听器	localhost:5678	0.0.0.0:5678

身份验证

服务支持通过以下两种方式接收 Bearer Token：

选项 A — Authorization 标头（推荐）

将令牌作为标准 HTTP 标头传递：

Authorization: Bearer YOUR_TOKEN

选项 B — ?token= 查询参数

某些 MCP 客户端或环境不支持自定义 HTTP 标头。在这种情况下，可以将令牌直接嵌入服务器 URL，作为查询参数：

http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN

服务器会在请求到达 MCP 层之前，自动将其转换为 Authorization: Bearer 标头，因此行为完全相同。

何时使用 ?token=： Claude Desktop（截至 2025 年年中）、某些基于浏览器的 MCP 体验环境，以及任何配置只接受普通 URL、不提供标头字段的客户端。

MCP 客户端配置（VS Code）

1. 生成 Bearer 令牌 从门户 https://console.openapi.com/oauth 创建一个具有所需作用域的令牌。

2. 创建 .vscode/mcp.json 文件

   使用标头（推荐）：

   {
     "servers": {
       "openapi.com": {
         "type": "http",
         "url": "http://YOUR_SERVER_IP:8080/",
         "headers": {
           "Authorization": "Bearer YOUR_TOKEN"
         }
       }
     }
   }
   

   使用 ?token= 查询参数（适用于不支持自定义标头的客户端）：

   {
     "servers": {
       "openapi.com": {
         "type": "http",
         "url": "http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN"
       }
     }
   }
   

3. 测试集成

   • 重新加载 VS Code。
   • 打开 Copilot 聊天并输入 @workspace。
   • 使用 MCP 服务提供的工具。

文件存储

某些 openapi.com API（例如 visure camerali — 意大利官方公司文件）会返回无法内嵌到 MCP 流中的大型二进制文件（ZIP 压缩包、PDF）。服务器会下载并存储这些文件，然后通过单独的 HTTP 端点提供文件（GET /status/{id}/files/{filename}）。

默认设置：本地文件系统

默认情况下（MCP_STORAGE_BACKEND=local），文件会写入相对于服务器启动目录的 ./openapi_storage：

./openapi_storage/
└── <request_id>/
    ├── document.pdf
    └── attachments.zip

使用 MCP_STORAGE_PATH 环境变量覆盖路径：

export MCP_STORAGE_PATH=/var/data/openapi_storage
uvx openapi-mcp-sdk server

首次使用时会自动创建该目录。要确保下载链接正常工作，MCP_BASE_URL 必须指向服务器的公开地址（默认值：http://localhost:8080）。

云存储后端

MCP_STORAGE_BACKEND	其他变量	说明
local	MCP_STORAGE_PATH（默认值 ./openapi_storage）	默认设置 — 本地磁盘或挂载卷
gcs	MCP_STORAGE_BUCKET	Google Cloud Storage
s3	MCP_STORAGE_BUCKET、MCP_STORAGE_REGION	AWS S3 或任何兼容 S3 的服务

有关各环境的完整配置指南，请参阅 docs/env/。

部署环境

环境	指南
本地计算机（默认）	docs/env/local.md
Docker / Docker Compose	docs/env/docker.md
Google Cloud Platform	docs/env/gcp.md
Amazon Web Services	docs/env/aws.md
Kubernetes	docs/env/kubernetes.md

项目结构

• src/openapi_mcp_sdk/main.py：FastAPI + MCP 服务入口。
• src/openapi_mcp_sdk/mcp_core.py：MCP 初始化、API 调用辅助函数、错误处理。
• src/openapi_mcp_sdk/apis/：定义 MCP 工具的 Python 模块（每个 API/作用域一个）。
• requirements.txt：Python 依赖项。
• compose.yml：Docker Compose（默认使用生产镜像；请参阅注释以切换到调试镜像）。
• docker/latest/Dockerfile：生产环境 Docker 镜像。
• docker/dev/Dockerfile：包含用于 VS Code 远程调试的 debugpy 的开发镜像。
• .vscode/launch.json：VS Code 调试配置（附加到 debugpy）。
• docs/：文档和示例配置。

添加新工具/API

1. 在 /apis/ 中创建或修改文件，并遵循以下模式：

   from fastmcp import Context
   from typing import Any
   from mcp_core import make_api_call, mcp
   
   @mcp.tool
   async def tool_name(parameters..., ctx: Context) -> Any:
       # ...logic...
       return make_api_call(ctx, "GET", url, params=params)
   

2. 重启服务器以应用更改。

安全说明

• 切勿在代码中硬编码凭据或令牌。
• 服务器要求客户端通过 HTTP 标头提供 Bearer 令牌。
• 所有 API 调用都会使用客户端提供的令牌进行代理。

实用资源

• MCP 文档
• fastmcp
• openapi.com

参与贡献

欢迎大家参与贡献！无论是报告错误、提出新功能建议、改进文档，还是贡献代码，我们都非常感谢您的帮助。

请参阅 docs/contributing.md，了解如何开始参与的详细说明。请务必遵守本项目的 docs/code-of-conduct.md，共同维护一个友好、协作的环境。

作者

认识一下本项目的作者：

• Simone Desantis (@SimoneDesantis)
• Marco Prosperi (@MarcoProsperi)
• Francesco Bianco (@francescobianco)
• Openapi Team (@openapi-it)

合作伙伴

认识一下使用 Openapi 或为此 SDK 做出贡献的合作伙伴：

• Blank
• Credit Safe
• Deliveroo
• Gruppo MOL
• Jakala
• Octotelematics
• OTOQI
• PWC
• QOMODO S.R.L.
• SOUNDREEF S.P.A.

许可证

本项目采用 MIT 许可证。

MIT 许可证是一种宽松的开源许可证，允许您自由使用、复制、修改、合并、发布、分发、再许可和／或销售本软件的副本，前提是在所有副本或软件的重要部分中保留原始版权声明和本许可声明。

简而言之，您可以自由地在个人、学术或商业项目中使用此 SDK，且限制极少。本项目按“原样”提供，不提供任何形式的明示或暗示担保，包括但不限于适销性、特定用途适用性和不侵权担保。

如需了解详情，请参阅 MIT License 页面上的完整许可证文本。