API资源管理器MCP服务器
模型上下文协议（MCP）服务器，提供高效的OpenAPI/Swagger规范探索和API测试功能。该服务器没有将整个API规范加载到上下文中（这会消耗许多令牌），而是提供了一种具有详细端点探索的总结性第一方法。
运输方式
🌐 服务器模式 -HTTP传输
非常适合基于web的集成和部署：
- 可配置端口上的基于HTTP的MCP服务器
- 具有SSE或JSON响应的流式HTTP会话
- 易于使用curl和web工具进行测试
- 内存中的状态规范管理
📡 标准模式 -标准输入/输出传输
非常适合本地MCP客户端集成：
- MCP客户端的标准输入/输出传输
- 与人工智能助手和自动化工具直接集成
- 高效的二进制协议通信
- 非常适合本地MCP部署
特性
- 智能OpenAPI加载：从具有令牌高效摘要的文件或URL加载OpenAPI/Swagger规范
- 完整架构详细信息：获取有关任何模式/模型定义的详细信息
- 端点发现：获取所有可用端点的高级概述
- 详细端点信息：检索特定端点的全面详细信息
- API执行：执行具有完整参数支持的HTTP请求
- 多规格支持：同时管理多个API规范
- 双重运输：用于web部署的HTTP服务器+用于本地部署的stdio
🚀 快速入门
2分钟后起床跑步：
1.添加到MCP客户端配置
将其添加到您的MCP配置文件中（例如。， claude_desktop_config.json):
{
"mcpServers": {
"api-explorer": {
"command": "/opt/homebrew/bin/uv",
"args": [
"run",
"--with",
"api-explorer-mcp",
"api-explorer-mcp",
"stdio"
]
}
}
}2.开始使用它
配置后，您可以立即开始使用自然语言探索API：
Load the Shippo API spec from https://docs.goshippo.com/spec/shippoapi/public-api.yamlShow me the Address schema detailsGet shipping rates from San Francisco to New York for a 1lb package3.你得到了什么
- ✅ 零安装 -自动管理依赖关系
- ✅ 代币高效 -智能摘要而不是完整的规范转储
- ✅ 真正的API测试 -执行实际的HTTP请求
- ✅ 多个API -负载和不同规格之间的切换
需要更多控制？
安装和设置
依赖项
此项目使用 uv 用于依赖性管理。无需本地安装-依赖关系通过自动管理 uv run --with.
必需的依赖项
anyio>=4.5click>=8.1.0httpx>=0.27mcpPyYAML>=6.0starletteuvicorn
用法
运行服务器
HTTP传输（服务器模式）
# Start HTTP MCP server (default port 3000)
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py server
# Custom port and debug logging
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py server --port 8080 --log-level DEBUG
# JSON responses instead of SSE streams
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py server --json-response标准运输（标准模式）
# Start stdio MCP server
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py stdio
# With debug logging
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py --log-level DEBUG stdioMCP客户端集成
光标/Claude桌面配置
将其添加到您的MCP配置文件中（例如。， ~/.cursor/mcp.json):
{
"mcpServers": {
"api-explorer": {
"command": "/opt/homebrew/bin/uv",
"args": [
"run",
"--with",
"anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn",
"/path/to/your/api-explorer-mcp/main.py",
"stdio"
]
}
}
}替换 /path/to/your/api-explorer-mcp/ 带有此项目目录的实际路径。
此设置的好处
- ✅ 无需安装：依赖关系由自动管理
uv - ✅ 孤立的环境：每次运行都会获得新的、孤立的依赖关系
- ✅ 版本固定：特定的依赖版本确保一致性
- ✅ 零维护：没有虚拟环境或依赖关系冲突
- ✅ 交叉平台的：适用于任何系统
uv安装
MCP工具可用
1. load-openapi-spec
加载OpenAPI/Swagger规范并获得简洁的摘要。
参数：
file_path_or_url（必填）：获取规范的本地文件或URL的路径spec_id（可选）：此规范的标识符（默认值：“默认”）
例子：
{
"file_path_or_url": "https://petstore3.swagger.io/api/v3/openapi.json",
"spec_id": "petstore"
}2. get-schema-details
从加载的规范中获取有关特定模式的详细信息。
参数：
schema_name（必需）：要获取详细信息的架构名称spec_id（可选）：加载规范的ID（默认值：“默认”）
例子：
{
"schema_name": "Pet",
"spec_id": "petstore"
}3. get-endpoint-details
从加载的规范中获取特定端点的详细信息。
参数：
path（必需）：API端点路径（例如。，/users/{id})method（必填）：HTTP方法（GET、POST、PUT、DELETE等）spec_id（可选）：加载规范的ID（默认值：“默认”）
例子：
{
"path": "/pet/{petId}",
"method": "GET",
"spec_id": "petstore"
}4. execute-api-call
使用指定的参数执行HTTP API调用。
参数：
url（必需）：API调用的完整URLmethod（可选）：HTTP方法（默认：“GET”）headers（可选）：HTTP标头作为键值对params（可选）：将参数作为键值对进行查询body（可选）：请求正文（如果是对象/数组，则自动进行JSON编码）timeout（可选）：请求超时时间（秒）（默认值：30）
例子：
{
"url": "https://petstore3.swagger.io/api/v3/pet/1",
"method": "GET",
"headers": {
"Authorization": "Bearer your-token",
"Accept": "application/json"
}
}使用工作流程
- 加载规格：使用
load-openapi-spec加载API规范并查看所有架构和终结点的摘要 - 探索模式：使用
get-schema-details了解数据模型及其属性 - 探索端点：使用
get-endpoint-details获取特定端点的完整信息 - 执行通话：使用
execute-api-call向API发出实际的HTTP请求
命令行选项
全局选项
--log-level-日志记录级别（调试、信息、警告、错误、严重）--help-显示帮助消息
服务器模式选项
--port-监听端口（默认值：3000）--json-response-启用JSON响应而不是SSE流
例子
HTTP服务器模式测试
# 1. Start the server
uv run --with "anyio>=4.5,click>=8.1.0,httpx>=0.27,mcp,PyYAML>=6.0,starlette,uvicorn" main.py server --port 3000
# 2. Load a spec (using curl)
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "load-openapi-spec",
"arguments": {
"file_path_or_url": "https://petstore3.swagger.io/api/v3/openapi.json"
}
}
}'
# 3. Get schema details
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get-schema-details",
"arguments": {
"schema_name": "Pet"
}
}
}'
# 4. Execute API call
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "execute-api-call",
"arguments": {
"url": "https://petstore3.swagger.io/api/v3/pet/1",
"method": "GET"
}
}
}'MCP集成示例
在MCP客户端中配置后，您可以使用自然语言：
# Load Shippo API
"Load the Shippo API spec from https://docs.goshippo.com/spec/shippoapi/public-api.yaml"
# Explore schemas
"Show me the Address schema details"
# Make API calls
"Validate this address: 215 Clayton St, San Francisco, CA 94117"现实世界示例：Shippo API
以下是使用Shippo装运API的完整示例：
1.加载API规范
{
"method": "tools/call",
"params": {
"name": "load-openapi-spec",
"arguments": {
"file_path_or_url": "https://docs.goshippo.com/spec/shippoapi/public-api.yaml",
"spec_id": "shippo"
}
}
}2.探索地址模式
{
"method": "tools/call",
"params": {
"name": "get-schema-details",
"arguments": {
"schema_name": "Address",
"spec_id": "shippo"
}
}
}3.获取地址验证终结点详细信息
{
"method": "tools/call",
"params": {
"name": "get-endpoint-details",
"arguments": {
"path": "/addresses/{AddressId}/validate",
"method": "GET",
"spec_id": "shippo"
}
}
}4.验证地址
{
"method": "tools/call",
"params": {
"name": "execute-api-call",
"arguments": {
"url": "https://api.goshippo.com/addresses",
"method": "POST",
"headers": {
"Authorization": "ShippoToken shippo_test_5f7270ee3a59ac0bb0e5e993484fd472965d98c7",
"Content-Type": "application/json"
},
"body": {
"name": "Shawn Ippotle",
"street1": "215 Clayton St",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"country": "US",
"validate": true
}
}
}
}益处
服务器模式优势
- ✅ 易于测试：HTTP接口允许使用curl和web工具进行测试
- ✅ 柔性集成：适用于任何HTTP客户端
- ✅ 目视检查：易于检查请求和响应
- ✅ Web部署：非常适合基于网络的集成和服务
标准模式优势
- ✅ 直接积分法：本地MCP客户端通信
- ✅ 高效协议：二进制MCP协议，实现最佳性能
- ✅ 本地就绪：专为本地AI助手集成而设计
- ✅ 符合标准：完全符合MCP规范
共同利益
- ✅ 代币高效：只在需要时加载所需内容
- ✅ 持久状态：加载的规格在请求之间保留在内存中
- ✅ 全覆盖：完整的架构详细信息、终结点信息和API执行
- ✅ 实际测试：实际执行API调用，而不仅仅是探索文档
- ✅ 多个API：同时处理多个API规范
- ✅ 格式支持：OpenAPI 3.x和Swagger 2.x（JSON/YAML）
- ✅ 零安装：依赖关系由自动管理
uv - ✅ 孤立的环境：每次运行都会获得新的依赖关系
支持格式
- OpenAPI 3.x（JSON和YAML）
- Swagger 2.x（JSON和YAML）
- 基于文件扩展名和内容的自动检测
需求
uv-快速Python包安装程序和解析器- Python 3.8+（由自动管理）
uv)
______________________________________________________________________
选择您的交通工具：
- 使用 服务器模式 用于web部署和基于HTTP的集成
- 使用 标准模式 用于本地MCP客户端集成和AI助手
需要零设置： 只需使用配置MCP客户端 uv run 命令并开始探索API！