麦克普开放API代理

Name: 麦克普开放API代理
Author: matthewhand

作者：matthewhand119 星标更新：2025-04-23

安装使用来源：spider==github.com

项目介绍

mcp-openapi-proxy

mcp-openapi-proxy 是一个 Python 包，实现了 Model Context Protocol (MCP) 服务器，旨在动态暴露由 OpenAPI 规范定义的 REST API，作为 MCP 工具。这有助于将 OpenAPI 描述的 API 平滑地集成到基于 MCP 的工作流中。

概述

该包提供了两种操作模式：

低级模式（默认）： 动态注册与 OpenAPI 文档中指定的所有有效 API 端点相对应的工具（例如 /chat/completions 变成 chat_completions()）。
FastMCP 模式（简单模式）： 提供了一种简化的方法，通过暴露一组预定义的工具（例如 list_functions() 和 call_function()），这些工具基于静态配置。

特性

动态工具生成： 自动从 OpenAPI 端点定义创建 MCP 工具。
简单模式选项： 通过 FastMCP 模式提供静态配置替代方案。
OpenAPI 规范支持： 兼容 OpenAPI v3，可能支持 v2。
灵活过滤： 通过路径或其他标准白名单允许端点过滤。
负载身份验证： 支持通过 JMESPath 表达式进行自定义身份验证（例如，对于像 Slack 这样的 API，期望在负载而不是 HTTP 头部中的令牌）。
头部身份验证： 默认使用 Bearer 对 API_KEY 在 Authorization 头部进行身份验证，可定制以适应如 Fly.io 所需的 Api-Key。
MCP 集成： 无缝集成到 MCP 生态系统中，将 REST API 作为工具调用。

安装

使用以下命令直接从 PyPI 安装该包：

uvx mcp-openapi-proxy

MCP 生态系统集成

要将 mcp-openapi-proxy 集成到您的 MCP 生态系统中，请在您的 mcpServers 设置中进行配置。下面是一个通用示例：

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "${API_OPENAPI_KEY}"
            }
        }
    }
}

请参阅下面的示例部分，了解针对特定 API 的实际配置。

操作模式

FastMCP 模式（简单模式）

启用方式： 设置环境变量 OPENAPI_SIMPLE_MODE=true。
描述： 暴露一组固定工具，这些工具源自代码中定义的具体 OpenAPI 端点。
配置： 依赖于环境变量来指定工具行为。

低级模式（默认）

描述： 自动注册提供的 OpenAPI 规范中的所有有效 API 端点作为单独的工具。
工具命名： 从规范化 OpenAPI 路径和方法派生工具名称。
行为： 从 OpenAPI 操作摘要和描述生成工具描述。

环境变量

OPENAPI_SPEC_URL：（必需）指向 OpenAPI 规范 JSON 文件的 URL（例如 https://example.com/spec.json 或 file:///path/to/local/spec.json）。
OPENAPI_LOGFILE_PATH：（可选）指定日志文件路径。
OPENAPI_SIMPLE_MODE：（可选）设置为 true 启用 FastMCP 模式。
TOOL_WHITELIST：（可选）以逗号分隔的要暴露为工具的端点路径列表。
TOOL_NAME_PREFIX：（可选）要附加到所有工具名称前缀。
API_KEY：（可选）发送到 Authorization 头部的 API 身份验证令牌，默认为 Bearer <API_KEY>。
API_AUTH_TYPE：（可选）覆盖默认的 Bearer Authorization 头类型（例如，GetZep 使用 Api-Key）。
STRIP_PARAM：（可选）JMESPath 表达式用于剥离不需要的参数（例如，Slack 中的 token）。
DEBUG：（可选）当设置为 "true"、"1" 或 "yes" 时启用详细调试日志。
EXTRA_HEADERS：（可选）附加到传出 API 请求的额外 HTTP 头部，在 "Header: Value" 格式下（每行一个）。
SERVER_URL_OVERRIDE：（可选）当设置时覆盖 OpenAPI 规范中的基础 URL，适用于自定义部署。
TOOL_NAME_MAX_LENGTH：（可选）截断工具名称至最大长度。
额外变量：OPENAPI_SPEC_URL_<hash> – 用于独特测试配置的变体（回退到 OPENAPI_SPEC_URL）。
IGNORE_SSL_SPEC：（可选）设置为 true 以禁用获取 OpenAPI 规范时的 SSL 证书验证。
IGNORE_SSL_TOOLS：（可选）设置为 true 以禁用工具发出 API 请求时的 SSL 证书验证。

示例

为了测试，您可以运行 uvx 命令，然后通过 JSON-RPC 消息与 MCP 服务器交互以列出工具和资源。请参阅下面的“JSON-RPC 测试”部分。

Glama 示例

Glama 提供了最简单的 mcp-openapi-proxy 配置，仅需要 OPENAPI_SPEC_URL 环境变量。这种简洁性使其非常适合快速测试。

1. 验证 OpenAPI 规范

检索 Glama OpenAPI 规范：

curl https://glama.ai/api/mcp/openapi.json

确保响应是一个有效的 OpenAPI JSON 文档。

2. 配置 mcp-openapi-proxy 用于 Glama

向您的 MCP 生态系统设置添加以下配置：

{
    "mcpServers": {
        "glama": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json"
            }
        }
    }
}

3. 测试

启动服务：

OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json" uvx mcp-openapi-proxy

然后参阅 JSON-RPC 测试部分以获取列出资源和工具的说明。

Fly.io 示例

Fly.io 提供了一个简单的 API 来管理机器，使其成为理想的起点。从 Fly.io 文档获取 API 令牌。

1. 验证 OpenAPI 规范

检索 Fly.io OpenAPI 规范：

curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json

确保响应是一个有效的 OpenAPI JSON 文档。

2. 配置 mcp-openapi-proxy 用于 Fly.io

更新您的 MCP 生态系统配置：

{
    "mcpServers": {
        "flyio": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "API_KEY": "<your_flyio_token_here>"
            }
        }
    }
}

OPENAPI_SPEC_URL：指向 Fly.io OpenAPI 规范。
API_KEY：您的 Fly.io API 令牌（替换 <your_flyio_token_here>）。
API_AUTH_TYPE：设置为 Api-Key 以适应 Fly.io 的基于头部的身份验证（覆盖默认的 Bearer）。

3. 测试

启动服务后，参阅 JSON-RPC 测试部分以获取列出资源和工具的说明。

Render 示例

Render 提供了可以通过 API 管理的基础架构托管。提供的配置文件 examples/render-claude_desktop_config.json 展示了如何快速设置 MCP 生态系统，只需最少的设置。

1. 验证 OpenAPI 规范

检索 Render OpenAPI 规范：

curl https://api-docs.render.com/openapi/6140fb3daeae351056086186

确保响应是一个有效的 OpenAPI 文档。

2. 配置 mcp-openapi-proxy 用于 Render

向您的 MCP 生态系统设置添加以下配置：

{
    "mcpServers": {
        "render": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/6140fb3daeae351056086186",
                "TOOL_WHITELIST": "/services,/maintenance",
                "API_KEY": "your_render_token_here"
            }
        }
    }
}

3. 测试

使用您的 Render 配置启动代理：

OPENAPI_SPEC_URL="https://api-docs.render.com/openapi/6140fb3daeae351056086186" TOOL_WHITELIST="/services,/maintenance" API_KEY="your_render_token_here" uvx mcp-openapi-proxy

然后参阅 JSON-RPC 测试部分以获取列出资源和工具的说明。

Slack 示例

Slack 的 API 展示了如何使用 JMESPath 剥离不必要的令牌负载。从 Slack API 文档获取机器人令牌。

1. 验证 OpenAPI 规范

检索 Slack OpenAPI 规范：

curl https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json

确保它是一个有效的 OpenAPI JSON 文档。

2. 配置 mcp-openapi-proxy 用于 Slack

更新您的配置：

{
    "mcpServers": {
        "slack": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
                "TOOL_WHITELIST": "/chat,/bots,/conversations,/reminders,/files,/users",
                "API_KEY": "<your_slack_bot_token, starts with xoxb>",
                "STRIP_PARAM": "token",
                "TOOL_NAME_PREFIX": "slack_"
            }
        }
    }
}

OPENAPI_SPEC_URL：Slack 的 OpenAPI 规范 URL。
TOOL_WHITELIST：限制工具到有用的端点组（例如聊天、对话、用户）。
API_KEY：您的 Slack 机器人令牌（例如 xoxb-...，替换 <your_slack_bot_token>）。
STRIP_PARAM：从请求负载中移除令牌字段。
TOOL_NAME_PREFIX：在工具名称前附加 slack_。

3. 测试

启动服务后，参阅 JSON-RPC 测试部分以获取列出资源和工具的说明。

GetZep 示例

GetZep 提供了一个免费的云 API 用于记忆管理，具有详细的端点。由于 GetZep 没有提供官方的 OpenAPI 规范，该项目包括了一个在 GitHub 上方便使用的生成规范。用户可以类似地为任何 REST API 生成 OpenAPI 规范，并引用本地文件（例如 file:///path/to/spec.json）。从 GetZep 的文档获取 API 密钥。

1. 验证 OpenAPI 规范

检索项目提供的 GetZep OpenAPI 规范：

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json

确保它是一个有效的 OpenAPI JSON 文档。或者，生成您自己的规范并使用 file:// URL 引用本地文件。

2. 配置 mcp-openapi-proxy 用于 GetZep

更新您的配置：

{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
                "TOOL_WHITELIST": "/sessions",
                "API_KEY": "<your_getzep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "TOOL_NAME_PREFIX": "zep_"
            }
        }
    }
}

OPENAPI_SPEC_URL：指向项目提供的 GetZep Swagger 规范（或使用 file:///path/to/your/spec.json 引用本地文件）。
TOOL_WHITELIST：限制到 /sessions 端点。
API_KEY：您的 GetZep API 密钥。
API_AUTH_TYPE：使用 Api-Key 进行基于头部的身份验证。
TOOL_NAME_PREFIX：在工具名称前附加 zep_。

3. 测试

启动服务后，参阅 JSON-RPC 测试部分以获取列出资源和工具的说明。

VirusTotal 示例

此示例演示了：

使用 YAML 格式的 OpenAPI 规范文件
使用自定义 HTTP 认证头，“x-apikey”

1. 验证 OpenAPI 规范

检索 VirusTotal OpenAPI 规范：

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml

确保响应是一个有效的 OpenAPI YAML 文档。

2. 配置 mcp-openapi-proxy 用于 VirusTotal

向您的 MCP 生态系统设置添加以下配置：

{
    "mcpServers": {
        "virustotal": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml",
                "EXTRA_HEADERS": "x-apikey: ${VIRUSTOTAL_API_KEY}",
                "OPENAPI_SPEC_FORMAT": "yaml"
            }
        }
    }
}

关键配置点：

默认情况下，代理期望一个 JSON 规

麦克普开放API代理

项目介绍

mcp-openapi-proxy

目录

概述

特性

安装

MCP 生态系统集成

操作模式

FastMCP 模式（简单模式）

低级模式（默认）

环境变量

示例

Glama 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 Glama

3. 测试

Fly.io 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 Fly.io

3. 测试

Render 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 Render

3. 测试

Slack 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 Slack

3. 测试

GetZep 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 GetZep

3. 测试

VirusTotal 示例

1. 验证 OpenAPI 规范

2. 配置 mcp-openapi-proxy 用于 VirusTotal