UNIDOC / KNOWLEDGE IN MOTION

让 AI 发布交互网页

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

适用任务：用户已经要求把 AI 生成或用户提供的 HTML 发布到公网。此流程直接使用 UniDoc
MCP，不需要安装本地 UniDoc、操作浏览器上传窗口或获取服务器权限。

连接与授权

MCP 地址：https://app.unidoc.top/mcp。

OAuth 发现文档：https://app.unidoc.top/.well-known/oauth-authorization-server。
申请 mcp:read mcp:publish，完成 S256 PKCE 和账户授权。旧 read/write 授权不会自动
获得发布权限。新增 scope 是补充授权，不等于重新登录；已有登录会话有效时直接完成授权
确认。仅有浏览器 Cookie 不足以调用发布工具。认证材料只放在 MCP 客户端的凭据存储和
Authorization: Bearer … 请求头，
不放进 HTML、链接或对话正文。

先完成 initialize，再通过 tools/list 确认实际提供以下工具：

工具	用途
`unidoc_publish_website`	保存账户归属的 UDoc 来源并立即公开发布 HTML
`unidoc_get_website`	查询当前账户所属网站的发布信息
`unidoc_export_website`	取回当前账户所属网站的来源 `.udoc`

一次调用发布 HTML

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "unidoc_publish_website",
    "arguments": {
      "html": "<!doctype html><html lang=\"zh-CN\"><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>我的交互课堂</title><h1>我的交互课堂</h1><button onclick=\"this.textContent='欢迎开始探索'\">开始探索</button></html>",
      "title": "我的交互课堂",
      "requestId": "interactive-classroom-v1"
    }
  }
}

html、requestId 必填；title、baseUrl 可选。读取结果的 structuredContent；
兼容客户端也可解析 content[0].text 中的 JSON。若 isError=true，不能把它当成成功。
只向用户提供服务器实际返回的公网 URL，不拼接或猜测站点 ID。成功字段包括 siteId、
id、url、status:"published"、title、contentSha256、bytes、createdAt、
replayed 和 source:{"kind":"udoc","persisted":true}。

发布内容是不可变快照。网络中断或响应丢失时，保持同一 requestId 和原参数重试；服务端
应返回原站点。同 ID 携带不同内容会失败；要发布修改后的版本，使用新的 ID。发布来源和
幂等收据持久保存，不依赖进程内文稿会话。无需 expectedRevision。

图片、脚本与外部数据

单文件 HTML 可以内联 CSS、JS、SVG 和图片数据。若使用外部文件，将资源路径写成可公开
访问的 HTTPS 地址，或提供可选参数：

{"baseUrl":"https://assets.example.com/course/index.html"}

它只为相对路径提供解析基址，不会抓取该网页或上传同目录文件。AI 只有网页 URL 时，
应先通过已有且获授权的读取能力取得 HTML，再把内容交给发布工具。本地 HTML 相邻的
assets/、JS、CSS、图片不能自动随之上网；前端项目需先生成可托管的构建产物。

公网页面保留脚本交互，但运行在独立沙箱中；原网站的 Cookie、登录状态、同源存储及
后端服务不会一起迁移。动态数据接口、模块脚本、字体等外部资源仍需满足其 CORS 和权限
要求。发布链接后，实际打开它，检查主要按钮、资源与动态数据，再报告验收结果。

查询与取回原生文档

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "unidoc_get_website",
    "arguments": {"siteId":"发布结果中的站点 ID"}
  }
}

把工具名改为 unidoc_export_website，即可请求导出同一个站点的来源 .udoc。查询和
导出只对来源所属账户开放；有公开网页 URL 不等于有编辑或来源下载权限。导出返回
siteId、fileName、mimeType:"application/vnd.unidoc.udoc3" 和 base64；解码
base64 为原始字节，以返回的 .udoc 文件名保存。

遇到 401，恢复账户授权；缺少 mcp:publish 时重新申请包含该 scope 的授权；达到配额
则按服务器给出的重试信息稍后重试。不通过匿名请求、浏览器 Cookie 或伪造云对象 ID 绕过。

完整协议：MCP_PROTOCOL.md。客户端配置：AIMCPINTEGRATION.md。