在上文中我们简单介绍了 Yapi-MCP 的基本使用方式。本篇文章我们将深入探讨其实现原理，并通过一个完整的全栈开发实战（文档->后端->前端->迭代），演示如何利用 MCP 协议重塑开发流程。

一、Yapi-MCP 原理揭秘

Yapi-MCP 是基于 modelcontextprotocol/sdk 的 NodeJS 实现，采用 MCP 标准的 STDIO 通信方式。

1. 启动与连接

当 AI 助手（如 Claude Desktop 或 IDE 插件）与 MCP 建立连接时，实际上是在后台执行了如下命令：

npx -y yapi-auto-mcp --stdio \
--yapi-base-url=https://your-yapi-domain.com \
--yapi-token=projectId:your_token_here

参数解析：

npx -y: 自动从 npm registry 下载最新版本包并执行，无需交互确认。
yapi-auto-mcp: CLI 程序入口。
--stdio: 指定使用标准输入输出进行通信（MCP 协议的核心通道）。
后续参数: 用于配置 Yapi 的连接信息。

2. Server 初始化

CLI 启动后，会初始化一个本地服务器 YapiMcpServer，并将配置参数注入：

// 创建 YapiMcpServer 实例，使用配置中的所有参数
const server = new YapiMcpServer(
  config.yapiBaseUrl, 
  config.yapiToken, 
  config.yapiLogLevel, 
  config.yapiCacheTTL
);

这个 YapiMcpServer 本质上是对标准 McpServer 的一层封装。它不仅负责与 Yapi 接口交互，还引入了缓存机制（Cache），用于缓存项目ID及其描述信息，减少不必要的网络请求，提升 AI 响应速度。

3. 工具注册 (Tool Definition)

服务器启动后，会向 AI 注册 5 个核心工具（Tools）。以获取接口详情为例：

this.server.tool(
  "yapi_get_api_desc",
  "获取YApi中特定接口的详细信息",
  {
    projectId: z.string().describe("YApi项目ID；如连接/project/28/interface/api/66，则ID为28"),
    apiId: z.string().describe("YApi接口的ID；如连接/project/1/interface/api/66，则ID为66")
  },
  async ({ projectId, apiId }) => { 
      /* 
       1. 检查缓存
       2. 调用 Yapi HTTP API
       3. 数据清洗与格式化
       4. 返回给 Agent
      */ 
  }
);

工作流：

用户使用自然语言提问（例如：“查看登录接口的定义”）。
Agent 解析意图，根据 Tool 的描述（Description）匹配到 yapi_get_api_desc。
Agent 自动提取参数 projectId 和 apiId 并调用。
Server 执行 HTTP 请求获取 Yapi 数据并返回。

二、全流程实战演练

接下来，我们模拟一个真实的开发场景：从零开始实现一个登录功能。

场景背景

假设产品经理直接扔过来一段 Markdown 格式的技术文档：

# 登陆接口
路径: /api/login
请求方式: POST
参数:
    username: 用户名
    password: 密码
返回:
    code: 0
    data:
        token: 登录成功后的token

我们将演示如何利用 AI + MCP 完成：文档同步 -> 后端开发 -> 前端开发 -> 需求变更迭代。

Step 1: 智能同步文档 (Text to Yapi)

首先，将上述文档内容发送给已配置 Yapi-MCP 的 AI 助手。

现状分析：
目前的 Yapi 项目中，登录接口路径为 /login（与需求不符），且内容为空。

当前Yapi状态

AI 操作：
AI 识别出文档差异，自动调用 MCP 工具更新 Yapi 接口定义。

AI分析过程
工具调用详情
更新确认

结果验证：
检查 Yapi，发现新建了一个接口 /api/login。

Yapi更新后1
Yapi更新后2

第一步大业完成！我们现在拥有了一份标准的、与需求一致的 API 文档。

Step 2: 后端代码生成 (Yapi to Java)

接下来，我们清除 AI 上下文，假设它不知道刚才的 Markdown 文档，只通过 MCP 读取 Yapi 来工作。

此处我们结合了 IDEA 的 MCP 功能（关于 IDEA MCP 的详细介绍请移步 JetBrain新利器）。

指令：让 AI 根据 Yapi 中的 /api/login 接口生成后端 Controller 代码。

生成后端代码

自动测试：
代码生成后，IDEA 的 MCP 甚至可以自动启动服务并进行接口测试。

IDEA自动测试

Step 3: 前端代码生成 (Yapi to UI)

后端就绪，转战前端。这次我们要用另一个 AI 客户端 —— Cherry Studio。

指令：我需要你根据我的Yapi接口/project/168/interface/api/6530 使用单个HTML实现这个功能

CherryStudio操作
前端代码生成中

Step 4: 闭环迭代 (Bug Fix & Refactor)

在实际测试中，我们发现了一个问题：
当点击登录并使用错误的账号密码时，前端没有正确显示错误提示。

错误演示

原因分析：接口返回的数据结构中缺少 message 字段，导致前端无法展示具体错误信息。

修复流程：

后端 Agent：指示 AI 更新 Yapi 定义（增加 message 字段）。
前端 Agent：指示 AI 根据更新后的 Yapi 接口，重新实现前端逻辑。

最终效果：
错误提示功能正常工作，接口定义与代码完美同步。

前端代码修正最终修复效果

总结

通过 Yapi-MCP，我们将 API 文档平台变成了 AI 的"外部大脑"。无论是需求导入、代码生成，还是后续的变更迭代，MCP 协议让 AI 能够实时感知项目状态，实现了真正的文档驱动开发 (Docs as Code)。