siyuan-mcp-server

# siyuan-mcp-server    A lightweight SiYuan MCP Server based on the [official Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk), providing structured daily note read and write capabilities for AI Agents through the official SiYuan CLI. ## Project Overview `siyuan-mcp-server` is designed for users who want to maintain local SiYuan notes through Codex, VS Code, or other MCP clients. It encapsulates common search, read, create, append, and update operations as clearly parameterized MCP tools, allowing Agents to avoid manually constructing CLI commands and eliminating the need to read SiYuan API tokens or complete configurations. The MCP service layer is built using the official `@modelcontextprotocol/sdk`, adopting a local stdio communication method with `McpServer + StdioServerTransport`. This project does not reimplement the SiYuan storage layer, does not start an additional HTTP service, and does not directly modify `.sy` files. It only provides a lightweight adaptation layer between the MCP client and the user's installed SiYuan CLI. The current version primarily targets personal daily note workflows. The `standard` configuration is recommended; the complete management toolset is retained in the explicitly enabled `full` configuration. ## Core Features - Connects to MCP-enabled AI Agents via stdio - Searches and reads notebooks, documents, blocks, outlines, and backlinks - Creates documents, appends, inserts, and updates content blocks - Applies confirmed block modifications in batches - Replaces entire document bodies while preserving document IDs - Appends Markdown to daily notes - Controls tool exposure using `minimal`, `standard`, and `full` configurations - Explicitly enables write permissions and dangerous operations - Validates Markdown, inline formulas, and structured parameters - Audit logs do not store Markdown content - Supports Windows, macOS, and Linux in a single npm package ## Technical Implementation | Layer | Technology | Purpose | | --- | --- | --- | | Language | TypeScript | MCP Server and tool implementation | | Runtime | Node.js 18+ | stdio service and CLI subprocess | | MCP | [Official TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) (`@modelcontextprotocol/sdk`) | Server, tool registration, schema, and protocol communication | | Input Validation | Zod | Parameter, Markdown, and permission validation | | Testing | Vitest | Unit testing and tool behavior verification | | Upstream Backend | SiYuan CLI | Actual data access to local SiYuan workspace | Core call chain: ```text AI Agent → MCP stdio → siyuan-mcp-server → SiYuan CLI --format json → Local SiYuan workspace ``` The MCP Server uses the official SDK's `McpServer` to register tools, communicates with local MCP clients via `StdioServerTransport`, and handles tool discovery, parameter validation, permission control, CLI parameter construction, result normalization, and write auditing; the SiYuan CLI is responsible for actual data access. ### Design Boundaries - Does not provide arbitrary CLI command execution tools. - Does not directly call the local SiYuan HTTP API. - Does not read or return API tokens, sync keys, or complete configurations. - Does not include `SiYuan-Kernel` in the npm package. - Ordinary writes do not automatically increase full reads, snapshots, or rollbacks. - Multi-step writes explicitly report non-transactional behavior and partial execution progress. See the [architecture document](docs/architecture.md) for more design details. ## Usage Requirements - Node.js 18 or higher - SiYuan notes with a command-line interface - A local SiYuan workspace - A client that supports stdio MCP Server Verify SiYuan CLI availability: ```bash siyuan --help ``` If the system cannot find `siyuan`, set `SIYUAN_MCP_CLI_PATH` to the absolute path of `SiYuan-Kernel`. CLI commands and parameters follow the [official SiYuan project](https://github.com/siyuan-note/siyuan) and the current installed version's help. ## Installation ### Install from GitHub Release Download the `.tgz` file from the project's [Releases](https://github.com/William-Herly/siyuan-mcp-server/releases) page: ```bash npm install -g ./siyuan-mcp-server-1.0.1.tgz ``` The executable command after installation is: ```bash siyuan-mcp-server ``` Installing a new version will overwrite the current global version, and there is no need to uninstall it first. Restart the MCP client after upgrading. ### Install from Source ```bash git clone https://github.com/William-Herly/siyuan-mcp-server.git cd siyuan-mcp-server npm install npm run build npm install -g . ``` ## Quick Start Daily read and write operations are recommended with the `standard` configuration: ```json { "mcpServers": { "siyuan": { "command": "siyuan-mcp-server", "env": { "SIYUAN_MCP_WORKSPACE": "E:/SiYuan Data", "SIYUAN_MCP_CLI_PATH": "siyuan", "SIYUAN_MCP_PROFILE": "standard", "SIYUAN_MCP_ALLOW_WRITE": "true" } } } } ``` The outermost configuration format may vary for different clients, but the `command` and `env` contents remain consistent. Save the configuration and restart the MCP client completely, then let the Agent execute: ```text Check SiYuan MCP status, list notebooks, and search an existing note. ``` The expected result is that the Agent prioritizes discovering `siyuan_*` tools and accesses the SiYuan workspace through this project. If running directly from the source, change the command to: ```json { "command": "node", "args": ["F:/siyuan-mcp-server/dist/index.js"] } ``` Windows JSON paths should use forward slashes. ## Configuration | Environment Variable | Required | Default Value | Description | | --- | --- | --- | --- | | `SIYUAN_MCP_WORKSPACE` | Recommended | Parsed by CLI | Absolute path to SiYuan workspace | | `SIYUAN_MCP_CLI_PATH` | No | `siyuan` | `siyuan` command or absolute path to `SiYuan-Kernel` | | `SIYUAN_MCP_PROFILE` | No | `minimal` | `minimal`, `standard`, or `full` | | `SIYUAN_MCP_ALLOW_WRITE` | On write | `false` | Set to `true` to allow ordinary writes | | `SIYUAN_MCP_ALLOW_DANGEROUS` | On dangerous operations | `false` | Set to `true` to allow dangerous operations | | `SIYUAN_MCP_LOG_DIR` | No | `<cwd>/.siyuan-mcp/logs` | Audit log directory | | `SIYUAN_MCP_TIMEOUT_MS` | No | `30000` | CLI timeout in milliseconds | Common kernel paths: - Windows: `SiYuan-Kernel.exe` in the SiYuan installation directory's `resources/kernel` - macOS: `/Applications/SiYuan.app/Contents/Resources/kernel/SiYuan-Kernel` - Linux: `<SiYuan installation directory>/resources/kernel/SiYuan-Kernel` ### Tool Configuration | Configuration | Applicable Scenarios | Tool Range | Write Permissions | | --- | --- | --- | --- | | `minimal` | Read-only queries | Minimal read, search, and reference tools | No write permissions | | `standard` | Daily note maintenance | Adds create, diary, and content update tools | Requires `SIYUAN_MCP_ALLOW_WRITE=true` | | `full` | Advanced management and development | All implemented tools | Ordinary writes and dangerous operations authorized separately | `maintain` and `note-maintain` are compatible aliases for `standard`. `organize`, `advanced`, and `admin` are compatible aliases for `full`; new configurations should use the formal names. Do not set `SIYUAN_MCP_ALLOW_DANGEROUS=true` as a daily default. ## Common Tasks | Task | Recommended Tool | | --- | --- | | Search documents | `siyuan_document_search` | | Read entire documents | `siyuan_get_document_kramdown` | | Read related blocks | `siyuan_get_block_kramdown`, `siyuan_batch_get_kramdown` | | Create documents | `siyuan_create_document` | | Append or insert content | `siyuan_append_block`, `siyuan_insert_block` | | Update a block | `siyuan_update_block` | | Apply multiple block modifications | `siyuan_patch_blocks` | | Replace entire document body | `siyuan_replace_document_body` | | Append daily notes | `siyuan_append_daily_note` | See the [tool reference](docs/tool-coverage.md) for the complete tool list and parameter semantics. ## Write Semantics Ordinary writes are lightweight: - Creation, appending, and insertion return results directly after success. - Single block updates may generate new block IDs, and tools will prompt the Agent to re-read before continuing to rely on the old ID. - Batch patches include updates or deletions that return `requiresRefresh: true`. - Entire document body replacements preserve document IDs but are non-transactional multi-step operations. - Entire replacements return deletion counts, append status, commit hashes, and placeholder block cleanup results. - Automated tests can explicitly re-read critical writes, but daily tools do not enforce this. SiYuan inline formulas use `$...$`. fenced code blocks, indented code blocks, and inline code with `$` are treated literally and do not participate in formula validation. ## Security and Data Boundaries - The default configuration is read-only. - Write and dangerous operations are authorized separately. - CLI uses parameter arrays to call without shell-splicing user input. - Markdown content in audit logs is replaced with length, byte count, and SHA-256. - Error messages should not contain authentication headers or sensitive SiYuan configurations. - `notes/`, logs, test reports, build results, and installation packages are not submitted to Git. When submitting issues, do not attach real note content, workspace data, access credentials, or unanonymized logs. ## Development and Testing ```bash npm install npm run build npm test ``` Local development: ```bash npm run dev ``` Run `standard` integration tests in an independent test notebook: ```powershell $env:SIYUAN_TEST_WORKSPACE = "E:\SiYuan Data" $env:SIYUAN_TEST_NOTEBOOK_ID = "notebook-id" npm run test:standard ``` Integration tests create test documents and append unique markers to diaries; they should not be run in important notebooks. See the [testing guide](docs/testing.md) for detailed instructions. ## Project Structure ```text src/ MCP Server, tool registration, CLI encapsulation, and auditing tests/ Unit tests scripts/ Startup scripts and standard integration tests docs/ Public documentation for users and developers notes/ Local development process records, not submitted to Git dist/ TypeScript build output, not submitted to Git ``` ## Documentation and Support - [Tool Reference](docs/tool-coverage.md) - [Architecture Design](docs/architecture.md) - [Testing Guide](docs/testing.md) - [Issue Feedback](https://github.com/William-Herly/siyuan-mcp-server/issues) ## Contribution Contributions are welcome for bug fixes, compatibility improvements, tests, and documentation modifications. For larger tool range or write semantic changes, suggest creating an issue to describe the usage scenario first. Before submitting code, run at least: ```bash npm run build npm test ``` ## License This project is licensed under the [MIT License](LICENSE).