使用说明

openapi到mcp

根据OpenAPI规范生成模型上下文协议（MCP）服务器。将任何REST API转换为MCP服务器，以便与ChatGPT和Claude等人工智能助手一起使用。

概述

openapi-to-mcp 是一个代码生成工具，可以根据OpenAPI/Swagger规范自动创建MCP（模型上下文协议）服务器。它使人工智能助手能够通过将OpenAPI操作转换为MCP工具来与任何REST API交互。

特性

符合MCP 2025标准：完全支持MCP 2025第1阶段规范
- 具有默认值的JSON模式2020-12
- 符合MCP的工具命名
- 刀具级错误处理
- OAuth2范围提取和管理
自动代码生成：将OpenAPI规范转换为功能齐全的MCP服务器
多种运输方式：支持stdio和HTTP传输
身份验证支持：处理API密钥、承载令牌和无身份验证API
类型安全：生成具有正确类型定义的TypeScript代码
Web用户界面：包括MCP Hub，一个用于生成和部署MCP服务器的web界面
Cloudflare员工：将生成的MCP服务器直接部署到Cloudflare Workers
OpenAPI 2.0和3.0：支持Swagger 2.0和OpenAPI 3.0规范

快速开始

安装

选项1：全局安装CLI（推荐）

npm install -g @agentoauth/mcp

选项2：与npx一起使用（无需安装）

npx @agentoauth/mcp generate <openapi-spec>

选项3：克隆和开发

# Clone the repository
git clone https://github.com/yourusername/openapi-to-mcp.git
cd openapi-to-mcp

# Install dependencies
npm install

CLI使用情况

这 mcp CLI提供了一个简单、初学者友好的界面：

# Simple usage - auto-detects service name, auth, and base URL
mcp generate examples/petstore-openapi.json

# Specify output directory
mcp generate examples/petstore-openapi.json --out my-mcp-server

# With authentication
mcp generate examples/stripe-openapi.json \
  --out stripe-mcp \
  --auth-type bearer \
  --auth-env STRIPE_SECRET_KEY

# Build and run generated server
mcp serve ./stripe-mcp

智能默认值：

自动检测OpenAPI规范中的服务名称
自动检测来自安全方案的身份验证
从服务器自动检测API基本URL
适用于90%的用例，无需额外选项

请参阅 mcp自述以获取完整的文档。

传统CLI（开发模式）

对于开发或高级使用，您仍然可以使用原始CLI：

# Basic usage (stdio transport)
npm run dev -- \
  --openapi examples/petstore-openapi.json \
  --out my-mcp-server \
  --service-name petstore

# With HTTP transport (for Cloudflare Workers)
npm run dev -- \
  --openapi https://api.weather.gov/openapi.json \
  --out weather-mcp \
  --service-name weather \
  --transport http \
  --api-base-url https://api.weather.gov

Web用户界面（MCP Hub）

该项目包括一个用于生成和部署MCP服务器的web界面：

# Start the backend
cd apps/mcp-hub
npm install
npm run dev

# In another terminal, start the frontend
cd apps/mcp-hub/client
npm install
npm run dev

打开http://localhost:5173在浏览器中使用MCP Hub。

例子

请参阅 examples/ 例如OpenAPI规范和生成的MCP服务器。

示例：Petstore API

# Using mcp CLI (recommended)
mcp generate examples/petstore-openapi.json --out petstore-mcp
cd petstore-mcp
npm install
npm run build
export API_BASE_URL="https://petstore3.swagger.io/api/v3"
node dist/index.js

示例：Stripe API

# Generate with authentication
mcp generate examples/stripe-openapi.json \
  --out stripe-mcp \
  --service-name stripe \
  --auth-type bearer \
  --auth-env STRIPE_SECRET_KEY

# Build and test
cd stripe-mcp
npm install
npm run build
export API_BASE_URL="https://api.stripe.com"
export STRIPE_SECRET_KEY="sk_test_your_key"
node dist/index.js

示例：天气API

# Using mcp CLI
mcp generate https://api.weather.gov/openapi.json \
  --out weather-mcp \
  --service-name weather \
  --transport http \
  --api-base-url https://api.weather.gov

用法

mcp命令行界面（推荐）

这 mcp CLI提供了一个具有智能默认值的简单界面。请参阅完整的mcp文档了解详情。

快速参考：

# Generate MCP server
mcp generate <openapi-spec> [--out <dir>] [--force]

# With authentication
mcp generate <openapi-spec> \
  --auth-type bearer \
  --auth-env TOKEN_NAME

# Build and run
mcp serve <generated-directory>

简单选项：

-o, --openapi <path> -OpenAPI规范路径或URL
--out <dir> -输出目录（默认： ./generated-mcp)
--force -覆盖输出目录（如果存在）

高级选项 （使用 mcp --help-all 查看全部）：

--transport <type> -传输方式：stdio或http
--auth-type <type> -身份验证类型：无、apiKey或承载
--auth-header <name> -身份验证标头名称
--auth-env <name> -身份验证令牌的环境变量名称
--api-base-url <url> -用于HTTP传输的API基本URL
--config <file> -转换配置文件的路径
--include-tags <tags> -以逗号分隔的标签列表
--exclude-tags <tags> -以逗号分隔的要排除的标签列表
--include-paths <paths> -以逗号分隔的路径模式列表
--exclude-paths <paths> -以逗号分隔的要排除的路径模式列表
--service-name <name> -服务名称（如果未提供，则自动检测）

转换工具

您可以使用CLI标志或配置文件过滤和自定义哪些操作成为MCP工具。

使用CLI标志

按标签或路径筛选操作：

# Include only operations with "pet" or "store" tags
mcp generate examples/petstore-openapi.json \
  --include-tags "pet,store" \
  --out petstore-mcp

# Exclude admin and internal paths
mcp generate examples/petstore-openapi.json \
  --exclude-paths "/admin/*,/internal/*" \
  --out petstore-mcp

使用配置文件

创建一个 mcp.config.yaml 文件以获得更多控制：

# Include only operations with the "pet" tag
includeTags:
  - pet

# Exclude admin/internal paths
excludePaths:
  - /admin/*
  - /internal/*

# Per-operation overrides
tools:
  findPetsByStatus:
    name: listPets
    description: "List available pets filtered by status"

  getPetById:
    name: getPet
    description: "Get a pet by its ID"

  # Disable operations you don't want
  deletePet:
    enabled: false

然后使用它：

mcp generate examples/petstore-openapi.json \
  --config examples/petstore/mcp.config.yaml \
  --out petstore-mcp

看 examples/petstore/mcp.config.yaml 举一个完整的例子。

本地模式与云部署

该项目支持两种运营模式：

本地模式

目的：在本地生成MCP服务器，无需部署Cloudflare。

特性:

根据OpenAPI规范生成MCP项目
预览生成的代码
将项目下载为zip文件
在自己的环境中跑步
不需要Cloudflare帐户

用法:

集 MODE=local 在环境中（或使用默认值）
使用MCP Hub web UI或CLI
项目已生成，但不会自动部署

云部署（可选）

目的：自动将生成的MCP服务器部署到Cloudflare Workers。

需求:

Cloudflare帐户
环境变量： ENABLE_CLOUDFLARE_DEPLOY=true
Cloudflare凭据（可选，牧者可以使用本地配置）

安全:

默认情况下，部署已禁用 出于安全考虑
仅在以下情况下启用 ENABLE_CLOUDFLARE_DEPLOY=true 已明确设置
使用您自己的Cloudflare凭据（从未硬编码）
前端检查功能，仅在启用时显示部署按钮

设置:

复制 apps/mcp-hub/.env.example 到 apps/mcp-hub/.env
集 ENABLE_CLOUDFLARE_DEPLOY=true
配置Cloudflare凭据（或使用wrangler的本地配置）
部署按钮将出现在UI中

备注：从不承诺 .env 具有版本控制凭据的文件。

生成的项目结构

my-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── tools.ts          # Generated tool definitions
├── package.json
├── tsconfig.json
└── README.md

运行生成的MCP服务器

标准输入输出传输

cd my-mcp-server
npm install
npm run build
API_BASE_URL="https://api.example.com" npm start

HTTP传输（Cloudflare Workers）

cd my-mcp-server
npm install
npm run build
npx wrangler deploy

对于需要身份验证的API，将令牌设置为Cloudflare Worker密钥：

npx wrangler secret put API_TOKEN

精心策划的基准

这些OpenAPI规范定期进行测试 npm run bench:

API	来源	工具（约）
Petstore v3	示例/Petstore-openapi.json	19
Petstore v2	示例/Petstore-v2-openapi.json	20
Weather.gov	示例/Weather-openapi.json	2
GitHub	GitHub REST OpenAPI	约1100
Slack	Slack Web API OpenAPI	~ 170
条纹	条纹API OpenAPI	~ 580
Twilio	Twilio API OpenAPI	~190
Kubernetes	Kubernetes上游OpenAPI	~1050
DigitalOcean	官方数字海洋OpenAPI	~540

跑 npm run bench 以测试所有规格，并验证生成器在不同的API格式和大小下正确工作。

建筑

该项目采用模块化架构：

packages/mcp/：用于生成和运行MCP服务器的简单CLI（推荐）
packages/cli/：旧版命令行界面（用于开发）
packages/core/：核心域类型(mcp-core 包装）
packages/generator/：核心代码生成逻辑
packages/templates/：生成代码的Handlebars模板
apps/mcp-hub/：用于生成和部署MCP服务器的Web UI
examples/：OpenAPI规范示例

有关详细的体系结构文档，请参阅 docs/ARCHITECTURE.md.

项目结构

openapi-to-mcp/
├── packages/              # Core packages
│   ├── mcp/          # Simple CLI (recommended)
│   │   ├── src/
│   │   │   └── index.ts # CLI entry point
│   │   └── README.md    # CLI documentation
│   ├── core/            # Core domain types
│   │   └── src/
│   │       └── index.ts # Shared types and generator wrapper
│   ├── cli/             # Legacy command-line interface
│   │   └── src/
│   │       └── index.ts # Legacy CLI entry point
│   ├── generator/        # Code generation engine
│   │   └── src/
│   │       ├── openapiLoader.ts      # OpenAPI spec loading
│   │       ├── operationExtractor.ts # Extract API operations
│   │       ├── toolInferer.ts        # Convert operations to MCP tools
│   │       ├── schemaUtils.ts        # Schema conversion utilities
│   │       ├── projectRenderer.ts    # stdio transport renderer
│   │       └── httpRenderer.ts        # HTTP transport renderer
│   └── templates/        # Handlebars templates
│       ├── *.hbs         # stdio transport templates
│       └── http/         # HTTP transport templates
├── apps/                 # Applications
│   └── mcp-hub/         # Web UI for MCP generation
│       ├── src/         # Backend (Express server)
│       └── client/      # Frontend (React + Vite)
├── examples/            # Example OpenAPI specifications
│   ├── petstore-openapi.json
│   ├── stripe-openapi.json
│   ├── slack-openapi.json
│   └── README.md
├── docs/                # Documentation
│   ├── QUICKSTART.md
│   └── ARCHITECTURE.md
├── scratch/             # Generated/test projects (gitignored)
├── LICENSE              # MIT License
├── README.md            # This file
├── CONTRIBUTING.md      # Contribution guidelines
└── package.json         # Root package configuration

密钥目录

packages/mcp/：用于生成和运行MCP服务器的简单CLI（建议用户使用）
packages/core/：核心域类型(mcp-core npm包）
packages/generator/：代码生成引擎
packages/cli/：遗留CLI（用于开发）
apps/：包含独立应用程序（如MCP Hub web UI）
examples/：用于测试和演示的OpenAPI规范示例
docs/：项目文件
scratch/：生成项目的临时目录（git除外）

文档

mcp CLI指南：完整的指南 mcp 命令行界面
测试生成的MCP服务器：如何测试生成的服务器
测试松弛MCP：Slack特定测试指南
快速入门指南：分步教程
建筑：技术细节和设计决策
贡献：如何为项目做出贡献
GitHub设置：GitHub存储库设置和工作流程指南
Git指南：Git命令和工作流

构建和编译

先决条件

Node.js 18或更高版本
npm（附带Node.js）

构建步骤

# 1. Clone the repository
git clone https://github.com/yourusername/openapi-to-mcp.git
cd openapi-to-mcp

# 2. Install dependencies
npm install

# 3. Build the project (compiles TypeScript to JavaScript)
npm run build

构建过程编译中的所有TypeScript文件 packages/ JavaScript在 dist/ 目录。

发展模式

对于开发，您可以直接运行CLI，而无需构建：

# Run CLI in development mode (uses ts-node)
npm run dev -- --openapi examples/petstore-openapi.json --out test-output

类型检查

在不构建的情况下检查TypeScript错误：

npm run type-check

构建单个包

该项目使用单仓库结构。要构建特定包，请执行以下操作：

# Build CLI package
cd packages/cli
npm run build  # if package.json has build script

# Build generator package
cd packages/generator
npm run build  # if package.json has build script

测试

运行测试

目前，该项目使用手动测试。以下是如何测试代码生成：

1.生成测试MCP服务器

# Generate Petstore MCP (included example)
npm run cli:generate:petstore

这将在中创建一个测试MCP服务器 scratch/petstore-mcp-cli/.

2.构建生成的服务器

cd scratch/petstore-mcp-cli
npm install
npm run build

3.使用MCP客户端脚本进行测试

# From project root
npm run test:mcp

这运行 scripts/test-mcp-client.ts，其中：

生成生成的MCP服务器
发送JSON-RPC请求以执行工具
验证响应

4.MCP检查员测试（推荐）

cd scratch/petstore-mcp-cli
API_BASE_URL="https://petstore3.swagger.io/api/v3" \
  npx @modelcontextprotocol/inspector node dist/index.js

这将启动一个web UI，您可以在其中：

浏览可用工具
使用不同参数执行工具
查看请求/响应日志

5.手动JSON-RPC测试

cd scratch/petstore-mcp-cli
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
  API_BASE_URL="https://petstore3.swagger.io/api/v3" node dist/index.js

测试不同场景

使用HTTP传输进行测试

# Generate HTTP transport MCP
npm run dev -- \
  --openapi https://api.weather.gov/openapi.json \
  --out test-weather-mcp \
  --service-name weather \
  --transport http \
  --api-base-url https://api.weather.gov

# Build and deploy
cd test-weather-mcp
npm install
npm run build
npx wrangler deploy

使用身份验证进行测试

# Generate MCP with bearer token auth
npm run dev -- \
  --openapi https://api.github.com/openapi.json \
  --out test-github-mcp \
  --service-name github \
  --transport http \
  --api-base-url https://api.github.com \
  --auth-type bearer \
  --auth-env GITHUB_TOKEN

# Build, deploy, and set secret
cd test-github-mcp
npm install
npm run build
npx wrangler deploy
npx wrangler secret put GITHUB_TOKEN

建造和测试

建设项目

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Type check without building
npm run type-check

构建过程编译中的所有TypeScript文件 packages/ JavaScript在 dist/ 目录。

测试

类型检查

# Check for TypeScript errors
npm run type-check

测试CLI

生成测试MCP服务器：

# Generate Petstore MCP (included example)
npm run cli:generate:petstore

构建并测试生成的服务器：

cd scratch/petstore-mcp-cli
npm install
npm run build

使用MCP客户端脚本进行测试：

# From project root
npm run test:mcp

这运行 scripts/test-mcp-client.ts，其中：

生成生成的MCP服务器
发送JSON-RPC请求以执行工具
验证响应

MCP检查员测试（推荐）：

cd scratch/petstore-mcp-cli
API_BASE_URL="https://petstore3.swagger.io/api/v3" \
  npx @modelcontextprotocol/inspector node dist/index.js

这将启动一个web UI，您可以在其中：

浏览可用工具
使用不同参数执行工具
查看请求/响应日志

手动JSON-RPC测试：

cd scratch/petstore-mcp-cli
echo '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' | \
  API_BASE_URL="https://petstore3.swagger.io/api/v3" node dist/index.js

测试MCP集线器

启动后端：

cd apps/mcp-hub
npm install
npm run dev

启动前端（在另一个终端中）：

cd apps/mcp-hub/client
npm install
npm run dev

测试API端点：

# Health check
curl http://localhost:4000/health

# Mode detection
curl http://localhost:4000/api/mode

# Capabilities check
curl http://localhost:4000/api/capabilities

# Extract operations (dry run)
curl -X POST http://localhost:4000/api/operations \
  -H "Content-Type: application/json" \
  -d '{"openapiUrlOrText": "examples/petstore-openapi.json"}'

# Generate MCP (public mode)
curl -X POST http://localhost:4000/api/generate-mcp \
  -H "Content-Type: application/json" \
  -d '{
    "openapiUrlOrText": "examples/petstore-openapi.json",
    "serviceName": "petstore"
  }'

使用转换配置进行测试：

# Generate with transform
curl -X POST http://localhost:4000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "openapiUrlOrText": "examples/petstore-openapi.json",
    "serviceName": "petstore",
    "transport": "http",
    "transform": {
      "includeTags": ["pet"],
      "tools": {
        "findPetsByStatus": {
          "name": "listPets",
          "description": "List available pets"
        }
      }
    }
  }'

测试生成的MCP服务器

stdio传输：

cd scratch/petstore-mcp-cli
npm install
npm run build
API_BASE_URL="https://petstore3.swagger.io/api/v3" npm start

服务器在stdin/stdout上监听JSON-RPC请求。

HTTP传输（Cloudflare Workers）：

cd scratch/petstore-mcp-cli
npm install
npm run build
npx wrangler deploy

测试部署的工作程序：

curl -X POST https://your-worker.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

调试脚本

该项目包括用于开发的调试脚本：

# Debug OpenAPI parsing
npm run debug:parse

# Debug tool inference
npm run debug:tools

# Debug stdio generation
npm run debug:generate

# Debug HTTP generation
npm run debug:generate:http

测试检查表

在提交更改之前，请验证：

[ ] npm run type-check 通过
[ ] npm run build 无错误地完成
[ ] npm run cli:generate:petstore 生成成功
[]生成的MCP服务器构建(cd scratch/petstore-mcp-cli && npm run build)
[ ] npm run test:mcp 成功执行
[]MCP Hub后端启动时没有错误
[]MCP Hub前端启动时没有错误
[]API端点响应正确

发展

# Build the project
npm run build

# Type check
npm run type-check

# Run CLI in development mode
npm run dev -- --openapi examples/petstore-openapi.json --out test-output

# Lint code (when configured)
npm run lint

# Format code (when configured)
npm run format

贡献

欢迎投稿！请阅读我们的贡献指南有关我们的行为准则和提交pull请求流程的详细信息。

快速Git参考

# Clone the repository
git clone https://github.com/yourusername/openapi-to-mcp.git
cd openapi-to-mcp

# Create a feature branch
git checkout -b feature/your-feature-name

# Make changes, then commit
git add .
git commit -m "feat: Add new feature"

# Push to your fork
git push origin feature/your-feature-name

有关Git的详细说明，请参阅 Git指南.

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

使用说明

openapi到mcp

概述

特性

快速开始

安装

CLI使用情况

传统CLI（开发模式）

Web用户界面（MCP Hub）

例子

示例：Petstore API

示例：Stripe API

示例：天气API

用法

mcp命令行界面（推荐）

转换工具

使用CLI标志

使用配置文件

本地模式与云部署

本地模式

云部署（可选）

生成的项目结构

运行生成的MCP服务器

标准输入输出传输

HTTP传输（Cloudflare Workers）

精心策划的基准

建筑

项目结构

密钥目录

文档

构建和编译

先决条件

构建步骤

发展模式

类型检查

构建单个包

测试

运行测试

1.生成测试MCP服务器

2.构建生成的服务器

3.使用MCP客户端脚本进行测试

4.MCP检查员测试（推荐）

5.手动JSON-RPC测试

测试不同场景

使用HTTP传输进行测试

使用身份验证进行测试

建造和测试

建设项目

测试

类型检查

测试CLI

测试MCP集线器

测试生成的MCP服务器

调试脚本

测试检查表

发展

贡献

快速Git参考

许可证

相关项目

相关 MCP

网页搜索MCP服务器

Zotero文献库搜索与阅读MCP服务

Prometheus 指标查询 MCP 服务器

SSH远程命令执行MCP服务器

电话服务 MCP 服务器

Unity MCP AI游戏开发工具