企业服务 · 财税合规 · AI 落地 · 技术定制
联系人:展欣 咨询热线:188 1922 9158 邮箱:huaqidao@qq.com

墨问 MCP 实测:五个工具、一套文档模型,和四条它做不到的事

2026-11-16

我们在做站内文章的多平台分发时,把墨问笔记的 MCP 接口按文档实测了一遍。这篇只写实测到的东西:协议形态、5 个工具能干什么、正文用什么数据结构、素材怎么进去,以及四条它明确做不到的事。如果你正打算把自己的内容同步到墨问,后面的检查清单能省掉一轮试错。

一、它是什么形态的 MCP

墨问开放的是 Streamable HTTP 形态的 MCP 服务,一个固定的 POST 端点,鉴权靠查询串里的 key,不是 OAuth,也不是 stdio。

POST https://open.mowen.cn/api/open/mcp/v1/note?key=<your-key>
Content-Type: application/json
Accept: application/json, text/event-stream

握手之后返回的信息很干净:

{
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "logging": {}, "tools": { "listChanged": true } },
    "serverInfo": { "name": "mowen-note-mcp-server", "version": "0.1.0" }
  }
}

一个容易被忽略但很关键的细节:它是无状态的。响应里不带 Mcp-Session-Id,只有网关自己的 SERVERID / SERVERCORSID cookie。这意味着两件事——重试是安全的(不需要重放会话),但「重复创建」的风险得你自己兜,服务端不会帮你判重。

二、五个工具,覆盖的是「写」这半边

  • CreateRichNote — 新建一篇富文本笔记。必填 body;选填 settings(紧凑 JSON,可设 autoPublish 与 tags)。
  • EditRichNote — 编辑已有笔记。必填 note_id + body,整篇替换语义,没有增量更新,也没有 settings 参数。
  • ChangeNoteSettings — 改笔记设置。目前 section 只有 1,即私密规则:privacy.type 取 public / private / rule;rule 下可设 noShare(禁转发)与 expireAt(公开截止时间戳,秒,0 表示永久)。
  • UploadViaURL — 把一个远程 URL 的文件收进素材库。file_type 必填:1 图片、2 音频、3 PDF;返回 uuid 供正文引用。
  • Echo — 连通性测试,回显你给的字符串。

五个工具,四个动词:建、改、设隐私、传素材。这就是全部。

三、正文不是 Markdown,是一套文档树

body 要求的是紧凑 JSON 字符串,结构是 ProseMirror 风格的一棵 doc 树(文档里称为 NoteAtom)。段落、标题、引用都是节点,加粗、链接、行内代码是 marks。不是 HTML,也不是 Markdown——你贴 Markdown 进去它不会自己解析。

  • 节点:heading(attrs.level 取 1/2/3)、paragraph、quote、codeblock(可指定语言)、image、audio、pdf
  • 行内 marks:bold、highlight(高亮)、link(attrs.href)、code(行内代码)
  • 图片:{"type":"image","attrs":{"uuid":"...","align":"center","alt":"..."}}
  • 音频:除 audio-uuid 外还能带 show-note,也就是时间轴文本(02:00 开头 这种),对播客类内容很实用
  • 内链:支持指向另一篇笔记的内链节点,适合做系列内容的互链

一个诚实的说明:工具说明里没有出现列表(ul/ol)和表格这两类节点。我们没在真实账号上做投放验证,所以不能断言「不支持」,但按「文档没写就别指望」的工程习惯,转换器里必须准备好降级路径——列表逐项拆成段落加前缀,表格按「表头:值」逐行成段。这是接入前先要确认的一条。

四、素材必须先换 uuid,不能直接塞外链

正文里的图片不是给个 src 就完事,得先UploadViaURL把它收进墨问的素材库,拿到 uuid 再在节点里引用:

// 1) 收素材
{ "name": "UploadViaURL",
  "arguments": { "url": "https://example.com/a.jpg", "file_type": 1, "file_name": "a.jpg" } }

// 2) 正文里引用它的 uuid
{ "type": "image", "attrs": { "uuid": "<uuid>", "align": "center", "alt": "配图说明" } }

这条链路对同步场景有三点影响:一是图片量大的文章(我们这边有单篇 22 张的)会明显拉长耗时;二是映射必须自己缓存(源 URL → uuid),否则每次重跑都重复上传;三是源图必须公网可访问,本地文件得先有 URL。

五、四条硬边界,比功能更值得先知道

1. 只写不读。没有列笔记、没有读正文、没有搜索。工具清单里没有任何「get / list / search」。写完就只能去墨问端里看,程序侧拿不回来。

2. 不能删。只有 Create 和 Edit,没有 Delete。写错一篇、多建一篇,都只能到端内手动处理。这条直接决定了接入策略:先草稿,人工验收,再公开。

3. 没有专栏。我们试探过 column、columns、series 等路径,全部 404;公开文档里也查不到「专栏 / 合集 / 系列」,能用的归类手段只有 tags。专栏只能在客户端或网页端手工创建。

4. 发布时间不可指定。Create 的 settings 只认 autoPublish 和 tags,没有 publishTime / publishAt 之类的字段;ChangeNoteSettings 里的 expireAt 是「公开截止时间」,不是发布时间。也就是说:笔记时间永远等于创建那一刻,不能回填、不能修改。把历史文章批量搬过去,端内时间线就是「同一天出现 N 篇」。

顺手记录两个小坑:

  • 字段命名不一致:公开文档的示例写 autoPublish(驼峰),MCP 工具自带的示例写 auto_publish(下划线)。到底哪个生效,得实测,别照抄。
  • 没有发布开关:ChangeNoteSettings 的 section 目前只有隐私规则一类,没有「草稿 → 发布」的入口。如果创建时就设成草稿,很可能只能在端内点发布。

六、实测过程(可直接复用)

# 握手
curl -sS -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"probe","version":"0.0.1"}}}'

# 通知(返回 202)
curl -sS -X POST "$URL" -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 取工具清单
curl -sS -X POST "$URL" -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 连通性
{ "method": "tools/call", "params": { "name": "Echo", "arguments": { "message": "ping" } } }
# → {"result":{"content":[{"type":"text","text":"ping"}]}}

整套流程没有 OAuth 跳转、没有令牌刷新,一个 key 走到底,接入成本确实低。反过来说,key 是拼在 URL 查询串里的,等于一条明文凭据——它该被当成密码对待,落进 600 权限的文件,别进代码仓、别进日志。

七、这些边界对工程意味着什么

  • 幂等要自己造。既然服务端不判重,就在本地维护「源内容 → note_id」的映射表,并记录内容哈希:哈希没变就跳过,变了才用 EditRichNote 整篇覆盖。
  • 草稿优先。无删除能力意味着错误不可回收。默认 autoPublish 设 false,人工过一遍再放出来。
  • 时间线必须先规划。不能指定时间、不能删除、不能改时间,三条叠加起来是一次性动作:要么分批慢慢投(每次几篇),要么接受「同一天全冒出来」。批量前想清楚,之后改不回来。
  • 转换器要有降级层。自家文章里的列表、表格、脚注、图注,都得有「拆成段落」的兜底写法;先把结构对齐,再谈排版好看。
  • 限速是礼貌也是自保。素材上传串行 + 间隔,比一次并发几十个请求稳得多;失败要有重试与断点,别让一次 429 打断整批。

八、什么样的需求适合它

适合:把站内内容单向同步成笔记、做内容矩阵的程序化发文、批量入库图文素材、给营销团队做「一处写作、多处分发」的出口。

不适合:要求双向同步(读回来做比对)、要求栏目/合集结构、要求精确复刻历史时间线、要求「发错能撤回」的流程、需要按内容分层做权限(目前只有整篇级隐私)。

我们自己的结论是:这套接口适合当「出口」,不适合当「库」。源头内容留在自己站点,墨问作为分发渠道之一;需要栏目和时间的场景,仍然得回到自己的站点解决。

九、接入前检查清单

  • 1. 拿真实 key 跑通 initialize → tools/list → Echo,确认 serverInfo 与协议版本
  • 2. 用一个测试笔记验证 autoPublish 与 auto_publish 哪个生效、草稿是否真的不出现在公开页
  • 3. 验证列表与表格节点:能接受就保留结构,报错就走段落化降级
  • 4. 先上传一张小图,确认返回体里的 uuid 字段名与引用方式
  • 5. 建立 note_id 映射表与内容哈希,写完立刻落盘(避免重复创建)
  • 6. 建立 URL → uuid 素材缓存,避免重复上传
  • 7. 单篇长度上限没在文档里写死,长文(我们这边最长两万字)先用一篇探顶
  • 8. 把 key 放进 600 文件,脚本只读不打印;日志里做脱敏

写在最后

评估一个 MCP,功能清单只是上半场。真正决定能不能上生产的,往往是下半场那几个问题:能不能读回来、能不能撤回、能不能定时间、出错谁来收。墨问这套接口在上半场做得干净利落——五个工具、一套文档模型、一个端点,接进来半小时能跑通;下半场则需要接入方自己补齐一套幂等与验收流程。

这不是缺陷,是取向:它把「写」做小、做稳,把「管控」留给使用方的流程。想清楚这一点再动手,返工会少很多。

我们做企业服务与技术定制,习惯先把接口的边界摸清楚再谈方案——道化天下企服,官网 martale.com。