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):```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.yaml
``````
Show me the Address schema details
``````
Get shipping rates from San Francisco to New York for a 1lb package
3.你得到了什么
- ✅ 零安装 -自动管理依赖关系
- ✅ 代币高效 -智能摘要而不是完整的规范转储
- ✅ 真正的API测试 -执行实际的HTTP请求
- ✅ 多个API -负载和不同规格之间的切换
需要更多控制?
- Web部署:使用 服务器模式 用于基于HTTP的集成
- 详细设置:参见 安装和设置 用于高级配置
- API 参考:检查 MCP工具可用 所有功能
安装和设置
依赖项
此项目使用 uv 用于依赖性管理。无需本地安装-依赖关系通过自动管理 uv run --with.
必需的依赖项
anyio>=4.5click>=8.1.0httpx>=0.27mcpPyYAML>=6.0starletteuvicorn
用法
运行服务器
HTTP传输(服务器模式)```bash
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
#### 标准运输(标准模式)```bash
# 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 stdio
MCP客户端集成
光标/Claude桌面配置
将其添加到您的MCP配置文件中(例如。, ~/.cursor/mcp.json):```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` (可选):此规范的标识符(默认值:“默认”)
**例子:**```json
{
"file_path_or_url": "https://petstore3.swagger.io/api/v3/openapi.json",
"spec_id": "petstore"
}
2. get-schema-details
从加载的规范中获取有关特定模式的详细信息。
参数:
schema_name(必需):要获取详细信息的架构名称spec_id(可选):加载规范的ID(默认值:“默认”)
例子:```json
{
"schema_name": "Pet",
"spec_id": "petstore"
}
### 3. `get-endpoint-details`
从加载的规范中获取特定端点的详细信息。
**参数:**
- `path` (必需):API端点路径(例如。, `/users/{id}`)
- `method` (必填):HTTP方法(GET、POST、PUT、DELETE等)
- `spec_id` (可选):加载规范的ID(默认值:“默认”)
**例子:**```json
{
"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)
例子:```json
{
"url": "https://petstore3.swagger.io/api/v3/pet/1",
"method": "GET",
"headers": {
"Authorization": "Bearer your-token",
"Accept": "application/json"
}
}
## 使用工作流程
1. **加载规格**:使用 `load-openapi-spec` 加载API规范并查看所有架构和终结点的摘要
1. **探索模式**:使用 `get-schema-details` 了解数据模型及其属性
1. **探索端点**:使用 `get-endpoint-details` 获取特定端点的完整信息
1. **执行通话**:使用 `execute-api-call` 向API发出实际的HTTP请求
## 命令行选项
### 全局选项
- `--log-level` -日志记录级别(调试、信息、警告、错误、严重)
- `--help` -显示帮助消息
### 服务器模式选项
- `--port` -监听端口(默认值:3000)
- `--json-response` -启用JSON响应而不是SSE流
## 例子
### HTTP服务器模式测试```bash
# 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规范```json
{
"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.探索地址模式```json
{
"method": "tools/call",
"params": {
"name": "get-schema-details",
"arguments": {
"schema_name": "Address",
"spec_id": "shippo"
}
}
}
### 3.获取地址验证终结点详细信息```json
{
"method": "tools/call",
"params": {
"name": "get-endpoint-details",
"arguments": {
"path": "/addresses/{AddressId}/validate",
"method": "GET",
"spec_id": "shippo"
}
}
}
4.验证地址```json
{
"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!
