From ed3a8f8174bb8b74a8184e50b5dcfe35a4de3452 Mon Sep 17 00:00:00 2001 From: agent_coder Date: Sun, 12 Jul 2026 07:57:26 +0300 Subject: [PATCH] docs(mcp): sync write-tool specs with #502 literal-markdown behavior (#502 review) The four MCP markdown-write tools (updatePageMarkdown/createPage/patchNode/ insertNode) still described the old parse-everything behavior after #502 turned TeX math and fuzzy autolink OFF on the write paths. Add a concise contract hint to each: $...$ / $$...$$ stay literal (not a math formula) and schemeless www.host / bare emails are not auto-linked (explicit https:// still links); for a real formula use updatePageJson (or a mathInline/mathBlock node via `node` on patch/insert). Also note getPage format:"text" in README.md/README.ru.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/mcp/README.md | 5 ++++- packages/mcp/README.ru.md | 5 ++++- packages/mcp/src/tool-specs.ts | 24 ++++++++++++++++++++---- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/packages/mcp/README.md b/packages/mcp/README.md index e6c93341..d60409a4 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -118,7 +118,10 @@ All 41 tools, grouped by what you'd reach for them. - **`getPage`** — A page's content as clean **Markdown** (canonical for text; drops only block ids, resolved-comment anchors, and a fixed no-Markdown-representation attr set — table spans/colwidth/background, indent, `callout.icon`, `orderedList.type`, and link - `internal`/`target`/`rel`/`class`; use `getPageJson` when you need those). + `internal`/`target`/`rel`/`class`; use `getPageJson` when you need those). Pass + `format:"text"` for a flat, deterministic plain-text rendering (one line per block, + marks dropped, stable `[image]`/`[table RxC]` placeholders) to machine-diff what you + wrote against what was stored. - **`getPageJson`** — A page's **lossless ProseMirror/TipTap JSON**, including every block's `attrs.id` and the `slugId` used in URLs. This is what the per-block editing tools consume. diff --git a/packages/mcp/README.ru.md b/packages/mcp/README.ru.md index 3b3de41d..574839d6 100644 --- a/packages/mcp/README.ru.md +++ b/packages/mcp/README.ru.md @@ -123,7 +123,10 @@ Docmost-MCP не сочетают: лишь id блоков, якоря разрешённых комментариев и фиксированный набор атрибутов без markdown-представления — спаны/colwidth/фон ячеек таблиц, отступы (indent), `callout.icon`, `orderedList.type` и `internal`/`target`/`rel`/`class` у ссылок; - используйте `getPageJson`, когда они нужны). + используйте `getPageJson`, когда они нужны). Передайте `format:"text"` для плоского + детерминированного plain-text рендера (одна строка на блок, маркировка убрана, + стабильные плейсхолдеры `[image]`/`[table RxC]`) — чтобы machine-diff'ом сверить то, + что вы записали, с тем, что сохранилось. - **`getPageJson`** — **Lossless ProseMirror/TipTap JSON** страницы, включая `attrs.id` каждого блока и `slugId`, используемый в URL. Именно его потребляют инструменты поблочного редактирования. diff --git a/packages/mcp/src/tool-specs.ts b/packages/mcp/src/tool-specs.ts index 9fd57311..c94eba12 100644 --- a/packages/mcp/src/tool-specs.ts +++ b/packages/mcp/src/tool-specs.ts @@ -469,7 +469,11 @@ export const SHARED_TOOL_SPECS = { '(markdown). The fragment may be SEVERAL blocks (a "1 → N" splice: rewrite a ' + 'whole section in one call) — the first block inherits this block id, the ' + 'rest get fresh ids. `^[...]` footnotes are supported (their definitions ' + - "merge into the page's footnote list). REJECTED when the target is a table " + + "merge into the page's footnote list). Markdown is taken LITERALLY — " + + '`$...$`/`$$...$$` are NOT parsed as math and schemeless `www.host` / bare ' + + 'emails are NOT auto-linked (an explicit `https://` URL still links); for a ' + + 'real formula pass a `mathInline`/`mathBlock` ProseMirror node via `node` ' + + '(or updatePageJson). REJECTED when the target is a table ' + 'cell with attributes markdown cannot represent (merged/colored/fixed-width) ' + '— use the table tools or `node`. ' + '`node` (for precise attr/mark work): a raw ProseMirror node, e.g. a ' + @@ -535,6 +539,10 @@ export const SHARED_TOOL_SPECS = { 'Provide EXACTLY ONE of `markdown` or `node`. ' + '`markdown` (RECOMMENDED): a canonical markdown fragment — may be SEVERAL ' + 'blocks, inserted in order at the anchor; `^[...]` footnotes supported. ' + + 'Markdown is taken LITERALLY — `$...$`/`$$...$$` are NOT parsed as math and ' + + 'schemeless `www.host` / bare emails are NOT auto-linked (an explicit ' + + '`https://` URL still links); for a real formula pass a ' + + '`mathInline`/`mathBlock` ProseMirror node via `node` (or updatePageJson). ' + '`node` (for precise attr/mark work OR table structure): a raw ProseMirror ' + 'node. Table structure is JSON-only (not expressible in markdown): to add a ' + 'tableRow, pass a tableRow node with position before/after and anchor INSIDE ' + @@ -1095,8 +1103,12 @@ export const SHARED_TOOL_SPECS = { description: 'Create a new page with a Markdown body in a space, optionally under a ' + 'parent page (omit parentPageId to create at the space root). Returns ' + - 'the new page id and title. Reversible: a page can be moved to trash ' + - 'later.', + 'the new page id and title. Body text is taken LITERALLY — ' + + '`$...$`/`$$...$$` are NOT parsed into a math formula and schemeless ' + + '`www.host` / bare emails are NOT auto-linked (an explicit `https://` URL ' + + 'still links); for a real formula use updatePageJson with ' + + '`mathInline`/`mathBlock` nodes instead. Reversible: a page can be moved ' + + 'to trash later.', tier: 'deferred', catalogLine: 'createPage — create a new page with a Markdown body in a space.', // Reconciled schema DRIFT: the MCP copy pinned `content` to .min(1) while @@ -1355,7 +1367,11 @@ export const SHARED_TOOL_SPECS = { 'title). The whole body is re-imported from the markdown (block ids ' + 'regenerate — for surgical or id-preserving edits use the find/replace, ' + 'node-patch or page-JSON tools instead). Docmost-flavoured markdown is ' + - 'parsed, including `^[...]` inline footnotes. Reversible: the previous ' + + 'parsed, including `^[...]` inline footnotes. Text is taken LITERALLY — ' + + '`$...$`/`$$...$$` are NOT parsed into a math formula and schemeless ' + + '`www.host` / bare emails are NOT auto-linked (an explicit `https://` URL ' + + 'still links); for a real formula use updatePageJson with ' + + '`mathInline`/`mathBlock` nodes instead. Reversible: the previous ' + 'version is kept in page history.', tier: 'deferred', catalogLine: