siyuan-mcp

# SiYuan MCP Server A Model Context Protocol (MCP) server for [SiYuan Note](https://b3log.org/siyuan/) with pluggable authentication. Enables AI assistants like Claude to interact with your SiYuan knowledge base through a secure, authenticated API. ## Features - **Full SiYuan Integration**: Read, write, search, and manage documents, blocks, flashcards, and more - **Pluggable Authentication**: - OAuth 2.1 + PKCE via Cloudflare Access (supports Okta, Azure AD, Google, etc.) - Simple API key authentication via `X-SiYuan-Key` header - **Multi-Worker Architecture**: Separate auth and MCP backend for flexibility - **Two Deployment Modes**: - **Cloudflare Workers**: Production deployment with multiple auth options - **CLI (stdio)**: Standalone MCP server for direct Claude Desktop integration - **RAG Support**: Optional vector search integration for semantic document retrieval - **Read-Only Mode**: Configurable restrictions for safe read-only access ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Cloudflare Workers Mode │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ │ │ CF Access Auth (sy.wenri.org)│ │ API Key Auth (api-sy.wenri.org)│ │ │ - OAuth flow (/authorize) │ │ - X-SiYuan-Key validation │ │ │ │ - /download (grant-based) │ │ - /download (stateless) │ │ │ └──────────────┬──────────────┘ └──────────────┬──────────────┘ │ │ │ Service Binding │ Service Binding │ │ └───────────────────┬───────────────┘ │ │ ▼ │ │ ┌───────────────────────────────┐ │ │ │ MCP Backend Worker │ │ │ │ - SiyuanMCP Durable Object │ │ │ │ - Tool execution │ │ │ │ - SiYuan Kernel API calls │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │ CLI Mode (stdio) │ ├─────────────────────────────────────────────────────────────────────────┤ │ Claude Desktop ←──stdio──→ handlers/cli.ts ←──HTTP──→ SiYuan Kernel │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## Available MCP Tools | Tool Category | Tools | |---------------|-------| | **Document Read** | List notebooks, get document tree, read document content, outline | | **Document Write** | Create, rename, move, delete documents | | **Block Operations** | Insert, update, delete, move blocks (with batch support) | | **Search** | Full-text search (`siyuan_find_block`), SQL queries | | **Vector Search** | RAG-based semantic search (requires RAG backend) | | **Daily Notes** | Create and manage daily notes | | **Flashcards** | Create and review flashcards | | **Attributes** | Manage custom attributes on documents/blocks | | **Relations** | Manage block relations | | **Assets** | Upload assets (batch, URL fetch, JSON auto-serialize) | | **File System** | Read/write files, create archives | | **Templates** | Render and manage SiYuan templates | | **Help Docs** | Built-in documentation resources | | **Utilities** | Get time, push notifications, reindex, flush transactions | ## Quick Start ### Option 1: CLI Mode (Local Development) Use stdio transport for direct Claude Desktop integration: ```bash # Clone and install git clone <repo-url> cd mcp_saas npm install # Run with SiYuan kernel URL npx tsx handlers/cli.ts --kernel-url http://localhost:6806 # Or with authentication token npx tsx handlers/cli.ts --kernel-url http://localhost:6806 --token YOUR_TOKEN ``` Add to Claude Desktop (`claude_desktop_config.json`): ```json { "mcpServers": { "siyuan": { "command": "npx", "args": ["tsx", "/path/to/handlers/cli.ts", "--kernel-url", "http://localhost:6806"] } } } ``` ### Option 2: Cloudflare Workers (Production) Deploy multi-worker MCP server to Cloudflare Workers. #### Project Structure ``` workers/ ├── mcp-backend/ # MCP Backend (internal, no public routes) │ ├── index.ts # Entry point, WorkerEntrypoint with RPC methods │ ├── server/ # MCP server core │ │ ├── agent.ts # SiyuanMCP Durable Object │ │ └── index.ts # Server initialization │ └── wrangler.jsonc # DO bindings │ ├── auth-cfaccess/ # CF Access OAuth (sy.wenri.org) │ ├── index.ts # OAuthProvider + RPC forwarding │ ├── access-handler.tsx # Hono app: OAuth flow, consent (JSX) │ └── wrangler.jsonc # KV + service binding │ └── auth-apikey/ # API Key Auth (api-sy.wenri.org) ├── index.ts # Hono app: X-SiYuan-Key validation └── wrangler.jsonc # Service binding ``` #### Deploy MCP Backend (First) ```bash cd workers/mcp-backend wrangler secret put SIYUAN_KERNEL_TOKEN # If SiYuan kernel is behind CF Access: wrangler secret put CF_ACCESS_SERVICE_CLIENT_ID wrangler secret put CF_ACCESS_SERVICE_CLIENT_SECRET npx wrangler deploy ``` #### Deploy CF Access Auth Worker ```bash cd workers/auth-cfaccess # Create KV namespace (one-time) npx wrangler kv namespace create "OAUTH_KV" # Update KV ID in wrangler.jsonc # Set secrets from CF Access SaaS app dashboard wrangler secret put ACCESS_CLIENT_ID wrangler secret put ACCESS_CLIENT_SECRET wrangler secret put ACCESS_TOKEN_URL wrangler secret put ACCESS_AUTHORIZATION_URL wrangler secret put ACCESS_JWKS_URL wrangler secret put COOKIE_ENCRYPTION_KEY # openssl rand -hex 32 npx wrangler deploy ``` #### Deploy API Key Auth Worker ```bash cd workers/auth-apikey wrangler secret put SIYUAN_KERNEL_TOKEN wrangler secret put COOKIE_ENCRYPTION_KEY npx wrangler deploy ``` #### Connect with Claude Desktop **Via OAuth (CF Access):** ```json { "mcpServers": { "siyuan-oauth": { "command": "npx", "args": ["mcp-remote", "https://sy.wenri.org/sse"] } } } ``` **Via API Key:** ```bash claude mcp add siyuan https://api-sy.wenri.org/sse \ -t sse -H "X-SiYuan-Key: YOUR_TOKEN" ``` ## Configuration Reference ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `SIYUAN_KERNEL_URL` | Yes | SiYuan kernel URL | | `SIYUAN_KERNEL_TOKEN` | If auth enabled | SiYuan API token | | `COOKIE_ENCRYPTION_KEY` | Workers mode | For download URL encryption | | `RAG_BASE_URL` | Optional | RAG backend URL for vector search | | `RAG_API_KEY` | Optional | RAG backend API key | | `FILTER_NOTEBOOKS` | Optional | Newline-separated notebook IDs to include | | `FILTER_DOCUMENTS` | Optional | Newline-separated document IDs to include | | `READ_ONLY_MODE` | Optional | `allow_all`, `allow_non_destructive`, or `deny_all` | | `AUTO_APPROVE_LOCAL_CHANGE` | Optional | Auto-approve local change operations | ### CF Access Auth Worker Secrets | Secret | Description | |--------|-------------| | `ACCESS_CLIENT_ID` | From CF Access SaaS app dashboard | | `ACCESS_CLIENT_SECRET` | From CF Access SaaS app dashboard | | `ACCESS_TOKEN_URL` | Token endpoint URL | | `ACCESS_AUTHORIZATION_URL` | Authorization endpoint URL | | `ACCESS_JWKS_URL` | JWKS endpoint URL | ### CLI Options ``` Options: -u, --kernel-url <url> SiYuan kernel URL (required) -t, --token <token> SiYuan API token --rag-url <url> RAG backend URL --rag-key <key> RAG API key --filter-notebooks <ids> Notebook IDs to filter (newline-separated) --filter-documents <ids> Document IDs to filter (newline-separated) --read-only <mode> Read-only mode: allow_all, allow_non_destructive, deny_all -h, --help Show help message ``` ## API Endpoints ### OAuth Auth Worker (sy.wenri.org) - `GET /authorize` - Initiate OAuth flow - `GET /callback` - OAuth callback, consent page - `POST /callback` - Complete authorization - `POST /token` - Token endpoint - `POST /register` - Dynamic client registration - `GET /.well-known/oauth-authorization-server` - OAuth metadata - `POST /mcp`, `GET /sse` - MCP endpoints (forwarded to backend via RPC) - `GET /download/*` - File downloads (grant-based validation) ### API Key Auth Worker (api-sy.wenri.org) - `POST /mcp`, `GET /sse` - MCP endpoints (X-SiYuan-Key required, forwarded via RPC) - `GET /download/*` - File downloads (stateless validation) ## Development ```bash # Install dependencies npm install # Local development - start each worker separately cd workers/mcp-backend && npx wrangler dev # http://localhost:8787 cd workers/auth-cfaccess && npx wrangler dev # http://localhost:8788 cd workers/auth-apikey && npx wrangler dev # http://localhost:8789 # Run tests npm test # Deploy (order matters: backend first) cd workers/mcp-backend && npx wrangler deploy cd workers/auth-cfaccess && npx wrangler deploy cd workers/auth-apikey && npx wrangler deploy ``` ## Testing ### MCP Inspector ```bash npx @modelcontextprotocol/inspector@latest # Connect to deployed URL or localhost ``` ### Manual Testing ```bash # Test OAuth discovery curl https://sy.wenri.org/.well-known/oauth-authorization-server # Test API key auth curl -X POST https://api-sy.wenri.org/mcp \ -H "X-SiYuan-Key: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' ``` ## Security - **OAuth 2.1 + PKCE**: Prevents authorization code interception - **Cloudflare Access**: Enterprise identity provider support - **Service Bindings**: Internal worker communication (no public routes for backend) - **Durable Objects**: Session state with SQLite storage - **Download URL Encryption**: Time-bound, path-bound download tokens - **Read-Only Mode**: Optional restriction of write operations ## Troubleshooting ### Common Issues **"SIYUAN_KERNEL_URL not configured"** - Set `SIYUAN_KERNEL_URL` in wrangler.jsonc vars **"Failed to get SiYuan config"** - Verify SiYuan kernel is running and accessible - Check `SIYUAN_KERNEL_TOKEN` if authentication is enabled **"Unauthorized: Missing auth context"** - MCP backend requires auth headers from auth workers - Cannot be accessed directly; use auth worker endpoints **"Invalid or expired state"** - OAuth state expired (10 min timeout) - Verify KV namespace is configured correctly **Tool not appearing** - Check `READ_ONLY_MODE` setting - Verify tool annotations allow current mode ## License MIT