奥宏文档
欢迎 MCP 文档 MCP 接入指南 MCP 工具详解 MCP 最佳实践
上一页
下一页
首页 MCP 文档 MCP 工具详解

MCP 工具详解

本文档列出奥宏文档 MCP 端点提供的所有 27 个工具，包括完整的参数说明、返回值格式和典型用法。

关于如何配置 MCP 连接，请参考 MCP 接入指南。

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

权限说明

每个工具旁标注了权限要求：

  • 公开 -- 无需认证，任何人可用
  • 认证 -- 需要 Bearer Token
  • 所有者 -- 需要认证 + 项目所有者身份

1. 读取工具

list_projects

权限：公开 | 端点：仅全局端点

列出当前可访问的项目。公开项目所有人可见，已认证用户还能看到自己拥有或有阅读权限的项目。

参数：

参数 类型 必填 说明
page integer 否 页码，默认 1
limit integer 否 每页数量，默认 20

返回值：

{
  "total": 5,
  "projects": [
    {
      "uid": "my-project",
      "title": "我的项目",
      "intro": "项目简介",
      "default_lang": "zh-cn",
      "show_status": 0
    }
  ]
}

list_pages

权限：公开 | 端点：全局 + 项目

列出项目的页面树结构，支持按版本过滤。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID（项目端点自动注入）
version_id integer 否 版本 ID，用于过滤页面
page integer 否 页码，默认 1
limit integer 否 每页数量，默认 100

返回值：

{
  "project_uid": "my-project",
  "total": 3,
  "pages": [
    {
      "id": 1,
      "uid": "abc123",
      "title": "首页",
      "pid": 0,
      "as_group": 0,
      "sort": 0,
      "children": [...]
    }
  ]
}

get_page

权限：公开 | 端点：全局 + 项目

获取页面详情，包含块列表。支持按版本过滤。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
lang string 否 语言标识
version_id integer 否 版本 ID

返回值：

{
  "id": 1,
  "uid": "abc123",
  "title": "页面标题",
  "blocks": [
    {
      "block_id": 10,
      "block_uid": "block123",
      "type": "markdown",
      "sort": 1,
      "lang": "zh-cn"
    }
  ]
}

get_page_content

权限：公开 | 端点：全局 + 项目

获取页面全部内容，包含每个块的 Markdown 原文和渲染后的 HTML 预览。支持多语言回退。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
lang string 否 语言标识，默认使用项目默认语言
version_id integer 否 版本 ID

返回值：

{
  "page_title": "页面标题",
  "lang": "zh-cn",
  "blocks": [
    {
      "block_id": 10,
      "type": "markdown",
      "sort": 1,
      "lang": "zh-cn",
      "content": "# 标题\n\n正文内容...",
      "preview": "<h1>标题</h1><p>正文内容...</p>"
    }
  ]
}

search

权限：公开 | 端点：全局 + 项目

搜索项目、页面和内容，使用 MySQL 全文索引。

参数：

参数 类型 必填 说明
keyword string 是 搜索关键词
project_uid string 否 限定搜索到指定项目
page integer 否 页码，默认 1
limit integer 否 每页数量，默认 20

list_versions

权限：公开 | 端点：全局 + 项目

列出项目的所有版本。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID

2. 管理读取工具

get_project_info

权限：认证 + 所有者 | 端点：全局 + 项目

获取项目完整信息，包含所有语言和版本配置（包括隐藏的）。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID

返回值：

{
  "uid": "my-project",
  "title": "项目标题",
  "intro": "项目简介",
  "default_lang": "zh-cn",
  "project_lang": {"zh-cn": "简体中文", "en": "English"},
  "show_status": 0,
  "versions": [...],
  "pages_count": 10
}

list_pages_all

权限：认证 + 所有者 | 端点：全局 + 项目

列出项目全部页面，无版本过滤，包含隐藏页面，以树结构返回。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID

返回值： 与 list_pages 类似，但额外包含 in_version 字段标记页面所属版本。

get_page_detail

权限：认证 + 所有者 | 端点：全局 + 项目

获取页面完整详情，包含所有块的原始内容，无版本过滤。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
lang string 否 语言标识

3. 写入工具

create_project

权限：认证 | 端点：仅全局端点

创建新项目。

参数：

参数 类型 必填 说明
title string 是 项目标题
intro string 否 项目简介
default_lang string 否 默认语言，默认 zh-cn

返回值：

{
  "uid": "auto-generated-uid",
  "title": "新项目",
  "intro": "项目简介"
}

update_project

权限：认证 + 所有者 | 端点：全局 + 项目

更新项目信息。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
title string 否 项目标题
intro string 否 项目简介
default_lang string 否 默认语言
project_lang string 否 语言配置，JSON 格式，如 {"zh-cn":"中文","en":"English"}
show_status integer 否 是否显示状态，1 显示 / 0 隐藏

update_project_uid

权限：认证 + 所有者 | 端点：全局 + 项目

修改项目 UID。警告：修改后旧链接将失效。

参数：

参数 类型 必填 说明
project_uid string 是 当前项目 UID
uid string 是 新 UID，仅允许字母、数字、下划线和连字符

create_page

权限：认证 + 所有者 | 端点：全局 + 项目

创建页面。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
title string 是 页面标题
pid integer 否 父页面 ID，默认 0（顶级页面）
as_group integer 否 是否为分组，1 是 / 0 否
intro string 否 页面简介

返回值：

{
  "id": 100,
  "uid": "auto-generated-uid",
  "title": "新页面",
  "pid": 0,
  "sort": 50
}

update_page

权限：认证 + 所有者 | 端点：全局 + 项目

更新页面信息。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
title string 否 页面标题
intro string 否 页面简介
sort integer 否 排序值
as_group integer 否 是否为分组

delete_page

权限：认证 + 所有者 | 端点：全局 + 项目

删除页面及其所有块和内容。此操作不可撤销。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID

update_page_content

权限：认证 + 所有者 | 端点：全局 + 项目

更新页面内容。这是最常用的写入工具。不指定 block_id 时自动查找或创建 Markdown 块。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
lang string 是 语言标识，如 zh-cn
content string 是 Markdown 格式的内容
block_id integer 否 块 ID，不提供则自动查找或创建首个 Markdown 块

使用示例： 这是最简单的写入方式，AI 只需要标题和内容即可创建文档：

1. create_page(title="新页面") → 获得 page_uid
2. update_page_content(page_uid="xxx", lang="zh-cn", content="# 标题\n\n正文...")

update_page_uid

权限：认证 + 所有者 | 端点：全局 + 项目

修改页面 UID。警告：修改后旧链接将失效。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 当前页面 UID
uid string 是 新 UID，仅允许字母、数字、下划线和连字符

update_page_sort

权限：认证 + 所有者 | 端点：全局 + 项目

批量更新页面排序和父级关系。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
sort_list array 是 排序列表，每项包含 page_uid（字符串）、sort（整数）、pid（整数，可选）

sort_list 格式示例：

[
  {"page_uid": "page-1", "sort": 1},
  {"page_uid": "page-2", "sort": 2, "pid": 5}
]

4. 版本管理工具

create_version

权限：认证 + 所有者 | 端点：全局 + 项目

创建版本。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
title string 是 版本标题
desc string 否 版本描述
status integer 否 状态：0 = 启用，1 = 隐藏（默认 1）
sort integer 否 排序值，不填则自动递增

update_version

权限：认证 + 所有者 | 端点：全局 + 项目

更新版本信息。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
version_id integer 是 版本 ID
title string 否 版本标题
desc string 否 版本描述
status integer 否 状态
sort integer 否 排序值

delete_version

权限：认证 + 所有者 | 端点：全局 + 项目

删除版本。不允许删除唯一版本或默认版本。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
version_id integer 是 版本 ID

5. 块管理工具

页面内容由多个「块」组成。MCP 仅支持操作 markdown、code、html 三种块类型。

create_block

权限：认证 + 所有者 | 端点：全局 + 项目

创建内容块。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
page_uid string 是 页面 UID
type string 是 块类型，仅允许 markdown / code / html
sort integer 否 排序值

update_block

权限：认证 + 所有者 | 端点：全局 + 项目

更新块信息。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
block_id integer 是 块 ID
type string 否 块类型，仅允许 markdown / code / html
sort integer 否 排序值

delete_block

权限：认证 + 所有者 | 端点：全局 + 项目

删除块及其所有内容（包括临时内容）。此操作不可撤销。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
block_id integer 是 块 ID

update_block_sort

权限：认证 + 所有者 | 端点：全局 + 项目

批量更新块排序。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
sort_list array 是 排序列表，每项包含 id（块 ID，整数）和 sort（排序值，整数）

6. 文件上传工具

upload_file

权限：认证 + 所有者 | 端点：全局 + 项目

通过 Base64 编码上传文件。大小限制 10MB。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
data string 是 Base64 编码的文件数据
filename string 是 文件名，不允许 .php 扩展名

安全检测： 上传内容会自动扫描 PHP 标记（<?php），检测到则拒绝上传。

upload_file_from_url

权限：认证 + 所有者 | 端点：全局 + 项目

通过 URL 下载文件并上传。大小限制 10MB。

参数：

参数 类型 必填 说明
project_uid string 是 项目 UID
url string 是 文件 URL
filename string 否 文件名，不提供则从 URL 自动提取

返回值通用格式

成功响应

工具调用成功时返回 JSON 对象，具体字段见各工具说明。写入操作通常返回操作后的完整对象。

错误响应

工具调用失败时返回：

{
  "isError": true,
  "error": "错误描述信息"
}

常见错误：

错误信息 原因
Authentication required for write operations 写入操作未提供认证
Permission denied 无项目访问权限
Project not found 项目 UID 不存在
Page not found 页面 UID 不存在
Block type not allowed 块类型不在白名单中
Invalid UID format UID 包含非法字符

原文标题：MCP 工具详解

原文文档：奥宏文档

原文地址：/read/augushong/ulthon-document/zh-cn/1.0.0/mcp-docs/mcp-tools-reference.html

原文平台：奥宏文档

1.0.0
由 Ulthon 提供技术支持。 支持MCP浏览。 进入文档中心