AI导哈

API文档同步工具

Apidog Sync是一个用于读取、写入和组织API文档的MCP服务器，适用于Claude Desktop、Claude CLI、Cursor和Antigravity等平台。

  • by akhelij
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 akhelij/apidog-sync-mcp-server

使用说明

Apidog同步-MCP服务器

MCP服务器 阅读、写作和组织 Apidog中的API文档。适用于Claude Desktop、Claude CLI、Cursor和Antigravity。

基于经过验证的POC构建：导出→ Find → Diff → 合并→ 导入→ 核实。

工具

阅读

工具 说明
apidog_export_spec 导出完整的OpenAPI规范
apidog_list_endpoints 列出端点（可按标签/路径/文件夹/状态过滤）
apidog_get_endpoint 获取特定端点的完整详细信息
apidog_search_endpoints 按关键字在路径/摘要/标签/文件夹中进行模糊搜索

写

工具 说明
apidog_upsert_endpoint 创建或更新单个端点（使用diff+verify）
apidog_upsert_endpoints 批量创建/更新多个端点
apidog_delete_endpoint 删除终结点
apidog_upsert_schema 创建或更新组件架构
apidog_import_spec 导入完整或部分OpenAPI规范

组织

工具 说明
apidog_analyze_folders 分析当前文件夹结构和统计信息
apidog_propose_reorganization 建议更好的文件夹组织（模拟运行，无更改）
apidog_apply_reorganization 应用用户验证的重组计划

快速开始

1.获取Apidog证书

  • 访问令牌：Apidog→ 账户设置→ API访问令牌→ New
  • 项目编号：在项目URL或项目设置中找到

2.添加到您的MCP客户端

无需安装——只需添加以下配置块：

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "your-project-id"
      }
    }
  }
}

就这样 npx 自动下载并运行服务器。

将此配置放在哪里

客户端 配置文件
克劳德代码（全球） ~/.claude.json
克劳德代码（每个项目） .mcp.json 在项目根中
克劳德桌面 ~/Library/Application Support/Claude/claude_desktop_config.json
光标 .cursor/mcp.json
Windsurf MCP设置面板

多个Apidog项目

使用单独的条目——每个条目指向不同的项目ID：

{
  "mcpServers": {
    "apidog-frontend": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "frontend-project-id"
      }
    },
    "apidog-backend": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "backend-project-id"
      }
    }
  }
}

使用示例

路线更改后更新端点

“我更新了peppol端点的验证规则，描述应该说格式必须是带有单个冒号的scheme:identifier。更新文档。”

代理人将：

  1. 搜索peppol端点(apidog_search_endpoints)
  2. 获取当前格式(apidog_get_endpoint)
  3. 构建与现有格式完全匹配的更新操作
  4. 推送更新，显示更改内容(apidog_upsert_endpoint)
  5. 验证更新是否已登录

重新组织文件夹

“分析我的API文件夹结构，并建议一个更好的组织”

代理人将：

  1. 分析当前文件夹(apidog_analyze_folders)
  2. 提议重组(apidog_propose_reorganization)
  3. 展示计划并等待您的批准
  4. 只有在您确认后才能申请(apidog_apply_reorganization)

路线更改后的批量更新

“我为发票管理添加了3条新路由：POST/api/v1/发票、GET/api/v1/发票/{id}、DELETE/api/v1/发票/{id}。将它们添加到文档中。”

代理人将：

  1. 检查现有端点以了解格式
  2. 构建与项目格式匹配的所有3个操作
  3. 批量追加销售(apidog_upsert_endpoints)

重组策略

策略 描述
path-based 从URL路径推断文件夹： /api/v1/admin/billing/... → Admin/Billing
preserve-top-level 保留现有顶级文件夹，重新组织子级别
flat 按主资源名称划分的单层

自定义映射允许您覆盖特定的前缀：

{
  "customMappings": {
    "/api/v1/admin": "Administration",
    "/auth": "Authentication",
    "/api/v1/public": "Public API"
  }
}

Apidog扩展

全力支持：

  • x-apidog-folder --文件夹路径： "Safetytracker V1/Super Admin/Billing"
  • x-apidog-status --生命周期： designing, developing, released, deprecated
  • x-apidog-maintainer --团队成员分配
  • x-apidog-orders --模式对象中的字段排序
  • x-apidog-ignore-properties --隐藏属性
  • x-apidog-name --响应显示名称
  • x-apidog-ordering --响应排序

写作是如何工作的

每个写入操作都遵循POC验证的流程：

Export current spec (preserves all formatting)
    ↓
Find target endpoint (exact match or fuzzy search)
    ↓
Compute diff (show what changed)
    ↓
Merge into full spec (deep merge, preserve untouched endpoints)
    ↓
Import with OVERWRITE_EXISTING
    ↓
Verify (re-export and confirm)

没有端点丢失。未接触的端点上的格式不会更改。

发展

从源代码运行（用于贡献或本地测试）：

git clone https://github.com/YOUR_USERNAME/apidog-sync-mcp-server.git
cd apidog-sync-mcp-server
npm install

然后将MCP配置指向本地源：

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/path/to/apidog-sync-mcp-server/src/index.js"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "your-project-id"
      }
    }
  }
}

许可证

麻省理工学院

相关 MCP