AI导哈

OpenAPI协议服务器

一个通用的MCP服务器，提供对任何OpenAPI规范的访问，适用于需要集成多API的开发场景。

  • by dfitchett
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 dfitchett/openapi-mcp

使用说明

OpenAPI MCP服务器

一个通用的MCP（模型上下文协议）服务器，提供对任何OpenAPI规范的访问作为资源。该服务器从可配置的API端点获取并缓存OpenAPI规范，使其可用于Claude Desktop或Cursor等MCP客户端。

特性

  • 通用和可配置：适用于任何OpenAPI规范URL-不绑定到任何特定的API提供程序
  • 自动规格获取：启动时自动下载最新的OpenAPI规范
  • 本地高速缓存：本地缓存性能和离线访问规范
  • MCP资源协议：将OpenAPI规范作为MCP资源公开
  • 可扩展设计：通过简单的配置轻松添加API
  • 可定制的：通过环境变量配置服务器名称、URI方案和缓存目录
  • 配置示例：预先配置了VA（退伍军人事务部）API
    • 福利声明API V2
    • 福利文档API V1

运作原理

  1. 启动时，服务器从已配置的API端点获取OpenAPI规范
  2. 规范在本地缓存（默认值： .cache/openapi-specs/)
  3. MCP服务器通过HTTP/SSE传输将这些规范作为资源公开
  4. MCP客户端可以发现和阅读OpenAPI规范

配置

服务器可以通过环境变量进行配置：

  • MCP_SERVER_NAME：MCP服务器的名称（默认值： openapi-mcp)
  • MCP_URI_SCHEME：资源的URI方案（默认值： openapi)
  • CACHE_DIR：缓存目录路径（默认值： .cache/openapi-specs)
  • DEBUG：启用调试日志记录（默认值： False)

您也可以在中直接修改API配置 src/app/config.py 通过编辑 API_CONFIGS 字典。

项目结构

.
├── api/                # Vercel serverless functions
│   └── index.py        # HTTP/SSE entry point for Vercel
├── end_to_end/          # End-to-end tests
│   ├── __init__.py
│   ├── conftest.py
│   └── test_end_to_end.py
├── integration/         # Integration tests
│   ├── __init__.py
│   ├── conftest.py
│   └── test_integration.py
├── src/                # Source code
│   └── app/
│       ├── __init__.py
│       ├── http_server.py  # HTTP/SSE server for Vercel
│       ├── mcp_server.py   # Core MCP server logic
│       ├── spec_fetcher.py # OpenAPI spec fetcher
│       └── config.py       # Configuration
├── test/               # Unit tests
│   ├── __init__.py
│   ├── conftest.py
│   └── test_app.py
├── docker-entrypoint.sh
├── DEPLOYMENT.md      # Deployment guide
├── getting_started.md
├── pyproject.toml
├── requirements.txt    # For Vercel deployment
├── vercel.json         # Vercel configuration
├── .vercelignore       # Files to exclude from deployment
└── README.md

文件目的

  • README.md -项目概述、文档、说明和使用示例
  • DEPLOYMENT.md -本地运行和部署到Vercel的详细部署指南
  • getting_started.md -详细的开发设置说明
  • pyproject.toml -使用Poetry的项目元数据、依赖关系和构建配置
  • requirements.txt -Vercel部署的Python依赖关系
  • vercel.json -Vercel部署配置
  • .vercelignore -要从Vercel部署中排除的文件
  • docker-entrypoint.sh -与docker compose一起使用的简单docker入口点
  • **/__init__.py -将目录标记为Python包

文件夹用途

  • /api -HTTP/SSE传输的Vercel无服务器功能入口点
  • /src -包含应用程序源代码
  • /test -包含不需要外部资源的单元测试
  • /integration -包含与外部资源（如数据库、消息队列）交互的测试，并带有一些模拟功能
  • /end_to_end -包含无需模拟即可验证整个应用程序的测试

安装

先决条件

  • Python 3.12或更高版本
  • 诗2依赖管理

设置

  1. 克隆此存储库：
git clone <repository-url>
cd va-api-mcp
  1. 安装诗歌（如果尚未安装）：
curl -sSL https://install.python-poetry.org | python3 -
  1. 安装依赖项：
poetry install
  1. （可选）为开发设置预提交挂钩：
pre-commit install

用法

此服务器使用HTTP/SSE传输，可以在本地运行进行测试，也可以部署到Vercel进行远程访问。

有关详细的部署说明，请参阅 部署.md.

快速开始

在本地运行服务器：

poetry install
poetry run uvicorn app.http_server:app --reload --port 8000

配置您的MCP客户端（Cursor或Claude Desktop）以连接到 http://localhost:8000/sse.

有关Vercel的生产部署和完整的配置说明，请参阅 部署指南.

发展

开发设置

  1. 激活虚拟环境：
# For Poetry 2.0.0+, you need to install the shell plugin first:
poetry self add poetry-plugin-shell

# Then you can activate the virtual environment:
poetry shell

可用命令

  • 运行测试：
poetry run pytest
  • 运行集成测试：
poetry run pytest integration
  • 运行端到端测试：
poetry run pytest end_to_end
  • 运行linting：
poetry run ruff check .
  • 运行类型检查：
poetry run mypy src
  • 格式代码：
poetry run ruff format .
  • 运行安全检查：
poetry run bandit -r src

预提交钩子

这个项目使用预提交挂钩来确保代码质量。每次提交前都会自动执行以下检查：

  • 代码格式化（ruff）
  • 类型检查（mypy）
  • 安全检查（土匪）
  • YAML验证
  • 诗歌依赖性验证
  • 还有更多。..

要手动运行预提交检查，请执行以下操作：

pre-commit run --all-files

代码质量工具

该项目使用多种工具来维护代码质量：

  • 拉夫：快速Python linter和格式化程序
  • 米皮：静态类型检查器
  • 匪徒：安全门楣
  • Pytest：测试框架
  • 预承诺：Git挂钩管理器

这些工具的配置可以在中找到 pyproject.toml 和 .pre-commit-config.yaml.

建筑

openapi-mcp/
├── api/
│   └── index.py              # Vercel serverless function entry point (HTTP/SSE)
├── src/
│   └── app/
│       ├── config.py         # Configuration (API URLs, server settings, cache settings)
│       ├── spec_fetcher.py   # Generic OpenAPI spec fetcher and caching
│       ├── mcp_server.py     # Generic MCP server implementation
│       └── http_server.py    # HTTP/SSE server for remote deployment
├── test/                     # Unit tests
├── .cache/                   # Cached OpenAPI specifications (gitignored, local only)
├── pyproject.toml           # Project dependencies (Poetry)
├── requirements.txt         # Dependencies for Vercel
└── vercel.json              # Vercel deployment configuration

运输模式

此服务器使用 HTTP/SSE（服务器发送事件） 交通通讯。实施于 http_server.py，它可以是：

  • 在本地运行 uvicorn 用于在部署前测试HTTP/SSE传输
  • 部署到Vercel等云平台，供多个客户端远程访问

设计理念

此服务器是有意通用的，不与任何特定的API提供程序绑定。核心组件(spec_fetcher.py, mcp_server.py)使用任何有效的OpenAPI规范。唯一特定于VA的元素在默认配置中，可以很容易地用任何其他API替换。

资源

许可证

该项目提供了通过MCP访问OpenAPI规范的通用工具。当将此服务器与特定API（如默认配置中的VA API）一起使用时，请确保遵守相应API的服务条款。

贡献

欢迎投稿！请随时提交拉取请求。

相关 MCP