Sunsama

Sunsama MCP 服务

一个 Model Context Protocol（MCP）服务，通过 Sunsama API 提供全面的任务管理功能。此服务可让 AI 助手访问 Sunsama 任务、创建新任务、标记任务为已完成，并管理你的工作效率工作流。

功能

任务管理

• 创建任务 - 创建包含备注、时间预估、截止日期、流分配以及 GitHub/Gmail 集成的新任务
• 读取任务 - 按日期获取任务并筛选完成状态、访问积压任务、检索已归档的任务历史记录
• 更新任务 - 使用自定义时间戳标记任务为已完成、重新安排任务或将任务移至积压列表
• 子任务 - 在任务中添加、更新、完成和管理子任务
• 删除任务 - 从工作区永久移除任务

用户和流操作

• 用户信息 - 访问用户个人资料、时区和群组详情
• 流管理 - 获取用于项目组织的流/频道
• 双传输模式 - 支持 stdio 和 HTTP stream MCP 传输

安装

前提条件

• Bun 运行时（用于开发）
• 可访问 API 的 Sunsama 账户

使用 NPX（推荐）

无需安装！直接使用：

npx mcp-sunsama

开发环境设置

1. 克隆仓库：

git clone https://github.com/robertn702/mcp-sunsama.git
cd mcp-sunsama

2. 安装依赖项：

bun install

3. 设置环境变量：

cp .env.example .env
# Edit .env and add your Sunsama credentials

环境变量：

• SUNSAMA_EMAIL - 你的 Sunsama 账户邮箱（stdio 传输必需）
• SUNSAMA_PASSWORD - 你的 Sunsama 账户密码（stdio 传输必需）
• TRANSPORT_MODE - 传输类型：stdio（默认）或 http
• PORT - HTTP 传输的服务端口（默认：8080）
• HTTP_ENDPOINT - MCP 端点路径（默认：/mcp）
• SESSION_TTL - 会话超时时间，单位为毫秒（默认：3600000 / 1 小时）
• CLIENT_IDLE_TIMEOUT - 客户端空闲超时时间，单位为毫秒（默认：900000 / 15 分钟）
• MAX_SESSIONS - HTTP 传输的最大并发会话数（默认：100）

使用方法

传输模式

此服务支持两种传输模式：

Stdio 传输（默认）

适用于本地 AI 助手（Claude Desktop、Cursor 等）：

bun run dev
# or
TRANSPORT_MODE=stdio bun run src/main.ts

HTTP Stream 传输

适用于远程访问和基于 Web 的集成：

TRANSPORT_MODE=http PORT=8080 bun run src/main.ts

HTTP 端点：

• MCP 端点：POST http://localhost:8080/mcp
• 健康检查：GET http://localhost:8080/

身份验证： HTTP 请求需要使用你的 Sunsama 凭据进行 HTTP Basic Auth 身份验证：

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Basic $(echo -n 'your-email:your-password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Claude Desktop 配置

将此配置添加到 Claude Desktop MCP 设置中：

{
  "mcpServers": {
    "sunsama": {
      "command": "npx",
      "args": ["mcp-sunsama"],
      "env": {
        "SUNSAMA_EMAIL": "[email protected]",
        "SUNSAMA_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code 配置

使用 Claude Code CLI 添加 Sunsama MCP 服务：

claude mcp add sunsama --scope user \
  -e [email protected] \
  -e SUNSAMA_PASSWORD=your-password \
  -- npx mcp-sunsama

作用域选项：

• --scope user - 在所有项目中均可用（推荐）
• --scope project - 仅在当前项目中可用

添加服务后，重启 Claude Code 以连接到 Sunsama MCP 服务。

API 工具

任务管理

• create-task - 创建新任务，可选择设置属性，包括 GitHub 问题/PR 和 Gmail 集成
• get-tasks-by-day - 获取指定日期的任务，并可按完成状态筛选
• get-tasks-backlog - 获取待办任务
• get-archived-tasks - 分页获取已归档任务（包含供大模型上下文使用的 hasMore 标记）
• get-task-by-id - 根据 ID 获取指定任务
• update-task-complete - 将任务标记为已完成
• update-task-planned-time - 更新任务的计划时间（时间估算）
• update-task-notes - 更新任务备注内容（需要提供 html 或 markdown 参数之一，二者不可同时使用）
• update-task-due-date - 更新任务的截止日期（设置或清除截止日期）
• update-task-text - 更新任务文本/标题
• update-task-stream - 更新任务所属的工作流/频道
• update-task-snooze-date - 将任务重新安排到其他日期
• update-task-backlog - 将任务移至待办列表
• delete-task - 永久删除任务

子任务管理

• add-subtask - 一次调用即可创建带标题的子任务（推荐用于创建单个子任务）
• create-subtasks - 为任务创建多个子任务（用于批量操作的底层 API）
• update-subtask-title - 更新子任务标题
• complete-subtask - 将子任务标记为已完成，可选择指定完成时间戳
• uncomplete-subtask - 将子任务标记为未完成

用户与工作流操作

• get-user - 获取当前用户信息
• get-streams - 获取用于项目组织的工作流/频道

集成示例

create-task 工具支持将任务关联到 GitHub 和 Gmail 等外部服务。

GitHub 集成

将任务关联到 GitHub 问题：

{
  "text": "Fix authentication bug",
  "integration": {
    "service": "github",
    "identifier": {
      "id": "I_kwDOO4SCuM7VTB4n",
      "repositoryOwnerLogin": "robertn702",
      "repositoryName": "mcp-sunsama",
      "number": 42,
      "type": "Issue",
      "url": "https://github.com/robertn702/mcp-sunsama/issues/42",
      "__typename": "TaskGithubIntegrationIdentifier"
    },
    "__typename": "TaskGithubIntegration"
  }
}

将任务关联到 GitHub 拉取请求：

{
  "text": "Review API refactoring PR",
  "integration": {
    "service": "github",
    "identifier": {
      "id": "PR_kwDOO4SCuM7VTB5o",
      "repositoryOwnerLogin": "robertn702",
      "repositoryName": "mcp-sunsama",
      "number": 15,
      "type": "PullRequest",
      "url": "https://github.com/robertn702/mcp-sunsama/pull/15",
      "__typename": "TaskGithubIntegrationIdentifier"
    },
    "__typename": "TaskGithubIntegration"
  }
}

Gmail 集成

将任务关联到 Gmail 邮件：

{
  "text": "Respond to project update email",
  "integration": {
    "service": "gmail",
    "identifier": {
      "id": "19a830b40fd7ab7d",
      "messageId": "19a830b40fd7ab7d",
      "accountId": "[email protected]",
      "url": "https://mail.google.com/mail/u/[email protected]/#inbox/19a830b40fd7ab7d",
      "__typename": "TaskGmailIntegrationIdentifier"
    },
    "__typename": "TaskGmailIntegration"
  }
}

注意：所有集成参数均为可选项。也可以不使用集成创建任务，以进行标准任务管理。

开发

在开发环境中运行

bun run dev

使用 MCP Inspector 测试

bun run inspect

然后连接 MCP Inspector，以交互方式测试这些工具。

测试

bun test                   # Run unit tests only
bun test:unit              # Run unit tests only (alias)
bun test:integration       # Run integration tests (requires credentials)
bun test:all               # Run all tests
bun test:watch             # Watch mode for unit tests

构建与类型检查

bun run build              # Compile TypeScript to dist/
bun run typecheck          # Run TypeScript type checking
bun run typecheck:watch    # Watch mode type checking

发布流程

有关创建版本并发布到 npm 的信息，请参阅 CONTRIBUTING.md。

代码架构

该服务采用模块化、基于资源的架构：

src/
├── tools/
│   ├── shared.ts          # Common utilities and patterns
│   ├── user-tools.ts      # User operations (get-user)
│   ├── task-tools.ts      # Task operations (15 tools)
│   ├── stream-tools.ts    # Stream operations (get-streams)
│   └── index.ts           # Export all tools
├── resources/
│   └── index.ts           # API documentation resource
├── auth/                  # Authentication strategies
│   ├── stdio.ts           # Stdio transport authentication
│   ├── http.ts            # HTTP Basic Auth parsing
│   └── types.ts           # Shared auth types
├── transports/
│   ├── stdio.ts           # Stdio transport implementation
│   └── http.ts            # HTTP Stream transport with session management
├── session/
│   └── session-manager.ts # Session lifecycle management
├── config/                # Environment configuration
│   ├── transport.ts       # Transport mode configuration
│   └── session-config.ts  # Session TTL configuration
├── utils/                 # Utilities (filtering, trimming, etc.)
│   ├── client-resolver.ts # Transport-agnostic client resolution
│   ├── task-filters.ts    # Task completion filtering
│   ├── task-trimmer.ts    # Response size optimization
│   └── to-tsv.ts          # TSV formatting utilities
├── schemas.ts             # Zod validation schemas
└── main.ts                # Server setup (47 lines vs 1162 before refactoring)

__tests__/
├── unit/                  # Unit tests (no auth required)
│   ├── auth/              # Auth utility tests
│   ├── config/            # Configuration tests
│   └── session/           # Session management tests
└── integration/           # Integration tests (requires credentials)
    └── http-transport.test.ts

主要特性：

• 类型安全：全面的 TypeScript 类型支持，并使用 Zod 进行模式验证
• 参数解构：简洁明了的函数签名
• 共享实用工具：提取通用模式以减少重复
• 错误处理：所有工具采用标准化的错误处理
• 响应优化：针对大型数据集筛选和精简任务
• 会话管理：基于 TTL 生命周期管理的双层缓存
• 测试覆盖：251+ 项单元测试和全面的集成测试

身份验证

**Stdio 传输：**需要 SUNSAMA_EMAIL 和 SUNSAMA_PASSWORD 环境变量。

**HTTP 传输：**每次请求通过 HTTP Basic Auth 提供凭据。无需设置凭据环境变量。

贡献

欢迎贡献！详细指南请参阅 CONTRIBUTING.md，内容包括：

• 开发工作流
• 代码风格与约定
• 测试要求
• 发布流程（适用于维护者）

快速入门：

1. Fork 并克隆仓库
2. 安装依赖：bun install
3. 进行更改
4. 创建变更集：bun run changeset
5. 提交拉取请求

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

支持

• sunsama-api 库 - 底层 API 客户端
• Model Context Protocol 文档
• 问题跟踪器