STARWARCLOUD STARWAR.AI
返回市场
MCP开放API服务器

MCP开放API服务器

作者：ivo-toby202 星标更新：2025-11-06
安装使用来源：spider==github.com

项目介绍

OpenAPI MCP Server

smithery badge

这是一个暴露OpenAPI端点作为MCP资源的Model Context Protocol (MCP)服务器。此服务器允许大型语言模型通过MCP协议发现并交互由OpenAPI规范定义的REST API。

📖 文档

  • 用户指南 - 针对希望使用此MCP服务器与Claude Desktop、Cursor或其他MCP客户端的用户
  • 库使用 - 针对使用此包作为库创建自定义MCP服务器的开发者
  • 开发者指南 - 针对贡献者和在代码库上工作的开发者
  • AuthProvider指南 - 详细的认证模式和示例

用户指南

本节介绍了如何作为最终用户使用MCP服务器，与Claude Desktop、Cursor或其他兼容MCP的工具一起使用。

概览

此MCP服务器有两种使用方式：

  1. CLI工具：使用npx @ivotoby/openapi-mcp-server直接通过命令行参数快速设置
  2. 库：在自己的Node.js应用程序中导入并使用OpenAPIServer类进行自定义实现

服务器支持两种传输方法：

  1. Stdio传输（默认）：用于直接集成到管理MCP连接的标准输入/输出的AI系统，如Claude Desktop。
  2. 可流式传输的HTTP传输：通过HTTP连接到服务器，允许Web客户端和其他支持HTTP的系统使用MCP协议。

快速开始

方案1：与Claude Desktop（Stdio传输）一起使用

无需克隆此仓库。只需配置Claude Desktop以使用此MCP服务器：

  1. 找到或创建你的Claude Desktop配置文件：

    • 在macOS上：~/Library/Application Support/Claude/claude_desktop_config.json

  2. 添加以下配置：

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}
  1. 使用实际的API配置替换环境变量：
    • API_BASE_URL：你的API的基础URL
    • OPENAPI_SPEC_PATH：你的OpenAPI规范的URL或路径
    • API_HEADERS：用于API认证头的逗号分隔的键值对

方案2：与HTTP客户端（HTTP传输）一起使用

要使用HTTP客户端：

  1. 不需要安装！使用npx直接运行包：
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000
  1. 使用HTTP请求与服务器交互：
# 初始化会话（第一个请求）
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'

# 响应包括一个Mcp-Session-Id头，你必须在后续请求中使用它
# 并且InitializeResult直接在POST响应正文中。

# 发送一个请求来列出工具
# 这个请求也会直接在这个POST请求中收到响应。
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 打开一个流式连接以接收其他服务器响应（例如，工具执行结果）
# 这使用了服务器发送事件（SSE）。
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# 示例：执行一个工具（响应将在GET流中到达）
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# 完成后终止会话
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

配置选项

服务器可以通过环境变量或命令行参数进行配置：

环境变量

  • API_BASE_URL - API端点的基础URL
  • OPENAPI_SPEC_PATH - OpenAPI规范的路径或URL
  • OPENAPI_SPEC_FROM_STDIN - 设置为“true”以从标准输入读取OpenAPI规范
  • OPENAPI_SPEC_INLINE - 直接提供OpenAPI规范内容作为字符串
  • API_HEADERS - 用于API头的逗号分隔的键值对
  • SERVER_NAME - MCP服务器的名称（默认：“mcp-openapi-server”）
  • SERVER_VERSION - 服务器的版本（默认：“1.0.0”）
  • TRANSPORT_TYPE - 要使用的传输类型：“stdio”或“http”（默认：“stdio”）
  • HTTP_PORT - HTTP传输的端口（默认：3000）
  • HTTP_HOST - HTTP传输的主机（默认：“127.0.0.1”）
  • ENDPOINT_PATH - HTTP传输的端点路径（默认：“/mcp”）
  • TOOLS_MODE - 工具加载模式：“all”（加载所有基于端点的工具）、“dynamic”（仅加载元工具）或“explicit”（仅加载在includeTools中指定的工具）（默认：“all”）
  • DISABLE_ABBREVIATION - 禁用名称优化（当名称超过64个字符时可能会抛出错误）

命令行参数

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true

OpenAPI规范加载

MCP服务器支持多种加载OpenAPI规范的方法，提供了不同部署场景的灵活性：

1. URL加载（默认）

从远程URL加载OpenAPI规范：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json

2. 本地文件加载

从本地文件加载OpenAPI规范：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./path/to/openapi.yaml

3. 标准输入加载

从标准输入读取OpenAPI规范（适用于管道或容器化环境）：

# 从文件管道
cat openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# 从curl管道
curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# 使用环境变量
export OPENAPI_SPEC_FROM_STDIN=true
echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com

4. 内联规范

直接提供OpenAPI规范内容作为命令行参数：

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'

# 使用环境变量
export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com

支持的格式

所有加载方法都支持JSON和YAML格式。服务器自动检测格式并解析。

Docker和容器使用

对于容器化部署，可以挂载OpenAPI规范或使用标准输入：

# 挂载本地文件
docker run -v /path/to/spec:/app/spec.json your-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec /app/spec.json

# 使用Docker中的标准输入
cat openapi.json | docker run -i your-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

错误处理

服务器为规范加载失败提供了详细的错误消息：

  • URL加载：HTTP状态码和网络错误
  • 文件加载：文件系统错误（未找到、权限等）
  • 标准输入加载：空输入或读取错误
  • 内联加载：缺少内容错误
  • 解析错误：详细的JSON/YAML语法错误消息

验证

一次只能使用一种规范来源。服务器将验证以下内容之一被提供：

  • --openapi-spec（URL或文件路径）
  • --spec-from-stdin
  • --spec-inline

如果指定了多个来源，服务器将以错误消息退出。

工具加载及过滤选项

根据Stainless文章《将复杂OpenAPI规范转换为MCP服务器的经验》（https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers），添加了以下标志来控制哪些API端点（工具）被加载：

  • --tools <all|dynamic|explicit>：选择工具加载模式：
    • all（默认）：加载OpenAPI规范中的所有工具，并应用任何指定的过滤器
    • dynamic：仅加载动态元工具（list-api-endpoints，get-api-endpoint-schema，invoke-api-endpoint）
    • explicit：仅加载在--tool选项中明确列出的工具，忽略所有其他过滤器
  • --tool <toolId>：仅导入指定的工具ID或名称。可以多次使用。
  • --tag <tag>：仅导入具有指定OpenAPI标签的工具。可以多次使用。
  • --resource <resource>：仅导入具有指定资源路径前缀的工具。可以多次使用。
  • --operation <method>：仅导入具有指定HTTP方法（get，post等）的工具。可以多次使用。

示例：

# 仅加载动态元工具
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic

# 仅加载明确指定的工具（忽略其他过滤器）
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users

# 仅加载GET /users端点工具（使用带有过滤器的all模式）
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users

# 加载具有“user”标签的“/users”资源下的工具
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users

# 仅加载POST操作
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post

传输类型

Stdio传输（默认）

Stdio传输设计用于直接集成到通过标准输入/输出管理MCP连接的AI系统，如Claude Desktop。这是最简单的设置，不需要网络配置。

何时使用：当与Claude Desktop或其他支持基于stdio的MCP通信的系统集成时。

可流式传输的HTTP传输

HTTP传输允许MCP服务器通过HTTP访问，使Web应用程序和其他支持HTTP的客户端能够与MCP协议交互。它支持会话管理、流式响应和标准HTTP方法。

关键特性：

  • 使用Mcp-Session-Id头进行会话管理
  • 对于initialize和tools/list请求，HTTP响应同步发送在POST上。
  • 其他服务器到客户端的消息（例如，tools/execute结果、通知）通过GET连接使用服务器发送事件（SSE）进行流式传输。
  • 支持POST/GET/DELETE方法

何时使用：当你需要向Web客户端或通过HTTP而不是stdio通信的系统公开MCP服务器时。

健康检查端点

使用HTTP传输时，健康检查端点在/health可用，用于监控和服务发现：

# 检查服务器健康状况
curl http://localhost:3000/health

# 响应：
# {
#   "status": "healthy",
#   "activeSessions": 2,
#   "uptime": 3600
# }

健康响应字段：

  • status：当服务器运行时始终返回“healthy”
  • activeSessions：活动的MCP会话数量
  • uptime：服务器运行时间（秒）

关键特性：

  • 不需要身份验证
  • 支持任何HTTP方法（GET，POST等）
  • 适合负载均衡器、Kubernetes探针和监控系统

集成示例：

# Kubernetes存活探测
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 3
  periodSeconds: 10

# Docker健康检查
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1

安全注意事项

  • HTTP传输验证Origin头以防止DNS重新绑定攻击
  • 默认情况下，HTTP传输仅绑定到localhost（127.0.0.1）
  • 如果暴露给其他主机，请考虑实施额外的身份验证

调试

查看调试日志：

  1. 当使用与Claude Desktop集成的stdio传输时：

    • 日志出现在Claude Desktop的日志中

  2. 当使用HTTP传输时：

    npx @ivotoby/openapi-mcp-server --transport http &2>debug.log

库使用

本节针对希望使用此包作为库来创建自定义MCP服务器的开发者。

🚀 作为库使用

通过导入和配置OpenAPIServer类来创建特定API的专用MCP服务器。这种方法适用于：

  • 自定义认证：使用AuthProvider接口实现复杂的认证模式
  • API特定优化：过滤端点、自定义错误处理并针对特定用例进行优化
  • 分发：将服务器打包为独立的npm模块以便轻松共享
  • 集成：嵌入更大的应用程序或添加自定义中间件

基础库使用

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  headers: {
    Authorization: "Bearer your-token",
    "X-API-Key": "your-api-key",
  },
  transportType: "stdio" as const,
  toolsMode: "all" as const, // 选项："all", "dynamic", "explicit"
}

const server = new OpenAPIServer(config)
const transport = new StdioServerTransport()
await server.start(transport)

工具加载模式

toolsMode配置选项控制从您的OpenAPI规范中加载哪些工具：

// 从规范中加载所有工具（默认）
const config = {
  // ... 其他配置
  toolsMode: "all" as const,
  // 可选：应用过滤器以控制加载哪些工具
  includeTools: ["GET::users", "POST::users"], // 仅这些工具
  includeTags: ["public"], // 仅具有这些标签的工具
  includeResources: ["users"], // 仅这些资源下的工具
  includeOperations: ["get", "post"], // 仅这些HTTP方法
}

// 仅加载用于API探索的动态元工具
const config = {
  // ... 其他配置
  toolsMode: "dynamic" as const,
  // 提供：list-api-endpoints，get-api-endpoint-schema，invoke-api-endpoint
}

// 仅加载明确指定的工具（忽略其他过滤器）
const config = {
  // ... 其他配置
  toolsMode: "explicit" as const,
  includeTools: ["GET::users", "POST::users"], // 仅这些确切的工具
  // 在显式模式下忽略includeTags，includeResources，includeOperations
}

使用AuthProvider