Apidog MCP服务器,连接API规范和AI编码助手的桥梁

#作者：曹付江

随着人工智能越来越多地融入编码工作流程，软件开发正在经历一场深刻的变革。该领域最重要的创新之一就是模型上下文协议（MCP）,一种在人工智能编码助手和外部知识源之间建立智能连接的突破性技术。

1.了解 MCP

MCP 作为一种标准化的通信渠道，允许大型语言模型 (LLM) 直接访问、理解和利用来自外部应用程序的专门信息。对于开发人员来说，这意味着人工智能助手现在可以利用训练数据以外的上下文信息，使其在处理特定领域任务时更加强大和精确。
该协议代表了人工智能辅助编码方式的根本转变。启用了 MCP 的人工智能助手可以利用您的特定文档、代码库和技术规范，而不是仅仅依赖一般知识。这样，您就能得到一个更准确、更了解上下文、更能理解您特定项目细微差别的编码助手。

2.什么是 Apidog MCP 服务器？

在這一革命性的 MCP 基礎上，Apidog 開發了 Apidog MCP Server - 專為 API 開發工作流程而設計的專門實現。这一功能强大的工具在您的 API 文档和人工智能编码助手之间架起了一座直接的桥梁，实现了开发人员现在所说的 “动态编码”–在这种流程状态下，您专注于创造性地解决问题，而人工智能助手则在完全了解您的 API 规范的情况下处理实施细节。
Apidog MCP 服务器允许您将 Apidog 项目、Apidog 发布的公共 API 文档站点以及任何 OpenAPI Specification (OAS) 文件用作 Cursor 等人工智能集成开发环境的数据源。这种全面的集成意味着Agentic AI可以直接访问并使用您的API文档，从而加快开发速度，提高工作效率。

3.Apidog MCP 服务器如何工作

一旦设置好 Apidog MCP 服务器，它就会自动从本地机器上的 Apidog 项目或在线项目中读取并缓存所有 API 文档数据。然后，人工智能就可以无缝地检索和利用这些数据，为您的人工智能助手创造一种体验：

• 根据您准确的 API 规格生成或修改代码
• 搜索 API 文档内容以回答特定问题
• 创建类型安全的 API 客户端，与您的 API 结构完美匹配
• 根据您的文档要求实施数据验证逻辑
• 生成涵盖所有文档场景的综合测试案例
• 服务器的使用非常简单。只需指示人工智能您想通过 API 文档实现的功能即可。
• 例如
  • “使用 MCP 获取 API 文档，并为产品模式和相关模式生成 Java 记录
  • “根据 API 文档，在产品 DTO 中添加新字段
  • “根据 API 文档，为产品类中的每个字段添加注释
  • “根据 API 文档生成与端点/用户相关的所有 MVC 代码

这种直接连接消除了 API 开发中最重要的摩擦点之一：在文档和实现之间不断切换上下文。您现在可以依靠人工智能助手直接通过 MCP 服务器访问这些信息，而无需手动参考 API 规范或向人工智能助手解释数据模型。

4.利用人工智能改变开发工作流程

Apidog MCP Server 与人工智能编码助手的整合产生了强大的协同效应，从根本上改变了开发人员处理 API 相关任务的方式。这种组合实现了真正的代理式人工智能体验，您的编码助手将成为开发流程的积极参与者，深入了解您的特定 API 设计。
在使用 Apidog MCP Server 时，您的人工智能助理可以作为一个自主代理，它可以

• 从您的自然语言指令中分析需求
• 直接从您的文档中检索相关的 API 规范
• 根据这些规范生成实施代码
• 解释其推理并强调重要的注意事项
• 提出改进建议或替代方法

这种代理能力大大减轻了开发人员的认知负担。在编写实施代码时，您不必再费心地处理 API 规范，而是可以专注于更高层次的设计决策和问题解决，而您的人工智能助手则可以精确地处理细节问题。

5.设置 Apidog MCP 服务器： 分步指南

开始使用 Apidog MCP Server 非常简单。请按照以下步骤将您的 API 文档与人工智能编码助手连接起来：
先决条件:
在开始设置过程之前，请确保您拥有

• Node.js（18 或更高版本，最好是最新的 LTS 版本）
• 支持 MCP 的集成开发环境，如带有 Cline 插件的 Cursor 或 VSCode
• 可访问您的 API 项目的 Apidog 账户

步骤1：在 Apidog 中生成访问令牌
1)打开 Apidog 并登录您的账户
2)将鼠标悬停在右上角您的个人资料图片上
3)单击 "帐户设置 > API 访问令牌
4)创建一个新的 API 访问令牌
5)将生成的令牌复制到一个安全的位置 - 您需要它来进行配置

步骤2：找到 Apidog 项目 ID
1)在 Apidog 中打开所需的项目
2)单击左侧边栏中的 "设置
3)在 “基本设置 ”页面中找到项目 ID
4)复制此 ID，以便在配置中使用

步骤 3：为集成 MCP 配置集成开发环境

1. 根据您的集成开发环境创建或修改 MCP 配置文件：

• 对于游标： 使用 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json （特定于项目）。
• 对于 Cline： 打开 Cline 面板 > MCP 服务器 > 配置 MCP 服务器

2. 在 MCP 文件中添加以下 JSON 配置：

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--project-id="
      ],
      "env": {
        "APIDOG_ACCESS_TOKEN": ""
      }
    }
  }
}

3. 替换占位符值：
   将 替换为实际的 Apidog 项目 ID
   将 替换为您的 Apidog API 访问令牌
   对于 Windows 用户，如果上述配置不起作用，请使用以下替代方法：

{
  "mcpServers": {
    "API specification": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apidog-mcp-server@latest",
        "--project-id="
      ],
      "env": {
        "APIDOG_ACCESS_TOKEN": ""
      }
    }
  }
}

步骤 4：验证和测试集成
•重启集成开发环境，确保加载新的 MCP 配置
•向人工智能助手提出一个有关 API 的问题来测试集成，例如：“使用 MCP 获取 API 文档并列出所有可用端点”：

• “使用 MCP 获取 API 文档并列出所有可用端点
• “根据 API 文档，用户模型中有哪些字段？

•如果集成工作正常，人工智能助手应该能够访问并提供 API 文档中的信息，而无需您手动引用或解释。

5.高级功能和提示

5.1 使用 OpenAPI 规范

除 Apidog 项目外，Apidog MCP Server 还能直接读取 Swagger 或 OpenAPI Specification (OAS) 文件。要使用此功能

1. 删除 --project-id= 参数
2. 添加–oas=参数，
   例如
   npx apidog-mcp-server -oas=https://petstore.swagger.io/v2/swagger.json
   npx apidog-mcp-server --oas=~/data/petstore/swagger.json

5.2.多个项目配置

如果需要使用多个项目的 API 文档，只需在配置文件中添加多个 MCP 服务器配置即可。每个项目都应有自己唯一的项目 ID。为清楚起见，请按照 “xxx API 文档 ”的格式为每个 MCP 服务器命名。

5.3.安全最佳实践

如果你的团队将 MCP 配置文件同步到代码库，建议删除 “APIDOG_ACCESS_TOKEN ”行： “"一行，而是将 APIDOG_ACCESS_TOKEN 配置为每个成员机器上的环境变量，以防止令牌泄漏。

5.4.内部部署

对于内部部署的用户，请在集成开发环境中的 MCP 配置文件中添加以下参数：“–apidog-api-base-url=<内部服务器的 API 地址，以 http:// 或 https://> 开头”。
此外，请确保您的网络可以正常访问 www.npm.com。

6.结论

Apidog MCP Server 代表着开发人员在与 API 文档交互和实现 API 相关功能方面的重大进步。通过在您的 API 规范和人工智能编码助手之间建立直接连接，这一强大的集成消除了上下文切换，提高了代码质量，并显著加快了开发速度。

通过将 Apidog MCP Server 集成到您的开发工作流程中，您所采用的不仅仅是一种新工具，而是一种从根本上提高开发 API 驱动型应用程序的效率和乐趣的方式。您的文档和人工智能助手之间的无缝连接消除了上下文切换，减少了错误，使您能够保持梦寐以求的流程状态，在这种状态下进行最佳工作。