AI导哈

OpenAPI MCP工具生成器

AGDevX OpenAPI MCP Server是一款将OpenAPI规范转换为AI助手可用MCP工具的服务，支持动态生成工具、多环境切换和实时规范刷新。

  • by agdevx
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 AGDevX/OpenAPI-MCP-Server

使用说明

AGDevX OpenAPI MCP服务器

将任何OpenAPI规范转化为用于AI助手的MCP工具。将其指向API的OpenAPI/Swagger规范，您的助手可以立即与您的API交互。

特性

  • 动态工具生成 -根据OpenAPI 3.0/3.1规范自动创建MCP工具
  • 友好工具名称 -智能命名： post_api_v1_users → create_user 有有用的描述
  • 多环境支持 -根据请求在dev、qa和其他环境之间切换
  • 实时规格刷新 -无需重新启动即可更新工具
  • 速率限制 -具有可配置请求限制的内置保护
  • 两种运输方式 -stdio（最简单）或HTTP（Docker）
  • 简易安装向导 -面向非技术用户的基于Web的向导

快速入门：安装向导

配置此服务器的最简单方法是通过基于web的设置向导：

npx agdevx-openapi-mcp-server@latest setup

这将启动一个基于浏览器的向导，该向导：

  1. 指导您输入API详细信息
  2. 测试您的OpenAPI规范URL以验证其是否有效
  3. 自动检测您安装了哪些MCP客户端
  4. 自动更新配置文件（带备份）或显示要复制的内容

特征：

  • 可视化多步骤向导
  • 实时URL验证
  • 支持多种环境（开发、质量保证等）
  • 自动检测VS代码、克劳德桌面和克劳德代码
  • 具有备份或手动复制选项的安全自动更新

选项：

# Custom port
npx agdevx-openapi-mcp-server@latest setup --port 3001

# Don't auto-open browser
npx agdevx-openapi-mcp-server@latest setup --no-open

配置后，重新启动MCP客户端，服务器将可用。

手动配置

通过环境变量进行配置。使用npx时，在MCP客户端配置中设置这些。使用Docker时，将它们设置为 .env 文件。

必需设置

# Define your environments (comma-separated)
ENVIRONMENTS=dev

# OpenAPI spec URL for each environment (used ONLY to fetch the spec)
API_SPEC_URL_PDEV=https://dev-api.example.com/openapi/v1.json

# Base API URL for each environment (used for all API calls)
API_BASE_URL_DEV=https://dev-api.example.com

多个环境

ENVIRONMENTS=dev,qa
DEFAULT_ENVIRONMENT=dev

# OpenAPI spec URLs (used to fetch the spec)
API_SPEC_URL_DEV=https://dev-api.example.com/openapi/v1.json
API_SPEC_URL_QA=https://qa-api.example.com/openapi/v1.json

# Base API URLs (used for API calls)
API_BASE_URL_DEV=https://dev-api.example.com
API_BASE_URL_QA=https://qa-api.example.com

可选设置

变量 默认值 描述
MCP_SERVER_NAME agdevx-openapi-mcp-server 为服务器提供自定义名称（例如，帐户api）
MCP_VERBOSE false 启用详细日志记录
PORT 3000 HTTP传输端口（Docker）
API_TIMEOUT 30000 API请求超时（ms）
NODE_TLS_REJECT_UNAUTHORIZED 1 （已启用） TLS证书验证。设置为 0 禁用自签名证书（dev）
RATE_LIMIT_ENABLED true 启用速率限制
RATE_LIMIT_REQUESTS 10 每个窗口的最大请求数
RATE_LIMIT_WINDOW_MS 60000 速率限制窗口（ms）

看 .env.example 所有可用选项。

Docker设置（可选）

使用预构建图像

# Docker Hub
docker pull agdevx/agdevx-openapi-mcp-server:latest

# Run with docker-compose
docker-compose up -d

在当地建设

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

验证Docker部署

# Test the endpoint
curl http://localhost:3001/mcp

# Check logs for successful startup
docker-compose logs -f | grep "initialized successfully"

客户端设置

VS Code

编辑您的VS Code MCP配置文件(mcp.json):

  • 窗户： %APPDATA%\Code\User\mcp.json
  • macOS/Linux： ~/.config/Code/User/mcp.json
{
	"servers": {
		"my-api": {
			"type": "stdio",
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

重新加载VS代码： Ctrl+Shift+P → “开发人员：重新加载窗口”

克劳德桌面版

编辑您的Claude Desktop配置：

  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
{
	"mcpServers": {
		"my-api": {
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

重新启动克劳德桌面。

克劳德代码

# Add the server
claude mcp add my-api --scope user -- npx agdevx-openapi-mcp-server

# Edit config to add environment variables
claude config edit

添加到配置文件：

{
	"mcpServers": {
		"my-api": {
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

Docker（HTTP传输）

注： HTTP传输仅由VS Code和Claude Desktop支持。Claude Code不支持HTTP传输。

对于VS Code或Claude Desktop，如果使用Docker而不是npx：

VS代码（mcp.json）：

{
	"servers": {
		"my-api": {
			"type": "http",
			"url": "http://localhost:3001/mcp"
		}
	}
}

克劳德桌面（Claude_Desktop_config.json）：

{
	"mcpServers": {
		"my-api": {
			"url": "http://localhost:3001/mcp",
			"transport": "http"
		}
	}
}

克劳德代码： 不支持Docker/HTTP传输。使用 npx 使用stdio传输（请参阅上面的Claude Code部分）。

测试

问克劳德：

  • “我的API提供了哪些工具？”
  • “从我的API获取所有用户”
  • “列出所有可用环境”
  • “检查服务器状态”

特性

友好工具名称和描述

工具会以直观、友好的方式自动命名：

  • post_api_v1_users → create_user
  • get_api_v1_users → list_users
  • get_api_v1_users_id → get_user
  • put_api_v1_users_id → update_user
  • delete_api_v1_users_id → delete_user

增强的描述 包括所需参数：

  • 创建新用户。需要：姓名、电子邮件、正文
  • “获取单个用户。需要：id。”
  • “列出用户”

服务器智能地：

  • 将camelCase操作Id转换为snake_case(getUserProfile → get_user_profile)
  • 从HTTP方法+资源路径生成友好名称
  • 处理非RESTful API：解析camelCase(/searchItems)烤肉串箱(/calculate-tax)，以及RPC样式路径
  • 识别POST操作： POST /users/search → search_user （不是 create)
  • 发现 70+动作词：搜索、查询、过滤、计算、验证、激活、导出、注册、转移、合并、认证、追加销售、发布、履行、持久化、接收等。
  • 将资源名称（用户）单数化→ 用户、类别→ 类别）
  • 在描述中显示所需参数

看 FRIENDLY_NAMES.md 了解详细的示例及其工作原理。

多个环境

每个API工具都包含一个可选的 environment 参数。根据请求在环境之间切换：

# List environments
"List all available environments"

# Use specific environment
"Get account information from the dev environment"

# Compare across environments
"Get user 123 from dev, then from qa"

# See differences between environments
"What's the difference between the APIs running in dev and qa?"

# Change default environment
"Set the default environment to qa"

管理工具：

  • list_environments -查看所有已配置的环境
  • get_current_environment -检查当前默认值
  • set_default_environment -更改默认值
  • check_server_status -使用环境可达性、速率限制和工具计数进行健康检查

刷新规范而不重新启动

当您的API发生变化时，随时更新您的API规范：

"Refresh the OpenAPI spec"

这个：

  • 获取最新规格
  • 立即更新现有工具
  • 注册新操作
  • 无需重新启动

速率限制

内置滑动窗口算法保护：

  • 默认值：每60秒10个请求
  • 可通过环境变量进行配置
  • 清除带有重试时间的错误消息
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW_MS=60000

服务器状态和运行状况检查

使用监视服务器运行状况和状态 check_server_status 工具：

"Check server status"

这提供了：

  • 环境状况：显示哪些环境可以通过访问✓/✗ 指标
  • 速率限制使用：当前请求计数与重置前的时间限制
  • 可用工具：API操作和管理工具总数
  • 上次规格刷新：自上次获取OpenAPI规范以来的时间

输出示例：

Environments: 2 (dev✓, qa✗ unreachable)
Rate Limit: 3/10 requests used (resets in 45s)
Tools Available: 15
Last Spec Refresh: 2 minutes ago

使用此功能：

  • 验证所有环境是否可访问
  • 在进行批量API调用之前监控速率限制使用情况
  • 确认规格刷新正在工作
  • 更新后检查可用工具总数

故障排除

服务器无法启动

“没有有效的OpenAPI规范，无法启动MCP服务器”

  • 验证 API_SPEC_URL 是正确的 .env 或客户端配置
  • 手动测试URL： curl https://api.example.com/openapi/v1.json
  • 确保API正在运行且可访问
  • 对于自签名证书（开发/测试），设置 NODE_TLS_REJECT_UNAUTHORIZED=0 在环境变量中

Docker问题

端口已在使用中：

# Change in docker-compose.yml
ports:
 - '3002:3000' # Use different port

容器无法启动：

# Check logs
docker-compose logs -f

无法从客户端连接：

# Verify container is running
docker ps | grep agdevx-openapi-mcp-server

# Test endpoint
curl http://localhost:3001/mcp

未显示任何工具

  • 验证OpenAPI规范是否有效（OpenAPI 3.0+）
  • 确保端点具有 operationId 在规格书中
  • 检查日志： docker-compose logs -f | grep "initialized successfully"
  • 重新启动客户端应用程序

一般问题

重新启动服务器：

docker-compose restart
# or
docker-compose down && docker-compose up -d

启用详细日志记录：

MCP_VERBOSE=true

发展

运行测试

该项目包括使用Jest的全面单元测试：

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

看 测试.md 获取详细的测试文档。

建筑

# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run watch

功能增强

  • 白名单和黑名单：只允许调用特定端点，或明确阻止调用特定端点。

相关 MCP