Sunsama

Sunsama MCP サーバー

Sunsama API を通じて包括的なタスク管理機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、AI アシスタントが Sunsama のタスクにアクセスしたり、新しいタスクを作成したり、タスクを完了としてマークしたり、生産性ワークフローを管理したりできます。

機能

タスク管理

• タスクの作成 - メモ、所要時間の見積もり、期限、ストリームの割り当て、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

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）

使用方法

トランスポートモード

このサーバーは、2 つのトランスポートモードに対応しています。

Stdio トランスポート（デフォルト）

ローカルの AI アシスタント（Claude Desktop、Cursor など）向け：

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

HTTP ストリームトランスポート

リモートアクセスやウェブベースの連携向け：

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 認証が必要です。

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 の Issue／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 - 1 回の呼び出しでタイトルを指定してサブタスクを作成します（単一のサブタスク作成に推奨）
• create-subtasks - タスクのサブタスクを複数作成します（一括操作用の低レベル API）
• update-subtask-title - サブタスクのタイトルを更新します
• complete-subtask - オプションで完了日時を指定して、サブタスクを完了としてマークします
• uncomplete-subtask - サブタスクを未完了としてマークします

ユーザーとストリームの操作

• get-user - 現在のユーザー情報を取得します
• get-streams - プロジェクトの整理に使うストリーム／チャンネルを取得します

連携の例

create-task ツールは、タスクを GitHub や Gmail などの外部サービスにリンクできます。

GitHub との連携

タスクを GitHub の Issue にリンクします：

{
  "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

主な機能：

• 型安全性：Zod スキーマ検証を備えた、完全な TypeScript の型付け
• パラメーターの分割代入：明確で分かりやすい関数シグネチャ
• 共有ユーティリティ：重複を減らすために共通パターンを抽出
• エラー処理：すべてのツールで標準化されたエラー処理
• レスポンスの最適化：大規模なデータセットに対するタスクのフィルタリングとトリミング
• セッション管理：TTL ベースのライフサイクル管理を備えた二層キャッシュ
• テストカバレッジ：251 件以上の単体テストと包括的な統合テスト

認証

Stdio トランスポート： SUNSAMA_EMAIL と SUNSAMA_PASSWORD の環境変数が必要です。

HTTP トランスポート： リクエストごとに HTTP Basic 認証で認証情報を指定します。認証情報用の環境変数は必要ありません。

コントリビューション

コントリビューションを歓迎します！詳細なガイドラインについては、CONTRIBUTING.md をご覧ください。

• 開発ワークフロー
• コードスタイルと規約
• テスト要件
• リリースプロセス（メンテナー向け）

クイックスタート：

1. リポジトリをフォークしてクローンします
2. 依存関係をインストールします：bun install
3. 変更を加えます
4. changeset を作成します：bun run changeset
5. プルリクエストを送信します

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

サポート

• sunsama-api Library - 基盤となる API クライアント
• Model Context Protocol Documentation
• Issue Tracker