API Explorer MCP

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.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.5
• click>=8.1.0
• httpx>=0.27
• mcp
• PyYAML>=6.0
• starlette
• uvicorn

用法

运行服务器

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 stdio

MCP客户端集成

光标/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调用的完整URL
• method （可选）：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"
  }
}

使用工作流程

1. 加载规格：使用 load-openapi-spec 加载API规范并查看所有架构和终结点的摘要
2. 探索模式：使用 get-schema-details 了解数据模型及其属性
3. 探索端点：使用 get-endpoint-details 获取特定端点的完整信息
4. 执行通话：使用 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！