背景
在使用 MCP Server 的 yuque_update_note 工具时,发现更新小记的 API 参数与创建小记不一致,导致无法用相同方式传入内容。
问题
创建小记 (POST /api/v2/notes) 接受 body 字段:
{ "body": "# 标题\n\n正文内容" }
更新小记 (PUT /api/v2/notes/{id}) 不接受 body,必须传入 source、html、abstract 三个字段:
{
"source": "# 标题\n\n正文内容",
"html": "<h1>标题</h1><p>正文内容</p>",
"abstract": "# 标题\n\n正文内容"
}
这意味着调用方必须自行将 markdown 转换为 HTML,否则接口返回 html,source,abstract invalid 错误。
尝试过的方案
方案一:直接传 body(失败)
尝试让 updateNote 与 createNote 一样只传 body:
await client.updateNote(noteId, { body: args.body });
// → API 返回: html,source,abstract invalid
API 不接受此参数,直接报错。
方案二:自行将 markdown 转为 HTML(放弃)
在 MCP Server 端实现 markdown → HTML 转换:
const html = markdownToHtml(args.body);
await client.updateNote(noteId, {
source: args.body,
html,
abstract: args.body.substring(0, 200),
});
放弃原因:
- 转换不可靠:完整的 markdown 规范非常复杂(嵌套列表、表格、代码块、数学公式等),在 MCP Server 端用正则实现无法保证与语雀渲染结果一致
- 维护负担:语雀支持的 markdown 扩展语法会变化,MCP Server 端的转换逻辑需要持续跟进
- 重复劳动:语雀服务端本身已有完善的 markdown 解析能力,客户端再实现一遍毫无意义
- abstract 截断粗暴:直接
substring(0, 200) 可能截断在 UTF-8 多字节字符中间,或截断 markdown 语法标记
期望
希望 PUT /api/v2/notes/{id} 接口也能像创建接口一样支持 body 参数:
{ "body": "# 标题\n\n正文内容" }
由语雀服务端负责 markdown → HTML 的转换,与创建接口行为保持一致。这样 MCP Server(以及所有第三方集成)可以统一用 body 传入内容,无需自行处理 HTML 转换。
背景
在使用 MCP Server 的
yuque_update_note工具时,发现更新小记的 API 参数与创建小记不一致,导致无法用相同方式传入内容。问题
创建小记 (
POST /api/v2/notes) 接受body字段:{ "body": "# 标题\n\n正文内容" }更新小记 (
PUT /api/v2/notes/{id}) 不接受body,必须传入source、html、abstract三个字段:{ "source": "# 标题\n\n正文内容", "html": "<h1>标题</h1><p>正文内容</p>", "abstract": "# 标题\n\n正文内容" }这意味着调用方必须自行将 markdown 转换为 HTML,否则接口返回
html,source,abstract invalid错误。尝试过的方案
方案一:直接传 body(失败)
尝试让
updateNote与createNote一样只传body:API 不接受此参数,直接报错。
方案二:自行将 markdown 转为 HTML(放弃)
在 MCP Server 端实现 markdown → HTML 转换:
放弃原因:
substring(0, 200)可能截断在 UTF-8 多字节字符中间,或截断 markdown 语法标记期望
希望
PUT /api/v2/notes/{id}接口也能像创建接口一样支持body参数:{ "body": "# 标题\n\n正文内容" }由语雀服务端负责 markdown → HTML 的转换,与创建接口行为保持一致。这样 MCP Server(以及所有第三方集成)可以统一用
body传入内容,无需自行处理 HTML 转换。