Fertant MCP

OpenAPI 到 MCP 服务器

一个工具，能够根据OpenAPI/Swagger规范或GraphQL内省信息创建MCP（模型上下文协议）服务器，使AI助手能够与您的API进行交互。 创造属于你自己的 品牌定制化MCP（多路复用器/控制器/模块等，具体根据上下文确定） 针对特定的API或服务。

概述

本项目创建了一个动态MCP服务器，该服务器能将OpenAPI规范和GraphQL内省转化为带有过滤参数的MCP工具。它通过模型上下文协议实现了REST API与AI助手的无缝集成，使任何API都能成为AI可访问的工具。MCP工具的描述以及每种工具的参数均基于API文档的描述来准备。

特点/特性

• 从文件或HTTP/HTTPS URL动态加载OpenAPI规范
• 从API端点动态加载内省查询
• 支持 OpenAPI 叠加层（或“覆盖层”） 从文件或HTTP/HTTPS URL加载
• 可自定义OpenAPI操作到MCP工具的映射
• 使用通配符模式对操作ID和URL路径进行高级过滤
• MCP参数和工具的白名单和黑名单
• 针对难以发现的参数或分类预设的过滤参数
• GraphQL API的API发现深度，该深度限制了在MCP工具中表示的字段和过滤器的数量
• 全面的参数处理，保持格式并包含位置元数据
• 根据配置处理API认证或作为优先认证密钥从原始请求中绕过至MCP服务器。
• 用于配置MCP服务器的OpenAPI元数据（标题、版本、描述）
• 层次化描述回退机制（操作描述 → 操作摘要 → 路径摘要）
• 通过环境变量和命令行界面（CLI）支持自定义HTTP头部
• 用于API请求跟踪和识别的X-MCP头部信息
• 支持自定义 x-mcp 在路径级别上进行扩展，以覆盖工具名称和描述
• 传输类型：SSE（服务器发送事件）或可流式传输的HTTP

与AI助手一起使用

这个工具创建了一个MCP服务器，使AI助手能够与OpenAPI规范或GraphQL Introspection定义的API进行交互。使用它的主要方式是将您的AI助手配置为直接将其作为MCP工具运行。

配置

配置通过环境变量或JSON配置文件进行管理：

环境变量

你可以将这些设置在 .env 文件或直接在您的环境中：

• TYPE接口类型：GraphQL 或 OpenAPI
• TRANSPORT传输类型已弃用：SSE 或新的 StreamableHTTP
• PATH_DEPTHGraphQL参数发现的深度
• OPENAPI_SPEC_PATHOpenAPI 规范文件的路径
• OPENAPI_OVERLAY_PATHS以逗号分隔的覆盖JSON文件路径
• TARGET_API_BASE_URLAPI调用的基础URL（覆盖OpenAPI服务器）
• MCP_WHITELIST_OPERATIONS以逗号分隔的操作ID或URL路径列表，用于包含（支持类似通配符的模式，如 getPet* 或者 GET:/pets/*)
• MCP_BLACKLIST_OPERATIONS逗号分隔的操作ID列表或要排除的URL路径（支持通配符模式，如果使用了白名单则忽略）
• MCP_PRESET_PARAMS过滤器参数预设为预定义选项，该选项将包含在所有请求中
• API_KEY目标API的API密钥（如需）
• SECURITY_SCHEME_NAME需要API密钥的安全方案名称
• SECURITY_CREDENTIALS包含多种方案安全凭证的JSON字符串
• CUSTOM_HEADERS包含要在所有API请求中包含的自定义标头的JSON字符串
• HEADER_*任何以（某个字符或字符串）开头的环境变量 HEADER_ 将被添加为自定义头部（例如。， HEADER_X_API_Version=1.0.0 添加了标题 X-API-Version: 1.0.0）
• DISABLE_X_MCP设置为 true 禁用添加功能 X-MCP: 1 所有API请求的头部
• CONFIG_FILEJSON配置文件的路径
• DESCRIPTION简要说明大型语言模型（LLM）中MCP的目的，以便更好地将其与其他工具区分开来。

JSON 配置

您也可以使用JSON配置文件，而不是环境变量或命令行选项。MCP服务器将按以下顺序查找配置文件：

1. 由……指定的路径 --config 命令行选项
2. 由……指定的路径 CONFIG_FILE 环境变量
3. config.json 在当前目录中
4. openapi-mcp.json 在当前目录中
5. .openapi-mcp.json 在当前目录中

示例JSON配置文件：

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

一个带有解释性注释的完整示例配置文件可在以下位置获取： config.example.json 在根目录中。

配置优先级

配置设置按以下优先级顺序（从高到低）应用：

1. 命令行选项
2. 环境变量
3. JSON配置文件

发展

安装

# Clone the repository
git clone 
cd mcp-http-gateway

# Install dependencies
npm install

# Build the project
npm run build

本地测试

# Start the MCP server
npm run start

# Development mode with auto-reload
npm run dev

定制并发布您自己的版本

您可以使用此存储库作为创建您自己的自定义OpenAPI/GraphQL到MCP服务器的基础。本节将介绍如何克隆该存储库，根据您的特定API进行定制，并将其发布为一个包。

分叉和定制

1. 克隆（或“分叉”）该仓库：

在GitHub上对此仓库进行分支复制，以创建自己的副本并进行自定义。

1. 添加您的OpenAPI规范：

   # Create a specs directory if it doesn't exist
   mkdir -p specs

   # Add your OpenAPI specifications
   cp path/to/your/openapi-spec.json specs/

   # Add any overlay files
   cp path/to/your/overlay.json specs/

1. 配置默认设置：

创建一个自定义配置文件，该文件将与您的包一起打包：

   # Copy the example config
   cp config.example.json config.json

   # Edit the config to point to your bundled specs
   # and set any default settings

1. 更新 package.json：

   {
     "name": "your-custom-mcp-server",
     "version": "1.0.0",
     "description": "Your customized MCP server for specific APIs",
     "files": [
       "dist/**/*",
       "config.json",
       "specs/**/*",
       "README.md"
     ]
   }

1. 确保规范已打包：

这个（或：该） files 在 package.json 文件中（如上所示）的字段确保您的规范文件和配置文件将被包含在发布的包中。

许可证

麻省理工学院（MIT）