Openapi Navigator

OpenAPI Navigator

一个 MCP（Model Context Protocol）服务，提供用于浏览和查询 OpenAPI 规范的工具。此服务让 AI Agent 可以轻松探索、搜索和理解 OpenAPI 规范，而无需手动解析复杂的 JSON/YAML 文件。

功能

• 加载 OpenAPI 规范，支持本地文件或 URL
• 浏览端点，支持按标签筛选
• 搜索端点，通过路径、摘要和操作 ID 进行模糊匹配，并支持分页
• 浏览架构及其定义，并支持分页
• 仅显示摘要——获取精简的端点信息以减少 token 用量
• API 交互——直接调用 REST API 来测试端点
• 支持多个规范——同时加载和管理多个 OpenAPI 规范
• 智能索引，支持快速查找和搜索
• 保留引用——保留 $ref 结构，由 Agent 决定何时解析
• 全面的演示环境——使用 Nanobot 和 MCP Inspector 进行交互式测试

安装

OpenAPI Navigator 已发布到 PyPI，可使用 uvx（推荐）或 pip 安装：

# Using uvx (recommended)
uvx openapi-navigator

# Or install globally with pip
pip install openapi-navigator

用法

MCP 配置

将 OpenAPI Navigator 添加到 MCP 客户端配置中：

对于 Cursor

将其添加到 Cursor MCP 设置中：

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

对于 Claude Desktop

将其添加到 Claude Desktop 配置文件中（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

对于 Code

将其添加到 Code MCP 配置中：

{
  "mcpServers": {
    "openapi-navigator": {
      "command": "uvx",
      "args": ["openapi-navigator"],
      "env": {}
    }
  }
}

可用工具

OpenAPI Navigator 提供以下工具：

核心操作

• load_spec - 从本地文件加载 OpenAPI 规范（需要绝对路径）
• load_spec_from_url - 从 URL 加载 OpenAPI 规范
• list_loaded_specs - 列出当前已加载的所有规范
• unload_spec - 从内存中移除规范

端点操作

• search_endpoints - 通过模糊匹配搜索端点，支持分页。使用 "" 或 "a" 作为查询即可获取所有端点
  • 参数：spec_id、query、limit（最大值为 200）、offset（默认为 0）
• get_endpoint - 按路径和方法获取特定端点的详细信息
  • 参数：spec_id、path、method、summary_only（布尔值，默认为 false）

架构操作

• search_schemas - 通过模糊匹配搜索架构名称，支持分页。使用 "" 或 "a" 作为查询即可获取所有架构
  • 参数：spec_id、query、limit（最大值为 200）、offset（默认为 0）
• get_schema - 按名称获取特定架构的详细信息
• get_spec_metadata - 获取已加载 OpenAPI 规范的完整元数据

标头管理

• set_spec_headers - 为已加载的规范附加身份验证标头或其他标头。使用 spec_id 参数调用 make_api_request 时，会自动应用这些标头。
  • 参数：spec_id、headers（对象，可选）

API 交互

• make_api_request - 直接调用 REST API 来测试端点
  • 参数：url、method（GET/POST/PUT/PATCH/DELETE 等）、headers、params、data、timeout、spec_id（可选）

工具文档

set_spec_headers

为已加载的规范挂载身份验证或其他标头。使用 spec_id 参数调用 make_api_request 时，会自动应用这些标头。

参数：

• spec_id（字符串）：已加载规范的 ID
• headers（对象，可选）：HTTP 标头字典

示例：

{
  "spec_id": "my-api",
  "headers": {
    "Authorization": "Bearer secret-token-12345",
    "X-API-Key": "api-key-67890"
  }
}

使用场景：

// Load your API spec
load_spec_from_url("https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json", "github-api")

// Mount your auth token once
set_spec_headers("github-api", {"Authorization": "Bearer ghp_your_token"})

// Make requests without repeating auth
make_api_request("https://api.github.com/user", spec_id="github-api")
make_api_request("https://api.github.com/user/repos", spec_id="github-api")

make_api_request

向 REST API 发送 HTTP 请求。

参数：

• url（字符串）：请求的完整 URL
• method（字符串，可选）：HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）。默认值："GET"
• headers（对象，可选）：HTTP 标头字典
• params（对象，可选）：URL 参数字典
• data（字符串，可选）：字符串形式的请求正文
• timeout（整数，可选）：超时时间，单位为秒。默认值：30
• spec_id（字符串，可选）：从此规范加载默认标头。请求标头会覆盖规范标头。

使用 spec_id 的示例：

{
  "url": "https://api.example.com/users",
  "spec_id": "my-api",
  "headers": {
    "X-Custom-Header": "custom-value"
  }
}

这会将 set_spec_headers("my-api") 中的标头与 X-Custom-Header 合并，并以请求标头为准。

示例工作流

1. 加载规范：

   load_spec("/absolute/path/to/schema.yaml", "my-api")
   

2. 通过分页获取所有端点：

   search_endpoints("my-api", "", 50, 0)  # First 50 endpoints
   search_endpoints("my-api", "", 50, 50) # Next 50 endpoints
   

3. 获取所有架构：

   search_schemas("my-api", "")
   

4. 搜索特定端点：

   search_endpoints("my-api", "virtual machine")
   

5. 获取端点详情（摘要视图）：

   get_endpoint("my-api", "/api/virtualization/virtual-machines/", "GET", true)
   

6. 获取完整端点详情：

   get_endpoint("my-api", "/api/virtualization/virtual-machines/", "GET", false)
   

7. 获取架构详情：

   get_schema("my-api", "VirtualMachine")
   

8. 为规范挂载身份验证标头：

   set_spec_headers("my-api", {"Authorization": "Bearer secret-token"})
   

9. 测试 API 端点（使用已挂载的标头）：

   make_api_request("https://api.example.com/users", spec_id="my-api")
   

10. 覆盖特定请求的标头：

    make_api_request("https://api.example.com/admin", spec_id="my-api", headers={"X-Admin-Token": "admin-token"})
    

11. 获取规范元数据：

    get_spec_metadata("my-api")
    

演示环境

OpenAPI Navigator 提供了全面的演示环境，用于交互式测试和开发。

Nanobot 集成

使用 Nanobot 运行交互式演示（需要安装）：

# Install nanobot
brew install nanobot-ai/tap/nanobot

# Create .env file with your API key
echo "ANTHROPIC_API_KEY=your-key-here" > .env

# Start the demo
make demo

演示将在 http://localhost:8080 上提供，并提供用于测试 OpenAPI Navigator 功能的 Web 界面。

MCP Inspector 集成

Web UI 检查器

make inspect

打开 MCP Inspector Web UI，地址为 http://localhost:6274，用于交互式工具测试。

CLI 检查器

make inspect-cli

通过命令行列出所有可用工具。

自动化检查器测试

make test-inspector

使用 MCP Inspector CLI 运行自动化测试，以验证工具功能。

开发

测试

OpenAPI Navigator 提供全面的测试套件，包括单元测试和集成测试。

运行测试

所有测试：

uv run pytest

仅运行单元测试（速度快）：

uv run pytest tests/unit/

仅运行集成测试：

uv run pytest tests/integration/

生成覆盖率报告：

uv run pytest --cov=src --cov-report=html

使用 Makefile

为方便起见，项目提供了一个包含常用测试目标的 Makefile：

# Run all tests
make test

# Run only unit tests (fast feedback)
make test-unit

# Run integration tests
make test-integration

# Run tests with coverage report
make test-cov

# Clean up generated files
make clean

# Format code
make format

# Lint code
make lint

测试结构

• tests/unit/ - 各个组件的单元测试
  • test_spec_manager.py - 核心规范管理功能的测试
• tests/integration/ - 完整工作流的集成测试
  • test_integration.py - 端到端工作流测试
• tests/conftest.py - 共享测试夹具和配置

测试覆盖率

测试套件的目标是实现至少 65% 的代码覆盖率，并包含：

• 31 项单元测试，覆盖核心功能
• 5 项集成测试，覆盖完整工作流
• 模拟测试，用于外部依赖项
• 错误处理验证
• 边界情况覆盖

检查服务

使用 FastMCP CLI 检查服务：

uvx fastmcp inspect openapi-navigator

这将生成 server-info.json 文件，其中包含所有可用工具的详细信息。

CI/CD 流水线

OpenAPI Navigator 使用 GitHub Actions 进行持续集成和部署。

工作流

🔄 CI (ci.yml)

• 触发条件：拉取请求以及推送到 main
• 运行内容：在 Python 3.10、3.11 和 3.12 上运行测试
• 功能：
  • 运行完整测试套件
  • 报告代码覆盖率
  • 使用 ruff 进行 lint 检查和格式检查
  • 使用 black 格式化代码

🏗️ 构建 (build.yml)

• 触发条件：合并到 main 分支
• 功能：
  • 全面测试
  • 构建软件包
  • 代码质量检查
  • 上传构建产物

🚀 发布 (release.yml)

• 触发条件：GitHub 发布
• 功能：
  • 自动发布到 PyPI（支持可信发布者 OIDC）
  • 创建 GitHub 发布
  • 发布前测试

📦 依赖项 (dependencies.yml)

• 触发条件：每周（周一）+ 手动触发
• 功能：
  • 自动更新依赖项
  • 创建拉取请求
  • 测试验证

设置要求

选项 1：可信发布者（推荐）

1. PyPI 账号：在 pypi.org 创建账号
2. 配置可信发布者：在 PyPI 设置中，将 GitHub 添加为可信发布者
3. 推送到 GitHub：工作流将自动启用

选项 2：API 令牌（传统方式）

1. PyPI 账号：在 pypi.org 创建账号
2. 生成 API 令牌：在 PyPI 设置中创建 API 令牌
3. GitHub Secrets：添加 PYPI_API_TOKEN 并填入你的 PyPI 令牌
4. 更新工作流：取消注释 .github/workflows/release.yml 中的 UV_TOKEN 行
5. 推送到 GitHub：工作流将自动启用

发布流程

1. 创建发布：在 GitHub 中为新版本打标签
2. 自动化测试：CI 运行完整测试套件
3. 构建软件包：创建可分发的软件包
4. 发布到 PyPI：自动发布到 PyPI
5. 发布说明：生成全面的发布说明

质量门槛

• ✅ 测试覆盖率：至少达到 65%
• ✅ 所有测试通过：单元测试和集成测试
• ✅ 代码质量：使用 ruff 和 black 进行 lint 检查和格式检查
• ✅ 依赖项：保持最新且安全

架构

OpenAPI Navigator 由两个主要组件构成：

1. SpecManager：负责加载、验证和索引 OpenAPI 规范
2. MCP 服务：通过 Model Context Protocol 提供工具

SpecManager 功能

• 多格式支持：支持 YAML 和 JSON 格式的 OpenAPI 规范
• 版本检测：自动检测 OpenAPI 3.x 与 Swagger 2.x
• 智能索引：建立索引，以便快速查找端点和架构
• 模糊搜索：支持对端点元数据进行智能搜索
• 引用处理：保留 $ref 结构，不进行自动解析

错误处理

• 验证警告：出现验证问题时发出警告，并在可能的情况下继续
• 优雅降级：仅拒绝会阻碍核心功能的规范
• 实用的错误消息：清晰说明出错原因

安全注意事项

• 仅限绝对路径：出于安全考虑，本地文件加载必须使用绝对路径
• 不自动执行：服务仅读取和解析规范，不会执行代码
• 输入验证：处理所有输入前都会进行验证

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行修改
4. 适用时添加测试
5. 提交拉取请求

许可证

本项目采用 MIT 许可证。