Focalboard MCP 服务器

关键词

FocalboardKanbanAI 助手 集成事务性操作Bun 运行时

使用说明内容（Markdown格式）

  • 项目简介

    • 该项目实现了一个 MCP 服务器，能够通过 MCP 的接口向客户端提供对 Focalboard 的资源（看板、块等）、工具（创建/查询/更新等操作）以及组合操作的访问能力。服务器通过 Bun 运行时运行，使用 Stdio 传输实现与客户端的通信，采用 JSON-RPC 风格的请求/响应。

  • 主要功能点

    • 资源托管与数据访问：提供看板（Board）和块（Block）的创建、读取、更新、删除、搜索等基础操作，以及批量操作和原子事务能力。
    • 工具注册与执行：将对看板和块的操作封装为工具，注册给 MCP 客户端，客户端可通过调用工具来完成相应的后端操作。
    • 会话与认证协作：支持基于 Focalboard 的 API 认证方式（令牌、可选的用户名/密码登录）以及会话的登出处理。
    • 多传输协议与扩展能力：当前实现以 Stdio 传输为主，理论上可扩展为 SSE、WebSocket 等传输协议，以提供更高并发与实时交互能力。
    • 代码与测试结构完善：包含服务器入口、工具实现、客户端封装、以及详细的类型定义与测试用例，帮助确保请求/响应的结构与数据一致性。

  • 安装步骤

    • 环境要求：需要 Bun 运行时（bun v1.3.5+）。
    • 安装依赖：bun install
    • 运行模式：
      • 开发模式（热更新可用）：bun --hot index.ts
      • 生产模式：bun run index.ts
    • 本地快速验证：
      • 服务器默认通过环境变量获取 Focalboard 的连接信息，若需要本地测试，请配置 FOCALBOARD_URL、FOCALBOARD_API_PREFIX、FOCALBOARD_TOKEN 等环境变量。

  • 服务器配置（给 MCP 客户端启动服务的配置信息） 说明：MCP 客户端需要提供服务器的启动命令及参数，以便在运行时启动 MCP 服务器并建立连接。以下配置根据仓库信息生成，非代码形式展示，便于直观理解。 { "server": "focalboard-mcp", "command": "bun", "args": ["--hot", "index.ts"], "env": { "FOCALBOARD_URL": "https://your-focalboard-instance.com", "FOCALBOARD_API_PREFIX": "/api/v2", "FOCALBOARD_TOKEN": "your-auth-token", "FOCALBOARD_AUTH_MODE": "auto", "FOCALBOARD_REQUESTED_WITH": "XMLHttpRequest" }, "notes": "开发模式可使用上述 --hot 的方式启动，生产模式请改为 'bun run index.ts'，并根据实际部署环境调整 FOCALBOARD_API_PREFIX、认证等参数。" } 注：该配置信息用于 MCP 客户端在首次建立连接时启动服务器进程；客户端并不需要实现服务器逻辑，只需知道如何启动即可。

  • 基本使用方法

    • 启动后，客户端通过 MCP 的列表工具接口（ListTools）获得可用工具清单，随后通过 CallTool 请求执行具体工具（如创建看板、查询块、批量操作等）。
    • 典型工作流包括：
      • 注册工具：客户端请求获取可用工具列表。
      • 调用工具：客户端按名称传递参数，服务器执行对应的后端逻辑并返回结构化数据。
      • 错误处理：服务器在捕获异常时返回带有错误信息的内容块，便于客户端在对话中展示。
    • 重要注意事项：
      • 需确保 Focalboard 接入地址和 Token 配置正确，以保证服务器能对 Focalboard API 做出调用。
      • 若需要实现更高安全性或多传输协议的支持，可以在未来扩展传输层实现。

服务器信息

访问项目