Open Sunsama MCP Server

使用说明（Markdown 格式）

• 项目简介

  • 本仓库实现了一个基于 Model Context Protocol 的 MCP 服务器，用于向 AI 客户端提供统一的上下文信息、资源访问能力和外部工具执行能力，方便将 Open Sunsama 的数据和功能暴露给大模型进行智能化协作。

• 主要功能点

  • 提供资源管理接口：任务、时间块、子任务、用户等数据的读取与操作。
  • 注册并暴露工具：如 list_tasks、create_task、update_time_block、get_user_profile 等，方便 LLM 调用外部功能。
  • 支持多种传输方式（本实现以 stdio 传输为主，易于在桌面 AI 助手中通过管道连接）。
  • 会话与能力声明：通过 MCP 服务对象实现会话管理、能力注册与错误处理。
  • 与后端 REST API 的集成：通过 ApiClient 封装对 Open Sunsama API 的访问。

• 安装步骤

  • 确保环境中安装了 Bun/Node 运行时。
  • 安装依赖并构建：
    • bun install
  • 配置环境变量（运行时必需，示例见下方“服务器配置”）：
    • OPENSUNSAMA_API_KEY：API Key，用于访问 Open Sunsama REST API
    • OPSENSUNSAMA_API_URL（可选，默认公开 API 地址）
  • 启动 MCP 服务器（示例命令，实际部署请根据本地环境调整）：
    • 直接通过 Node/Bun 运行对应入口（仓库内 mcp/src/index.ts 为入口，使用 Bun/Node 环境编译执行）。
    • 或在支持的打包发布场景中，通过 npm/npx 方式启动，例如 npm 包发布后以 npm run mcp 启动。

• 服务器配置 MCP 客户端需要提供的配置信息（JSON 文本，示例仅供参考，实际由客户端读取并连接服务器）： { "server": "open-sunsama", "command": "npx", "args": ["-y", "@open-sunsama/mcp"], "env": { "OPENSUNSAMA_API_KEY": "os_your_api_key_here", "OPENSUNSAMA_API_URL": "https://api.opensunsama.com" } // 说明：该配置用于 MCP 客户端启动服务端进程，确保服务器可通过标准输入/输出通信。 }

• 基本使用方法

  • 启动后，LLM 客户端（如 Claude/Cursor 等）可以通过 JSON-RPC 形式向 MCP 服务器请求资源读取、工具调用等。
  • 客户端应在启动时提供必要的 API Key，服务器会通过 ApiClient 与 Open Sunsama API 进行数据交互。
  • 注册的工具可通过相应的名称直接被调用，以完成任务管理、日程安排等操作，提升 AI 助手的上下文能力与执行能力。

• 注意事项

  • 该实现示例以 stdio 传输为核心，确保本地桌面 AI 客户端的集成友好。
  • 生产环境中建议结合日志、错误追踪与鉴权策略进行部署。