Macro MCP 内容类工具怎么用：ReadContent、ReadMetadata 与 CreateDocument 的参数与陷阱
把 Macro 的 MCP 服务接到 Claude Code 或者 Codex CLI 上，第一轮对话往往很顺：让模型搜一下有没有关于某个项目的文档，它能搜；让它把那份文档的正文读出来，它就开始来回试探，最后回一句“没有找到该文档”。
问题基本不在模型，而在这一组内容类工具的设计前提上。Macro 的文档站有一页 Tool Reference，页面开头写明这些页面是从 Macro 的 Rust MCP 工具注册表生成的，一共列了 16 个工具。其中直接跟“文档正文”打交道的是三个：ReadContent、ReadMetadata、CreateDocument。这三个工具里，前两个都是纯 id 驱动的——你手上没有 documentId，它们一个字也读不出来。
这篇就按官方那几张生成出来的参数表，把这三个工具各自要什么、缺了什么、连起来该怎么排序讲清楚。需要先说明的是：这些参考页是从工具注册表自动生成的，只列了入参，没有描述返回值结构，也没有给示例调用。所以下面凡是文档没写的地方，我都会直接标出来是空白，而不是替官方补一个我猜的答案。
三个工具的参数表，先原样摆出来
按官方生成页逐字对照，三个工具的入参是这样的：
| 工具 | 参数 | 类型 | 必填 | 官方描述（原意） |
|---|---|---|---|---|
ReadContent | documentId | string | 是 | 你想取正文的那份文档的 id |
ReadMetadata | documentId | string | 是 | 你想取元数据的那份文档的 id |
CreateDocument | documentName | string | 是 | 文档名，不带扩展名 |
CreateDocument | fileContent | string | 是 | 你要创建的这份文档的字符串内容 |
CreateDocument | fileExtension | string | 是 | 你要创建的这个纯文本文件的扩展名 |
CreateDocument | isTask | boolean | 是 | 这份文档是否是一个任务，只对 md 文档生效 |
两个读取工具的参数表干净得有点极端：一个必填字符串，没有分页参数，没有范围参数，没有格式开关。这意味着你不能只读某文档的前 200 行，也不能要求它按某种格式返回——文档没有提供这类参数，就别指望在提示词里写“只读前三段”能被工具层面执行，那只是让模型自己截断而已。
documentId 到底从哪来：官方参数表没有回答
这是接入之后最先撞上的墙。ReadContent 和 ReadMetadata 都要求 documentId，但生成出来的参考页里既没写这个 id 长什么样，也没写哪个工具会返回它。
从工具清单本身能看出的、可以确定的事只有一件：Macro 这套 MCP 里另外提供了 ContentSearch、NameSearch、ListEntities、GetEntityProperties 这类检索与实体工具。ContentSearch 的参数表写着两个必填项——entityTypes（要搜哪些类型的条目，留空表示搜全部类型，官方举的例子是 ['documents']、['emails', 'documents']、['channels']）和 query（要搜的文本内容，搜的是文档、邮件、消息的正文）。也就是说，实际链路只能是“先用搜索或实体类工具定位到条目，再拿着标识去读正文”。但这条链路的衔接细节，也就是搜索结果里究竟以什么字段名给出 documentId，官方生成页没有说明。搜索类工具的用法我在搜索类工具：内容搜索与名称搜索里单独拆过，实体类那三个则在实体类工具：列实体、取属性、改属性。
实践上的建议就一条：不要在提示词里让模型“直接读某某文档”，而是显式要求它先搜索、再基于搜索结果调用读取工具。省掉第一步，模型就只能凭空捏一个 id，然后你会看到一串失败重试。
为什么要分成 ReadContent 和 ReadMetadata 两个工具
两个工具入参完全一样，只有描述里一个说 content、一个说 metadata。拆成两个而不是加一个 include 开关，最直接的好处是省 token：Agent 判断“这份文档是不是我要找的那份”时，往往不需要把整篇正文灌进上下文。
不过要克制的是，官方参考页没有列出 metadata 具体包含哪些字段。所以在写自动化流程时，别把“ReadMetadata 一定会返回作者/创建时间/所在文件夹”当成前提去写条件分支；稳妥的做法是先在真实环境里调一次看返回，再照着返回结构写下游逻辑。另一个容易想当然的点是，产品侧文档能力再丰富，也不代表这些属性会 1:1 出现在 metadata 返回里，MCP 这边确实没有交代。
CreateDocument：四个参数全是必填，isTask 最容易漏
CreateDocument 的参数表有一个很容易踩的点：四个参数的必填列全是 Yes，包括那个看起来像可选开关的 isTask。模型在生成工具调用时经常只填名字和内容，把布尔量漏掉，于是请求在参数校验这一层就被打回。如果你在编排里发现建文档反复失败，先检查是不是这个字段没给。
另外三处需要照字面理解的约定：
documentName官方明确写了是不带扩展名的名字。写成会议纪要.md属于把扩展名重复塞了一遍。fileExtension单独一个字段，描述里限定的是“你要创建的这个纯文本文件的扩展名”。所以这个工具的适用面是纯文本类文件，不要拿它去构造二进制格式。isTask的描述里带了限定语：只对 md 文档生效。换句话说，扩展名不是 md 的时候这个字段填 true 也没有产品意义，参数表只是仍然要求你把它填上。
组合起来，一次典型调用的参数形状大致是这样（字段名严格照参数表，值是示意）：
{
"documentName": "2026-08-17-mcp-jieru-jilu",
"fileContent": "# 接入记录\n\n- 端点已配置\n- OAuth 登录完成\n",
"fileExtension": "md",
"isTask": false
}
参数表没有写的是：同名文档会怎么处理、文档默认落在哪个位置、创建后是否返回新文档的 id。最后一条对编排影响最大——如果创建之后想立刻回读校验，你需要确认返回里有没有 id，没有就得退回搜索一遍。
text_editor_code_execution 和 CreateDocument 不是一回事
工具清单里还有一个 text_editor_code_execution，名字里带 editor，很容易被当成 CreateDocument 的升级版。看参数表就知道不是：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
command | string | 是 | 要执行的命令：view、create 或 str_replace |
path | string | 是 | 文件路径 |
file_text | string | 否 | create 操作的文件内容 |
old_str | string | 否 | str_replace 要查找的字符串 |
new_str | string | 否 | str_replace 的替换字符串 |
区别在寻址方式：CreateDocument 用的是 documentName 这种“Macro 里的一份文档”的概念，而这个工具用的是 path 文件路径，命令集也是典型的文本编辑器三件套。它旁边还有一个 bash_code_execution，只有一个必填参数 command（要执行的 bash 命令）。这两个明显属于代码执行那一侧的能力，跟“往 Macro 库里建一份文档”不是同一条路径。官方参考页没有说明这个路径的根在哪、作用域有多大，所以在没搞清楚边界之前，需要往 Macro 里落内容就老老实实用 CreateDocument，而不是用 path 去猜。
接上去之前：端点和连接方式
内容类工具能不能被调到，前提是 MCP 服务连上了。官方给的端点是：
https://mcp-server.macro.com/mcp
文档写明这是远程服务，不需要本地进程，客户端连接时通过 Macro 的 OAuth 流程完成鉴权，并且 MCP 访问在每个 Macro 套餐上都可用，包含免费版。两个命令行客户端的接入命令分别是：
claude mcp add --transport http macro https://mcp-server.macro.com/mcp
codex mcp add macro --url https://mcp-server.macro.com/mcp
接受 JSON 配置的编辑器则在 mcpServers 下加一段，类型是 http。加完之后由编辑器触发一次连接，在浏览器里走完登录。连接环节本身的坑我放在MCP 连不上：动态客户端注册与鉴权头里说。
什么时候不适用，以及文档还没回答的
先说不适用的场景。这三个工具解决的是“一份一份地读和建”，不是批处理：ReadContent 没有批量入参，也没有分页，想遍历一个文件夹里的几十份文档，只能靠上层循环反复调用，上下文很快就会被撑爆。要做规模化的内容盘点，更合理的入口是搜索和实体类工具先收敛范围。
再说几个官方参考页确实空着、我也不打算替它编的问题：
- 三个工具的返回结构一律没写，包括
ReadMetadata到底给哪些字段、CreateDocument会不会回传新 id； documentId的来源链路没写，只能推断要靠搜索或实体工具，但字段名要以实际返回为准；- 没有任何限流、大小上限、超时方面的说明，超长文档一次读会发生什么，参数表给不出答案；
- 权限边界这一层也没有在工具页上体现——同一个账号在 Macro 里能看到什么，取决于产品侧的权限模型，而不是 MCP 工具本身。
所以落地节奏建议这样排：先按上面的端点把连接跑通，再手工调一次 ContentSearch 看清返回长什么样，把真实的 id 字段名记下来，然后才去写涉及 ReadContent 和 CreateDocument 的自动化。整套 MCP 服务覆盖了哪些能力、16 个工具怎么分组，可以对照Macro 的 MCP 服务能做什么一起看。
延伸阅读
- 从头读起：Macro 是什么：邮件、任务、文档、CRM 共用一个双向数据库的开源工作区
- 本专题共 40 篇，完整分组目录见专题页
- Macro MCP 的会话与邮件四工具：读会话、发邮件、改标签各要什么参数
- Macro 的 blocks 数据模型：十几类内容共用一份库，到底改变了什么
本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、
MCP 工具参考与自托管说明整理，核对日 2026-08-17。
我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感；
官方标注为计划中的能力文中已如实标明，不代表当前可用。
价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。