MCP Docs Sync

MCP文档同步服务器

一个模型上下文协议（MCP）服务器，可以自动将OpenAPI规范与Mintlify文档同步。

特性

• 自动同步：关注OpenAPI规范的变化并同步到Mintlify
• 手动同步：手动更新的一次性同步命令
• 验证：同步前验证OpenAPI规范
• MCP集成：为人工智能助手提供管理文档的工具

安装

cd mcp-docs-sync
npm install

用法

1.观看模式（推荐）

OpenAPI规范更改时自动同步：

npm run watch

这将：

• 执行初始同步
• 注意更改 openapi.json 和 openapi.yaml
• 检测到更改时自动同步
• 继续运行，直到按下Ctrl+C

2.手动同步

执行一次性同步：

npm run sync

3.MCP服务器模式

运行HTTP MCP服务器进行AI助手集成（VS Code、Claude等）：

npm start

这将在以下位置启动HTTP端点 http://localhost:3003/mcp （用覆盖 PORT).你的 mcp.json 应使用：

{
   "servers": {
      "docs-sync-server": {
         "url": "http://localhost:3003/mcp",
         "type": "http"
      }
   }
}

如果您更喜欢stdio（命令）传输，请更改 index.js 回到 runStdio() 或者创建一个单独的条目文件并配置：

{
   "servers": {
      "docs-sync-server": {
         "type": "command",
         "command": "node",
         "args": ["./index.js"]
      }
   }
}

它做什么

同步时，MCP服务器：

1. 倒像 OpenAPI规范来自 user-api/openapi.json
2. 副本 它到 procore-connect-docs/api-reference/user-api-openapi.json
3. 更新 这 docs.json 配置
4. 更新 包含最新信息的介绍页
5. 添加 同步时间戳以跟踪更改

MCP工具（HTTP和Stdio）

健康终点（非MCP）

服务器还公开了一个简单的监控路由：

GET /health → 返回JSON：

{
   "status": "ok",
   "timestamp": "2025-11-04T12:34:56.000Z",
   "server": "docs-sync-server",
   "version": "1.0.1",
   "tools": ["sync_openapi", "get_openapi_info", "validate_openapi", "health", "search"]
}

将其用于外部探测或容器编排就绪检查。

服务器为AI助手提供了五个MCP工具：

sync_openapi

将OpenAPI规范同步到Mintlify文档。

输入（可选）：

{
   "force": false
}

force 可以在将来用于跳过更改检测（目前是占位符）。

get_openapi_info

获取当前OpenAPI规范的摘要详细信息。

退货：

{
   "title": "string",
   "version": "string",
   "description": "string",
   "servers": [ { "url": "..." } ],
   "pathCount": 42,
   "schemaCount": 10
}

validate_openapi

验证OpenAPI规范和表面错误和警告。

退货：

{
   "valid": true,
   "errors": ["..."],
   "warnings": ["..."],
   "spec": { /* original spec */ }
}

health

MCP服务器的简单健康检查。

退货：

{
   "status": "ok",
   "timestamp": "2025-11-04T12:34:56.000Z",
   "server": "docs-sync-server",
   "version": "1.0.1"
}

search

搜索Mintlify文档页面和同步的OpenAPI规范。

输入：

{
   "query": "user permissions",
   "maxResults": 15,            // optional (default 25)
   "includeOpenApi": true,      // optional (default true)
   "includePages": true         // optional (default true)
}

退货：

{
   "tool": "search",
   "query": "user permissions",
   "elapsedMs": 42,
   "totalMatches": 31,
   "truncated": true,
   "results": [
      {
         "type": "page",
         "source": "api-reference/user-api/introduction.mdx#paragraph-3",
         "snippet": "…Permissions enable fine-grained access control…",
         "score": 2.14,
         "metadata": {
            "file": "api-reference/user-api/introduction.mdx",
            "paragraphIndex": 3
         }
      },
      {
         "type": "openapi",
         "source": "openapi://GET/users/{id}/permissions",
         "snippet": "GET /users/{id}/permissions\nReturns the effective permissions for a user…",
         "score": 2.7,
         "metadata": {
            "method": "GET",
            "path": "/users/{id}/permissions",
            "operationId": "getUserPermissions"
         }
      }
   ]
}

笔记：

• 匹配目前是简单的子字符串搜索（不区分大小写）。
• 页面结果为段落级别；OpenAPI结果为操作级别。
• score 是一种结合了发生次数和接近度的启发式方法。
• 未来的改进可能包括模糊匹配和排名（见建议部分）。

调用工具（示例）

在启用MCP的客户端中，您可以请求：

Call the `validate_openapi` tool.
Then call `sync_openapi` with {"force": true}.

配置

编辑 config.js 要自定义路径和设置，请执行以下操作：

export const config = {
  // Paths
  userApiPath: '../user-api',
  mintlifyDocsPath: '../procore-connect-docs',

  // Watch settings
  watchPaths: ['../user-api/openapi.json', '../user-api/openapi.yaml'],

  // ... more settings
};

与用户API集成

MCP服务器与您的用户API项目集成：

code/
├── user-api/              # Your API
│   ├── openapi.json       # Generated OpenAPI spec (watched)
│   └── openapi.yaml       # Alternative format (watched)
├── procore-connect-docs/  # Mintlify docs
│   └── api-reference/
│       ├── user-api-openapi.json  # Synced spec
│       └── user-api/              # API documentation pages
└── mcp-docs-sync/         # This server
    └── ...

工作流程

典型开发流程：

1. 开始观看模式 在一个终端中：

   cd mcp-docs-sync
   npm run watch

1. 更新API 带有新端点或更改的代码

1. 重新启动用户API （重新生成OpenAPI规范）：

   cd user-api
   npm start

1. MCP服务器检测到更改 并自动同步到Mintlify

1. Mintlify自动重新加载 更新文档

故障排除

同步不工作？

1. 检查路径 config.js 是正确的
2. 确保 openapi.json 存在于用户api文件夹中
3. 检查文件权限
4. 在控制台中查找错误消息

监视模式未检测到更改？

1. 确保你正在保存文件
2. 尝试手动同步： npm run sync
3. 检查监视路径 config.js 是正确的

脚本

依赖项

• @modelcontextprotocol/sdk -用于AI集成的MCP SDK
• chokidar -文件监视
• chalk -终端颜色

许可证

国际学生委员会