SiYuan Sisyphus MCP & CLI Docs

Latest: v0.7.0. Safe-write preflight now shows a write-impact preview; query_sql runs in a restricted, notebook-scoped mode when some notebooks are unreadable; reads return ifMatch, with an optional low-risk one-step write mode (off by default); document create supports batch docs. Includes many fixes from multi-round AI usability testing. CLI is now v0.3.0. See the changelog for earlier releases.

Highlights

• Notebook-level permissions. Every notebook is none, r, rw or rwd, and risky actions such as delete, move and replace have their own switches.
• Strict safe writes. A write is checked against the target's current-state hash, committed once and read back. Nothing is retried blindly.
• A document timeline for AI edits. Take a node before the agent starts, compare it with the current document, and roll back the whole document or a single block.
• Small context, broad coverage. More than 100 SiYuan capabilities sit behind 14 action-routed tools. Detailed help and Skills load only when needed.
• Human-readable paths. fs works with paths like /Notebook/Project/Note, so agents do not need to know block IDs or the document tree.
• MCP Apps. Flashcard review, the document timeline and the mascot shop open inside the conversation, and the user makes the final click.
• The official MCP ecosystem. extension bridges SiYuan's official /mcp, so tools registered by other plugins appear in the same session.
• MCP and CLI share one core. A tool behaves the same whether an agent calls it over MCP or a script runs it from the terminal.

Quick start

1. Install SiYuan Sisyphus from the SiYuan marketplace. The plugin runs on SiYuan 2.9.0+; the official MCP bridge and the kernel endpoint need SiYuan 3.7.0+.
2. Open the plugin settings, go to Connection Config → MCP Connection, pick your client and transport, then copy the generated config. Presets cover Claude Code, Codex CLI, Cursor, Cherry Studio, Kimi Code, OpenCode, CC Switch and DSH.
3. Start with a read-only request such as "List my SiYuan notebooks".

Prefer the terminal? The CLI runs the same tools directly and keeps their schemas out of the model's context:

npm i -g siyuan-sisyphus
siyuan-sisyphus init                       # SiYuan API URL and token
siyuan-sisyphus notebook list
siyuan-sisyphus document list-tree --notebook <id> --json

Local, remote, Docker, HTTPS and mobile setups are covered in Getting Started and Deployment.

You stay in control

Notebook permissions

Level	Read	Write	Delete
rwd	✓	✓	✓
rw	✓	✓
r	✓
none

Documents inherit their notebook's level. Notebooks without an entry are read-only, and notebooks created after installation start at rwd. The badge beside each notebook in the file tree shows its level; click it to cycle through the levels.

Strict safe writes

Strict safe writes are on by default (Settings & Debug → Strict safe writes).

• A mutation first runs with validateOnly=true to get the target's current-state hash. The commit then carries the server-issued requestId and the matching expected*Hash.
• A write is sent once. A timeout or a dropped connection returns outcome_unknown instead of risking a duplicate, and a committed requestId replays from the ledger.
• No SiYuan data snapshots are created. Side effects that cannot be read back, such as sync, exports, notifications and third-party tools, are marked as not strictly guaranteed.
• The CLI and stdio forward strict writes to a single coordinator: the plugin's HTTP server, or the kernel endpoint when it is enabled (the option for Docker and browser setups).

Dangerous actions such as deletes, moves, replacements and asset uploads need explicit confirmation. Clients that support MCP elicitation confirm them in a form before anything is sent; other clients keep the confirm=true convention. See Strict Safe Writes and Permissions.

Review and roll back with the document timeline

• Create a document node before handing a document to an agent, or a global node that every document can see.
• Select a node to open Document Diff, with unified and split views, word-level highlights, folded unchanged blocks and a change minimap.
• Roll back the whole document or restore a single block.
• Deleting a node removes only its protective tag. The underlying SiYuan snapshot stays.

Agents get the same workflow through the timeline tool. Deleting nodes and rolling back are high-risk and disabled for AI by default. The timeline is built on SiYuan's workspace snapshots, so it is a safety net rather than a full Git replacement.

MCP Apps in the conversation

Clients that negotiate io.modelcontextprotocol/ui get three launcher tools, each opening an inline App.

App	Launcher	What happens
Flashcard review	flashcard_review_session	The agent picks 1–20 due cards. You reveal each answer and rate it Again, Hard, Good or Easy.
Document timeline	timeline_app	Browse and create nodes, inspect the block diff, and restore the document or one block.
Mascot shop	mascot_shop_app	Spend the coins the mascot earns from tool calls. Picking up an item feeds the desktop mascot.

• Only the launcher opens an App. Ordinary flashcard, timeline and mascot calls remain data tools.
• The agent prepares the round and you make the decisions. The model never answers cards, picks ratings, rolls back notes or buys items for you.
• App actions are hidden from the model with visibility: ["app"] and are enabled one by one under Settings → MCP Apps.
• Clients without MCP Apps support see none of this. Aggregate tools and the CLI work as before.

Works with SiYuan's official MCP

On SiYuan 3.7.0+, extension reads the official /mcp registry and turns each allowed tool into an action. Downstream arguments stay inside arguments, so a tool's own action field never collides with Sisyphus routing:

{ "action": "plugin__example__search", "arguments": { "action": "query", "keyword": "MCP" } }

Tool source	Default	Security boundary
Sisyphus aggregate tools	On	Notebook permissions, action switches and strict safe writes
Tools registered by other plugins	On	Discovered by extension; each tool keeps its own permission semantics
Native SiYuan MCP tools	Off	Run with the administrator session or API token

Discovery is lazy and version-gated: below SiYuan 3.7.0, /mcp is never requested, and when it is unavailable only the dynamic actions disappear. The tool settings page lists every discovered tool with its source, schema size and risk, and any of them can be turned off. Plugin developers only need to register a tool with SiYuan's official MCP; Sisyphus finds it there without a separate adapter. Details are in the extension reference.

Security note: tools from other plugins and native SiYuan tools do not pass through Sisyphus notebook permissions or dangerous-action controls. Enable native tools only for local, fully trusted clients.

How it works

Everything Sisyphus owns, including fs, document tools, the timeline, permissions and the CLI, talks to SiYuan only through /api/*, so it works the same on desktop, Docker and remote setups. /mcp is used only by extension.

• MCP over HTTP, stdio or the kernel endpoint suits agents that discover tools and chain multi-step work.
• The CLI suits scripts and one-shot tasks.

The server speaks MCP 2026-07-28 (stateless HTTP with per-request metadata) and keeps session-based support for 2025-era clients; see protocol compatibility.

Skills for agents

Sisyphus ships scenario guides for browsing, editing, search, databases, exports, tags, flashcards, the timeline, system safety and SiYuan markup. MCP clients read siyuan://skills/index and load siyuan://skills/{name} on demand. The same guides are published through the draft SEP-2640 Skills over MCP extension. Agents that install SKILL.md packages can copy them locally:

siyuan-sisyphus skill install --bundle mcp   # MCP calling conventions
siyuan-sisyphus skill install --bundle all   # MCP and CLI bundles

A Codex agent plugin wrapper lives in agent-plugin/siyuan-sisyphus. More in Scenario Skills and MCP Prompts.

Project direction

I built Sisyphus because I wanted my own SiYuan notes to connect naturally with external AI agents. Now that SiYuan provides an official MCP implementation, I am glad to see a shared ecosystem taking shape. As one plugin developer in that ecosystem, I want Sisyphus to keep its existing workflows, embrace official MCP and work alongside other plugins to make the connection between SiYuan and external agents smoother and more reliable.

Next, the project focuses on connection setup and compatibility across popular agents; HTTP, stdio, local, remote and Docker deployments; discovery and schema size of official MCP tools; clearer call status, errors and recovery; and task-oriented Skills, help and real-world validation.

Feedback

Bug reports, experience notes and design ideas are all welcome:

• GitHub Issues for public discussion.
• The built-in feedback tool: an agent can call feedback(action="submit", description="...").

Please leave out API tokens, secrets, private note content and local paths.

Documentation

Getting Started · Common Tasks · Tool Reference · Permissions · Strict Safe Writes · Development

❤️ Contributors

Made with contrib.rocks.

Support

If Sisyphus helps you, please consider supporting it. Sponsorship keeps maintenance and agent integration work going.

Thanks to undefined, Fngd Z, ou, 米建, 锋🌀☁️, wooh, 芝士柴犬 and every other supporter.

License

MIT