内容
# 思源笔记MCP服务端
思源笔记内核的符合人体工程学的MCP服务端。它是一个干净、自主的替换方案，用于替代`leolulu/siyuan-mcp-server`，解决了三个问题：
1. **纯中文环境。** 所有的工具名称、描述、参数文档和错误信息都是清晰的中文。
2. **无主动UI通知。** 写入操作从不推送通知到思源笔记UI。仅存在一个可选的`notify`工具，用于显示消息时使用。
3. **合理的写入操作。** `create_document`需要显式提供`title`，正确构建思源笔记路径，并将YAML frontmatter（思源笔记**不**解析）转换为`custom-*`块属性。每次写入操作都会返回新的块ID，以便您可以链接后续操作。
## 思源笔记数据模型（需要注意的事项）
- **笔记本 -> 文档 -> 块。** 块ID类似于`20260619181928-palr67f`（14位时间戳、短划线、短后缀）。
- **文档的标题来自最后一个路径段**，通过`title`参数设置 - 永远不会从YAML frontmatter和前导`# heading`中获取。思源笔记不解析frontmatter：前导`---`块渲染为水平线，`key: value`行成为纯文本。
- **元数据存储为`custom-*`块属性**，而不是frontmatter。请使用`set_block_attributes` / `get_block_attributes`。
- **`query_sql`仅只读**（SELECT/WITH）。请使用块工具进行写入操作。
有关LLM的完整驱动指南，请参阅`skills/siyuan/SKILL.md`。
## 工具列表
**读取操作：** `list_notebooks`、`find_documents`、`search_blocks`、`get_block_markdown`、`get_blocks_markdown`、`get_block_children`、`query_sql`、`get_block_attributes`、`list_files`、`read_file`。
**写入操作：** `create_document`、`insert_block`、`prepend_block`、`append_block`、`update_block`、`move_block`、`delete_block`、`set_block_attributes`。
**杂项：** `notify`（可选，仅英文，绝不会自动触发）。
## 配置
| 环境变量 | 是否必需 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `SIYUAN_API_URL` | 否 | `http://127.0.0.1:6806` | 思源笔记内核基础URL |
| `SIYUAN_API_TOKEN` | 是 | - | 思源笔记API令牌（设置 -> 关于） |
| `SIYUAN_MCP_HOST` | 否 | `0.0.0.0` | 绑定主机 |
| `SIYUAN_MCP_PORT` | 否 | `8000` | 绑定端口 |
传输方式为**可流式HTTP**，在`/mcp`上提供服务。禁用DNS重新绑定保护，以便网关可以转发任意`Host`头部（否则MCP SDK会拒绝`Host: siyuan-mcp:8000`，并提示“无效的主机头部”）。
## 运行
```bash
git clone https://github.com/metaember/siyuan-mcp.git
cd siyuan-mcp
uv run siyuan-mcp # 本地开发（读取环境变量）
# 或
pip install . && siyuan-mcp
```
## Docker
```bash
docker build -t siyuan-mcp .
docker run --rm -p 8000:8000 \
-e SIYUAN_API_URL=http://siyuan:6806 \
-e SIYUAN_API_TOKEN=your-token \
siyuan-mcp
```
镜像以`nobody`用户运行，并暴露`8000`端口。它作为`siyuan-mcp`镜像的替换（相同的环境变量 + `/mcp`端点）进入隔离环境编排；请参阅`docker-compose.example.yml`。
## 测试
```bash
uv run pytest # 或：pip install -e '.[dev]' && pytest
```
测试套件涵盖了创建带标题、处理frontmatter、写入操作返回ID、仅SELECT的SQL保护和错误消息质量 - 所有这些都不需要运行思源笔记内核（内核客户端被模拟）。`tests/integration`中有一个可选的端到端测试（模拟内核 + 真实服务器通过HTTP）：
```bash
RUN_INTEGRATION=1 pytest tests/integration -q
```
## 致谢
API表面和端点形状是从[`leolulu/siyuan-mcp-server`](https://github.com/leolulu/siyuan-mcp-server)（MIT）和[官方思源笔记内核API](https://github.com/siyuan-note/siyuan/blob/master/API.md)学习而来。
这是独立的、优先支持英文的重实现。
## 许可证
MIT - 请参阅[LICENSE](LICENSE)。
