| name | siyuan-mcp-browse-read |
| description | MCP playbook for browsing and reading SiYuan notes. Use for notebooks, document trees, human-readable paths, IDs, storage paths, block content, and read-only discovery. |
Browse and Read SiYuan with MCP
Start with fs and human-readable paths. Drop to document or block actions only when IDs, storage paths, metadata, or block structure are required.
Discovery workflow
notebook(action="list")
fs(action="ls", path="/")
fs(action="tree", path="/Notebook/Folder", maxDepth=4)
fs(action="read", path="/Notebook/Folder/Doc", page=1, pageSize=8000)
Use search-assisted discovery when the path is unknown:
fs(action="search", path="/Notebook", query="keyword", page=1, pageSize=20)
search(action="fulltext", query="keyword", page=1, pageSize=20)
Low-level reads
document(action="lookup", id="<doc-id>", include=["path","hpath","notebook"])
document(action="get_doc", id="<doc-id>", mode="markdown")
block(action="get_kramdown", id="<block-id>")
Path semantics
| Value | Example | Typical use |
|---|
| Workspace path | /Notebook/Folder/Doc | fs actions |
| Notebook-local hpath | /Folder/Doc | document create or lookup with notebook |
| Storage path | /20260712123000-abc123.sy | low-level rename, remove, or move |
Never derive a storage path from a title. Resolve the document first and reuse the returned path. Treat pages and truncation notices as incomplete data, and continue with explicit page and pageSize values.
