使用说明

项目简介

Yapi MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在将 YApi 的能力暴露给支持 MCP 协议的 LLM 客户端（如 Cursor）。通过该服务器，LLM 可以查询、搜索 YApi 中的接口文档，甚至进行接口的新增和更新，从而提高LLM在涉及API文档理解和操作场景下的效能。

主要功能点

该服务器通过MCP协议向LLM客户端提供以下核心工具能力：

获取 YApi 项目列表: 列出配置中所有可访问的 YApi 项目及其基本信息，帮助LLM了解可用的上下文范围。
获取 YApi 项目下的接口分类列表: 获取指定项目中的接口分类信息，便于LLM组织和查找接口。
搜索 YApi 中的接口: 根据关键字（项目、接口名称、接口路径）搜索匹配的接口列表，快速定位目标API。
获取特定 YApi 接口的详细信息: 获取指定接口（通过项目ID和接口ID）的详细文档，包括请求、响应等信息，为LLM提供丰富的上下文。
新增或更新 YApi 中的接口信息: 允许LLM根据提供的参数在YApi中创建新接口或修改现有接口，实现接口文档的自动化管理。

这些功能作为可调用的工具暴露给LLM，使LLM能够根据对话需要主动获取和操作YApi数据。

安装步骤

环境准备: 确保您的系统已安装 Node.js (推荐LTS版本) 和 pnpm。

克隆仓库: 将 Yapi-MCP 仓库克隆到本地目录。

git clone https://github.com/lzsheng/Yapi-MCP.git
cd Yapi-MCP

配置环境变量: 在项目根目录创建 '.env' 文件，并配置连接 YApi 所需的基础 URL 和 Token。
- 'YAPI_BASE_URL': 您的 YApi 实例的地址（例如：'http://your_yapi_instance_url'）。
- 'YAPI_TOKEN': 用于访问 YApi 的 Token。Token 可以配置为针对特定项目（格式：'projectId:token,projectId:token,...'）或配置一个默认Token（不含冒号，将应用于所有未指定Token的项目）。您可以从YApi的用户中心获取个人Token。
- 'PORT': (可选) 服务器监听的端口，默认为 '3333'。
- 'YAPI_CACHE_TTL': (可选) YApi数据缓存的有效期（分钟），默认为 '360' 分钟（6小时）。
- 'YAPI_LOG_LEVEL': (可选) 日志级别（'debug', 'info', 'warn', 'error', 'none'），默认为 'info'。
```
YAPI_BASE_URL=http://your_yapi_instance_url
YAPI_TOKEN=1026:your_token_for_project_1026,2048:your_token_for_project_2048
PORT=3388
YAPI_CACHE_TTL=360
YAPI_LOG_LEVEL=info
```
安装依赖: 在项目根目录运行安装命令。
```
pnpm install
```

启动服务器: 运行以下命令启动 Yapi MCP Server。服务器启动后，会打印监听的地址和端口。

pnpm run dev
# 或者直接运行入口文件（可能需要先构建项目，或确保ts-node等环境已配置）
# node src/cli.ts

服务器配置 (用于 LLM 客户端)

服务器启动后，您需要将该 MCP Server 添加到支持 MCP 协议的 LLM 客户端（如 Cursor）的配置中。配置信息通常以 JSON 格式定义，描述如何连接到该服务器。

示例客户端配置（例如在 Cursor 的 'mcpServers' 部分）：

{
  "mcpServers": {
    "yapi-mcp": {
      "url": "http://localhost:3388/sse" 
      // 替换 3388 为您在 .env 中配置或服务器启动时显示的实际端口。
      // /sse 是服务器提供的 Server-Sent Events 协议端点。

      // 如果客户端支持 Stdio 协议，也可以配置 command 和 args 来启动一个进程：
      // "command": "node", 
      // "args": ["src/cli.ts", "--stdio"]
      // 注意：command 和 args 需要根据您的实际环境（Node.js安装路径）和项目结构进行调整。
    },
    // ... 其他MCP Server配置
  }
}

'yapi-mcp': 是您为该服务器定义的名称，客户端将使用此名称引用它。
'url': 指定使用 SSE 协议连接时的服务器地址。
'command'/'args': (备选) 指定使用 Stdio 协议时启动服务器进程的命令和参数。

基本使用方法

服务器启动并成功添加到 LLM 客户端配置后，LLM 即可感知并使用 Yapi MCP Server 提供的工具。在与LLM的对话中，您可以通过自然语言指令让AI执行YApi相关的操作，例如：

"帮我在Yapi中搜索关于订单管理的接口"
"获取项目ID为1026，接口ID为500的详细信息"
"列出项目ID 2048 下的接口分类"
"新增一个项目ID 1026 下的 GET /api/users 接口，标题为 '获取用户列表'"

LLM会根据您的指令，判断是否需要调用Yapi MCP Server提供的工具，并根据工具的返回结果来回答您或执行后续操作。

关键词