Openapi Spec MCP Server

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

建筑

核心组件

1. MCP服务器核心 (src/core/mcp-server.ts)

- 处理MCP协议通信 - 管理工具注册和执行 - 协调规范加载和缓存

1. OpenAPI客户端 (src/core/openapi-client.ts)

- 从URL获取规格 - 处理重试和错误恢复 - 解析$ref引用 - 验证OpenAPI格式

1. 缓存管理器 (src/core/cache-manager.ts)

- 用于热数据的LRU内存缓存 - 压缩磁盘缓存以实现持久性 - ETag/上次修改对条件请求的支持 - 自动缓存失效

1. 工具 (src/tools/)

- 模块化工具实施 - 一致性基础工具类 - 模式验证和错误处理

缓存策略

• 内存缓存：快速访问常用规格
• 磁盘缓存：使用gzip压缩的持久存储
• HTTP缓存：尊重ETags和上次修改的标头
• 基于TTL的到期：可配置缓存寿命

支持的版本

• Swagger 2.0（为兼容而自动转换）
• OpenAPI 3.0.x
• OpenAPI 3.1.x

错误处理

服务器实现了全面的错误处理：

• 指数回退重试的网络错误
• 当规格部分无效时，性能会下降
• 网络不可用时缓存回退
• 调试的详细错误消息

性能优化

• 规范部分的延迟加载
• 使用Fuse.js进行高效模糊搜索
• 请求重复数据删除
• HTTP请求的连接池
• 压缩缓存存储

安全考虑

• URL验证和净化
• 请求超时限制
• 安全的JSON/YAML解析
• 不执行任意代码
• 安全处理身份验证令牌

贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

麻省理工学院

支持

有关问题、疑问或建议，请在GitHub上打开问题。