Sunsama MCP Server

Sunsama MCP服务器

模型上下文协议（MCP）服务器，通过Sunsama API提供全面的任务管理功能。此服务器使AI助手能够访问Sunsama任务、创建新任务、标记任务完成以及管理您的生产力工作流程。

特性

任务管理

• 创建任务 -使用笔记、时间估计、截止日期、流任务和GitHub/Gmail集成创建新任务
• 阅读任务 -通过完成过滤按天获取任务，访问积压任务，检索存档的任务历史记录
• 更新任务 -使用自定义时间戳将任务标记为已完成，重新安排任务或移至待办事项列表
• 子任务 -在任务中添加、更新、完成和管理子任务
• 删除任务 -从工作区永久删除任务

用户和流操作

• 用户信息 -访问用户配置文件、时区和组详细信息
• 流管理 -获取项目组织的流/渠道
• 双重运输 -支持stdio和HTTP流MCP传输

安装

先决条件

• 包子 运行时（用于开发）
• 具有API访问权限的Sunsama帐户

使用NPX（推荐）

无需安装！直接使用：

npx mcp-sunsama

开发设置

1. 克隆存储库：

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

1. 安装依赖项：

bun install

1. 设置环境变量：

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 -客户端空闲超时（毫秒）（默认值：90000/15分钟）
• MAX_SESSIONS -HTTP传输的最大并发会话数（默认值：100）

用法

运输方式

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

标准传输（默认）

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

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

HTTP流传输

对于远程访问和基于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基本身份验证：

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桌面配置

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

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

Claude代码配置

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

claude mcp add sunsama --scope user \
  -e SUNSAMA_EMAIL=your-email@example.com \
  -e SUNSAMA_PASSWORD=your-password \
  -- npx mcp-sunsama

范围选项：

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

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

API工具

任务管理

• create-task -使用可选属性创建新任务，包括GitHub issues/PR和Gmail集成
• get-tasks-by-day -通过完成筛选获取特定日期的任务
• get-tasks-backlog -获取积压任务
• get-archived-tasks -获取带有分页的存档任务（包括LLM上下文的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 pull请求：

{
  "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": "user@example.com",
      "url": "https://mail.google.com/mail/u/user@example.com/#inbox/19a830b40fd7ab7d",
      "__typename": "TaskGmailIntegrationIdentifier"
    },
    "__typename": "TaskGmailIntegration"
  }
}

备注：所有集成参数都是可选的。可以在不集成标准任务管理的情况下创建任务。

发展

在发展中奔跑

bun run dev

MCP检验员测试

bun run inspect

然后连接MCP检查器以交互方式测试工具。

测试

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的信息，请参阅 贡献.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

主要特点：

• 类型安全：带Zod模式验证的完整TypeScript类型
• 参数解构：干净、明确的函数签名
• 共享公用设施：提取常见模式以减少重复
• 错误处理：所有工具的标准化错误处理
• 响应优化：大型数据集的任务过滤和修剪
• 会话管理：具有基于TTL的生命周期管理的双层缓存
• 测试覆盖率：251+单元测试和综合集成测试

认证

标准运输： 需要 SUNSAMA_EMAIL 和 SUNSAMA_PASSWORD 环境变量。

HTTP传输： 根据请求通过HTTP基本身份验证提供的凭据。凭据不需要环境变量。

贡献

我们欢迎捐款！请查看 贡献.md 有关以下内容的详细指南：

• 开发工作流程
• 代码风格和惯例
• 测试要求
• 发布流程（针对维护人员）

快速启动：

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

• sunsama api库 -底层API客户端
• 模型上下文协议文档
• 问题追踪器