siyuan-cli 1.1.0__tar.gz

siyuan_cli-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xingrove
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

siyuan_cli-1.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: siyuan-cli
+Version: 1.1.0
+Summary: CLI tool + MCP server + Agent Skills for SiYuan Note (思源笔记) — zero deps, permission system, workspace management
+Author: Mino
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xingrove/siyuan-skills
+Project-URL: Repository, https://github.com/xingrove/siyuan-skills
+Keywords: siyuan,思源笔记,notes,markdown,pkm,self-hosted,agent-skills
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Editors :: Documentation
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# SiYuan Agent Tools
+
+[![PyPI](https://img.shields.io/pypi/v/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![CI](https://github.com/xingrove/siyuan-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/xingrove/siyuan-skills/actions)
+[![Python](https://img.shields.io/pypi/pyversions/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![License](https://img.shields.io/pypi/l/siyuan-cli)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-229%20passed-brightgreen)](https://github.com/xingrove/siyuan-skills)
+
+> [中文](README.md)
+
+CLI tool, MCP server, and AI Agent Skills for [SiYuan Note](https://github.com/siyuan-note/siyuan). Pure Python, zero dependencies. Compatible with Claude Code, Codex, OpenCode, and Hermes.
+
+---
+
+## Install
+
+```bash
+pip install siyuan-cli
+```
+
+Or the one-command installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xingrove/siyuan-skills/main/scripts/install.sh | bash
+```
+
+---
+
+## Quick Start
+
+```bash
+siyuan config url http://127.0.0.1:6806
+siyuan config token your-api-token
+
+siyuan stats          # verify connectivity
+```
+
+> Token location: SiYuan Desktop → Settings → API; for Docker, in `conf.json`.
+
+---
+
+## CLI Reference
+
+### Documents & Blocks
+
+| Command | Description |
+|---------|-------------|
+| `siyuan create /path [content]` | Create a note (`--file` / `--stdin` supported) |
+| `siyuan read /path` | Read document content |
+| `siyuan delete /path [--id]` | Delete a note |
+| `siyuan tree [notebook]` | Document tree |
+| `siyuan doc rename <title>` | Rename document |
+| `siyuan doc move <paths...> [--to-notebook]` | Move documents |
+| `siyuan doc export /path [--id]` | Export as Markdown |
+| `siyuan doc get-path <id>` | Resolve ID to path |
+
+### Block Operations
+
+| Command | Description |
+|---------|-------------|
+| `siyuan block get <id>` | Block info |
+| `siyuan block children <id>` | Child blocks |
+| `siyuan block append <id> -c <content>` | Append child block |
+| `siyuan block prepend <id> -c <content>` | Prepend child block |
+| `siyuan block insert <id> -c <content>` | Insert block after sibling |
+| `siyuan block update <id> -c <content>` | Update block |
+| `siyuan block delete <id>` | Delete block |
+| `siyuan block move <id> --parent <pid>` | Move block |
+| `siyuan block fold <id>` | Fold heading |
+| `siyuan block unfold <id>` | Unfold |
+
+### Block References & Embeds
+
+| Command | Output | Description |
+|---------|--------|-------------|
+| `siyuan block ref <id>` | `((id 'title'))` | Block reference markup |
+| `siyuan block embed <id>` | `{{embed ((id 'title'))}}` | Block embed markup |
+| `siyuan block link <id>` | `siyuan://blocks/id` | SiYuan internal link |
+
+```bash
+REF=$(siyuan block ref 20200812220555-lj3enxa)
+siyuan create "/article" "As mentioned in $REF..."
+```
+
+### Notebooks, Search & Daily Notes
+
+| Command | Description |
+|---------|-------------|
+| `siyuan notebook list` | List notebooks |
+| `siyuan notebook create <name>` | Create notebook |
+| `siyuan notebook remove <id>` | Remove notebook |
+| `siyuan notebook rename <id> <name>` | Rename |
+| `siyuan notebook conf <id>` | Notebook config |
+| `siyuan search <query>` | Full-text search |
+| `siyuan sql <statement>` | SQL query (SELECT only) |
+| `siyuan daily-note note` | Get or create today's note |
+| `siyuan daily-note append <content>` | Append to today's note |
+
+### Tags, Attributes & Assets
+
+| Command | Description |
+|---------|-------------|
+| `siyuan tag list` | All tags |
+| `siyuan tag blocks <tag>` | Find tagged blocks |
+| `siyuan attr get <id>` | Block attributes |
+| `siyuan attr set <id> <key> <val>` | Set attribute |
+| `siyuan asset upload <file>` | Upload asset |
+| `siyuan file list /data/` | List workspace files |
+| `siyuan file put <local> <remote>` | Upload file |
+
+### Batch & Utilities
+
+| Command | Description |
+|---------|-------------|
+| `siyuan batch create <file>` | Batch create notes |
+| `siyuan batch delete <file>` | Batch delete notes |
+| `siyuan stats` | Workspace statistics |
+| `siyuan overview` | Workspace overview |
+| `siyuan health` | Diagnostic health check |
+| `siyuan backlinks get <id>` | Block backlinks |
+| `siyuan notify push <msg>` | Push notification to UI |
+| `siyuan mcp` | Start MCP server |
+
+---
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--format pretty\|json\|compact` | Output format |
+| `--verbose` | Detailed logging |
+| `--no-color` | Disable colored output |
+| `--version` | Show version |
+| `--yes` | Skip confirmation on destructive ops |
+| `--dry-run` | Preview without applying |
+| `@file:/path` | Read content from file |
+| `@stdin` | Read content from stdin |
+
+**Read-only mode:** `SIYUAN_READ_ONLY=true siyuan <cmd>` blocks all writes.
+
+---
+
+## Multi-Server
+
+```bash
+siyuan workspace add hk --url http://server:6806 --token xxx
+siyuan workspace use hk
+siyuan workspace list
+```
+
+---
+
+## Permission System
+
+```bash
+siyuan permission deny --endpoint "*remove*"   # Block all deletes
+siyuan permission ask --endpoint "*delete*"    # Ask before delete
+siyuan permission list                          # Show rules
+```
+
+---
+
+## MCP Server
+
+```bash
+siyuan-mcp
+```
+
+23 tools: CRUD, search, SQL, block refs/embeds, tags, attributes, health checks. Works with Claude Desktop, Cursor, and any MCP client.
+
+---
+
+## Agent Skills
+
+| Agent | Install |
+|-------|---------|
+| **OpenCode** | `git clone https://github.com/xingrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills` |
+| **Codex CLI** | `cp -r skills/* ~/.codex/skills/` |
+| **Hermes** | `cp -r skills/* ~/.hermes/skills/` |
+| **npx** | `npx skills add https://github.com/xingrove/siyuan-skills` |
+
+| Skill | Description |
+|-------|-------------|
+| [siyuan-cli](skills/siyuan-cli) | Operate SiYuan via CLI |
+| [siyuan-api](skills/siyuan-api) | Direct REST API calls |
+| [siyuan-markdown](skills/siyuan-markdown) | SiYuan-flavored Markdown reference |
+
+---
+
+## Configuration
+
+Priority: `SIYUAN_URL` / `SIYUAN_TOKEN` env vars > active workspace > `~/.siyuan/config.json`
+
+```json
+{"url": "http://127.0.0.1:6806", "token": "your-token"}
+```
+
+Optional keyring storage:
+
+```bash
+pip install keyring
+siyuan keyring-set your-token
+siyuan keyring-unset
+```
+
+---
+
+*Community project, not official.*

siyuan_cli-1.1.0/README.md

@@ -0,0 +1,239 @@
+# SiYuan Agent Tools
+
+[![PyPI](https://img.shields.io/pypi/v/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![CI](https://github.com/xingrove/siyuan-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/xingrove/siyuan-skills/actions)
+[![Python](https://img.shields.io/pypi/pyversions/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![License](https://img.shields.io/pypi/l/siyuan-cli)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-229%20passed-brightgreen)](https://github.com/xingrove/siyuan-skills)
+
+> [English](README_EN.md)
+
+面向**思源笔记**的 CLI 工具 + MCP 服务器 + AI Agent 技能包。纯 Python 实现，零依赖，兼容 Claude Code、Codex、OpenCode、Hermes 等 AI 编程助手。
+
+---
+
+## 安装
+
+```bash
+pip install siyuan-cli
+```
+
+或一键安装脚本：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xingrove/siyuan-skills/main/scripts/install.sh | bash
+```
+
+---
+
+## 快速上手
+
+```bash
+siyuan config url http://127.0.0.1:6806
+siyuan config token 你的API令牌
+
+siyuan stats          # 验证连接是否正常
+```
+
+> Token 获取：思源桌面端 → 设置 → API；Docker 部署的在 `conf.json` 里。
+>
+> ⚠️ **Windows 用户**：git-bash / MSYS 下路径会被自动翻译，请加前缀：
+> ```bash
+> MSYS_NO_PATHCONV=1 siyuan create /path/to/doc
+> ```
+
+---
+
+## 命令参考
+
+### 笔记操作
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan create /路径 [内容]` | 创建笔记（支持 `--file` / `--stdin`） |
+| `siyuan read /路径` | 读取内容 |
+| `siyuan delete /路径 [--id]` | 删除笔记 |
+| `siyuan tree [笔记本]` | 文档树 |
+
+**扩展模式** (`siyuan doc`):
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan doc create /路径 [内容]` | 创建 |
+| `siyuan doc read /路径` | 读取 |
+| `siyuan doc delete /路径` | 删除 |
+| `siyuan doc tree [笔记本]` | 文档树 |
+| `siyuan doc rename <标题>` | 重命名 |
+| `siyuan doc move <路径...> [--to-notebook]` | 移动 |
+| `siyuan doc export /路径 [--id]` | 导出 Markdown |
+| `siyuan doc get-path <id>` | ID 查路径 |
+
+### 块操作
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan block get <id>` | 块信息 |
+| `siyuan block children <id>` | 子块列表 |
+| `siyuan block append <id> -c <内容>` | 追加子块 |
+| `siyuan block prepend <id> -c <内容>` | 前置子块 |
+| `siyuan block insert <id> -c <内容>` | 插入块 |
+| `siyuan block update <id> -c <内容>` | 更新块 |
+| `siyuan block delete <id>` | 删除块 |
+| `siyuan block move <id> --parent <pid>` | 移动块 |
+| `siyuan block fold <id>` | 折叠标题 |
+| `siyuan block unfold <id>` | 展开块 |
+
+### 块引用 & 嵌入
+
+| 命令 | 输出 | 说明 |
+|------|------|------|
+| `siyuan block ref <id>` | `((id '标题'))` | 生成块引用标记 |
+| `siyuan block embed <id>` | `{{embed ((id '标题'))}}` | 生成块嵌入标记 |
+| `siyuan block link <id>` | `siyuan://blocks/id` | 生成思源内部链接 |
+
+```bash
+REF=$(siyuan block ref 20200812220555-lj3enxa)
+siyuan create "/文章" "如上文 $REF 所述..."
+```
+
+### 笔记本管理
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan notebook list` | 列表 |
+| `siyuan notebook create <名称>` | 创建 |
+| `siyuan notebook remove <id>` | 删除 |
+| `siyuan notebook rename <id> <名称>` | 重命名 |
+| `siyuan notebook conf <id>` | 查看配置 |
+
+### 搜索
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan search <关键词>` | 全文搜索 |
+| `siyuan sql <SELECT 语句>` | SQL 查询 blocks 表 |
+
+### 每日笔记 & 标签
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan daily-note note` | 获取/创建今日笔记 |
+| `siyuan daily-note append <内容>` | 追加到今日笔记 |
+| `siyuan tag list` | 所有标签 |
+| `siyuan tag blocks <标签>` | 查找带标签的块 |
+| `siyuan attr get <id>` | 获取块属性 |
+| `siyuan attr set <id> <键> <值>` | 设置块属性 |
+
+### 文件 & 资源
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan file list /data/` | 列出文件 |
+| `siyuan file get /路径` | 获取内容 |
+| `siyuan file put <本地> <远程>` | 上传 |
+| `siyuan asset upload <文件>` | 上传资源 |
+
+### 批量 & 其他
+
+| 命令 | 说明 |
+|------|------|
+| `siyuan batch create <文件>` | 批量创建 |
+| `siyuan batch delete <文件>` | 批量删除 |
+| `siyuan stats` | 工作空间统计 |
+| `siyuan overview` | 工作空间概览 |
+| `siyuan health` | 诊断健康检查 |
+| `siyuan notify push <消息>` | 推送通知到 UI |
+| `siyuan backlinks get <id>` | 反向链接 |
+| `siyuan mcp` | 启动 MCP 服务 |
+
+---
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--format pretty\|json\|compact` | 输出格式（默认为 pretty） |
+| `--verbose` | 详细日志（含缓存命中/失效信息） |
+| `--no-color` | 禁用颜色输出 |
+| `--version` | 显示版本号 |
+| `--yes` | 跳过破坏性操作确认 |
+| `--dry-run` | 预览操作但不执行 |
+| `@file:/path` | 从文件读取内容 |
+| `@stdin` | 从标准输入读取内容 |
+
+**只读模式**：`SIYUAN_READ_ONLY=true siyuan <命令>` 阻止所有写操作。
+
+---
+
+## 多服务器
+
+```bash
+siyuan workspace add 香港 --url http://server:6806 --token xxx
+siyuan workspace use 香港
+siyuan workspace list
+```
+
+---
+
+## 权限控制
+
+控制 AI Agent 能做什么：
+
+```bash
+siyuan permission deny --endpoint "*remove*"   # 禁止删除操作
+siyuan permission ask --endpoint "*delete*"    # 删除前询问确认
+siyuan permission list                          # 查看规则
+```
+
+---
+
+## MCP 服务器
+
+```bash
+siyuan-mcp
+```
+
+提供 23 个工具：CRUD、搜索、SQL、块引用/嵌入、标签管理、权限、健康检查。兼容 Claude Desktop、Cursor 等 MCP 客户端。
+
+---
+
+## AI Agent 集成
+
+安装技能到你的 Agent：
+
+| Agent | 安装命令 |
+|-------|---------|
+| **OpenCode** | `git clone https://github.com/xingrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills` |
+| **Codex CLI** | `cp -r skills/* ~/.codex/skills/` |
+| **Hermes** | `cp -r skills/* ~/.hermes/skills/` |
+| **npx** | `npx skills add https://github.com/xingrove/siyuan-skills` |
+
+安装后 Agent 可读笔记、写笔记、搜索、分析、块引用/嵌入、批量操作、管理标签。
+
+| 技能 | 说明 |
+|------|------|
+| [siyuan-cli](skills/siyuan-cli) | 通过 CLI 操作思源笔记 |
+| [siyuan-api](skills/siyuan-api) | 直接调用思源 REST API |
+| [siyuan-markdown](skills/siyuan-markdown) | 思源特色 Markdown 语法参考 |
+
+---
+
+## 配置说明
+
+优先级：环境变量 > 当前 workspace > `~/.siyuan/config.json`
+
+```json
+{"url": "http://127.0.0.1:6806", "token": "你的Token"}
+```
+
+可选：Token 加密存储到系统密钥环
+
+```bash
+pip install keyring
+siyuan keyring-set 你的Token
+siyuan keyring-unset
+```
+
+---
+
+*社区项目，非官方。*

siyuan_cli-1.1.0/README_EN.md

@@ -0,0 +1,208 @@
+# SiYuan Agent Tools
+
+[![PyPI](https://img.shields.io/pypi/v/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![CI](https://github.com/xingrove/siyuan-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/xingrove/siyuan-skills/actions)
+[![Python](https://img.shields.io/pypi/pyversions/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
+[![License](https://img.shields.io/pypi/l/siyuan-cli)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-229%20passed-brightgreen)](https://github.com/xingrove/siyuan-skills)
+
+> [中文](README.md)
+
+CLI tool, MCP server, and AI Agent Skills for [SiYuan Note](https://github.com/siyuan-note/siyuan). Pure Python, zero dependencies. Compatible with Claude Code, Codex, OpenCode, and Hermes.
+
+---
+
+## Install
+
+```bash
+pip install siyuan-cli
+```
+
+Or the one-command installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xingrove/siyuan-skills/main/scripts/install.sh | bash
+```
+
+---
+
+## Quick Start
+
+```bash
+siyuan config url http://127.0.0.1:6806
+siyuan config token your-api-token
+
+siyuan stats          # verify connectivity
+```
+
+> Token location: SiYuan Desktop → Settings → API; for Docker, in `conf.json`.
+
+---
+
+## CLI Reference
+
+### Documents & Blocks
+
+| Command | Description |
+|---------|-------------|
+| `siyuan create /path [content]` | Create a note (`--file` / `--stdin` supported) |
+| `siyuan read /path` | Read document content |
+| `siyuan delete /path [--id]` | Delete a note |
+| `siyuan tree [notebook]` | Document tree |
+| `siyuan doc rename <title>` | Rename document |
+| `siyuan doc move <paths...> [--to-notebook]` | Move documents |
+| `siyuan doc export /path [--id]` | Export as Markdown |
+| `siyuan doc get-path <id>` | Resolve ID to path |
+
+### Block Operations
+
+| Command | Description |
+|---------|-------------|
+| `siyuan block get <id>` | Block info |
+| `siyuan block children <id>` | Child blocks |
+| `siyuan block append <id> -c <content>` | Append child block |
+| `siyuan block prepend <id> -c <content>` | Prepend child block |
+| `siyuan block insert <id> -c <content>` | Insert block after sibling |
+| `siyuan block update <id> -c <content>` | Update block |
+| `siyuan block delete <id>` | Delete block |
+| `siyuan block move <id> --parent <pid>` | Move block |
+| `siyuan block fold <id>` | Fold heading |
+| `siyuan block unfold <id>` | Unfold |
+
+### Block References & Embeds
+
+| Command | Output | Description |
+|---------|--------|-------------|
+| `siyuan block ref <id>` | `((id 'title'))` | Block reference markup |
+| `siyuan block embed <id>` | `{{embed ((id 'title'))}}` | Block embed markup |
+| `siyuan block link <id>` | `siyuan://blocks/id` | SiYuan internal link |
+
+```bash
+REF=$(siyuan block ref 20200812220555-lj3enxa)
+siyuan create "/article" "As mentioned in $REF..."
+```
+
+### Notebooks, Search & Daily Notes
+
+| Command | Description |
+|---------|-------------|
+| `siyuan notebook list` | List notebooks |
+| `siyuan notebook create <name>` | Create notebook |
+| `siyuan notebook remove <id>` | Remove notebook |
+| `siyuan notebook rename <id> <name>` | Rename |
+| `siyuan notebook conf <id>` | Notebook config |
+| `siyuan search <query>` | Full-text search |
+| `siyuan sql <statement>` | SQL query (SELECT only) |
+| `siyuan daily-note note` | Get or create today's note |
+| `siyuan daily-note append <content>` | Append to today's note |
+
+### Tags, Attributes & Assets
+
+| Command | Description |
+|---------|-------------|
+| `siyuan tag list` | All tags |
+| `siyuan tag blocks <tag>` | Find tagged blocks |
+| `siyuan attr get <id>` | Block attributes |
+| `siyuan attr set <id> <key> <val>` | Set attribute |
+| `siyuan asset upload <file>` | Upload asset |
+| `siyuan file list /data/` | List workspace files |
+| `siyuan file put <local> <remote>` | Upload file |
+
+### Batch & Utilities
+
+| Command | Description |
+|---------|-------------|
+| `siyuan batch create <file>` | Batch create notes |
+| `siyuan batch delete <file>` | Batch delete notes |
+| `siyuan stats` | Workspace statistics |
+| `siyuan overview` | Workspace overview |
+| `siyuan health` | Diagnostic health check |
+| `siyuan backlinks get <id>` | Block backlinks |
+| `siyuan notify push <msg>` | Push notification to UI |
+| `siyuan mcp` | Start MCP server |
+
+---
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--format pretty\|json\|compact` | Output format |
+| `--verbose` | Detailed logging |
+| `--no-color` | Disable colored output |
+| `--version` | Show version |
+| `--yes` | Skip confirmation on destructive ops |
+| `--dry-run` | Preview without applying |
+| `@file:/path` | Read content from file |
+| `@stdin` | Read content from stdin |
+
+**Read-only mode:** `SIYUAN_READ_ONLY=true siyuan <cmd>` blocks all writes.
+
+---
+
+## Multi-Server
+
+```bash
+siyuan workspace add hk --url http://server:6806 --token xxx
+siyuan workspace use hk
+siyuan workspace list
+```
+
+---
+
+## Permission System
+
+```bash
+siyuan permission deny --endpoint "*remove*"   # Block all deletes
+siyuan permission ask --endpoint "*delete*"    # Ask before delete
+siyuan permission list                          # Show rules
+```
+
+---
+
+## MCP Server
+
+```bash
+siyuan-mcp
+```
+
+23 tools: CRUD, search, SQL, block refs/embeds, tags, attributes, health checks. Works with Claude Desktop, Cursor, and any MCP client.
+
+---
+
+## Agent Skills
+
+| Agent | Install |
+|-------|---------|
+| **OpenCode** | `git clone https://github.com/xingrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills` |
+| **Codex CLI** | `cp -r skills/* ~/.codex/skills/` |
+| **Hermes** | `cp -r skills/* ~/.hermes/skills/` |
+| **npx** | `npx skills add https://github.com/xingrove/siyuan-skills` |
+
+| Skill | Description |
+|-------|-------------|
+| [siyuan-cli](skills/siyuan-cli) | Operate SiYuan via CLI |
+| [siyuan-api](skills/siyuan-api) | Direct REST API calls |
+| [siyuan-markdown](skills/siyuan-markdown) | SiYuan-flavored Markdown reference |
+
+---
+
+## Configuration
+
+Priority: `SIYUAN_URL` / `SIYUAN_TOKEN` env vars > active workspace > `~/.siyuan/config.json`
+
+```json
+{"url": "http://127.0.0.1:6806", "token": "your-token"}
+```
+
+Optional keyring storage:
+
+```bash
+pip install keyring
+siyuan keyring-set your-token
+siyuan keyring-unset
+```
+
+---
+
+*Community project, not official.*