UNIDOC / KNOWLEDGE IN MOTION

AI MCP 接入指南

从理解，到动手实现。步骤、协议与可复制的示例，都在这份文档中。

1. 客户端配置

MCP 客户端只需要服务地址，不需要部署 UniDoc 源码：

{
  "mcpServers": {
    "unidoc": {
      "url": "https://app.unidoc.top/mcp",
      "oauth": {
        "authorizationServer": "https://app.unidoc.top/.well-known/oauth-authorization-server",
        "scopes": ["mcp:read", "mcp:write"]
      }
    }
  }
}

支持 OAuth 动态注册的客户端直接按发现文档完成注册、S256 PKCE、UniDoc 登录和授权确认。
客户端实现固定回调时，可由部署者设置 UNIDOC_MCP_REDIRECT_URIS（JSON 字符串数组），例如：

UNIDOC_MCP_REDIRECT_URIS=["https://ai.example.test/oauth/callback"]

不要把真实 token、会话 Cookie 或生产密钥写入配置文件、仓库、日志或提示词。

UniDoc MCP 的授权码交换会同时返回 access token 和 refresh token。当前默认有效期为
30 天（2592000 秒）；refresh token 也默认有效 30 天，并且每次刷新都会轮换成新的
refresh token。服务端只持久化 refresh token 的 SHA-256 摘要，因此重启不会让已签发的
refresh token 自动失效，也不会把原始 refresh token 写入状态文件。

客户端应把 token 响应安全存储在自己的凭据存储中，并在 access token 过期前或收到
401 后使用 refresh grant：

POST /oauth/mcp/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<current_refresh_token>&
client_id=<registered_client_id>

响应仍包含新的 access_token、expires_in、refresh_token 和
refresh_token_expires_in。旧 refresh token 在成功轮换后立即失效；并发刷新时只允许
其中一个请求成功，客户端应保存最后一次成功响应。refresh token 不能放进 URL、日志、
网页源码或 MCP 工具参数。

2. 推荐调用顺序

initialize
tools/list
unidoc_open_document（传入已获取的 UDoc JSON）
unidoc_list_blocks / unidoc_list_comments
读取目标段落和当前 revision
执行一个带 expectedRevision 与稳定 requestId 的写操作
冲突时重新读取，不要盲目覆盖
需要下载时调用 unidoc_export_udoc

若任务是“把这份 HTML 发布成网站”，直接使用下面的网站发布流程，无需先调用
unidoc_open_document。

示例：

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "unidoc_create_comment",
    "arguments": {
      "documentId": "doc_…",
      "paraId": 42,
      "start": 12,
      "end": 25,
      "text": "请补充这一段的来源。",
      "author": "AI 审阅",
      "expectedRevision": 3,
      "requestId": "review-20260912-42-1"
    }
  }
}

3. AI 直接发布 HTML / PDF 网站

HTML 使用 unidoc_publish_website；PDF 使用 unidoc_publish_pdf，传入标准 Base64 的
pdfBase64、.pdf 文件名 fileName、requestId 和可选 title。PDF 经 UniDoc PDF2HTML
转换后按相同流程发布，MCP 文件上限 16 MiB。返回网址可在 UDOC 中作为 HTTPS 沙箱嵌入。
完整产品上传与 MCP 示例见 PDF 发布接口。

网站发布使用独立授权范围。客户端配置示例：

{
  "mcpServers": {
    "unidoc": {
      "url": "https://app.unidoc.top/mcp",
      "oauth": {
        "authorizationServer": "https://app.unidoc.top/.well-known/oauth-authorization-server",
        "scopes": ["mcp:read", "mcp:publish"]
      }
    }
  }
}

旧 mcp:read / mcp:write 授权不包含网站发布。客户端应完成包含 mcp:publish 的授权，
然后读取 tools/list，确认服务器提供 unidoc_publish_website。这是补充发布权限；已有
UniDoc 登录会话有效时无需重新登录。单独的浏览器 Cookie 也不会被提升为发布授权。

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "unidoc_publish_website",
    "arguments": {
      "html": "<!doctype html><meta charset=\"utf-8\"><title>实验课堂</title><h1>实验课堂</h1><button onclick=\"this.textContent='已开始'\">开始</button>",
      "title": "实验课堂",
      "requestId": "classroom-page-20260916-v1"
    }
  }
}

这是立即公开发布操作。服务端为显式提交内容保存账户归属的 .udoc 来源，再返回独立
公网 URL；AI 不需要浏览器 Cookie、OmniDoc 上传签名或服务器 SSH 权限。网络超时后以
同一个 requestId 和原参数重试；修改内容应使用新 ID，不要用随机 ID 重放同一次发布。

baseUrl 可选，仅用于解析资源相对地址，不抓取网页。本地相邻文件需内联或改为可公开
访问的 HTTPS 地址；前端工程应提交构建产物中的 HTML，后端服务和原网站的登录状态
不会随 HTML 迁移。取得 URL 后实际打开页面，检查按钮和资源加载，再向用户报告完成。

发布结果包含 siteId、url、status:"published"、contentSha256、bytes、
createdAt、replayed 及 source:{"kind":"udoc","persisted":true}。
后续使用 unidoc_get_website({"siteId":"…"}) 查询发布信息，使用
unidoc_export_website({"siteId":"…"}) 取回来源 .udoc。这两个工具校验账户归属。
导出结果的 fileName、mimeType、base64 描述原生文件；将 base64 解码后保存为返回的
.udoc 文件名。完整说明与重试规则见 AI 网页发布说明。

4. 与编辑器、iframe 的关系

MCP 是可选的 AI 控制平面：它不参与编辑器启动，不改变页面排版，也不取代 iframe 整档
桥。iframe 适合宿主加载/读取整份 HTML 或 UDoc；MCP 适合 AI 按 para_id、批注 ID 和
revision 做局部读写。接入方只需使用公开接口并妥善保管授权信息。

当前 unidoc_open_document 的会话是进程内隔离会话，完成一次转换或审阅后可导出 UDoc；
如果需要把写入绑定到云文稿，应由宿主先完成账号授权和文稿存取，再把最新 UDoc 交给 MCP，
或在后续版本接入同一账号授权的持久存储。网站发布工具使用独立的持久来源与发布收据，
不会依赖这个进程内文稿会话存活。