siyuan-mcp-create-edit

Create and Edit SiYuan Content with MCP

Read the target first, choose the highest-level action that preserves intent, perform one bounded change, then read it again.

Protected writes and readback

For a mutation covered by strict safe writes, call the same action and business arguments with validateOnly=true, use the returned precondition field, and submit the server-issued requestId. Never invent or recycle a hash credential. After the write, reread the exact stable ID or resolved path with enough bounded fields to prove the intended change and continue until the response is complete.

If the connection fails after execution may have started, or the result says outcome_unknown or readback_mismatch, do not retry with a new request ID. Inspect the target and resolve the outcome first. A CLI command, raw MCP payload, or Agent-generated call is not by itself evidence that this coordinator path or its guarantees applied; use the current safety response and runtime help.

Create documents

Use a workspace path for convenient path-based creation:

fs(action="write", path="/Notebook/Project/Notes", markdown="# Notes\n\nInitial content.")

Use a notebook ID plus notebook-local hpath when low-level control is needed:

document(action="create", notebook="<notebook-id>", path="/Project/Notes", markdown="# Notes")

Do not include the notebook name in the low-level hpath.

Edit blocks

block(action="append", parentID="<doc-id>", dataType="markdown", data="## New section\n\nParagraph.")

block(action="insert", previousID="<block-id>", dataType="markdown", data="Inserted paragraph.")

block(action="update", id="<block-id>", dataType="markdown", data="Replacement block content.")

Use block update only when replacing the whole block is intended. Prefer a scoped replacement for a small textual change:

block(action="replace", id="<block-id>", edit={"old":"draft","new":"final"})

Metadata and daily notes