AI导哈

OpenAPI规范交互服务器

一个提供动态获取、探索和从OpenAPI规范生成代码的工具的MCP服务器，适用于API开发与集成场景。

  • by vimalprakashts
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 vimalprakashts/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协议通信
    • 管理工具注册和执行
    • 协调规范加载和缓存

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

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

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

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

  4. 工具 (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上打开问题。

相关 MCP