星战科技xingzhan.cloud
返回市场
MCP-太阳马

MCP-太阳马

作者：robertn70222 星标更新：2025-11-15
安装使用来源：spider==github.com

项目介绍

Sunsama MCP Server

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

<a href="https://glama.ai/mcp/servers/@robertn702/mcp-sunsama"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=792081009,1916937968&fm=3081&app=3081&f=PNG?w=760&h=400" /> </a>

功能

任务管理

  • 创建任务 - 创建带有备注、时间估计、截止日期、流分配以及GitHub/Gmail集成的新任务。
  • 读取任务 - 按天获取任务并进行完成过滤，访问待办任务，检索归档任务历史。
  • 更新任务 - 使用自定义时间戳标记任务为已完成，重新安排任务或移动到待办。
  • 删除任务 - 永久从您的工作区中移除任务。

用户与流操作

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

安装

预备条件

  • Bun 运行时（用于开发）
  • 具有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
# 编辑.env并添加您的Sunsama凭证

环境变量：

  • 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
# 或
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 Desktop配置

在您的Claude Desktop MCP设置中添加以下配置：

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

API工具

任务管理

  • create-task - 创建带有可选属性的新任务，包括GitHub问题/PR和Gmail集成。
  • get-tasks-by-day - 获取特定日期的任务并进行完成过滤。
  • get-tasks-backlog - 获取待办任务。
  • get-archived-tasks - 获取归档任务（包括分页，包含hasMore标志供LLM上下文使用）。
  • 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 - 永久删除任务。

用户与流操作

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

集成示例

create-task工具支持将任务链接到外部服务，如GitHub和Gmail。

GitHub集成

将任务链接到GitHub问题：

{
  "text": "修复身份验证错误",
  "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": "审查API重构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": "回复项目更新邮件",
  "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 Inspector测试

bun run inspect

然后连接MCP Inspector以交互式测试工具。

测试

bun test                   # 仅运行单元测试
bun test:unit              # 仅运行单元测试（别名）
bun test:integration       # 运行集成测试（需要凭据）
bun test:all               # 运行所有测试
bun test:watch             # 单元测试的监视模式

构建和类型检查

bun run build              # 将TypeScript编译到dist/
bun run typecheck          # 运行TypeScript类型检查
bun run typecheck:watch    # 类型检查的监视模式

发布过程

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

代码架构

服务器采用模块化、资源为基础的架构：

src/
├── tools/
│   ├── shared.ts          # 公用工具和模式
│   ├── user-tools.ts      # 用户操作（get-user）
│   ├── task-tools.ts      # 任务操作（15个工具）
│   ├── stream-tools.ts    # 流操作（get-streams）
│   └── index.ts           # 导出所有工具
├── resources/
│   └── index.ts           # API文档资源
├── auth/                  # 认证策略
│   ├── stdio.ts           # Stdio传输认证
│   ├── http.ts            # HTTP基本认证解析
│   └── types.ts           # 共享认证类型
├── transports/
│   ├── stdio.ts           # Stdio传输实现
│   └── http.ts            # 带会话管理的HTTP流传输
├── session/
│   └── session-manager.ts # 会话生命周期管理
├── config/                # 环境配置
│   ├── transport.ts       # 传输模式配置
│   └── session-config.ts  # 会话TTL配置
├── utils/                 # 工具（过滤、修剪等）
│   ├── client-resolver.ts # 传输无关的客户端解析
│   ├── task-filters.ts    # 任务完成过滤
│   ├── task-trimmer.ts    # 响应大小优化
│   └── to-tsv.ts          # TSV格式化工具
├── schemas.ts             # Zod验证模式
└── main.ts                # 服务器设置（47行，重构前1162行）

__tests__/
├── unit/                  # 单元测试（不需要认证）
│   ├── auth/              # 认证工具测试
│   ├── config/            # 配置测试
│   └── session/           # 会话管理测试
└── integration/           # 集成测试（需要凭据）
    └── http-transport.test.ts

关键特性：

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

认证

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

HTTP传输：凭据通过每次请求的HTTP基本认证提供。无需凭据的环境变量。

贡献

我们欢迎贡献！请参阅CONTRIBUTING.md以了解详细指南：

  • 开发工作流程
  • 代码风格和约定
  • 测试要求
  • 发布过程（维护者）

快速开始：

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

许可

本项目根据MIT许可发布 - 详情见LICENSE文件。

支持