借助 AI 进行开发

本指南说明开发者如何将兼容 MCP 的 IDE（Cursor / VS Code + Cline）连接到 Cobre 的公开 API 文档，从而使 IDE 的 AI 智能体能够读取 OpenAPI Specification（OAS）并生成准确的代码、DTO、文档等内容。

您将获得什么（为何重要）

配置 MCP 后，您的 AI IDE 可以拉取与 Cobre 文档中相同的 API 详情，并利用这些信息：

生成客户端代码（SDK 片段、服务类、控制器）
根据 Schema 创建或扩展 DTO/模型
添加字段级文档注释
搜索接口端点、参数及错误响应
为特定接口端点（鉴权、PayOuts、Webhook 等）搭建完整流程

前提条件

在开始配置前，请确认：

Node.js 18+（推荐使用最新 LTS 版本）
一个兼容 MCP 的 IDE，例如：
- Cursor
- VS Code + Cline
- 任何支持 MCP 的编辑器
网络可访问 npx（须能连通 npm 镜像源）

第一步 — 添加 Cobre 的 MCP 服务器配置

在您的 IDE 中添加如下 MCP 配置：

{
  "mcpServers": {
    " - API Documentation": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--site-id=760877"
      ]
    }
  }
}

该配置使用已发布文档数据源，通过 site-id=760877 直接指向 Cobre 的公开 API 文档，无需 Token。

Cursor 快速配置

打开 Cursor
进入 Settings → MCP
点击 Add new global MCP server
将 JSON 粘贴到生成的 mcp.json 中
保存，如有需要请重启
使用简单提示词测试 MCP

VS Code + Cline 快速配置

安装并启用 Cline 插件
找到 MCP 配置设置
添加相同的 mcpServers JSON
如有需要请重新加载 VS Code
使用基于 MCP 的提示词进行测试

第二步 — 验证 MCP 是否正常运行

在您 IDE 的 AI 智能体模式下，尝试以下操作：

基础连通性测试

"请通过 MCP 获取 API 文档，并告诉我共有多少个接口端点。"

基于接口端点的开发

"使用 MCP，为 /v1/... 生成请求与响应示例，并生成一个带类型的 TypeScript 客户端方法。"

DTO / Schema 生成

"使用 MCP 为所使用的 Schema 生成 Java/Kotlin/TypeScript 模型。"

Schema 同步 / 重构

"将此仓库中当前的 DTO 与 MCP Schema 进行比对，并添加缺失字段及文档注释。"

TIP

强烈推荐：将 MCP 与 Cobre 的 LLM 文档索引结合使用

如需获取更广泛的集成指导（流程说明、集成步骤等），您还可以指示 AI 读取：

https://docs.cobre.com/llms.txt

该文件以 Markdown 格式提供结构化的文档导航。

最佳实践：

使用 llms.txt 进行概念理解和流程设计。
使用 MCP 进行精确的 OpenAPI Schema 校验（字段、枚举值、必填参数、错误码）。

详情请参阅以下指南：将 Cobre 文档连接至 AI

以下是结合两种方式的提示词示例：

"使用 MCP 以及 https://docs.cobre.com/llms.txt 中的 llms.txt 和 Cobre 的扩展文档，创建一个演示如何向 Bre-B Key 发送付款的流程。"

刷新缓存的 API 规范

您的 MCP 配置会在本地缓存规范以提升性能。如果 Cobre 更新了文档，您可能需要让 AI 刷新/重新加载 MCP。

如果您认为文档已发生变更（新增字段、枚举值更新、参数变更）：

请向您的 IDE 发出如下指令：

"刷新 MCP 并重新加载最新的 API 规范。"

由于 MCP 在本地缓存规范，刷新操作可确保您始终使用最新版本。

常见故障排查

Windows 下 `npx` 问题

如果 Windows 无法执行默认配置，请使用：

{
  "mcpServers": {
    " - API Documentation": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apidog-mcp-server@latest",
        "--site-id=760877"
      ]
    }
  }
}

企业网络限制

请确保您的开发环境可以访问：

www.npmjs.com

如果处于防火墙之后，您可能需要配置 npm 代理设置。

返回过时字段

如果 Schema 显示已过时：

要求 AI 刷新 MCP
如有需要请重启 IDE
重新发起请求

团队高价值应用场景

使 DTO 与持续演进的 API 规范保持同步
生成强类型 SDK 层
自动为后端模型生成文档
减少因字段过时导致的集成错误
加速新开发者的入职上手