MCP 工具详解
按实际调用流程梳理 Anydocs MCP 工具，帮助 agent 更快选对入口和写入方式。
把这页当成 Anydocs MCP 的工作流速查表更合适：先开项目，再读内容，最后按页面、批量或导航场景选择写入工具。
推荐入口
大多数 agent 会从 `project_open` 开始。它不只返回项目配置和路径，还会带回当前允许的块类型、行内样式、作者约束、内置模板，以及可用的 resources / resourceTemplates。只有在需要明确确认工作流兼容性时，才额外调用 `project_validate`。
- `project_open`：读取 config、paths、enabledLanguages，以及 authoring guidance / templates / resources
- `project_validate`：确认项目 contract 和 agent-safe workflow 兼容性
- `project_set_languages`：更新语言集合，并可同时切换默认语言
页面读取与直接修改
写入前优先用读取工具建立上下文。需要常规修改时，用 `page_create`、`page_update`、`page_delete`、`page_set_status`。其中 `page_update` 只接受白名单字段：`slug`、`title`、`description`、`tags`、`content`、`render`、`review`；在常规流程里，应把 canonical `content` 视为事实来源，需要重建 markdown / plainText 时再把 `regenerateRender` 设为 `true`。`page_delete` 还会同步删除当前语言导航里的对应页面引用。
- `page_list` / `page_get` / `page_find`：先读再写
- `page_create`：手动创建 canonical page
- `page_update`：对白名单字段做浅合并更新
- `page_delete`：删除页面，并移除同语言导航引用
- `page_set_status`：单页切换 `draft` / `in_review` / `published`
模板化页面工具
当你希望 agent 直接生成结构更完整的初稿时，优先用模板工具，而不是手写原始 canonical content。当前内置模板只有 `concept`、`how_to`、`reference` 三种。`how_to` 必须至少提供一个 step；否则调用会失败。`page_create_from_template` 用于新建页，`page_update_from_template` 用于把已有页面重整成模板结构，并重新生成 content 与 render。
- `page_create_from_template`：基于模板创建新页
- `page_update_from_template`：按模板重写现有页面结构
- `concept`：解释概念、边界和适用场景
- `how_to`：步骤导向，至少要有一个 step
- `reference`：稳定事实、约束和参数速查
批量页面工具
多页维护时，优先使用批量工具，避免一页一页串行调用。它们会以一次校验过的批次写入，适合批量建页、统一补 `render`，或批量调整状态。
- `page_batch_create`：一次创建多页
- `page_batch_update`：批量应用 patch，并可按页设置 `regenerateRender`
- `page_batch_set_status`：一次切换多页状态
导航工具
导航改动通常从 `nav_get` 开始。常规场景优先用增量工具：`nav_insert`、`nav_move`、`nav_delete`。只有在你确实要整体替换时，才考虑 `nav_replace_items` 或 `nav_set`。两者的区别是：`nav_replace_items` 只替换 `navigation.items`，保留当前文档版本；`nav_set` 则替换完整 navigation document。
- `nav_get`：读取当前语言导航
- `nav_insert`：在根级或 section / folder 下插入节点
- `nav_move`：按 slash path 移动节点
- `nav_delete`：删除导航节点
- `nav_replace_items`：只替换 `items`
- `nav_set`：替换整个 navigation document
除了 tools 之外
如果是第一次接入 Anydocs MCP，可以先做 resource discovery；但对大多数 agent 来说，直接看 `project_open.authoring.resources` 和 `project_open.authoring.resourceTemplates` 就够了。当前静态 resources 包括 `anydocs://authoring/guidance`、`anydocs://templates/index`、`anydocs://content/allowed-types`；旧资料里可能还会看到 `anydocs://yoopta/allowed-types` 这个兼容别名，但新接入应以 canonical 资源名为准。resource templates 包括 `anydocs://templates/{templateId}` 和 `anydocs://blocks/{blockType}/example`。前者适合读规范和模板索引，后者适合拿具体模板细节或最小块示例。