OpenAPI的MCP

![CI](https://github.com/davidruzicka/mcp4openapi/actions/workflows/ci.yml) ![codecov](https://codecov.io/gh/davidruzicka/mcp4openapi) ](https://www.npmjs.com/package/mcp4openapi) ](https://hub.docker.com/r/mcp4openapi/mcp4openapi) ![License: MIT](./LICENSE.md)

将任何OpenAPI规范转换为更小、LLM友好的MCP服务器。

概览

输入：任何OpenAPI 3.x规范
成型层：可选的MCP配置文件，用于减少工具、重命名参数、组合工作流和修剪响应
输出：MCP工具暴露在外 stdio 或HTTP

![mcp4openapi-diagram](docs/mcp4openapi-principle.png)

运作原理

步骤	发生了什么	为什么重要
1.加载API	`mcp4openapi` 读取OpenAPI规范	原始REST操作可用于工具生成
2.形状工具	配置文件可以分组、过滤和简化操作	LLM看到的工具更少，但更有用
3.连接客户端	您的MCP客户端通过以下方式连接 `stdio` 或HTTP	您通过MCP使用API，而无需自定义服务器代码

典型结果：

更少的工具和更小的响应，因此LLM保持了更相关的上下文
一台服务器具有多个配置文件，用于开发、暂存、生产或特定角色的访问
具有复合工具和提示定义的可重用高级工作流

从中的现有配置文件开始 profiles/，然后只适应你需要的东西。

从这里开始

我想快点试试：跳转到快速开始并使用现有的捆绑配置文件。
我需要远程访问或OAuth：使用 HTTP传输和 OAuth设置.
我想要定制工具设计：从开始个人资料指南.
我想要自主代理机器合同：参见代理输出模式和自主代理.

核心能力

任何OpenAPI API：适用于OpenAPI 3.x规范
档案：将原始API转换为LLM友好的MCP工具 MCP配置文件
工具聚合：通过对相关操作进行分组来减少工具混乱
复合动作：将API调用链接到可重复使用的工作流
快速定义：直接在配置文件中添加可重用的MCP提示
MCP应用程序资源：暴露静态或获取支持 resources/list, resources/templates/list, resources/read，以及从配置文件完成模板变量
上游MCP提供商配置：配置文件可以声明远程HTTP可流式传输的MCP上游（首先是模式和验证；传输执行在后面的路线图问题中进行）
OAuth 2.0：HTTP传输的基于浏览器的身份验证流（请参见 docs/OAUTH.md)
企业管理授权：使用配置文件驱动的颁发者/JWKS策略和不透明的MCP访问令牌对HTTP传输进行入站JWT承载授予（请参阅 docs/OAUTH.md)
多身份验证：将多个身份验证方法与优先级回退相结合（请参见 docs/MULTI-AUTH.md)
多部分上传: HttpClient 手柄 multipart/form-data
可观测性：具有机密编辑和Prometheus指标的结构化日志记录

安全说明

DNS重新绑定保护：绑定到localhost时(127.0.0.1/::1)，HTTP传输强制执行主机标头验证并返回 403 { "error": "Forbidden" } 关于不匹配。这减轻了针对本地开发服务器的基于浏览器的DNS重新绑定攻击。
对于远程部署，绑定到显式接口或将服务器置于强制执行严格主机检查和源地址分配的反向代理之后。

查看中的示例配置文件配置文件/.

上游MCP路线图配置

配置文件声明单个 upstream_mcp 远程MCP提供程序的对象，或通过从env支持的JSON对象解析它 upstream_mcp_from_env.

第一次迭代中支持的传输： transport.type: "http-streamable"
支持的上游身份验证子集： bearer, query, custom-header
必须引用机密 value_from_env；内联凭据被拒绝
如果 upstream_mcp_from_env 设置并解析为非空JSON，它覆盖静态 upstream_mcp 对象
stdio 上游提供者被有意推迟到稍后的明确门控迭代

例子：

{
  "upstream_mcp_from_env": "MCP4_UPSTREAM_MCP_JSON",
  "upstream_mcp": {
    "name": "remote-mcp",
    "transport": {
      "type": "http-streamable",
      "url": "https://remote-mcp.example/mcp"
    },
    "auth": {
      "type": "bearer",
      "value_from_env": "REMOTE_MCP_TOKEN"
    },
    "tool_prefix": "remote",
    "tools": {
      "allow": ["github_*"],
      "deny": ["admin_*"]
    },
    "timeout_ms": 30000
  }
}

当特定于部署的上游在环境之间不同时，并且您不想编辑签入的配置文件，请使用环境支持的路径。

MCP应用程序配置文件

配置文件现在可以声明顶级 resources[] 对于MCP Apps UI和只读数据表面：

固定资源 uri 并预加载 file_path 或有界 inline_text
模板资源 uri_template，可选变量完成，以及通过声明的只读OpenAPI/复合绑定进行可选的获取支持渲染
刀具水平仪 apps 元数据，用于附加输出模板和小部件元数据，而无需更改核心工具模式生成器

看 docs/PROFILE-GUIDE.md 用于配置文件形状和验证规则。

快速开始

对于大多数用户来说，最简单的路径是：

选择一个捆绑的配置文件，例如 gitlab, codecov，或 n8n.
开始 mcp4openapi 随着 npx.
在下面粘贴一个匹配的MCP客户端配置。

最小本地示例：

export MCP4_API_TOKEN=your_token
npx mcp4openapi --profile gitlab --api-base-url https://gitlab.example.com/api/v4

如果你已经知道你的MCP客户端，直接转到它的配置示例。如果没有，请先使用文件位置部分。

配置文件位置

光标：

项目具体： .cursor/mcp.json 在项目根目录中
全球的： 用户配置文件配置（例如Linux ~/.config/Cursor/User/mcp.json；使用 ⚙ → Tools & MCP → New MCP Server)

VS代码+副本：

项目具体： .vscode/mcp.json 在项目根目录中
全球的： ~/.config/Code/User/mcp.json 在主目录中（取决于平台；使用 Ctrl+Shift+P → MCP: Open User Configuration)

JetBrains IDE+Copilot：

项目具体： .idea/mcp.json 在项目根目录中
全球的： ~/.config/github-copilot/intellij/mcp.json （依赖于平台；使用GitHub Copilot图标右下角→ Edit Setting... → Model Context Protocol (MCP) → Configure)

克劳德代码：

项目具体： .claude/mcp.json 在项目根目录中
全球的： ~/.claude.json 在主目录中（取决于平台）

选项A:npx

无需安装。

VS代码+副本示例：

使用VS Code对话框输入访问令牌（出于安全考虑，建议使用）：

访问令牌（承载）示例：

{
    "servers": {
        "mcp4openapi": {
            "command": "npx",
            "args": [
                "-y", "mcp4openapi",
                "--profile", "
",
                "--api-base-url", "https://api.example.com"
            ],
            "env": {
                "MCP4_API_TOKEN": "${input:api-token}",
            }
        },
        "inputs": [
            {
                "type": "promptString",
                "id": "api-token",
                "description": "API Authorization Token",
                "password": true
            }
        ]
    }
}

_inputs 部分在服务器启动时提示您输入令牌，因此不需要环境变量。_

光标示例

游标stdio示例（非OAuth，仅基于令牌的身份验证）：

{
    "mcpServers": {
        "mcp4openapi": {
            "command": "npx",
            "args": [
                "-y", "mcp4openapi",
                "--profile", "
",
                "--api-base-url", "https://api.example.com"
            ],
            "env": {
                "MCP4_API_TOKEN": "${env:MCP4_API_TOKEN}",
            }
        }
    }
}

游标OAuth示例（HTTP传输，基于URL的MCP服务器）：

{
    "mcpServers": {
        "mcp4openapi-oauth": {
            "url": "http://127.0.0.1:3003/profile/
/mcp"
        }
    }
}

配置文件快捷方式

如果配置文件定义 profile_id （或 profile_name 或 profile_alias)，您可以从以下内容开始：

npx mcp4openapi --profile (profile-id/name/alias)

列出可用配置文件，包括：

npx mcp4openapi --list-profiles
npx mcp4openapi -l

使用以下命令显示标准CLI信息：

npx mcp4openapi --help
npx mcp4openapi -h
npx mcp4openapi --version
npx mcp4openapi -v

中的预定义配置文件 profiles/ 目录包含便于参考的名称：

GitLab简介： gitlab
YouTrack个人资料： youtrack
Codecov配置文件： codecov
GitHub安全配置文件： github-security
SemGrep简介： semgrep
Grafana简介： grafana
n8n配置文件： n8n
n8n简单节点列表配置文件： n8n-nodes

配置文件解析自 ./profiles 默认路径。如果缺少该目录，则使用捆绑的npm包配置文件。覆盖 --profiles-dir 或 MCP4_PROFILES_DIR.

⚠️ 先决条件

MCP4_API_TOKEN 必须为具有经过身份验证的API的stdio传输设置具有访问令牌（Bearer）的（或配置文件中定义的等效环境变量名）。OAuth授权流仅支持HTTP传输。

Claude代码示例：

claude mcp add --transport stdio mcp4openapi \
  -- npx mcp4openapi --profile 
 --api-base-url https://api.example.com

⚠️ 先决条件

MCP4_API_TOKEN 必须设置访问令牌（承载）。

JetBrains IDE+Copilot示例：

{
    "servers": {
        "mcp4openapi": {
            "command": "npx",
            "args": [
                "mcp4openapi",
                "--profile",
                "
",
                "--api-base-url",
                "https://api.example.com"
            ],
            "env": {
                "MCP4_API_TOKEN": "${input:api-token}",
            }
        }
    }
}

备注

JetBrains IDE展⚠️ 紧挨着 ${input:api-token} 以指示您需要在IDE对话框中手动输入令牌。

选项B:Docker

看用于构建、运行、身份验证模式、生产部署和安全性。

本地开发

1.克隆和安装：

git clone https://github.com/davidruzicka/mcp4openapi.git
cd mcp4openapi
npm install

2.构建：

npm run build

3.配置：

cp env.example .env
# Edit .env with your settings

4.运行：

# uses .env for configuration
npm start

或者，使用CLI标志运行：

export MCP4_API_TOKEN=glpat-xxxxxxxxxxxx
npm start --profile mcp-profile

看 docs/HTTP-TRANSPORT.md 用于传输选项（stdio与HTTP）和身份验证模式。

自定义CA证书

Node.js有一个固定的证书颁发机构列表。如果你的MCP服务器使用自签名证书，你需要配置Node.js来信任它们。

Linux

选项1：禁用证书验证（仅限测试）

export NODE_TLS_REJECT_UNAUTHORIZED=0
# Persist for current user
echo 'export NODE_TLS_REJECT_UNAUTHORIZED=0' >> $HOME/.profile

选项2：将自定义CA添加到Node.js

export NODE_EXTRA_CA_CERTS=$HOME/ca-bundle.pem
# Persist for current user
echo 'export NODE_EXTRA_CA_CERTS="$HOME/ca-bundle.pem"' >> $HOME/.profile

Windows（PowerShell）

选项1：禁用证书验证（仅限测试）

# Session only
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
# Persist for current user
setx NODE_TLS_REJECT_UNAUTHORIZED 0

选项2：将自定义CA添加到Node.js

# Session only
$env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\ca-bundle.pem"
# Persist for current user
setx NODE_EXTRA_CA_CERTS "%USERPROFILE%\ca-bundle.pem"

macOS（zsh/bash）

选项1：禁用证书验证（仅限测试）

# Session only
export NODE_TLS_REJECT_UNAUTHORIZED=0
# Persist for current user (zsh)
echo 'export NODE_TLS_REJECT_UNAUTHORIZED=0' >> $HOME/.zshrc
# or for bash
echo 'export NODE_TLS_REJECT_UNAUTHORIZED=0' >> $HOME/.bash_profile

选项2：将自定义CA添加到Node.js

# Session only
export NODE_EXTRA_CA_CERTS="$HOME/ca-bundle.pem"
# Persist for current user (zsh)
echo 'export NODE_EXTRA_CA_CERTS="$HOME/ca-bundle.pem"' >> $HOME/.zshrc
# or for bash
echo 'export NODE_EXTRA_CA_CERTS="$HOME/ca-bundle.pem"' >> $HOME/.bash_profile

环境变量

必需

MCP4_API_TOKEN：API令牌（默认env var名称；可通过 MCP4_AUTH_ENV_VAR 或个人资料 value_from_env 用于身份验证参数）

- stdio需要 具有经过身份验证的API的模式 - HTTP可选 在HTTP标头中发送每个会话令牌的模式 - 当使用无配置文件模式时，OpenAPI会自动检测身份验证类型 security 方案（如有）

可选-核心

MCP4_PROFILE：用于从目录解析配置文件的配置文件ID（由 --profile)
MCP4_PROFILES_DIR：配置文件ID解析的配置文件根目录（默认值： ./profiles)
MCP4_PROFILE_PATH：配置文件JSON路径（默认：从OpenAPI规范自动生成工具；如果工具超过60个参数，则记录警告）
MCP4_OPENAPI_SPEC_PATH：OpenAPI规范的路径或URL（YAML/JSON，支持本地文件和HTTP/HTTPS URL）。当配置文件未提供时需要 openapi_spec_path在HTTP配置文件路由中，这充当了没有配置文件的全局回退 openapi_spec_path.
MCP4_TRANSPORT: stdio （默认）或 http
MCP4_API_BASE_URL：覆盖OpenAPI服务器URL
MCP4_TRUST_BOOTSTRAP_URLS：设置为 true 跳过引导URL获取的SSRF检查（远程OpenAPI规范加载和OAuth元数据发现）。默认为安全模式(false).
MCP4_SSRF_ALLOW_PRIVATE_NETWORK：设置为 true 以允许SSRF验证路径中的私有/环回/链接本地目标，包括引导URL检查。

配置文件身份验证环境变量：使用特定于配置文件的名称 value_from_env （例如， GITLAB_TOKEN, YOUTRACK_TOKEN)而不是通用 MCP4_API_TOKEN.

企业授权环境变量: enterprise_authorization 还支持选择性 *_from_env 发布者、受众、模式、范围、工具类别和声明映射的引用，因此可以在不编辑配置文件的情况下部署HTTP企业身份验证。看 docs/OAUTH.md 对于支持的字段和格式。

CLI映射规则：记录在案 MCP4_* 通过丢弃以下命令，可以将env变量作为CLI标志传递 MCP4_ 前缀和使用烤肉串大小写。例子： MCP4_PROFILE_PATH -> --profile-path, MCP4_OPENAPI_SPEC_PATH -> --openapi-spec-path未知标志导致启动失败。

可选-工具筛选

全局工具筛选在每个会话的配置文件加载期间删除工具。

MCP4_TOOL_FILTER_ALLOW_NAMES：要保留逗号分隔的工具名称（精确匹配，区分大小写）
MCP4_TOOL_FILTER_ALLOW_NAME_REGEX：允许使用逗号分隔的正则表达式模式（除非已经用 ^ 和 $)
MCP4_TOOL_FILTER_DENY_NAMES：要排除的逗号分隔的工具名称
MCP4_TOOL_FILTER_DENY_NAME_REGEX：要排除的逗号分隔正则表达式模式（自动锚定）
MCP4_TOOL_FILTER_ALLOW_CATEGORIES：逗号分隔的操作类别允许(list 和 read).只有当所有步骤都在允许的类别内时，才允许使用复合工具。
MCP4_TOOL_FILTER_WARN_THRESHOLD_PCT：当筛选百分比超过此阈值时发出警告（默认值： 90)
MCP4_TOOL_FILTER_SESSION_MAX_TOOLS：中的最大条目数 X-Mcp4-Tools 标题（默认值： 100)

对正则表达式模式进行长度、嵌套量词和量词替换验证，以降低ReDoS风险。

工具筛选故障排除

如果启动失败并显示“工具过滤器配置无效”，请确保允许或拒绝模式实际更改了工具集。
如果启动失败，并显示“所有工具已过滤”，请放宽允许或拒绝设置，以保留至少一个工具。
如果会话初始化失败，并显示“X-Mcp4-Tools过滤器无效”，请删除空标头或调整条目以限制工具。
如果会话初始化失败，并显示“X-Mcp4-Tools已过滤掉所有工具”，请验证工具名称或正则表达式模式是否与可用工具匹配。
如果正则表达式验证失败，请缩短模式并避免嵌套量词或替换量词。

可选-参数筛选

全局参数过滤在两个过程中都约束了工具调用参数 stdio 和 http.

MCP4_PARAM_FILTER：使用与相同格式的基线参数筛选器 X-Mcp4-Params

CLI映射：

MCP4_PARAM_FILTER -> --param-filter

规则：

在 stdio, MCP4_PARAM_FILTER 适用于本地进程的生命周期。
在 http, MCP4_PARAM_FILTER 是每个会话的基线。
如果客户端也发送 X-Mcp4-Params 在HTTP初始化期间，会话标头可能只会缩小全局基线。
冲突重叠失败，出现验证错误。

示例:

npx mcp4openapi \
  --transport stdio \
  --tool-filter-allow-names manage_merge_requests \
  --param-filter "project_id=123,_allow_read"

可选-身份验证（无配置文件模式）

当在没有配置文件的情况下运行时（仅限OpenAPI规范），身份验证将从OpenAPI规范自动配置 security 计划：

MCP4_AUTH_ENV_VAR：身份验证令牌的环境变量名称（默认值： MCP4_API_TOKEN)

支持的OpenAPI安全类型：

持有者令牌 (http 随着 scheme: bearer)：用途 Authorization: Bearer 头球
标题中的API键 (apiKey 随着 in: header)：使用自定义标头（例如。， X-API-Key: )
查询中的API密钥 (apiKey 随着 in: query)：将令牌添加到查询字符串中（例如。， ?api_key=)
OAuth2/OpenID连接：映射到承载令牌身份验证（仅配置文件模式）
公共API：如果OpenAPI规范没有，则不进行身份验证 security 定义的

示例：为GitLab自己的实例令牌使用自定义env var：

export MCP4_API_TOKEN=xxxxxxxxxxxx
npm start \
  --api-base-url https://gitlab.example.com/api/v4 \
  --openapi-spec-path https://gitlab.example.com/api/v4/openapi.yaml

_⚠️ 警告：在没有配置文件的情况下运行可能会生成许多具有许多参数的工具，从而导致LLM上下文污染。_

强制身份验证覆盖

对于OpenAPI规范不完整的API（缺失 security 定义但需要身份验证）：

MCP4_AUTH_FORCE：启用强制身份验证覆盖(true|false，默认值： false)
MCP4_AUTH_TYPE：身份验证类型： bearer|query|custom-header （默认值： bearer)
MCP4_AUTH_HEADER_NAME：自定义标头名称（当 MCP4_AUTH_TYPE=custom-header)
MCP4_AUTH_QUERY_PARAM：查询参数名称（当 MCP4_AUTH_TYPE=query)

示例：不完整规范的强制承载身份验证：

export MCP4_AUTH_FORCE=true
export MCP4_AUTH_TYPE=bearer
export MCP4_API_TOKEN=your_token_here
export MCP4_OPENAPI_SPEC_PATH=./incomplete-spec.yaml
npm start

CLI替代方案：

export MCP4_API_TOKEN=your_token_here
npm start \
  --auth-force true \
  --auth-type bearer \
  --openapi-spec-path ./incomplete-spec.yaml

备注：如果OpenAPI规范有 security 定义后，它优先于强制身份验证设置。

可选-代理下载大小限制

MCP4_PROXY_MAX_BYTES：代理下载大小限制的全局覆盖（字节）。必须是正整数。
当配置文件通过以下方式定义时，特定于配置文件的环境变量可以优先 max_size_bytes_from_env 在一个 proxy_download 操作。

优先：配置文件特定的环境覆盖→ MCP4_PROXY_MAX_BYTES → 简介 max_size_bytes → 内置默认值（10MB）。

示例：全球代理下载量上限为2MB

export MCP4_PROXY_MAX_BYTES=2097152

可选-工具名称缩短

当从OpenAPI生成没有配置文件的工具时，长操作ID可能会超过限制。配置自动缩短：

MCP4_TOOLNAME_MAX：最大工具名称长度（默认值： 45)
MCP4_TOOLNAME_STRATEGY缩短战略： none|balanced|iterative|hash|auto （默认值： none)

- none：没有缩短，只有警告 - balanced：按重要性添加零件，直到独特且有意义（推荐） - iterative：逐步消除噪音，直到低于极限（保守） - hash：使用动词+资源+哈希保证唯一性 - auto：按顺序尝试策略：平衡→ 迭代的→ hash

MCP4_TOOLNAME_WARN_ONLY：仅警告，不要缩短： true|false （默认值： true)
MCP4_TOOLNAME_SIMILAR_TOP：在警告中显示多少个类似的operationId对（默认值： 3)
MCP4_TOOLNAME_SIMILARITY_THRESHOLD：警告示例的相似性阈值（默认值： 0.75)
MCP4_TOOLNAME_MIN_PARTS：平衡策略的最小部件（默认值： 3)
MCP4_TOOLNAME_MIN_LENGTH：平衡策略的最小长度（以字符为单位）（默认值： 20)

示例：使用平衡缩短法（推荐）：

export MCP4_TOOLNAME_STRATEGY=balanced
export MCP4_TOOLNAME_WARN_ONLY=false

结果平衡战略：

putApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImagesMetricImageId
    → put_alert_management_image (26 chars)
deleteApiV4ProjectsIdAlertManagementAlertsAlertIidMetricImagesMetricImageId
    → delete_alert_management_image (26 chars)

示例2：应用30个字符限制的迭代缩短：

export MCP4_TOOLNAME_STRATEGY=iterative
export MCP4_TOOLNAME_WARN_ONLY=false
export MCP4_TOOLNAME_MAX=30

可选-HTTP传输

MCP4_HOST：绑定地址（默认值： 127.0.0.1)
MCP4_PORT：端口（默认值： 3003)
MCP4_ALLOWED_ORIGINS：逗号分隔的起源（支持精确、通配符 *.domain.com，CIDR 192.168.1.0/24)
MCP4_SESSION_TIMEOUT_MS：会话超时（默认值： 1800000 =30分钟）
MCP4_OAUTH_SESSION_TIMEOUT_MS：具有刷新令牌的会话的OAuth会话超时（默认值： 86400000 =24h， 0 =无限制）
MCP4_OAUTH_REFRESH_THRESHOLD_MS：在到期前几毫秒刷新访问令牌（默认值： 60000 =60秒）
MCP4_HEARTBEAT_ENABLED, MCP4_HEARTBEAT_INTERVAL_MS：SSE心跳设置
MCP4_TOKEN_MAX_LENGTH：最大令牌长度（以字符为单位）（默认值： 4096，从 1000 在阶段03.4中容纳加密令牌信封）
MCP4_TOKEN_KEY：AES-256-GCM加密令牌信封的可选对称密钥。设置后，网关会发出问题 mcp4.v1.* OAuth客户端上的令牌 /oauth/token 并在重新启动时从它们中重新水化会话，从而消除了k8s重新启动场景中的重新身份验证往返。接受任何密码（SHA-256派生）或64个字符的十六进制字符串（32个原始字节）。默认未设置（纯令牌模式，向后兼容）。看 docs/HTTP-TRANSPORT.md ->加密令牌信封以获取详细信息。
MCP4_FILTER_MAX_VALUES：每个筛选键的最大值（默认值： 10)
MCP4_HTTP_PROFILE_ROUTING：启用配置文件路由(/profile/:id/mcp).如果在没有默认配置文件的情况下启用， /mcp 未注册。
MCP4_HTTP_PROFILE_INDEX：启用配置文件索引 GET / 用于路由配置文件。
MCP4_PROFILES_DESCRIPTION：可选的JSON对象将配置文件id/name/alias映射到配置文件描述之前的HTML配置文件详细信息卡中显示的管理员提供的HTML代码段。启动时解析一次，JSON索引响应忽略一次，无效JSON、非字符串值、重复解析冲突或长度超过 10000 字符。
MCP4_ALLOW_PROFILES：路由配置文件允许使用逗号分隔的配置文件ID/名称/别名。
MCP4_ALLOW_PROFILES_REGEX：允许的配置文件ID/名称/别名的正则表达式（仅在启用路由时适用）。
MCP4_HIDDEN_PROFILES：逗号分隔的配置文件ID/名称/别名，用于在索引页中隐藏（配置文件仍保持完全功能）。
MCP4_HTTP_TENANTS_FILE：租户选择器配置JSON的路径。
MCP4_HTTP_TENANTS_JSON：内联租户选择器配置JSON。
MCP4_HTTP_TENANTS_ALLOW_HTTP：允许 http 租户选择器（默认值为 https 仅）。

配置文件路由示例:

export MCP4_TRANSPORT=http
export MCP4_HTTP_PROFILE_ROUTING=true
export MCP4_HTTP_PROFILE_INDEX=true
export MCP4_ALLOW_PROFILES=gitlab-optimized,youtrack-optimized
export MCP4_PROFILES_DIR=./profiles
npx mcp4openapi

CLI替代方案：

npx mcp4openapi --transport http \
  --http-profile-routing true \
  --http-profile-index true \
  --allow-profiles gitlab,github \
  --profiles-dir ./profiles

卷曲测试:

curl -X POST http://localhost:3003/profile/mcp-profile-name/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

配置文件索引管理说明:

export MCP4_HTTP_PROFILE_ROUTING=true
export MCP4_HTTP_PROFILE_INDEX=true
export MCP4_PROFILES_DESCRIPTION='{"gitlab":"
Internal: Use SSO token.
","youtrack":"
Use permanent token from Hub.
"}'

笔记：

钥匙与 profileId, profileName和别名。
HTML仅在上的HTML配置文件索引详细信息卡中呈现 GET /，不在JSON有效载荷中。
该值呈现为原始HTML，因此只应使用受信任的管理员提供的内容。

如果 MCP4_PROFILE_PATH （或 --profile-path)设置， /mcp 仍然可用 /profile/:id/mcp.

HTTP租户选择器（X-Mcp4-租户Id/X-Mcp4-Api-Base-Url）

租户选择是通过以下方式配置的 MCP4_HTTP_TENANTS_FILE 或 MCP4_HTTP_TENANTS_JSON 并同时支持：

精确选择器： https://team-a.example.com/api
掩码选择器： mask:https://grafana.*.security.*.ops.iszn.cz/api
掩码路径通配符： mask:https://monitoring.ops.iszn.cz/*/api (* 恰好匹配一个路径段）

选择标头（初始化请求）：

X-Mcp4-Tenant-Id：按以下方式选择租户 tenant_id
X-Mcp4-Api-Base-Url：按精确或选择具体租户端点 mask: 选择器

所需租户范围：

profile_ids：租户处于活动状态时，需要配置文件id的非空数组

解决顺序：

X-Mcp4-Tenant-Id
精确 X-Mcp4-Api-Base-Url
mask: X-Mcp4-Api-Base-Url

规则：

对于 mask: 租户选择，具体 X-Mcp4-Api-Base-Url 是必需的。
如果提供了两个租户标头，则它们必须解析为同一租户。
在现有会话请求上，提供的租户标头必须与存储的租户上下文匹配。
启动时拒绝选择器冲突（精确/精确与不兼容的身份验证、精确/掩码重叠、掩码/掩码重叠），运行时拒绝模糊的掩码匹配。
如果没有发送租户标头，则不会应用租户覆盖，并使用配置文件级别配置。

当 MCP4_HTTP_PROFILE_INDEX=true，HTML配置文件索引显示每个配置文件的租户可用性，并为支持的远程代码段格式提供交互式租户选择器，以注入 X-Mcp4-Tenant-Id 转换为复制的代码段输出。Picker始终包含一个“无租户”选项，该选项保留没有租户标头的代码段。对于 mask: 租户，复制的片段还包括示例 X-Mcp4-Api-Base-Url 通配符部分替换为 `.In Local stdio 模式下，租户选择在支持本地env注入的片段中更新API基本URL（使用概要文件API端点env var）。同一页面还公开了一个每个配置文件的工具目录，其中包含交互式构建器，用于 X-Mcp4-Tools 和 X-Mcp4-Params：在远程模式下，当筛选处于活动状态时，隐藏不受支持的自定义标头片段变体；在本地模式下，相同的过滤器状态被转换为 --tool-filter-allow-names, --tool-filter-allow-categories，以及 --param-filter 内部生成的stdio代码片段。使用的配置文件 auth.type: "session-cookie" 仅在以下内容中故意显示 Local stdio` 代码片段，因为远程HTTP初始化不接受通过请求标头的上游登录/密码。

参数过滤（HTTP:X-Mcp4-Params）

X-Mcp4-Params 是用于约束工具调用参数（而非工具选择）的每个会话标头。它在会话初始化时解析，然后在会话的生命周期内强制执行：后续请求可能会省略标头，但如果提供了标头，它必须与会话值匹配，或者服务器返回 400 验证错误。如果 MCP4_PARAM_FILTER 如果设置了，会话标头可能只会缩小该进程范围的基线。

格式：逗号分隔 key=value 对。重复按键以允许多个值。

GitLab配置文件示例:

X-Mcp4-Params: project_id=123, project_id=mcp/mcp-gitlab, _allow_list, _allow_read

这意味着什么:

会话仅限于由以下任一项标识的GitLab项目 123 或 mcp/mcp-gitlab （两者都指同一个项目） project_id （或映射到它的别名）。如果工具调用提供了不同的 project_id，服务器拒绝它。
这对于代理风格的工作流（例如，“仅在项目123/456内进行代码审查”）很有用，因为客户端可以在会话初始化时强制执行作用域，而不是依赖代理始终记住传递正确的项目参数。
_allow_list 和 _allow_read 放宽列表和读取操作的过滤强制；如果你想允许列表/读取调用，即使它们省略了筛选键，或者传递了不同的值，也可以使用它们。

备注:

根据当前可用的工具参数（包括参数别名）验证密钥。
每个键的最大值受到以下限制 MCP4_FILTER_MAX_VALUES.
控制键（无值）：

- _allow_list：允许列表操作省略筛选键（仅影响存在强制）。 - _allow_read：允许读取操作省略筛选键（仅影响存在强制）。 - 如果参数中存在筛选键，则其值不受列表/读取操作的约束。 - 控制键不会放松修改操作。 - 只有当至少有一个控制键时，控制键才有意义 key=value 过滤器存在（否则无需强制执行）。

看 docs/HTTP-TRANSPORT.md 详细的HTTP传输配置。

SSL/TLS配置

MCP4_SSL_CERT_FILE, MCP4_SSL_KEY_FILE：SSL证书和密钥（PEM格式）

当两者都设置好时，服务器会自动以HTTPS模式启动。

看 docs/OAUTH.md 使用OAuth进行SSL配置。

OAuth 2.0配置

OAuth需要HTTP传输。标准(command/args)客户端配置不支持OAuth浏览器流。

游标OAuth设置（全局用户配置）示例：

{
    "mcpServers": {
        "gitlab-oauth": {
            "url": "http://127.0.0.1:3003/mcp"
        }
    }
}

自动发现 -只需提供DCR（动态客户端注册）凭据、API基本URL和OAuth回调：

export MCP4_TRANSPORT=http
export MCP4_HOST=127.0.0.1
export MCP4_PORT=3003
export MCP4_API_BASE_URL=https://www.gitlab.com/api/v4
export MCP4_OAUTH_CLIENT_ID=your_dcr_client_id
export MCP4_OAUTH_CLIENT_SECRET=your_dcr_client_secret
export MCP4_OAUTH_REDIRECT_URI=http://127.0.0.1:3003/oauth/callback
# OAuth endpoints are automatically discovered from API base URL

备注：DCR和OAuth回调必须向OAuth提供者注册。

配置优先级：

显式URL: MCP4_OAUTH_AUTHORIZATION_URL, MCP4_OAUTH_TOKEN_URL （最高优先级）
明确发行人: MCP4_OAUTH_ISSUER （自动导出标准OAuth路径）
自动发现：来自 MCP4_API_BASE_URL （获取RFC 8414元数据或使用标准路径）

环境变量：

MCP4_OAUTH_CLIENT_ID, MCP4_OAUTH_CLIENT_SECRET：OAuth客户端凭据（必需）
MCP4_OAUTH_REDIRECT_URI：OAuth重定向URI（必需，必须与注册的URI匹配）
MCP4_ALLOW_UNREGISTERED_CLIENTS：当重定向URI与批准的分配列表匹配时，允许对未注册的OAuth客户端进行授权请求（可选，默认： false)
MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS：未注册OAuth客户端的逗号分隔的批准重定向URI规则，例如。 http://localhost,cursor:// （可选）
MCP4_OAUTH_ISSUER：OAuth提供程序颁发者URL（可选，自动导出端点）
MCP4_OAUTH_AUTHORIZATION_URL, MCP4_OAUTH_TOKEN_URL：OAuth端点（可选，用于非标准路径）
MCP4_OAUTH_CLIENT_STORE_MAX_CLIENTS：内存中存储的最大动态OAuth客户端数（默认值： 1000)
MCP4_OAUTH_CLIENT_STORE_MAX_REDIRECT_URIS：Max redirect_uris 每个动态客户端（默认值： 10)
MCP4_OAUTH_CLIENT_STORE_MAX_REDIRECT_URI_LENGTH：一个重定向URI的最大长度（默认值： 256)
MCP4_OAUTH_CLIENT_STORE_IDLE_GRACE_MS：空闲OAuth客户端可驱逐之前的最小年龄（ms）（默认值： 0)

CLI等效项：

--allow-unregistered-clients true
--allowed-unregistered-redirect-uris http://localhost,cursor://

动态客户端商店驱逐行为：

驱逐更喜欢空闲的动态客户端(mcp-client-*)并且不会驱逐当前在会话/状态/代码流中活动的客户端。
如果存储已满，并且没有空闲的候选者可以安全地驱逐， /oauth/register 回报 429 随着 temporarily_unavailable.

看 docs/OAUTH.md 获取完整的设置指南，包括OAuth应用程序注册、SSL配置和故障排除。

HTTP速率限制（安全）

MCP4_HTTP_RATE_LIMIT_ENABLED：启用速率限制（默认值： true)
MCP4_HTTP_RATE_LIMIT_WINDOW_MS：速率限制窗口（默认值： 60000 =1分钟）
MCP4_HTTP_RATE_LIMIT_MAX_REQUESTS：MCP端点的最大请求数（默认值： 100)
MCP4_HTTP_RATE_LIMIT_METRICS_MAX：最大请求数 /metrics （默认值： 10)

OAuth速率限制 （对OAuth端点有更严格的限制）：

MCP4_OAUTH_RATE_LIMIT_MAX：每个窗口的最大OAuth请求数（默认值： 10)
MCP4_OAUTH_RATE_LIMIT_WINDOW_MS：OAuth速率限制窗口（默认值： 60000 =1分钟）

配置优先：配置文件>环境变量>默认值

默认值:

MCP端点每分钟100个请求，指标每分钟10个请求
10个请求/1分钟用于OAuth端点(/oauth/authorize, /oauth/token, /oauth/callback)

退货 429 Too Many Requests 当超过。

可选-可观察性

MCP4_LOG_LEVEL: debug, info （默认）， warn, error
MCP4_LOG_FORMAT: console （默认）或 json
MCP4_METRICS_ENABLED：启用Prometheus指标（默认值： false)
MCP4_METRICS_PATH：度量端点（默认值： /metrics)
HTTP/会话/工具/API指标包括 profile_id 和 tenant_id 标签；当未解决时，他们使用 profile_id="unknown" 和 tenant_id="none".

安全说明:

敏感的身份验证令牌会根据您的配置文件的身份验证配置（承载、查询、自定义标头或会话cookie）从日志中自动编辑
返回给客户端的所有错误都被净化为通用消息(Internal error)而完整的细节记录在服务器端

配置文件系统

Profile定义了OpenAPI规范中公开的MCP工具以及如何聚合它们。 从现有配置文件开始 从 profiles/ （例如GitLab）。

特征：

工具聚合（组相关操作）
响应字段过滤（减少LLM上下文）
复合操作（连锁API调用）
速率限制和重试逻辑

创建自己的个人资料：参见 docs/PROFILE-GUIDE.md

测试与验证

验证配置文件

npm run validate
# Checks: JSON syntax, schema, logic, OpenAPI operations

验证架构

npm run validate:schema
# Validates profile-schema.json itself

运行测试

npm test
npm run test:e2e

MCP故障排除

光标：

打开“输出”面板（Ctrl+Shift+U/Cmd+Shift+U）
从下拉列表中选择“MCP日志”
检查连接错误或身份验证问题

VS代码：

从“视图”菜单打开“输出”
从下拉列表中选择有问题的MCP服务器
查看MCP工具日志中的错误

JetBrains集成开发环境：

打开“帮助”→ “显示登录\”→ 访问mcp日志文件的“mcp”目录
检查 .log MCP相关错误

常见问题：

连接被拒绝： 检查MCP服务器是否正在运行且可访问
身份验证失败： 验证令牌是否正确以及是否具有所需权限
证书错误： 配置Node.js以信任自定义CA证书（请参阅自定义CA证书)
未找到工具： 验证OpenAPI规范路径和配置文件配置

IDE特定文档

光标： 光标MCP指南
VS代码+副本： VS代码MCP服务器,
JetBrains IDE+Copilot： JetBrains+副驾驶MCP指南

文档

文档/示例-GITLAB.md -使用curl命令完成GitLab API示例
docs/PROFILE-GUIDE.md -创建自定义配置文件指南
docs/HTTP-TRANSPORT.md -HTTP传输设置和使用
docs/OAUTH.md -OAuth 2.0身份验证设置指南
docs/MULTI-AUTH.md -多身份验证支持：OAuth+承载令牌
**** -Docker部署指南（包括Kubernetes示例）
docs/RELEASING.md -发布流程和CI/CD自动化（面向维护人员）
profiles/ -OpenAPI规范的示例配置文件
profiles/youtrack/ -YouTrack配置文件+捆绑的OpenAPI规范（即用型MCP工具）
profiles/codecov/ -Codecov CRUD风格配置文件+捆绑的OpenAPI规范
profile-schema.json -IDE自动补全的JSON模式

项目状态

带工具生成的核心MCP服务器
标准传输（MCP SDK）
HTTP流传输（MCP规范2025-03-26）
会话管理和SSE可恢复性
带验证的配置文件系统
Prometheus指标（HTTP、会话、工具、API调用）

贡献

看 CONTRIBUTING.md 发展指南。

许可证

麻省理工学院

MCP From Openapi

快速接入

详细介绍

OpenAPI的MCP

概览

运作原理

从这里开始

核心能力

安全说明

上游MCP路线图配置

MCP应用程序配置文件

快速开始

配置文件位置

选项A:npx

VS代码+副本示例：

光标示例

配置文件快捷方式

⚠️ 先决条件

Claude代码示例：

⚠️ 先决条件

JetBrains IDE+Copilot示例：

备注

选项B:Docker

本地开发

自定义CA证书

Linux

Windows（PowerShell）

macOS（zsh/bash）

环境变量

必需

可选-核心

可选-工具筛选

工具筛选故障排除

可选-参数筛选

可选-身份验证（无配置文件模式）

强制身份验证覆盖

可选-代理下载大小限制

可选-工具名称缩短

可选-HTTP传输

HTTP租户选择器（X-Mcp4-租户Id/X-Mcp4-Api-Base-Url）

参数过滤（HTTP:X-Mcp4-Params）

SSL/TLS配置

OAuth 2.0配置

HTTP速率限制（安全）

可选-可观察性

配置文件系统

测试与验证

验证配置文件

验证架构

运行测试

MCP故障排除

IDE特定文档

文档

项目状态

贡献

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP