Openapi Schema

🚀 OpenAPI 模型上下文协议服务器

OpenAPI 模型上下文协议（MCP）服务器的主要作用是向 Claude 等大型语言模型（LLMs）公开 OpenAPI 模式信息。借助该服务器，LLM 能够通过一系列专用工具探索和理解 OpenAPI 规范。

🚀 快速开始

命令行使用

运行 MCP 服务器并指定特定的模式文件：

# 使用当前目录中的默认openapi.yaml文件
npx -y mcp-openapi-schema

# 使用相对路径的特定模式文件
npx -y mcp-openapi-schema ../petstore.json

# 使用绝对路径的特定模式文件
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml

# 显示帮助信息
npx -y mcp-openapi-schema --help

Claude 桌面集成

要将此 MCP 服务器与 Claude Desktop 一起使用，请编辑 claude_desktop_config.json 配置文件：

{
  "mcpServers": {
    "OpenAPI Schema": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-schema", "/ABSOLUTE/PATH/TO/openapi.yaml"]
    }
  }
}

配置文件位置：

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: $env:AppData\Claude\claude_desktop_config.json

Claude Code 集成

要将此 MCP 服务器与 Claude Code CLI 一起使用，请按照以下步骤操作：

1. 将 OpenAPI Schema MCP 服务器添加到 Claude Code

# 基本语法
claude mcp add openapi-schema npx -y mcp-openapi-schema

# 示例带有特定模式文件
claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml

2. 验证注册的服务器

# 列出所有配置的服务器
claude mcp list

# 获取您OpenAPI模式服务器的详细信息
claude mcp get openapi-schema

3. 如有需要移除服务器

claude mcp remove openapi-schema

4. 在 Claude Code 中使用工具 配置完成后，您可以在 Claude Code 会话中通过询问有关 OpenAPI 模式的问题来调用此工具。

✨ 主要特性

• 可通过命令行参数指定，加载任何指定的 OpenAPI 模式文件（JSON 或 YAML）。
• 支持探索 API 路径、操作、参数和模式。
• 能够查看请求和响应的详细模式。
• 可查找组件定义和示例。
• 支持在整个 API 规范中进行搜索。
• 以 YAML 格式获取响应，便于 LLM 更好地理解。

💻 使用示例

基本用法

命令行使用

# 使用当前目录中的默认openapi.yaml文件
npx -y mcp-openapi-schema

# 使用相对路径的特定模式文件
npx -y mcp-openapi-schema ../petstore.json

# 使用绝对路径的特定模式文件
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml

# 显示帮助信息
npx -y mcp-openapi-schema --help

高级用法

Claude Code 集成

# 基本语法
claude mcp add openapi-schema npx -y mcp-openapi-schema

# 示例带有特定模式文件
claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml

📚 详细文档

MCP 工具

该服务器为 LLM 提供了以下工具以交互 OpenAPI 模式：

• list-endpoints：列出所有 API 路径及其 HTTP 方法和摘要，以嵌套对象结构显示。
• get-endpoint：获取特定端点的详细信息，包括参数和响应。
• get-request-body：获取特定端点和方法的请求正文模式。
• get-response-schema：获取特定端点、方法和状态码的响应模式。
• get-path-parameters：获取特定路径的参数。
• list-components：列出所有组件（如 schemas, parameters 等）。
• get-component：获取特定组件的详细信息。
• list-tags：列出所有标签。
• get-tag：获取特定标签的详细信息。

示例查询

列举所有端点

operation:
  name: list-endpoints
  parameters:
    - name: filter
      type: string
      description: 过滤器条件（可选）

获取特定端点的详细信息

operation:
  name: get-endpoint
  parameters:
    - name: endpointId
      type: string
      required: true
      description: 端点ID

获取请求正文模式

operation:
  name: get-request-body
  parameters:
    - name: requestId
      type: string
      required: true
      description: 请求ID

获取响应模式

operation:
  name: get-response-schema
  parameters:
    - name: responseId
      type: string
      required: true
      description: 响应ID

示例查询

curl -X GET "http://localhost:8080/api-docs"

💡 使用建议

• 使用-s或--scope标志与project（默认）或global指定配置存储的位置。
• 为不同的 API 添加多个 MCP 服务器，并使用不同名称。