MCP 最佳实践

本文档介绍使用奥宏文档 MCP 的常见工作流、使用技巧和注意事项。

如果你还没有配置 MCP 连接，请先阅读 MCP 接入指南。

完整的工具参数说明请参考 MCP 工具详解。

常见工作流

1. 创建一篇新文档

最简单的用法，只需两步：

1. create_page(title="API 文档") → 获得 page_uid
2. update_page_content(page_uid="xxx", lang="zh-cn", content="# API 文档\n\n接口说明...")

update_page_content 是最核心的工具，不指定 block_id 时会自动查找或创建 Markdown 块，适合大多数场景。

2. 浏览和了解项目结构

当 AI 助手需要了解文档全貌时：

1. list_pages() → 获取页面树结构
2. get_page_content(page_uid="xxx") → 读取具体页面内容
3. search(keyword="配置") → 搜索相关内容

3. 批量更新多个页面

调整文档结构时，使用批量排序工具：

1. list_pages() → 了解当前页面列表和排序
2. update_page_sort(sort_list=[
     {"page_uid": "page-1", "sort": 1},
     {"page_uid": "page-2", "sort": 2},
     {"page_uid": "page-3", "pid": 5, "sort": 1}  // 移为子页面
   ])

4. 版本管理

创建新版本进行文档迭代：

1. create_version(title="v2.0", desc="重构版") → 创建新版本
2. update_page_content(...) → 更新页面内容
3. update_version(version_id=1, status=1) → 隐藏旧版本

5. 在文档中插入图片

通过 URL 上传图片到项目中：

1. upload_file_from_url(url="https://example.com/diagram.png") → 获得文件 URL
2. update_page_content(content="![架构图](文件URL)") → 在 Markdown 中引用

6. 精细控制页面布局

使用块工具在页面中组合不同类型的内容：

1. create_block(type="markdown") → 创建 Markdown 块（正文说明）
2. create_block(type="code") → 创建代码块（示例代码）
3. create_block(type="html") → 创建 HTML 块（自定义嵌入）
4. update_block_sort(sort_list=[...]) → 调整块顺序

使用技巧

选择合适的端点

项目端点（推荐）：配置更简单，project_uid 自动注入，AI 不需要在每次调用时传递项目标识
全局端点：适合需要跨项目操作的场景（如创建新项目、列出所有项目）

减少不必要的调用

使用 get_page_content 而非先 get_page 再逐个获取内容
使用 list_pages 的树结构返回值，而非多次查询子页面
使用批量工具（update_page_sort、update_block_sort）而非逐个更新

内容格式

update_page_content 接受标准 Markdown 格式
支持的 Markdown 扩展：表格、代码块（带语法高亮）、任务列表
图片使用标准 Markdown 语法：![描述](URL)

多语言文档

每个项目可配置多种语言
更新内容时必须指定 lang 参数（如 zh-cn、en）
不指定语言时默认使用项目的默认语言

安全注意事项

Token 安全

API Token 等同于账户密码，不要泄露给不可信的第三方
建议为不同的 AI 工具创建不同的 Token，方便管理和撤销
不再使用的 Token 应及时删除

权限模型

公开项目（show_status=0）：任何人都可以通过 MCP 读取内容
私有项目（show_status=1）：只有项目所有者和授权读者可以读取
写入操作：所有写入操作都需要认证 + 项目所有者身份，读者权限无法写入

不可逆操作

以下操作不可撤销，请谨慎使用：

delete_page -- 删除页面及所有内容
delete_block -- 删除块及所有内容
delete_version -- 删除版本
update_project_uid -- 修改项目 UID（旧链接失效）
update_page_uid -- 修改页面 UID（旧链接失效）

文件上传限制

文件大小限制：10MB
禁止上传 .php 扩展名的文件
上传内容会扫描 <?php 标记，检测到则拒绝
块类型白名单：仅支持 markdown、code、html

常见问题

连接失败

问题： AI 工具无法连接到 MCP 端点。

排查：

确认域名正确，浏览器可以直接访问
检查 URL 路径是否正确（/mcp 或 /mcp/{project_uid}）
确认 HTTPS 证书有效
检查是否有防火墙或代理拦截

认证失败

问题： 返回 Authentication required 错误。

排查：

确认 Token 有效且未过期
确认 Header 格式正确：Authorization: Bearer YOUR_TOKEN（注意 Bearer 和 Token 之间有空格）
确认 Token 对应用户是项目所有者（写入操作）

缓存问题

问题： 修改了内容但 list_pages 或 get_page_content 返回旧数据。

原因： 系统使用缓存提高读取性能，缓存有效期约 5 分钟。

解决： 通过 MCP 写入操作（如 update_page）会自动清除相关缓存，等待几秒后重新查询即可。

项目端点工具数量

问题： 项目端点只有 25 个工具，少了 list_projects 和 create_project。

原因： 这两个工具是全局性的，不属于任何单个项目，因此只在全局端点（/mcp）提供。

多语言内容不显示

问题： get_page_content 返回的内容不是预期的语言。

原因： 不指定 lang 参数时使用项目默认语言。如果该语言没有内容，会进行回退。

解决： 显式指定 lang 参数（如 lang="en"）。

版本过滤

问题： list_pages 返回的页面比预期少。

原因： 如果指定了 version_id，只会返回属于该版本的页面。

解决： 不传 version_id 获取所有页面，或使用 list_pages_all（需认证）获取无版本过滤的完整列表。