内容
源笔记 MCP 服务器源笔记（SiYuan Note）模型上下文协议（MCP）服务器，支持可插拔身份验证。使 Claude 等 AI 助手可以通过安全、身份验证 与您的思源笔记交互。
## 功能特点
- **完整的思源笔记集成、写入、搜索、块、闪卡等
- **可插拔身份验证**：
- OAuth 2.1 + PKCE via Cloud（支持 Okta、Azure AD、Google 等）
`X-SiYuan-Key` 头部进行简单的 API 密钥身份验证
- **多工作器架构**：分离身份验证和 MCP 后端以提高灵活性
- **两种部署模式**：
- **Cloudflare Workers**：具有多个身份验证选项的生产环境部署
- **（CLI）**：用于直接与 Claude Desktop 集成的独立 MCP 服务器
- **RAG 支持**：可选的向量搜索集成，用于语义文档检索
- **只读模式**：可配置的限制以实现安全的只读访问
## 架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Cloudflare Workers │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────┐ ┌──────────────────────────── │
│ │ CF Access 身份验证（sy.wenri.org）│ │ API身份验证（api-sy.wenri.org）│
│ │ - OAuth 流程（/authorize） │ │ - X-SiYuan-Key 验证 │ │
│ │ - /download（基于授予） │ │ - /download（无状态） │ │
│ └──────────────┬──────────────┘ └──────────────┬──────────────┘ │
│ │ 服务绑定 │ 服务绑定 │
│ └───────────────────┬───────────────┘ │
│ ▼ │
│ ┌───────────────────────────────┐ │
│ │ MCP 后端工作器 │ │
│ │ - SiyuanMCP 可持久对象 │ │
│ │ - 工具执行 │ │
│ │ - 思源笔记内核 API 调用 │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ 命令行界面（stdio）模式 │
├─────────────────────────────────────────────────────────────────────────┤
│ Claude Desktop ←──stdio──→ handlers/cli.ts ←──HTTP──→ 思源笔记内核 │
└─────────────────────────────────────────────────────────────────────────┘
```
## 可用的 MCP 工具
| 工具类别 | 工具 |
|---------------|-------|
| **文档读取** | 列出笔记本、获取文档树、读取文档内容、概要 |
| **文档写入** | 创建、重命名、移动、删除文档 |
| **块操作** | 插入、更新、删除、移动块（支持批量操作） |
| **搜索** | 全文搜索（`siyuan_find_block`）、SQL 查询 |
| **向量搜索** | 基于 RAG 的语义搜索（需要 RAG 后端） |
| **每日笔记** | 创建和管理每日笔记 |
| **闪卡** | 创建和复习闪卡 |
| **属性** | 管理文档/块的自定义属性 |
| **关系** | 管理块关系 |
| **资产** | 上传资产（批量、URL 获取、JSON 自动序列化） |
| **文件系统** | 读取/写入文件、创建存档 |
| **模板** | 渲染和管理思源笔记模板 |
| **帮助文档** | 内置文档资源 |
| **实用工具** | 获取时间、推送通知、重新索引、刷新事务 |
## 快速入门
### 选项 1：命令行界面模式（本地开发）
使用 stdio 传输进行直接的 Claude Desktop 集成：
```bash
# 克隆并安装
git clone <仓库网址>
cd mcp_saas
npm install
# 使用思源笔记内核网址运行
npx tsx handlers/cli.ts --kernel-url http://localhost:6806
# 或使用身份验证令牌
npx tsx handlers/cli.ts --kernel-url http://localhost:6806 --token 您的令牌
```
添加到 Claude Desktop（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"siyuan": {
"command": "npx",
"args": ["tsx", "/路径/到/handlers/cli.ts", "--kernel-url", "http://localhost:6806"]
}
}
}
```
### 选项 2：Cloudflare Workers（生产环境）
将多工作器 MCP 服务器部署到 Cloudflare Workers。
#### 项目结构
```
workers/
├── mcp-backend/ # MCP 后端（内部，无公开路由）
│ ├── index.ts # 入口点，WorkerEntrypoint 具有 RPC 方法
│ ├── server/ 服务器核心
│ │ agent.ts #MCP 可持久对象
│ │ └── index # 服务器初始化
│ wrangler.jsonc # DO 绑定
│ auth-cfaccess/ # CF Access OAuth（enri.org）
│ ├── index.ts # OAuth 提供 RPC 转发
│ ├── access-handler.tsx # 应用：OAuth 流程（JSX）
│ wrangler.jsonc KV + 服务绑定
└── auth-ap # API 密钥身份验证（api-sy.w.org）
├── index # Hono 应用：Yuan-Key 验证
└── wrangler.json # 服务绑定
```
部署 MCP 后端（
```bash
cd workers/mcp-backend
wrangler secret put SIYUAN_KERNEL# 如果思源笔记内核位于 CF Access 后面：
wrangler secret put CF_CLIENT_ID
wrang put CF_ACCESS_SERVICE_CLIENT_SECRET
npx wrang
```
#### 部署 身份验证工作器
```bash
cd workers/authaccess
# 创建 KV 命名空间（一次性）
wrangler kv namespaceOAUTH_KV"
wrangler.jsonc 中更新 KV ID
# 从 CF Access SaaS 应用仪表盘设置密钥
wrangler ACCESS_CLIENT_ID
wr secret put ACCESS_CLIENT_SECRET
wrangler secret put_URL
wrangler ACCESS_AUTHORIZATION_URL
ler secret put ACCESS_J_URL
wrang put COOKIE_ENCRYPTION_KEY # openssl rand -32
npx wrangler deploy
```
#### API 密钥身份验证工作器
```bash
cd workers/auth-apikey
wrangler secret put SIYUAN_KERNEL_TOKEN
wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler deploy
```
#### 与 Claude Desktop 连接
**通过 OAuth（CF Access）：**
```json
{
"mcpServers": {
"siyuan-oauth": "command": "npx",
"argscp-remote", "https://sy.wen/sse"]
}
}
```
**通过密钥：**
```bash
claude mcp add https://api-sy.wenri.org/sse \
-t sse -H-SiYuan-Key您的令牌"
```
参考
### 环境变量
| 变量 | 是否 描述 |
|----------|----------|| `SIYUAN_KERNEL_URL` | 是 | 思源笔记内核网址 |
| `SIYUAN_KERNEL_TOKEN 如果启用身份验证 | 思源笔记 API 令牌 `COOKIE_ENCRYPT` | 工作器模式 | 用于下载网址加密 |
|AG_BASE_URL`选 | RAG 后端网址，用于向量搜索 |
| `RAG_API_KEY` | 可选 | RAG 后端 API 密钥 |
| `FILTER_NOTEBOOKS` | 可选 | 要包含的笔记本行分隔） `FILTER_DOCUMENTS`选 | 要包含 ID（换行分隔） |
READ_ONLY_MODE` | 可选 | ``、`allow_non_destructive` 或 `deny_all` |
| `AUTO_APPROVE_LOCAL_CHANGE` | 可选 | 自动批准本地更改操作 |
### CF Access 身份验证工作器密钥
| 密钥 | 描述 |
|--------|-------------|
| `ACCESS_CLIENT_ID` | 来自 CF Access SaaS 应用仪表盘 |
| `ACCESS_CLIENT_SECRET` | 来自 CF Access SaaS 应用仪表盘 |
| `ACCESS_TOKEN_URL` | 令牌端点网址 |
| `IZATION_URL` | 授权端点网址 `ACCESS_JWKS_URL` | JWKS 端点网址 |
### 命令行
```
选项：
-u, --kernel网址> 思源笔记内核网址（必需）
-t, --token <令牌> 思源笔记 API 令牌
--rag-url <网址> RAG 后端网址
--rag-key <密钥> RAG API 密钥
--filter-notebooks <ID> 要过滤的笔记本 ID（换行分隔）
--filter-documents <ID> 要过滤的文档 ID（换行分隔）
--read-only <模式> 只读模式：allow_all、allow_non_destructive、deny_all
-h, --help 显示帮助信息
```
## API 端点
### OAuth 身份验证工作器（sy.wenri.org）
- `GET /authorize` - 启动 OAuth 流程
- `GET /callback` - OAuth 回调，同意页面
- `POST /callback` - 完成授权
- `POST /token` - 令牌端点
- `POST /register` - 动态客户端注册
- `GET /.well-known/oauth-authorization-server` - OAuth 元数据
- `POST /mcp`、`GET /sse` - MCP 端点（通过 RPC 转发到后端）
- `GET /download/*` - 文件下载（基于授予的验证）
### API 密钥身份验证工作器（api-sy.wenri.org）
- `POST /mcp`、`GET /sse` - MCP 端点（需要 X-SiYuan-Key，转发通过 RPC）
- `GET /download/*` - 文件无状态验证）
## 开发
```bash
# 安装依赖项
npm install
# 本地开发 - 分别启动每个工作器
cd workers/mcp-backend && npx wrangler dev # http://localhost:
cd workers/auth-c && npx wr dev # http://8
cd-apikey && npxler dev #localhost:8789
测试
npm test 部署（顺序后端优先）
cd workers-backend && npxler deploy
cd workersfaccess && nangler deploy
cdikey && npx wrangler deploy
```
## 测试
### MCP 检查bash
npx @modelcontextprotocol/inspector# 连接到的网址或 localhost### 手动测试
```bash
# 测试 OAuth
curl https://sy.wenri.org/.wellization-server
# 测试 API 密钥身份验证
curl -X POST https://api-sy.wenri.org/mcp \
-H "X-SiYuan-Key: 您的令牌" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
## 安全
- **OAuth 2.1 + PKCE**：防止授权代码- **Cloudflare Access**：企业身份提供程序支持
- **服务绑定**：内部工作器通信（后端无公开路由）
- **可持久对象**：具有 SQLite 存储的会话状态
- **下载网址加密**：基于时间的、基于路径的下载令牌
- **只读模式**：可选的写入操作限制
## 故障排除
### 常见问题
**"SIYUAN_KERNEL_URL 未配置"**
- 在 wrangler.jsonc 变量中设置UAN_KERNEL_URL"无法获取思配置"**
- 验证思源笔记内核是否正在访问
- 如果启用身份验证，请检查 `SIYUAN_KERNEL_TOKEN`
**"未授权：缺少身份验证上下文"**
- MCP 后端需要来自身份验证工作器的身份验证标头
- 无法直接访问；使用身份验证工作器端点
**"无效或已过期的状态"**
- OAuth 状态已过期（10 分钟超时）
- 验证 KV 命名空间是否正确配置
**工具未显示**
- 检查 `READ_ONLY_MODE` 设置
- 验证工具注释是否允许当前模式
## 许可证
MIT
