# SiYuan MCP Server
一个为思源笔记（SiYuan）设计的 Model Context Protocol (MCP) 服务器，提供完整的 AI 集成和智能知识管理功能。
## 🌟 核心特性
### 笔记管理
- **笔记本操作**: 创建、列表、打开、关闭、重命名、删除笔记本
- **文档管理**: 创建、读取、更新、删除文档，支持批量操作
- **块操作**: 创建、读取、更新、删除笔记块，支持批量操作
- **块属性**: 设置和获取块属性，支持自定义属性管理
### 搜索功能
- **简单搜索**: 快速关键词搜索
- **递归搜索**: 深度内容挖掘，支持层级遍历
- **文档内搜索**: 在指定文档中精确查找
- **批量读取**: 高效批量读取多个文档
### 模板与渲染
- **模板渲染**: 支持标准模板语法
- **Sprig模板**: 支持Sprig函数库的高级模板功能
- **动态内容**: 基于模板生成格式化内容
### 导出功能
- **Markdown导出**: 导出为标准Markdown格式
- **多格式导出**: 支持PDF、Word、HTML等多种格式
- **树状结构导出**: 保留文档层级关系的JSON导出
### 资源管理
- **文件上传**: 上传图片、文档等资源文件
- **资源列表**: 列出文档中的所有资源
- **资源重命名**: 重命名资源文件
- **OCR识别**: 图片文字识别功能
### 数据操作
- **SQL查询**: 执行SQL查询，支持复杂的数据检索
- **文件操作**: 读取、写入、删除文件
- **文件列表**: 列出目录中的文件
### 系统工具
- **时间获取**: 获取当前真实时间，支持多种格式和时区
- **健康检查**: 系统健康状态监控
- **端口发现**: 自动发现思源笔记可用端口
### AI 智能集成
- **智能工具选择**: AI驱动的工具推荐和选择
- **使用场景指导**: 详细的工具使用场景和示例
- **性能优化建议**: 基于使用模式的优化建议
- **错误处理**: 标准化的错误处理和重试机制
### 性能优化
- **缓存机制**: 智能缓存提升响应速度
- **批量处理**: 高效的批量数据操作
- **性能监控**: 实时性能指标和统计
- **并发控制**: 合理的并发请求管理
## 🚀 快速开始
### 1. 安装思源笔记
1. 下载安装包：[https://github.com/siyuan-note/siyuan/releases](https://github.com/siyuan-note/siyuan/releases)
2. 启动思源笔记
### 2. 配置思源笔记
1. 启动思源笔记
2. 设置 → 关于 → API token
3. 复制API Token
### 3. 安装 MCP Server
#### 从 npm 安装
```bash
npm install -g siyuan-mcp-server
```
#### 从源码安装
```bash
git clone https://github.com/your-username/siyuan-mcp-server.git
cd siyuan-mcp-server
npm install
npm run build
npm link
```
### 4. 配置 MCP
在您的 MCP 客户端配置文件中添加：
```json
{
"mcpServers": {
"siyuan": {
"command": "npx",
"args": ["siyuan-mcp-server"],
"env": {
"SIYUAN_API_TOKEN": "your-api-token"
}
}
}
}
```
**注意**:
- `SIYUAN_API_URL` 是可选的，如果不配置，系统会自动发现思源笔记的可用端口
- 如果需要指定端口，可以添加 `"SIYUAN_API_URL": "http://127.0.0.1:6806"`
### 5. 环境变量
- `SIYUAN_API_TOKEN`: 思源笔记 API Token（必需）
- `SIYUAN_API_URL`: 思源笔记 API 地址（可选，默认自动发现可用端口）
**端口自动发现**:
- 系统会自动扫描思源笔记的常用端口（6806, 6807, 6808）
- 如果思源笔记正在运行，系统会自动连接到正确的端口
- 如果自动发现失败，会尝试使用默认端口 6806
- 如需指定端口，可手动设置 `SIYUAN_API_URL` 环境变量
## 🛠️ 技术栈
- **运行时**: Node.js 18+
- **语言**: TypeScript
- **协议**: Model Context Protocol (MCP)
- **HTTP客户端**: Axios
- **构建工具**: TypeScript Compiler
## 📡 MCP 工具列表
### 📚 笔记本操作 (Notebook)
- `list_notebooks` - 列出所有笔记本
- `open_notebook` - 打开笔记本
- `close_notebook` - 关闭笔记本
- `rename_notebook` - 重命名笔记本
- `remove_notebook` - 删除笔记本
### 📄 文档操作 (Document)
- `create_document` - 创建新文档
- `get_document` - 获取文档内容
- `update_document` - 更新文档
- `delete_document` - 删除文档
- `list_documents` - 列出文档
- `batch_read_all` - 批量读取所有文档
### 🧱 块操作 (Block)
- `create_block` - 创建块
- `get_block` - 获取块
- `update_block` - 更新块
- `delete_block` - 删除块
- `prepend_block` - 在块前插入
- `append_block` - 在块后追加
- `fold_block` - 折叠块
- `unfold_block` - 展开块
- `transfer_block_ref` - 转移块引用
- `set_block_attrs` - 设置块属性
- `get_block_attrs` - 获取块属性
- `batch_create_blocks` - 批量创建块
- `batch_update_blocks` - 批量更新块
- `batch_delete_blocks` - 批量删除块
### 🔍 搜索操作 (Search)
- `simple_search` - 简单搜索
- `recursive_search` - 递归搜索
- `search_in_document` - 在文档中搜索
### 🎨 模板操作 (Template)
- `render_template` - 渲染模板
- `render_sprig_template` - 渲染Sprig模板
### 📤 导出操作 (Export)
- `export_markdown` - 导出为Markdown
- `export_file` - 导出为指定格式
- `export_expand` - 导出为树状结构
### 🖼️ 资源操作 (Assets)
- `upload_asset` - 上传资源文件
- `list_assets` - 列出资源文件
- `rename_asset` - 重命名资源文件
- `ocr_asset` - OCR识别图片
### 💾 SQL查询 (SQL)
- `query_sql` - 执行SQL查询
### 📁 文件操作 (File)
- `read_file` - 读取文件
- `write_file` - 写入文件
- `delete_file` - 删除文件
- `list_files` - 列出文件
### ⏰ 系统操作 (System)
- `get_current_time` - 获取当前真实时间
## 📖 使用示例
### 创建文档
```typescript
// 创建新文档
await toolRegistry.execute('create_document', {
notebook: 'notebook-id',
path: '/path/to/document',
title: '文档标题',
content: '文档内容'
});
```
### 搜索内容
```typescript
// 递归搜索
await toolRegistry.execute('recursive_search', {
query: '关键词',
notebook: 'notebook-id',
maxDepth: 5
});
```
### 批量操作
```typescript
// 批量创建块
await toolRegistry.execute('batch_create_blocks', {
requests: [
{ content: '第一个块' },
{ content: '第二个块' }
]
});
```
### 获取时间
```typescript
// 获取当前时间
await toolRegistry.execute('get_current_time', {
format: 'iso',
timezone: 'Asia/Shanghai'
});
```
### 导出文档
```typescript
// 导出为Markdown
await toolRegistry.execute('export_markdown', {
id: 'document-id'
});
```
## 🔧 开发
### 构建项目
```bash
npm run build
```
### 运行测试
```bash
npm test
```
### 代码检查
```bash
npm run lint
```
### 类型检查
```bash
npm run typecheck
```
## 🤝 贡献指南
欢迎贡献代码、报告问题或提出改进建议！
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 🙏 致谢
感谢思源笔记团队提供优秀的笔记软件和 API 支持。
## 📮 联系方式
- 问题反馈: [GitHub Issues](https://github.com/your-username/siyuan-mcp-server/issues)
- 功能建议: [GitHub Discussions](https://github.com/your-username/siyuan-mcp-server/discussions)
