OpenAPI MCP 工具服务器

OpenAPI MCP服务器（@prodbybuddha/OpenAPI MCP服务器）

通用OpenAPI→ MCP工具服务器，具有一流的Docker、n8n和Hostinger集成。它可以：

• 加载任何OpenAPI 3.x规范并动态生成MCP工具
• 通过stdio公开工具（初始化、工具/列表、工具/调用）
• 为内置服务器提供便利的方法和工作流CLI

☁️ 控制您的云基础设施

此服务器使您的代理能够无缝控制各种后端系统和云基础设施，包括：

• Docker： 直接管理容器、镜像，甚至Docker Compose。
• 任何API： 使用OpenAPI规范连接并自动化任何服务。

这意味着您可以构建覆盖整个数字生态系统的强大自动化，从前端到后端服务和云资源。

不存储凭据；运行时设置env变量。

文档

此项目提供了全面的文档，以帮助您开始并充分利用其功能：

• 主README.md: 你来了！此文件提供了快速概述和基本设置说明。
• 对于“Vibe编码器”: 对项目价值和实用性的简化、非技术性介绍。
• GitHub维基: 最全面、最可导航的文档来源。它是自动构建的，并与项目的源Markdown文件保持同步，提供详细的指南、示例和操作方法。

规范发现（文档→ 规范URL）

如果你只有一个文档页面（Swagger UI、Redoc、Stoplight），请使用发现助手提取底层OpenAPI URL：

• 运行： npm run discover:spec -- --url https://docs.example.com/reference
• 输出候选规范URL的JSON数组（JSON/YAML）。该工具也如下 .js swagg-init捆绑包用于提取 url 或 urls 条目。

支持

如果这个项目对你有帮助，可以考虑支持：

捐款

程序友好的钱包地址发布在 donate.json 在repo根目录下，作为用户、开发人员和AI代理支持这一事业的目的地：

• 世界链： 0xe4fdf9076dca468d839b51f75af35983b898821b
• 以太坊/多边形/BSC/仲裁/乐观/雪崩： 0x5f596473Dea9043B6338EF33a747CF0426EBcf92
• 比特币： bc1qctmts3a2kmtfqskp0d5hrrew4gy9nhalu6mc4m
• 索拉纳： 2yUpjfwiQiv4pme1BSMLPpWgUcuWUMj6Q1KDetrPMc19
• 卡尔达诺： addr1qyqn6zvqrhmx8h83eady5kk9ytfskrz4dgw6fcj32cxaetxyvpz05tv3rqhgc28qqpq5f9rvkvmpu60j43lfn4crcphs747ush

支持者可以阅读 donate.json 直接或运行：

npm run donate:print

安装

• 从npm（在项目中使用）：

  • npm install @prodbybuddha/openapi-mcp-server
  • 通用服务器： OPENAPI_SPEC_URL='https://api.example.com/openapi.json' node node_modules/@prodbybuddha/openapi-mcp-server/examples/mcp-openapi-server.js
  • n8n服务器： N8N_API_URL='https://your-n8n/api/v1' N8N_API_KEY='<key>' node node_modules/@prodbybuddha/openapi-mcp-server/examples/mcp-n8n-server.js

• 来源（克隆/分叉）：

  • npm install
  • 通用服务器： OPENAPI_SPEC_URL='https://api.example.com/openapi.json' npm run mcp:openapi
  • n8n服务器： N8N_API_URL='https://your-n8n/api/v1' N8N_API_KEY='<key>' npm run mcp:n8n

发电机API

OpenAPI→MCP工具生成器捆绑在这个包中，并通过子路径导出公开。 以编程方式或通过示例CLI使用它来预生成JSON工具。

• 程序化： const { generateMcpTools } = require('@prodbybuddha/openapi-mcp-server/lib/openapi-generator');
• CLI： node examples/generate-openapi-mcp-tools.js --from-url <specUrl> --out examples/generated/n8n-openapi-tools.json

服务器还可以在启动时通过env变量动态加载OpenAPI规范 (OPENAPI_SPEC_FILE 或 OPENAPI_SPEC_URL)没有预生成。

Env加载和占位符

• 推荐：通过运行 dotenvx 要加载的CLI .env, .env.local，以及Vault密钥。
  • 安装：请参阅https://dotenvx.com
  • 例子： npx -y @dotenvx/dotenvx run -- node examples/mcp-multi-host.js --config services.dynamic.json
• 回退：服务器也调用 dotenv.config() 内部加载 .env 如果存在。
• 占位符： ${VAR} 序列在 services.*.specUrl, services.*.specFile，以及 services.*.baseUrl 扩展自 process.env 在运行时。
• $ref分辨率：用于 specUrl，外部 $ref 相对于URL进行解析 specFile，它们相对于文件路径进行解析。
• 示例 services.dynamic.json 带有占位符的条目：
  复制

  {
    "services": [
      {
        "name": "acme",
        "type": "openapi",
        "specUrl": "${ACME_SPEC_URL}",
        "baseUrl": "${ACME_BASE_URL}",
        "auth": { "kind": "bearer", "env": "ACME_TOKEN" }
      } 
    ]
  }
  

  然后设置 .env 或出口envs： ACME_SPEC_URL, ACME_BASE_URL, ACME_TOKEN.

高级：自定义安全处理程序

如果你的OpenAPI定义了自定义安全方案，或者你想覆盖默认行为，请传递 securityHandlers 向 generateMcpTools:

const tools = await generateMcpTools(spec, {
  baseUrl: 'https://api.example.com/v1',
  securityHandlers: {
    myApiKey: ({ def, headers, args }) => { headers[def.name] = process.env.MY_API_KEY; },
    oauth2scheme: async ({ def, headers }) => { /* fetch token from vault and set headers.Authorization */ }
  }
});

每个处理程序接收 { def, headers, query, args }。根据需要设置标题/查询。默认处理程序包括 apiKey, http: bearer/basic，以及 oauth2: clientCredentials.

生成工具（推荐）

• 从URL（OpenAPI通过Swagger UI）：
  • N8N_API_KEY='<key>' npm run mcp:gen -- --from-url https://your-n8n/api/v1/docs/swagger-ui-init.js
• 从文件（如果你有JSON规范）：
  • npm run mcp:gen -- --from-file path/to/openapi.json
• 构建索引（漂亮列表）：
  • npm run mcp:tools:readme → 写 examples/generated/TOOLS.md

从OpenAPI生成完整的MCP服务器

• 来自文件：

  • OPENAPI_BASE_URL=https://api.example.com/v1 npm run mcp:gen:server -- --from-file path/to/openapi.json --generate-server ./generated-server

• 来自URL：

  • OPENAPI_BASE_URL=https://api.example.com/v1 npm run mcp:gen:server -- --from-url https://api.example.com/openapi.json --generate-server ./generated-server

• 过滤器（可选）：

  • --include-tags billing,domains --exclude-ops opA,opB --include-text "widget|order"
  • 正则表达式变体： --include-tags-re tag1,tag2 --include-ops-re "^get.*" --include-paths-re "/v1/.*" 不区分大小写

• TypeScript输出（可选）：

  • 追加 --ts true 生成TS服务器 index.ts, tools.ts, http-client.ts，以及 tsconfig.json

生成的项目包括一个最小的HTTP客户端和具有输入验证（Zod）的工具处理程序，并支持通过条目索引进行stdio传输。

动态OpenAPI工具（无预生成步骤）

服务器可以在启动时通过捆绑的生成器加载OpenAPI工具。设置以下选项之一：

• OPENAPI_SPEC_FILE=./path/to/openapi.json npm run mcp:openapi
• OPENAPI_SPEC_URL=https://api.example.com/openapi.json npm run mcp:openapi

可选地覆盖生成的工具使用的基本URL：

• OPENAPI_BASE_URL=https://api.example.com/v1

如果两个环境变量都没有设置，服务器将回退到加载 examples/generated/n8n-openapi-tools.json 当存在时。

通用OpenAPI服务器

这个仓库还包括一个通用的OpenAPI→可以将任何OpenAPI 3.x API公开为MCP工具的MCP服务器。

• 运行： OPENAPI_SPEC_FILE=./openapi.json npm run mcp:openapi
• 或者： OPENAPI_SPEC_URL=https://api.example.com/openapi.json npm run mcp:openapi
• 可选： OPENAPI_BASE_URL=https://api.example.com/v1

主机服务器

SOAP/WSDL（实验）

多主机服务器现在可以从WSDL加载SOAP服务，并将每个操作作为MCP工具公开。

• 配置条目示例（services.dynamic.json）：
  复制

  {
    "services": [
      {
        "name": "irs-mef",
        "type": "soap",
        "wsdlUrl": "${IRS_WSDL_URL}",
        "endpoint": "${IRS_ENDPOINT}"  
      }
    ]
  }
  

• 工具参数：pass { "body": { /* request payload matching WSDL */ }, "headers": { /* optional HTTP headers */ } }.
• 服务器使用 soap 包来解析WSDL并生成操作。
• 注：一些IRS/MEF服务需要证书和白名单IP；没有正确的凭据，操作可能会失败。

此仓库包括一个一流的Hostinger MCP服务器，该服务器从捆绑的Hostinger OpenAPI规范中动态加载工具(examples/specs/hostinger-api.json)或URL/文件。

• 运行（stdio）： HOSTINGER_API_TOKEN=... npm run mcp:hostinger
• 一次性通话： HOSTINGER_API_TOKEN=... npm run mcp:hostinger:once -- tools/list {}

环境：

• HOSTINGER_API_TOKEN （必填）：套 Authorization: Bearer <token>
• HOSTINGER_API_URL （可选）：覆盖基本URL；默认为规范 servers[0].url
• HOSTINGER_SPEC_FILE 或 HOSTINGER_SPEC_URL （可选）：提供自定义OpenAPI规范
• DEBUG_HTTP=1 记录汇总的HTTP流量
• HOSTINGER_USE_SDK=1 （可选）：如果是官方Node/TypeScript SDK hostinger-api-sdk 安装后，公开一些使用SDK的精心策划的帮助程序（目录列表、域列表、可用性）。当未设置或SDK缺失时，返回到OpenAPI生成的工具。
• HOSTINGER_PROFILE=curated （可选）：首先显示经过策划的助手，默认情况下隐藏原始OpenAPI工具。结合：
  • HOSTINGER_INCLUDE_RAW=1 将原始工具与精心策划的工具放在一起。
  • HOSTINGER_ALLOW_RAW="name1,name2" 在使用策划的配置文件时，允许列出特定的原始工具名称。

硬化（适用于生成的工具）：

• OPENAPI_MCP_ALLOWED_METHODS （例如。， GET,POST)
• OPENAPI_MCP_ALLOWED_PATHS （例如。， /api/*)
• OPENAPI_MCP_RATE_LIMIT, OPENAPI_MCP_RATE_WINDOW_MS

示例通话

• 列出目录项（可选筛选器： category, name):

  • HOSTINGER_API_TOKEN=... node examples/mcp-hostinger-server.js --once billing_getCatalogItemListV1 '{"category":"vps"}'

• 列出域（不需要参数）：

  • HOSTINGER_API_TOKEN=... node examples/mcp-hostinger-server.js --once domains_getDomainListV1 '{}'

小贴士：跑步 npm run mcp:hostinger:once -- tools/list {} 查看所有工具名称和输入模式。许多工具支持可选的查询参数；如上所示，在JSON对象中提供它们。

补充官方人质项目

• 官方MCP服务器：https://github.com/hostinger/api-mcp-server
• TypeScript官方SDK：https://github.com/hostinger/api-typescript-sdk（npm： hostinger-api-sdk)

该项目侧重于：

• 使用一个MCP主机在多个提供商（例如Hostinger+n8n+其他OpenAPI规范）之间进行聚合和一致性。
• OpenAPI的动态生成、硬化控制和传输选项。
• 可选使用供应商SDK，以获得卓越的开发人员体验。

指导：

• 如果您只需要Hostinger，请选择官方服务器以获得第一方支持和功能。
• 当您想将Hostinger与其他API结合、实施共享策略或根据规范动态生成工具时，请使用此项目。

身份验证助手（可选，用于填充安全处理程序）：

• OPENAPI_API_KEY 或特定方案 OPENAPI_APIKEY_<SCHEMENAME>
• OPENAPI_BEARER_TOKEN
• OPENAPI_BASIC_USER 和 OPENAPI_BASIC_PASS

策略控制（可选）：

• OPENAPI_MCP_ALLOWED_METHODS （例如。， GET,POST)
• OPENAPI_MCP_ALLOWED_PATHS （例如。， /v1/users*,/v1/*)
• OPENAPI_MCP_RATE_LIMIT 和 OPENAPI_MCP_RATE_WINDOW_MS
• 登录中： OPENAPI_MCP_LOG_FILE, OPENAPI_MCP_LOG_MAX_SIZE, OPENAPI_MCP_LOG_MAX_FILES, OPENAPI_MCP_LOG_FORMAT

HTTP调试日志记录

对于通用服务器和生成的服务器，您可以在故障排除时启用详细的HTTP日志：

• DEBUG_HTTP=1 --打印出站请求标头和摘要响应。还记录客户端凭据流期间的OAuth2令牌交换（没有秘密）。

另请参见： examples/README.md 用于脚本快速启动。

Lint OpenAPI

• npm run openapi:lint （默认为 examples/specs/hostinger-api.json)
• npm run openapi:lint:all --递归地遍历以下所有规范 specs/
• 或者： npm run openapi:lint:file -- ./path/to/openapi.json

验证结构（如果已安装，则通过swagger解析器），检查重复/缺失的操作ID、路径/服务器的存在。

HTML测试客户端（HTTP）

• 打开 examples/http-html-client.html 在浏览器中。
• 在HTTP模式下运行生成的服务器，并将端点设置为 /mcp.
• 使用它发送 tools/list 或 tools/call 交互式有效载荷。

例子：

DEBUG_HTTP=1 OPENAPI_SPEC_FILE=./openapi.json npm run mcp:openapi

配置

直接或通过设置环境变量 .env （参见 .env.example):

• N8N_API_URL：以结尾的基本API URL /api/v1
• N8N_API_KEY：API密钥作为发送 X-N8N-API-KEY
• 可选： N8N_BEARER_TOKEN, N8N_BASIC_AUTH_USER/PASS

测试

• 端到端： N8N_API_URL=... N8N_API_KEY=... npm test
  • 生成工具，通过stdio调用MCP服务器，并断言可以列出工作流。
• 自动生成单元测试：测试运行器为每个OpenAPI工具创建一个模拟运行单元测试并执行（无网络）。

规格门（合规性+模糊性）

从结构上验证规范，然后用随机、无网络的模拟运行模糊每个操作。及早发现缺失的参数、错误的路径模板、枚举/约束问题，并强化“如果主机规范良好，则无错误”的承诺。

• 运行所有本地规范：
  • npm run openapi:spec-gate:all
• 单个文件：
  • node examples/scripts/spec-gate.js --file examples/specs/hostinger-api.json --runs 3
• 标签过滤器：
  • node examples/scripts/spec-gate.js --file examples/specs/hostinger-api.json --runs 3 --include-tags Domains
• 操作/路径过滤器：
  • --include-ops domains_getDomainListV1,domains_getDomainDetailsV1
  • --include-paths-re "/v1/domains/.*"
• 可选字段概率：
  • SPEC_GATE_OPT_PROB=0.6 node examples/scripts/spec-gate.js --file ... --runs 3

便利脚本：

• npm run openapi:spec-gate:hostinger
• npm run openapi:spec-gate:domains
• npm run openapi:spec-gate:dns
• npm run openapi:spec-gate:vps

CI（可选）

该仓库包括示例GitHub Actions工作流（在 .github/workflows/):

• CI：安装deps并运行测试。E2E仅在配置了回购机密时运行。
• Update Generated MCP Tools：按计划或手动调度重新生成OpenAPI工具。

有关具有n8n工人的本地CI，请参阅 docs/ONPREM-CI.md.

小贴士：在叉子里，摆好 N8N_API_URL 和 N8N_API_KEY 存储库机密，以在CI中启用E2E并自动更新生成的工具。

CLI（工作流）

• 列表： npm run n8n:list
• 出口： npm run n8n:export -- --id <id> --out backups/workflows/<name>.json
• 更新： npm run n8n:update -- --id <id> --file backups/workflows/<name>.json

加固

限制行为的环境变量：

• N8N_MCP_ALLOWED_METHODS=GET,POST --允许的HTTP方法
• N8N_MCP_ALLOWED_PATHS=/workflows*,/executions* --允许的路径模式
• N8N_MCP_RATE_LIMIT=120 N8N_MCP_RATE_WINDOW_MS=60000 --基本费率限制
• 日志记录（可选）： N8N_MCP_LOG_FILE=./logs/mcp-n8n.log

安全与分销

• MIT许可证
• 未存储任何秘密；仅限env的凭据
• .npmignore 不包括本地数据和生成的文件

鸣谢

由比利·科尔曼三世创作。

作者和许可证

• 许可证：麻省理工学院。看 LICENSE 和 NOTICE 用于归因指导。
• 作者：比利·科尔曼三世的原创作品；由社区贡献发展而来。

自动更新MCP工具（CI）

此回购包括一个工作流，该工作流从n8n API的OpenAPI规范重新生成MCP工具注册表，并自动提交更改。

• 触发器：手动调度或计划（每天03:00 UTC）
• 它的作用：从以下位置获取规格 ${N8N_API_URL}/docs/swagger-ui-init.js，再生 examples/generated/n8n-openapi-tools.json 和 examples/generated/TOOLS.md，验证负载。

硬化选项

您可以使用环境变量限制和限制MCP服务器可以针对n8n API调用的内容：

• N8N_MCP_DISABLE_GENERIC:
  • 禁用通用 n8n.request 工具完全设置为 1/true.
  • 只有生成/分配的工具仍然可用。
• N8N_MCP_ALLOWED_METHODS:
  • 允许逗号分隔的HTTP方法（默认值： GET,POST,PUT,PATCH,DELETE).
  • 例子： N8N_MCP_ALLOWED_METHODS=GET,POST.
• N8N_MCP_ALLOWED_PATHS:
  • 逗号分隔的路径模式（支持 *)相对于 N8N_API_URL 基础路径。
  • 示例： N8N_MCP_ALLOWED_PATHS=/workflows*,/executions* （允许工作流/执行）
  • 违约： * （允许配置的API源下的所有路径）。
• N8N_MCP_RATE_LIMIT 和 N8N_MCP_RATE_WINDOW_MS:
  • 每个流程的基本速率限制（默认值： 60 通话次数/ 60000 ms）。
  • 例子： N8N_MCP_RATE_LIMIT=30 N8N_MCP_RATE_WINDOW_MS=60000.

这些检查适用于所有工具，包括OpenAPI生成的工具。请求使用来自的固定源 N8N_API_URL 并且不接受任意URL。

审计日志

启用最少、安全的审核日志（方法、路径、状态、持续时间；无正文或标头）：

• N8N_MCP_LOG_FILE：可写日志文件的路径允许记录（例如。， ./logs/mcp-n8n.log).
• N8N_MCP_LOG_MAX_SIZE：当文件超过此字节数时旋转（默认值： 1048576).
• N8N_MCP_LOG_MAX_FILES：最多保留N个旋转文件（默认值： 5).
• N8N_MCP_LOG_FORMAT: json （默认）或 tsv.

例子：

N8N_MCP_LOG_FILE=./logs/mcp-n8n.log N8N_MCP_LOG_MAX_SIZE=1048576 N8N_MCP_LOG_MAX_FILES=7 npm run mcp:n8n

多服务主机（一个进程，N+1个服务）

• 运行： node examples/mcp-multi-host.js --config ./services.json
• 配置示例：

{
  "services": [
    { "name": "n8n", "type": "openapi", "specUrl": "https://your-n8n/api/v1/docs/swagger-ui-init.js", "baseUrl": "https://your-n8n/api/v1", "auth": { "kind": "header", "name": "X-N8N-API-KEY", "env": "N8N_API_KEY" } },
    { "name": "hostinger", "type": "openapi", "specFile": "./examples/specs/hostinger-api.json", "baseUrl": "https://developers.hostinger.com", "auth": { "kind": "bearer", "env": "HOSTINGER_API_TOKEN" } },
    { "name": "third", "type": "openapi", "specUrl": "https://api.example.com/openapi.json", "baseUrl": "https://api.example.com/v1", "auth": { "kind": "bearer", "env": "THIRD_TOKEN" } }
  ]
}

• 工具的命名空间为 <service>.<toolName> 以避免碰撞。
• 主机可扩展到您配置的服务数量（受计算限制）。强化envs适用于全球。

快速链接

• 多主机指南： examples/multi-host-README.md
• 配置示例： examples/services.example.json
• MCP客户端配置示例（Cursor/Kiro）： mcp.config.json
• 当地供应商规格： specs/ （在此处放置您自己的OpenAPI规范，并在配置中引用）
  • 根据规范生成服务： node examples/scripts/generate-services-from-specs.js --out examples/services.generated.json
  • 使用示例配置合并生成的服务： npm run services:merge
  • 完全刷新（剥离所有规格、生成、合并）： npm run services:regen
  • 合并策略报告（基于冲突；打印冲突）：
    • node examples/scripts/merge-services.js --base examples/services.example.json --add examples/services.generated.json --out examples/services.merged.json --strategy report --report-out examples/services.conflicts.json
    • 或者简单地说： npm run services:report
  • Lint服务配置（重复）： npm run services:lint:config
  • 完全刷新+冲突报告+配置lint： npm run services:regen:report

Docker服务器

使用安全门包裹Docker CLI和Docker引擎API。

• 运行（stdio）： node examples/mcp-docker-server.js
• 工具包括：
  • docker.ps, docker.images, docker.logs
  • docker.run （由 DOCKER_ALLOW_RUN=1；可选 DOCKER_ALLOWED_IMAGES 异教徒）
  • docker.stop, docker.rm, docker.exec （执行由 DOCKER_ALLOW_RUN=1)
  • docker.compose.up, docker.compose.down
  • docker.engine.request （通过调用引擎API DOCKER_SOCK 或 DOCKER_API_HOST)

环境：

• DOCKER_BIN （默认值 docker), DOCKER_COMPOSE_BIN （默认值 docker)
• DOCKER_SOCK=/var/run/docker.sock 或 DOCKER_API_HOST=http://localhost:2375
• DOCKER_ALLOW_RUN=1, DOCKER_ALLOWED_IMAGES="nginx,redis"
• DEBUG_DOCKER=1 用于命令/API日志

提示：通过以下方式将Docker Engine OpenAPI规范添加到多主机配置中 specUrl: https://docs.docker.com/reference/api/engine/version/v1.51.yaml