MCP 接入指南

MCP（Model Context Protocol）是一种让 AI 助手直接与外部系统交互的协议。奥宏文档支持 MCP，让你可以在 AI 工具中直接读取、搜索和管理文档。

端点地址

奥宏文档提供两种 MCP 端点：

类型	地址	说明
全局端点	`https://your-domain/mcp`	访问所有项目，27 个工具 + 4 个资源
项目端点	`https://your-domain/mcp/{project_uid}`	限定单个项目，25 个工具（无 list_projects / create_project）

将 your-domain 替换为你的奥宏文档实际域名，{project_uid} 替换为项目的 UID。

推荐使用项目端点。配置更简单，AI 不需要在每次调用时传递 project_uid 参数。

认证方式

读取公开项目：无需认证，直接访问
读取私有项目：需要 Bearer Token + 项目所有者或阅读权限
所有写入操作：需要 Bearer Token + 项目所有者权限

获取 API Token

登录系统前台
进入用户中心
在 API Token 管理页面创建新 Token
将 Token 填入配置中的 YOUR_API_TOKEN

工具概览

奥宏文档 MCP 提供 27 个工具，按功能分为 6 大类：

读取工具（公开，无需认证）

工具名	说明
`list_projects`	列出可访问的项目（仅全局端点）
`list_pages`	列出项目的页面树结构
`get_page`	获取页面详情，包含块列表
`get_page_content`	获取页面内容（Markdown 原文 + 渲染预览）
`search`	全文搜索项目、页面和内容
`list_versions`	列出项目的版本列表

管理读取工具（需要认证）

工具名	说明
`get_project_info`	获取项目完整信息（含隐藏版本和语言配置）
`list_pages_all`	列出全部页面（含隐藏页面，无版本过滤）
`get_page_detail`	获取页面完整详情（含所有块的原始内容）

写入工具（需要认证 + 项目所有者）

工具名	说明
`create_project`	创建新项目（仅全局端点）
`update_project`	更新项目信息（标题、简介、语言等）
`update_project_uid`	修改项目 UID
`create_page`	创建页面
`update_page`	更新页面信息（标题、排序、分组等）
`delete_page`	删除页面及其所有内容
`update_page_content`	更新页面 Markdown 内容
`update_page_uid`	修改页面 UID
`update_page_sort`	批量更新页面排序和层级

版本管理工具（需要认证 + 项目所有者）

工具名	说明
`create_version`	创建版本
`update_version`	更新版本信息
`delete_version`	删除版本（不允许删除唯一版本或默认版本）

块管理工具（需要认证 + 项目所有者）

工具名	说明
`create_block`	创建内容块（仅支持 markdown/code/html）
`update_block`	更新块信息
`delete_block`	删除块及其所有内容
`update_block_sort`	批量更新块排序

文件上传工具（需要认证 + 项目所有者）

工具名	说明
`upload_file`	通过 Base64 上传文件（限制 10MB）
`upload_file_from_url`	通过 URL 下载并上传文件（限制 10MB）

完整的参数说明和返回值格式，请参考 MCP 工具详解。

使用技巧和常见问题，请参考 MCP 最佳实践。

安全说明

块类型白名单：MCP 仅支持操作 markdown、code、html 三种类型的块，其他类型（如 naotu、bpmn、iframe）不暴露给 MCP
文件安全扫描：上传文件会检测 .php 扩展名和 <?php 内容标记，防止上传可执行脚本
权限隔离：写入操作要求认证 + 项目所有者身份，读者权限只能读取
UID 格式校验：修改 UID 时仅允许字母、数字、下划线和连字符

客户端配置示例

Claude Desktop

编辑配置文件 ~/AppData/Roaming/Claude/claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "ulthon-doc": {
      "url": "https://your-domain/mcp/your-project-uid",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "ulthon-doc": {
      "url": "https://your-domain/mcp/your-project-uid",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Windsurf

编辑 ~/.windsurf/settings/mcp.json：

{
  "mcpServers": {
    "ulthon-doc": {
      "url": "https://your-domain/mcp/your-project-uid",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

OpenCode

在项目根目录创建 opencode.json：

{
  "mcp": {
    "servers": {
      "ulthon-doc": {
        "type": "remote",
        "url": "https://your-domain/mcp/your-project-uid",
        "headers": {
          "Authorization": "Bearer YOUR_API_TOKEN"
        }
      }
    }
  }
}

Cline（VS Code 插件）

在 VS Code 设置中找到 Cline 的 MCP 配置，添加：

{
  "mcpServers": {
    "ulthon-doc": {
      "url": "https://your-domain/mcp/your-project-uid",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

协议细节

项目	说明
协议版本	2025-03-26
传输方式	Streamable HTTP
认证方式	Bearer Token（Header: `Authorization: Bearer YOUR_TOKEN`）
会话管理	基于 `Mcp-Session-Id` 头
工具总数	全局端点 27 个 / 项目端点 25 个
资源模板	全局端点提供 4 个资源模板（项目列表、页面树、页面内容、版本列表）