Agent SiYuan MCP Server

这是一个面向 HTTP MCP 客户端的通用思源笔记服务。

它提供两类能力：

1. Agent_MCP 专属写操作
2. 跨全部思源笔记本的关键词检索

当前配置方式

这个服务现在只支持 streamable_http。

思源连接信息不再从服务端 .env 读取，也不再依赖 MCP initialize.params.capabilities.extensions。
当前唯一有效的配置方式是：由 MCP 客户端在 HTTP 请求头里传入思源站点和思源密钥。

请求头约定：

• x-siyuan-api-url: 思源 API 地址，例如 http://192.168.3.56:6806
• x-siyuan-token: 思源 API token

兼容别名：

• URL: x-siyuan-base-url
• Token: x-siyuan-api-token
• Token: x-siyuan-auth-token

说明：

• 这些请求头需要在首次 initialize 请求时提供
• 服务端会把该配置绑定到当前 MCP session
• 如果缺少请求头，initialize 会直接失败，不创建 session

传输方式

• 传输协议：Streamable HTTP
• MCP 端点：/mcp
• 健康检查：/health
• 旧 /sse 和 /message 已废弃
• stdio 已不再支持

工具能力

写入范围固定在顶层笔记本 Agent_MCP。

支持的工具：

• agent_workspace_status
• agent_create_note
• agent_update_note
• agent_rename_note
• agent_delete_note
• search_all_notebooks

检索工具行为：

• search_all_notebooks 默认返回命中块和 context.snippet
• includeContext=false 可关闭上下文
• includeFullDoc=true 可附带整篇文档的 fullDocKramdown
• contextWindow 控制上下文截取段落数，默认 2

构建

npm install
npm run build

本地运行

HTTP：

npm run http

健康检查：

curl http://127.0.0.1:30088/health

初始化示例

初始化请求必须携带：

• Accept: application/json, text/event-stream
• Content-Type: application/json
• x-siyuan-api-url
• x-siyuan-token

最小示例：

curl -i http://127.0.0.1:30088/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'x-siyuan-api-url: http://127.0.0.1:6806' \
  -H 'x-siyuan-token: your-siyuan-token' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"curl","version":"1.0.0"}
    }
  }'

成功后你会看到：

• HTTP 状态 200 OK
• 响应头 content-type: text/event-stream
• 响应头 mcp-session-id: ...

MCP 客户端配置

如果你的 MCP 客户端支持自定义 HTTP headers，应该这样配置：

{
  "key": "siyuan-mcp-server",
  "name": "siyuan-mcp-server",
  "description": "连接思源笔记的 MCP 服务工具",
  "enabled": true,
  "transport": "streamable_http",
  "url": "http://192.168.3.56:30088/mcp",
  "headers": {
    "x-siyuan-api-url": "http://192.168.3.56:6806",
    "x-siyuan-token": "your-siyuan-token"
  },
  "command": "",
  "args": [],
  "env": {},
  "cwd": ""
}

注意：

• env 对远程 streamable_http 基本无效
• 当前服务也不会再从 env 读取思源配置
• 只有请求头会被用于建立思源连接

PM2 管理

仓库内提供了 ecosystem.config.cjs。

首次启动：

npm install
npm run build
pm2 start ecosystem.config.cjs

常用命令：

pm2 status
pm2 logs agent-siyuan-mcp
pm2 restart agent-siyuan-mcp
pm2 stop agent-siyuan-mcp
pm2 delete agent-siyuan-mcp

说明：

• PM2 只负责启动 HTTP MCP 服务
• PM2 不再需要 SIYUAN_TOKEN / SIYUAN_API_URL
• 服务默认监听 30088

Docker

如果需要容器化运行，可以继续使用仓库内的 docker-compose.yml 和 Dockerfile。

说明：

• Docker 镜像默认只暴露 HTTP MCP 服务
• 容器内不再内置思源凭据
• 思源配置应由客户端通过请求头传入

验证脚本

validate 不再读取思源 env fallback，必须显式提供配置。

示例 1：直接传参数

npm run validate -- --siyuan-api-url http://127.0.0.1:6806 --siyuan-token your-siyuan-token

示例 2：传 initialize payload

npm run validate -- --initialize-payload '{"params":{"capabilities":{"extensions":{"siyuan":{"apiUrl":"http://127.0.0.1:6806","token":"your-siyuan-token"}}}}}'