使用说明

项目简介

WebAPI MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端应用，专注于将现有的传统 Web API 接口封装并暴露为 LLM 可以理解和调用的 MCP 工具。它允许您通过简单的配置文件或动态注册的方式，将业务系统的 API 转化为大模型的“能力”，从而实现 LLM 与业务系统的无缝集成，支持函数调用等高级应用模式。

主要功能点

API 封装为工具: 自动将配置的 Web API 接口转化为 MCP 工具，供 LLM 调用。
批量导入: 支持从指定的目录或文件（JSON、Markdown 格式）批量加载 API 定义并注册为工具。
动态管理: 可以在服务器运行时注册或移除 API 工具。
全局请求头: 集中管理所有 API 请求默认携带的 HTTP 请求头（例如认证信息），简化配置和权限管理。
灵活参数处理: 支持多种参数类型定义和验证。
结果提取: 支持通过路径从嵌套的 API 响应中精确提取所需数据。

安装步骤

要安装和运行 WebAPI MCP 服务器，您需要先安装 Node.js 环境。

克隆项目: 打开终端，克隆项目的 Git 仓库到本地：

git clone https://github.com/yinzhouzhi/webapi-mcp-server.git
cd webapi-mcp-server

安装依赖: 进入项目目录后，使用 npm 安装所需的依赖包：
```
npm install
```
初始化项目目录 (可选): 运行初始化脚本，创建示例目录和文件：
```
npm run setup
```

服务器配置

MCP 服务器通常通过标准输入输出 (Stdio) 或其他传输方式与 MCP 客户端通信。MCP 客户端（如 Cursor、或其他基于 MCP SDK 的应用）需要知道如何启动这个服务器。

在 MCP 客户端的配置中，您需要指定服务器的启动命令和参数。典型的配置信息如下：

{
  "mcpServers": {
    "my-webapi-server": {  // 服务器的唯一名称，您可以自定义
      "command": "npx",    // 启动服务器的命令
      "args": [            // 传递给命令的参数数组
        "-y",
        "@yinzhouzhi/webapi-mcp-server",
        "start",           // 启动服务器的子命令
        // 以下是可选的服务器启动参数，可以添加到args数组中
        // "--config", "path/to/your/config.json", // 指定配置文件路径
        // "--apis-dir", "path/to/your/api/definitions", // 指定API定义文件目录
        // "--debug" // 启用调试模式
      ]
    }
  }
}

WebAPI MCP 服务器本身的配置可以通过配置文件或环境变量进行。

配置文件: 服务器启动时可以通过 '--config path/to/config.json' 参数指定一个 JSON、YAML 或 YML 格式的配置文件。该文件可以包含以下选项：
- 'apiDirectories': 一个字符串数组，列出包含 API 定义文件（JSON 或 Markdown）的目录路径。服务器会在启动时自动加载这些目录下的 API。
- 'apiFiles': 一个字符串数组，列出单独的 API 定义文件路径。
- 'globalHeaders': 一个键值对对象，定义应用于所有注册 API 请求的默认 HTTP 请求头。
- 'debug': 一个布尔值，设置为 'true' 启用调试日志。
环境变量: 也可以通过设置环境变量来配置，例如：
- 'WEBAPI_CONFIG_FILE': 配置文件路径。
- 'WEBAPI_APIS_DIR': API 定义目录路径。
- 'WEBAPI_DEBUG': 设置为 'true' 启用调试模式。

命令行参数的优先级高于环境变量。

基本使用方法

准备 API 定义: 按照项目文档中描述的 JSON 或 Markdown 格式，创建您的 Web API 定义文件。这些文件描述了您的 API 接口（URL、方法、参数等）。
启动服务器:
- 直接在终端中启动服务器（主要用于测试或非 MCP 客户端场景）：
```
npm start
# 或使用全局安装的 CLI 工具（如果已安装）
# webapi-mcp-server start
```
- 对于 MCP 客户端，客户端会根据其配置自动启动服务器进程（通常通过 Stdio 连接）。您只需要确保服务器的代码已安装并可通过 'npx @yinzhouzhi/webapi-mcp-server' 命令找到。
加载 API 定义:
- 将 API 定义文件放置在配置文件或启动参数 ('--apis-dir') 中指定的目录里，服务器启动时会自动加载。
- 或者，服务器启动后，MCP 客户端可以通过调用内置的 MCP 工具（如 'load_api_from_file', 'load_apis_from_directory', 'load_from_config'）来动态加载 API 定义。
LLM 调用工具: 一旦 API 被成功加载和注册，它们就会成为 MCP 工具。LLM 客户端可以发现这些工具（例如通过 MCP 的能力声明机制）并根据 API 定义中描述的参数进行函数调用。服务器会接收到调用请求，执行相应的 Web API 请求，并将结果返回给 LLM 客户端。

关键词