关键词

OpenAPI集成API连接器AI工具RESTful APILLM交互

使用说明

项目简介

该项目是一个强大的命令行工具，可以将任何遵循OpenAPI（原Swagger）规范定义的RESTful API自动转换为符合Model Context Protocol (MCP) 的服务器。通过这个工具，AI助手（如支持MCP的LLM客户端）可以直接发现并调用您的API，将您的后端服务变为AI可用的功能工具。

主要功能点

  • 动态加载规范： 从本地文件或HTTP/HTTPS URL加载OpenAPI/Swagger规范。
  • 支持叠加层： 应用OpenAPI Overlays文件，可以在不修改原始规范的情况下自定义API定义（如修改描述、过滤接口等）。
  • 灵活的接口映射： 将OpenAPI操作（Operation）映射为MCP工具，支持自定义工具名称和描述。
  • 接口过滤： 使用通配符（glob patterns）按Operation ID 或 URL 路径精确控制哪些API接口被暴露为工具。
  • 参数及请求体处理： 自动处理API的请求参数（路径、查询、头部）和请求体，并转换为MCP客户端可理解的格式。保留数据类型和格式信息。
  • API认证支持： 支持配置API Key、HTTP认证（Basic, Bearer）、OAuth2等，用于调用需要认证的后端API。
  • 自定义请求头部： 可以配置额外的HTTP头部，随所有API请求发送。
  • 使用OpenAPI元数据： 使用OpenAPI规范中的标题、版本、描述等信息来配置MCP服务器。
  • 描述文本层级回退： 在生成工具描述时，优先使用接口描述，然后是接口概要，最后是路径概要。
  • X-MCP头部： 默认会在发送给后端API的请求中添加 'X-MCP: 1' 头部，便于追踪（可配置禁用）。
  • x-mcp扩展支持： 支持在OpenAPI规范中使用 'x-mcp' 扩展属性自定义工具名称和描述。

安装步骤

本项目需要 Node.js 运行环境。请确保您的系统中已安装 Node.js（推荐 LTS 版本）。

您可以通过以下任一方式使用本项目：

  1. 直接使用 'npx' 运行 (推荐临时使用或测试)： 无需安装，直接使用 'npx' 运行命令。

    npx @tyk-technologies/api-to-mcp --spec <您的OpenAPI规范路径或URL>

  2. 全局安装 (推荐长期使用)： 将项目安装为全局命令后，可以在任何地方直接运行。

    npm install -g @tyk-technologies/api-to-mcp
api-to-mcp --spec <您的OpenAPI规范路径或URL>

服务器配置

MCP服务器通常由支持MCP的LLM客户端或框架启动和管理。您需要在MCP客户端的配置中指定如何启动 'api-to-mcp' 服务器。

以下是一个典型的MCP客户端配置示例（具体配置格式请参考您的MCP客户端文档），关键在于 'command' 和 'args' 字段：

{
  "mcpServers": {
    "api-tools-identifier": {  // MCP服务器的唯一标识符 (自定义)
      "command": "npx",        // 启动服务器的命令。如果全局安装，可以是 "api-to-mcp"
      "args": [                // 启动服务器的参数数组
        "-y", "@tyk-technologies/api-to-mcp", // 使用npx时需要这部分，全局安装则不需要
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json", // **必需**：您的OpenAPI规范文件路径或URL
        // 以下为可选参数：
        // "--overlays", "./path/to/overlay1.json,https://example.com/api/overlay.json", // 指定一个或多个Overlay文件/URL
        // "--targetUrl", "https://api.example.com", // 覆盖OpenAPI规范中的服务器URL，指定实际调用的API基地址
        // "--whitelist", "getPet*,POST:/users/*", // 白名单：指定Operation ID或方法:路径模式，只包含匹配的接口
        // "--blacklist", "deletePet,/admin/*",    // 黑名单：指定Operation ID或方法:路径模式，排除匹配的接口 (与whitelist互斥)
        // "--apiKey", "YOUR_API_KEY", // 提供API Key (如果API需要)
        // "--securitySchemeName", "apiKeyAuth", // 如果有多种认证方式，指定使用哪种方案 (对应OpenAPI securitySchemes中的名称)
        // "--headers", "{\"X-Custom-Header\":\"custom-value\"}", // 添加自定义HTTP头部 (JSON字符串)
        // "--disableXMcp", "true", // 禁用添加 X-MCP: 1 头部
        // "--config", "./path/to/config.json" // 从指定的JSON文件加载配置
      ],
      "enabled": true          // 是否启用此MCP服务器
    }
    // 您可以配置多个这样的服务器块，对应不同的API规范
  }
}

重要提示：

  • '--spec' 参数是必须的，用于指定要转换的OpenAPI规范文件或URL。
  • '--targetUrl' 可用于指定实际的API调用地址，它会覆盖OpenAPI规范中定义的 'servers'。如果未指定此参数且规范中也没有 'servers'，服务器将无法确定API调用地址而报错。
  • 您也可以通过环境变量（如 'OPENAPI_SPEC_PATH', 'TARGET_API_BASE_URL', 'API_KEY' 等）或一个JSON配置文件（使用 '--config' 参数或 'CONFIG_FILE' 环境变量指定路径）来配置服务器。命令行参数优先级最高，其次是环境变量，最后是配置文件。

基本使用方法

  1. 安装和配置： 按照上述步骤安装 'api-to-mcp'，并在您的MCP客户端（如Claude Desktop, Cursor等）的开发者设置或配置文件中添加启动 'api-to-mcp' 的配置，指定要暴露的OpenAPI规范。
  2. 重启客户端： 重启您的MCP客户端，使其加载新的MCP服务器配置。
  3. 发现工具： MCP客户端会自动连接并从 'api-to-mcp' 服务器获取暴露的API工具列表及其描述和参数 schema。
  4. 使用工具： 在与AI助手交互时，您可以通过客户端界面（如工具图标）或在对话中提及工具名称，让AI助手使用这些API工具来完成任务。AI助手会根据工具的参数 schema 向您或自动询问必要的输入，然后通过MCP协议调用 'api-to-mcp' 服务器，服务器再代为调用后端API并返回结果给AI助手。

例如，如果您的OpenAPI规范暴露了一个 'getPetById' 工具，AI助手可能会在对话中提示可以使用此工具，并询问 'petId' 参数。

信息

分类

网页与API

访问项目