Siyuan Bullet Journal MCP Server

关键词

SiYuan任务管理后端服务数据访问工具执行

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个基于 MCP 的服务器端组件，利用 Model Context Protocol 提供标准化的后端能力，向 MCP 客户端（如 Cursor、Claude 等 AI 助手）暴露任务数据、工具执行能力以及相关数据聚合结果。核心代码位于 src/mcp/server.ts，完整实现了 MCP 服务器并注册了三个工具：list_groups、list_projects、filter_items，用于获取分组、项目及任务项信息。

  • 主要功能点

    • MCP 服务器端实现：通过 McpServer 构造并绑定到标准输入输出传输（StdioServerTransport），实现对 MCP 客户端的请求处理与响应。
    • 三个工具接口：list_groups（获取分组列表）、list_projects（获取项目列表，支持按分组筛选）、filter_items（基于项目、分组、日期与状态筛选任务事项）。
    • 数据源与集成：通过 SiYuanClient 与 SiYuan 的 API/数据接口对接，加载设置、获取文档的 Kramdown 内容、解析成项目与事项结构，并提供给 MCP 客户端使用。
    • 环境与部署：服务器通过环境变量 SIYUAN_TOKEN 与 SIYUAN_API_URL 与 SiYuan 实例进行认证与访问，默认 SIYUAN_API_URL 为 http://127.0.0.1:6806。
    • 架构与扩展性：提供数据加载层（dataLoader.ts）、数据解析（parser 与 markdown 解析器）、以及对外暴露的执行函数，使服务器具备扩展工具集的能力。

  • 安装步骤

      1. 安装依赖：在项目根目录执行安装命令，安装所需的 Node 依赖。
      1. 构建 MCP 服务端：执行构建命令，将源代码打包为 dist/mcp-server.js（vite/构建配置在 vite.mcp.config.ts 中定义）。
      1. 运行 MCP 服务器：以 Node 直接执行打包后的 mcp-server.js，确保环境变量 SIYUAN_TOKEN 与 SIYUAN_API_URL 已正确设置。
      1. 客户端配置：MCP 客户端需要指向服务器的启动命令及参数，以便通过 JSON-RPC 与服务器通信；仓库中提供了 MCP 配置的使用说明，插件设置中可使用“Copy MCP Config”来生成对应的配置片段。

  • 服务器配置（MCP 客户端需要的最小信息，JSON 格式，包含 server name、command、args 等） { "server_name": "sy-task-assistant", "command": "node", "args": ["dist/mcp-server.js"], "env": { "SIYUAN_TOKEN": "<从思源设置→关于获取的 API Token>", "SIYUAN_API_URL": "http://127.0.0.1:6806" } } 说明：

    • server_name 指定 MCP 服务器的唯一标识，与客户端工具注册处使用的一致。
    • command 是用于启动服务器的执行命令，在生产打包后通常为 node。
    • args 指向启动脚本的位置，dist/mcp-server.js 表示构建产物所在路径。
    • env 提供了访问 SiYuan 的认证与 API 入口信息，客户端本身不需要额外配置。
    • 客户端仅需要读取该配置中的 server_name、command、args 与可选的环境变量信息，即可建立连接。

  • 基本使用方法

    • 启动后，MCP 客户端可通过 JSON-RPC 请求访问 server_name 对应的工具接口（list_groups、list_projects、filter_items），并获得标准的 JSON 响应数据。
    • 客户端可以组合使用工具来实现对分组/项目/事项的聚合查询，方便在 AI 助手对话场景中获取结构化数据。
    • 如需扩展工具集，可在服务器端注册更多工具实现，并在 MCP 客户端继续使用相同的接口风格进行调用。

  • 注意点

    • 服务器启动需要正确的 SIYUAN_TOKEN，确保有权限访问 SiYuan 的数据接口。
    • MCP 服务端与客户端之间的通信遵循 JSON-RPC，跨进程、跨上下文的调用依赖标准化协议。

  • 运行与验证

    • 构建产物 dist/mcp-server.js 会在打包阶段生成，运行 node dist/mcp-server.js 即可启动服务器。
    • 使用 MCP 客户端的 MCP 配置，将 server_name 设置为 sy-task-assistant，并指向上述命令与参数，即可测试 list_groups、list_projects、filter_items 的返回数据。

  • 重要依赖与资源

    • src/mcp/server.ts：核心 MCP 服务器实现与工具注册点。
    • src/mcp/listProjects.ts、src/mcp/filterItems.ts：工具实现的业务逻辑。
    • src/mcp/dataLoader.ts、src/mcp/siyuan-client.ts、src/parser、src/api 等：用于数据获取、解析与 API 调用的模块，支撑 MCP 的数据源。
    • vite.mcp.config.ts：将 MCP 服务器打包成 dist/mcp-server.js 的构建配置。

  • 关键词 SiYuan、任务管理、后端服务、数据访问、工具执行

  • 分类 5

服务器信息

访问项目