OpenAPI 搜索 MCP 服务器

这个项目是在……的协助下建成的克劳德·科德Anthropic的AI编码助手。

![Python 3.12](https://www.python.org/downloads/) ![FastMCP](https://github.com/jlowin/fastmcp) ![License: MIT](https://opensource.org/licenses/MIT)

一个强大的模型上下文协议（MCP）服务器，用于加载、解析和查询OpenAPI/Swagger文档。

特点/特性 • 快速入门 • 安装 • • 使用方法 • 建筑学

______________________________________________________________________

概述

OpenAPI搜索MCP服务器是一种专门的MCP服务器，它使OpenAPI/Swagger文档能够轻松被AI助手和其他MCP客户端访问。它提供了10个强大的工具，用于加载、搜索和查询多种格式的API规范。

为什么要使用这个？

AI友好型API文档使您的OpenAPI规范能够被Claude等AI助手查询
智能搜索跨路径、方法、标签和关键词的多标准搜索
快速查找为O(1)操作ID查询预构建索引
格式灵活性自动检测JSON和YAML格式
模块化架构遵循Python最佳实践的清晰、可维护的代码库

______________________________________________________________________

特点/特性

🔄（循环符号，无直接对应中文翻译，可理解为“循环”、“重复”或“旋转”的概念） 从URL加载 - 从任何HTTP/HTTPS端点获取OpenAPI文档
💾 代表“存储设备”或“硬盘”等意思。 内存存储 - 通过结构化文档存储实现快速访问
🔍 看起来像是一个放大镜的符号，通常用于表示搜索、查看细节或寻找隐藏内容。在中文里，它没有直接的对应文字，但可以根据上下文翻译为“🔍 搜索”、“🔍 查看细节”或“🔍 寻找隐藏内容”等。如果单独使用，也可以简单地描述为“放大镜符号”。 10个查询工具 - 全面的API探索能力
📚 书籍或学习的象征 多格式支持 - JSON和YAML，支持自动检测
🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或保持原样作为表情使用，表示快速、飞速或激动兴奋的情绪。在没有具体上下文的情况下，可以简单地将其理解为“火箭”或直接用该表情符号来传达相应的情感或氛围。 版本支持 - OpenAPI 3.0.x、3.1.x 和 Swagger 2.0
🏗️（建筑工地、施工中的标志） 分层架构 - 模块化设计，采用依赖注入
⚡（闪电符号，常用于表示快速、能量、电或警报等） 快速索引 - 预构建的操作ID和标签索引
🔐（锁形符号，常用于表示密码、保密或安全） 身份发现 - 提取安全方案和要求
🏷️ 基于标签的导航 - 按功能类别浏览API
🎯（目标） 精确搜索 - 按关键词、方法、标签或组合进行筛选

______________________________________________________________________

快速入门

# 1. Create conda environment
conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the server
python main.py

完成了！服务器现在正在运行，并准备好接受MCP连接。

______________________________________________________________________

安装

先决条件

Python 3.12 或更高版本
Conda（推荐）或 venv

步骤1：克隆仓库

git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

步骤2：创建虚拟环境

使用 Conda（推荐）：

conda create -n openapi-search-mcp python=3.12 -y
conda activate openapi-search-mcp

使用 venv：

python3.12 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

步骤3：安装依赖项

pip install -r requirements.txt

依赖项

FastMCP (>=0.2.0) - MCP 服务器框架
httpx（注：httpx是一个用于HTTP请求的工具或库的名称，在中文中通常直接保留原名，不进行翻译。） (>=0.27.0) - 用于获取文档的异步HTTP客户端
PyYAML (>=6.0) - 支持YAML解析
Pydantic（注：这是一个专有名词，通常不直接翻译，但在此提供其含义以供理解，即“一个用于数据验证和设置的Python库”） (>=2.0.0) - 类型安全的数据模型

______________________________________________________________________

Docker 部署

为了快速且独立地进行部署，您可以使用Docker。

先决条件

Docker 已安装)
Docker Compose（可选，Docker Desktop 已包含）

选项1：使用Docker Compose（推荐）

部署的最简单方法：

# Clone the repository
git clone https://github.com/Sheepion/openapi-search-mcp.git
cd openapi-search-mcp

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

服务器将在 http://localhost:8848

选项2：直接使用Docker

手动构建和运行：

# Build the image
docker build -t openapi-search-mcp:latest .

# Run the container
docker run -d \
  --name openapi-search-mcp \
  -p 8848:8848 \
  --restart unless-stopped \
  openapi-search-mcp:latest

# View logs
docker logs -f openapi-search-mcp

# Stop and remove
docker stop openapi-search-mcp
docker rm openapi-search-mcp

Docker 配置

Docker 设置包括：

基础镜像: python:3.12-slim （轻量级）
端口8848（可通过环境变量配置）
健康检查自动健康监测
资源限制可配置于 docker-compose.yml
记录日志带旋转功能的JSON文件驱动程序

环境变量

您可以通过设置环境变量来定制部署：

environment:
  - DEFAULT_HTTP_PORT=8848  # Change server port
  - PYTHONUNBUFFERED=1      # Enable real-time logs

通过Claude桌面版访问

使用 Docker 时，请更新您的 Claude Desktop 配置，使其指向 HTTP 端点：

{
  "mcpServers": {
    "openapi-search": {
      "url": "http://localhost:8848"
    }
  }
}

______________________________________________________________________

配置

Claude 桌面集成

要在Claude Desktop中使用此MCP服务器，请添加以下配置：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows： %APPDATA%\Claude\claude_desktop_config.json

选项1：使用Conda

{
  "mcpServers": {
    "openapi-search": {
      "command": "conda",
      "args": [
        "run",
        "-n",
        "openapi-search-mcp",
        "python",
        "/absolute/path/to/openapi-search-mcp/main.py"
      ]
    }
  }
}

选项2：使用直接的Python路径

{
  "mcpServers": {
    "openapi-search": {
      "command": "/path/to/conda/envs/openapi-search-mcp/bin/python",
      "args": ["/absolute/path/to/openapi-search-mcp/main.py"]
    }
  }
}

添加配置后，重启 Claude Desktop 以加载 MCP 服务器。

HTTP 模式（独立服务器）

默认情况下，服务器在8848端口以HTTP模式运行。如需自定义：

编辑 main.py 第57行：

# STDIO mode (for Claude Desktop)
mcp.run()

# HTTP mode with custom port
mcp.run(transport="streamable-http", port=8848)

______________________________________________________________________

使用

可用工具

服务器提供了10个MCP工具，用于全面探索API：

1. `load_openapi`

从URL加载OpenAPI文档并保存到内存中。

参数：

name （字符串，必填项）- 后续查询的API标识符
url （字符串，必填）- OpenAPI 文档的 URL

示例：

{
  "name": "petstore",
  "url": "https://petstore.swagger.io/v2/swagger.json"
}

回答：

{
  "status": "success",
  "message": "API 'petstore' loaded successfully",
  "info": {
    "title": "Swagger Petstore",
    "version": "1.0.0"
  },
  "paths_count": 14,
  "tags_count": 3
}

______________________________________________________________________

2. `list_apis`

列出所有已加载的API及其基本信息。

参数： 无

回答：

{
  "count": 2,
  "apis": [
    {
      "name": "petstore",
      "title": "Swagger Petstore",
      "version": "1.0.0",
      "paths_count": 14
    }
  ]
}

______________________________________________________________________

3. `get_path_details`

获取特定API路径的完整文档。

参数：

name （字符串，必填项）- API名称
path （字符串，必填项）- API路径，例如。， /users/{id}

示例：

{
  "name": "petstore",
  "path": "/pet/{petId}"
}

回答：

{
  "path": "/pet/{petId}",
  "methods": {
    "get": {
      "summary": "Find pet by ID",
      "operationId": "getPetById",
      "parameters": [...],
      "responses": {...}
    }
  }
}

______________________________________________________________________

4. `list_all_paths`

列出API中的所有路径。

参数：

name （字符串，必填）- API名称

回答：

{
  "count": 14,
  "paths": [
    {
      "path": "/pet",
      "methods": ["post", "put"]
    },
    {
      "path": "/pet/{petId}",
      "methods": ["get", "post", "delete"]
    }
  ]
}

______________________________________________________________________

5. `get_operation_by_id`

通过 operationId 快速查找。

参数：

name （字符串，必填）- API名称
operation_id (字符串，必填) - 操作ID，例如。， getUserById

示例：

{
  "name": "petstore",
  "operation_id": "getPetById"
}

回应：

{
  "operation_id": "getPetById",
  "path": "/pet/{petId}",
  "method": "get",
  "details": {
    "summary": "Find pet by ID",
    "parameters": [...],
    "responses": {...}
  }
}

______________________________________________________________________

6. `search_endpoints`

通过关键字、方法、标签或组合方式搜索端点。

参数：

name （字符串，必填项）- API名称
keyword （字符串，可选）- 在路径、摘要、描述中搜索
method (字符串，可选) - HTTP 方法过滤器 (GET, POST, 等)
tag (字符串，可选) - 标签过滤器

示例：

{
  "name": "petstore",
  "keyword": "pet",
  "method": "GET"
}

回答：

{
  "count": 3,
  "results": [
    {
      "path": "/pet/{petId}",
      "method": "get",
      "operationId": "getPetById",
      "summary": "Find pet by ID"
    }
  ]
}

______________________________________________________________________

7. `list_tags`

列出API中的所有标签。

参数：

name （字符串，必填项）- API名称

回答：

{
  "count": 3,
  "tags": [
    {
      "name": "pet",
      "description": "Everything about your Pets"
    }
  ]
}

______________________________________________________________________

8. `get_endpoints_by_tag`

获取带有特定标签的所有端点（仅概览）。

参数：

name （字符串，必填）- API名称
tag (字符串，必填) - 标签名称

示例：

{
  "name": "petstore",
  "tag": "pet"
}

回答：

{
  "tag": "pet",
  "count": 8,
  "endpoints": [
    {
      "path": "/pet",
      "method": "post",
      "operationId": "addPet",
      "summary": "Add a new pet"
    }
  ]
}

______________________________________________________________________

9. `get_schema_details`

从 components/schemas 中获取数据模型定义。

参数：

name （字符串，必填项）- API名称
schema_name (字符串，必填) - 模式名称，例如。， User， Pet

示例：

{
  "name": "petstore",
  "schema_name": "Pet"
}

回答：

{
  "schema_name": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"]
}

______________________________________________________________________

10. `get_auth_info`

获取认证配置。

参数：

name （字符串，必填项）- API名称

回答：

{
  "security_schemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "global_security": [
    {"bearerAuth": []}
  ]
}

______________________________________________________________________

典型工作流程

工作流1：探索新API

# Step 1: Load the API
load_openapi(name="petstore", url="https://petstore.swagger.io/v2/swagger.json")

# Step 2: See what tags/categories exist
list_tags(name="petstore")

# Step 3: Explore endpoints in a category
get_endpoints_by_tag(name="petstore", tag="pet")

# Step 4: Get detailed info for a specific endpoint
get_path_details(name="petstore", path="/pet/{petId}")

# Step 5: Check the data models
get_schema_details(name="petstore", schema_name="Pet")

工作流2：查找特定功能

# Search for user-related POST endpoints
search_endpoints(name="api", keyword="user", method="POST")

# Quick lookup by operationId
get_operation_by_id(name="api", operation_id="createUser")

# Get full path details
get_path_details(name="api", path="/users")

工作流3：理解身份验证

# Check what auth methods are required
get_auth_info(name="api")

______________________________________________________________________

建筑学

OpenAPI Search MCP 采用了一种受企业模式启发的简洁分层架构：

┌─────────────────────────────────────┐
│         main.py (Entry)             │  → Application initialization
├─────────────────────────────────────┤
│    Tools Layer (src/tools/)         │  → MCP tool definitions
├─────────────────────────────────────┤
│   Services Layer (src/services/)    │  → Business logic
├─────────────────────────────────────┤
│  Storage Layer (src/storage.py)     │  → Data access
├─────────────────────────────────────┤
│ Loaders/Indexers (src/loaders/,     │  → Utilities
│                   src/indexers/)    │
├─────────────────────────────────────┤
│  Models (src/models/)               │  → Data structures
├─────────────────────────────────────┤
│  Config (src/config.py)             │  → Constants
└─────────────────────────────────────┘

关键设计原则

关注点分离（或译为“职责分离”） - 每一层都有单一职责
依赖注入 - 服务通过构造函数接收依赖项
类型安全 - 全程使用 Pydantic 模型
面向接口的 - 层间合同清晰明确
可测试性 - 每一层都可以独立进行单元测试

各层解析

配置层 - 集中管理常量和错误信息
模型层 - 带验证的类型安全数据结构
存储层 - 内存中文档存储，具有一致的错误处理机制
加载器层 - HTTP获取和格式检测（JSON/YAML）
索引器层 - 构建反向索引以实现快速查找
服务层 - 业务逻辑（5项服务：API、路径、模式、搜索、标签）
工具层 - MCP工具注册（3个模块）
入口层 - 应用程序初始化并进行依赖注入

______________________________________________________________________

项目结构

openapi-search-mcp/
├── main.py                          # Entry point (~50 lines)
├── requirements.txt                 # Python dependencies
├── README.md                        # This file
├── README.zh.md                     # Chinese documentation
├── CLAUDE.md                        # Claude Code guidance
├── DESIGN.md                        # Detailed design docs
├── src/                             # Source code
│   ├── config.py                   # Configuration constants
│   ├── storage.py                  # Data storage layer
│   ├── models/                     # Data models
│   │   └── openapi_document.py    # Pydantic model
│   ├── loaders/                    # Document loaders
│   │   └── openapi_loader.py      # URL loading & format detection
│   ├── indexers/                   # Index builders
│   │   └── operation_indexer.py   # operationId and tag indexing
│   ├── services/                   # Business logic
│   │   ├── api_service.py         # API loading and listing
│   │   ├── path_service.py        # Path queries
│   │   ├── schema_service.py      # Schema and auth queries
│   │   ├── search_service.py      # Endpoint search
│   │   └── tag_service.py         # Tag queries
│   └── tools/                      # MCP tool definitions
│       ├── loading_tools.py       # load_openapi, list_apis
│       ├── query_tools.py         # path, operation, schema queries
│       └── search_tools.py        # search, tag queries
└── tests/                          # Test files

______________________________________________________________________

技术栈

技术	版本	目的
Python	3.12+	运行时环境
FastMCP	>=0.2.0	MCP服务器框架
httpx	>=0.27.0	异步HTTP客户端，用于获取文档
PyYAML	>=6.0	YAML 格式解析
Pydantic	>=2.0.0	类型安全的数据模型和验证

______________________________________________________________________

支持的OpenAPI版本

✅ OpenAPI 3.0.x（开放应用程序编程接口 3.0.x版本）
✅ OpenAPI 3.1.x
✅ Swagger 2.0

JSON和YAML格式均可自动检测并支持。

______________________________________________________________________

常见问题解答（FAQ）

如何加载本地的OpenAPI文件？

目前，仅支持URL加载。您可以：

使用本地文件服务器： python -m http.server 8000
访问方式： http://localhost:8000/openapi.json

未来版本将支持直接加载文件路径。

重启之间文档会被保存吗？

不，文档仅存储在内存中。服务器重启后，您需要重新加载您的OpenAPI文档。此设计以简洁和速度为优先，而非持久性。

如何在STDIO模式和HTTP模式之间切换？

编辑 main.py 第57行：

# STDIO mode (for Claude Desktop)
mcp.run()

# HTTP mode (standalone server)
mcp.run(transport="streamable-http", port=8848)

我可以加载同一个API的多个版本吗？

是的，只需使用不同的名字：

load_openapi(name="petstore-v1", url="...")
load_openapi(name="petstore-v2", url="...")

如果我加载一个已有名称的API会发生什么？

新文件将覆盖现有文件。服务器将记录一条警告信息。

______________________________________________________________________

发展

运行测试

pytest tests/

代码结构

见 “CLAUDE.md”翻译成中文可以是“克劳德.md”（假设“CLAUDE”为人名，且“md”为文件扩展名，如Markdown文件）。不过，具体翻译可能还需根据上下文或特定领域内的习惯来调整。如果“CLAUDE”不是人名而是其他含义，则翻译也会相应变化。但在此通用语境下，“克劳德.md”是一个合理的翻译以获取详细的架构文档和开发指南。

贡献；做出贡献

欢迎投稿！请：

为仓库创建分支（或“克隆仓库”）
创建一个特性分支
做出你的更改
添加测试
提交一个拉取请求

______________________________________________________________________

许可证

MIT 许可证 - 详见许可证详情如下。

______________________________________________________________________

致谢

这个项目是在……的协助下开发的克劳德·科德Anthropic的AI驱动编码助手，Claude Code提供了以下帮助：

从单体架构到分层架构的建筑设计与重构
实现带有依赖注入的服务层
文档编写与代码组织
Python企业开发的最佳实践

该项目展示了人机协作在软件开发中的强大能力。

______________________________________________________________________

链接

______________________________________________________________________

使用 Claude Code 构建 • OpenAPI 搜索 MCP 服务器 • MIT 许可证

OpenAPI Search MCP Server

快速接入

详细介绍

OpenAPI 搜索 MCP 服务器

概述

为什么要使用这个？

特点/特性

快速入门

安装

先决条件

步骤1：克隆仓库

步骤2：创建虚拟环境

步骤3：安装依赖项

依赖项

Docker 部署

先决条件

选项1：使用Docker Compose（推荐）

选项2：直接使用Docker

Docker 配置

环境变量

通过Claude桌面版访问

配置

Claude 桌面集成

选项1：使用Conda

选项2：使用直接的Python路径

HTTP 模式（独立服务器）

使用

可用工具

1. load_openapi

2. list_apis

3. get_path_details

4. list_all_paths

5. get_operation_by_id

6. search_endpoints

7. list_tags

8. get_endpoints_by_tag

9. get_schema_details

10. get_auth_info

典型工作流程

工作流1：探索新API

工作流2：查找特定功能

工作流3：理解身份验证

建筑学

关键设计原则

各层解析

项目结构

技术栈

支持的OpenAPI版本

常见问题解答（FAQ）

如何加载本地的OpenAPI文件？

重启之间文档会被保存吗？

如何在STDIO模式和HTTP模式之间切换？

我可以加载同一个API的多个版本吗？

如果我加载一个已有名称的API会发生什么？

发展

运行测试

代码结构

贡献；做出贡献

许可证

致谢

链接

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `load_openapi`

2. `list_apis`

3. `get_path_details`

4. `list_all_paths`

5. `get_operation_by_id`

6. `search_endpoints`

7. `list_tags`

8. `get_endpoints_by_tag`

9. `get_schema_details`

10. `get_auth_info`