Vims OpenAPI MCP服务器
一个模型上下文协议（MCP）服务器，提供与OpenAPI规范交互的工具。此服务器允许Claude和其他MCP客户端从OpenAPI规范中动态获取、探索和生成代码，而无需将整个规范加载到上下文中。
特性
- 动态规格加载：从任何URL获取OpenAPI规范
- 智能高速缓存：LRU内存缓存+带压缩的持久磁盘缓存
- 综合工具:
- 列出和搜索端点 - 获取详细的端点信息 - 探索模式定义 - 生成多种语言的代码片段 - 根据架构验证请求 - 获取API元数据和统计信息
- 多语言支持：使用JavaScript、TypeScript、Python、cURL和Axios生成代码
- 请求验证：根据OpenAPI模式验证请求参数和主体
- 模糊搜索：在多个字段中使用模糊匹配搜索端点
安装
# Clone the repository
git clone https://github.com/vimalprakashts/openapi-spec-mcp-server.git
cd openapi-spec-mcp-server
# Install dependencies
npm install
# Build the project
npm run build用法
命令行
# Run with npx (recommended)
npx vims-openapi-mcp --url https://api.example.com/openapi.json
# Run with custom cache settings
npx vims-openapi-mcp --url https://api.example.com/openapi.json --cache-ttl 7200 --cache-dir ./my-cache
# Run with all options
npx vims-openapi-mcp \
--url https://api.example.com/openapi.json \
--cache-ttl 3600 \
--cache-dir .cache \
--log-level info \
--max-cache-size 100 \
--request-timeout 30000 \
--retry-attempts 3 \
--retry-delay 1000环境变量
export OPENAPI_URL=https://api.example.com/openapi.json
export CACHE_TTL=3600
export CACHE_DIR=.cache
export LOG_LEVEL=info
export MAX_CACHE_SIZE=100
export REQUEST_TIMEOUT=30000
export RETRY_ATTEMPTS=3
export RETRY_DELAY=1000
node dist/index.js配置文件
创建 openapi-mcp.config.json 项目根目录中的文件：
{
"openApiUrl": "https://api.example.com/openapi.json",
"cacheTtl": 3600,
"cacheDir": ".cache",
"logLevel": "info",
"maxCacheSize": 100,
"requestTimeout": 30000,
"retryAttempts": 3,
"retryDelay": 1000
}可用的MCP工具
1. list_endpoints
列出所有具有可选筛选功能的API端点。
参数：
tag（字符串，可选）：按标签筛选method（字符串，可选）：按HTTP方法筛选deprecated（布尔值，可选）：包括/排除已弃用的端点limit（数字，可选）：最大结果（默认值：100）offset（数字，可选）：跳过结果（默认值：0）
例子：
{
"tool": "list_endpoints",
"arguments": {
"method": "GET",
"limit": 20
}
}2. get_endpoint_details
获取特定端点的详细信息。
参数：
path（字符串，必需）：API终结点路径method（string，必填）：HTTP方法
例子：
{
"tool": "get_endpoint_details",
"arguments": {
"path": "/users/{id}",
"method": "GET"
}
}3. search_endpoints
使用模糊匹配搜索端点。
参数：
query（字符串，必填）：搜索查询searchIn（数组，可选）：要搜索的字段limit（数字，可选）：最大结果（默认值：20）
例子：
{
"tool": "search_endpoints",
"arguments": {
"query": "user",
"searchIn": ["path", "summary"]
}
}4. get_schemas
从OpenAPI规范中获取模式定义。
参数：
schemaName（字符串，可选）：特定架构名称listAll（boolean，可选）：列出所有模式名称
例子：
{
"tool": "get_schemas",
"arguments": {
"schemaName": "User"
}
}5. generate_code
生成API终结点的代码段。
参数：
path（字符串，必需）：API终结点路径method（string，必填）：HTTP方法language（字符串，必填）：编程语言（javascript、typescript、python、curl、axios）includeAuth（布尔值，可选）：包括身份验证baseUrl（字符串，可选）：覆盖基本URL
例子：
{
"tool": "generate_code",
"arguments": {
"path": "/users/{id}",
"method": "GET",
"language": "python",
"includeAuth": true
}
}6. validate_request
根据OpenAPI模式验证请求。
参数：
path（字符串，必需）：API终结点路径method（string，必填）：HTTP方法params（对象，可选）：查询和路径参数headers（object，可选）：请求标头body（任意，可选）：请求正文
例子：
{
"tool": "validate_request",
"arguments": {
"path": "/users",
"method": "POST",
"body": {
"name": "John Doe",
"email": "john@example.com"
}
}
}7. get_api_info
获取有关API的一般信息。
参数： 无
例子：
{
"tool": "get_api_info",
"arguments": {}
}8. refresh_spec
从服务器刷新OpenAPI规范。
参数：
url（字符串，可选）：要从中获取的URL（如果未提供，则使用配置的URL）
例子：
{
"tool": "refresh_spec",
"arguments": {
"url": "https://api.example.com/openapi.json"
}
}与Claude Code CLI集成
有关将此MCP服务器与Claude Code CLI一起使用的详细说明，请参阅 CLAUDE_CODE_USAGE.md.
快速设置：
# Add the server (after publishing to npm)
claude mcp add openapi-prod -- npx vims-openapi-mcp --url https://api.example.com/openapi.json
# Or use local build
claude mcp add openapi-dev -- node /path/to/dist/index.js --url http://localhost:8080/swagger/doc.json与Claude Desktop集成
将此服务器添加到您的Claude Desktop配置中：
macOS
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"openapi": {
"command": "npx",
"args": ["vims-openapi-mcp", "--url", "https://api.example.com/openapi.json"]
}
}
}视窗
编辑 %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"openapi": {
"command": "npx",
"args": ["vims-openapi-mcp", "--url", "https://api.example.com/openapi.json"]
}
}
}发展
# Install dependencies
npm install
# Run in development mode with hot reload
npm run dev
# Build for production
npm run build
# Run tests
npm test
# Clean build artifacts
npm run clean建筑
核心组件
- MCP服务器核心 (
src/core/mcp-server.ts)
- 处理MCP协议通信 - 管理工具注册和执行 - 协调规范加载和缓存
- OpenAPI客户端 (
src/core/openapi-client.ts)
- 从URL获取规格 - 处理重试和错误恢复 - 解析$ref引用 - 验证OpenAPI格式
- 缓存管理器 (
src/core/cache-manager.ts)
- 用于热数据的LRU内存缓存 - 压缩磁盘缓存以实现持久性 - ETag/上次修改对条件请求的支持 - 自动缓存失效
- 工具 (
src/tools/)
- 模块化工具实施 - 一致性基础工具类 - 模式验证和错误处理
缓存策略
- 内存缓存：快速访问常用规格
- 磁盘缓存：使用gzip压缩的持久存储
- HTTP缓存：尊重ETags和上次修改的标头
- 基于TTL的到期：可配置缓存寿命
支持的版本
- Swagger 2.0（为兼容而自动转换）
- OpenAPI 3.0.x
- OpenAPI 3.1.x
错误处理
服务器实现了全面的错误处理：
- 指数回退重试的网络错误
- 当规格部分无效时，性能会下降
- 网络不可用时缓存回退
- 调试的详细错误消息
性能优化
- 规范部分的延迟加载
- 使用Fuse.js进行高效模糊搜索
- 请求重复数据删除
- HTTP请求的连接池
- 压缩缓存存储
安全考虑
- URL验证和净化
- 请求超时限制
- 安全的JSON/YAML解析
- 不执行任意代码
- 安全处理身份验证令牌
贡献
欢迎投稿！拜托：
- 复刻仓库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
麻省理工学院
支持
有关问题、疑问或建议，请在GitHub上打开问题。