Teamsnapmcp

🚀 TeamSnap MCP Server

このサーバーは、Model Context Protocol (MCP) を使用して、Claude を TeamSnap アカウントに接続します。Claude Desktop または CLI から直接、チーム、選手名簿、イベント、参加可否のデータにアクセスできます。

✨ 主な機能

• チーム — TeamSnap のすべてのチームを一覧表示および閲覧できます。
• 選手名簿 — 選手とコーチの情報を取得できます。
• イベント — 試合、練習、その他のイベントを日付でフィルタリングして閲覧できます。
• 参加可否 — イベントに参加可能なメンバーを確認でき、すべての RSVP ステータス（数値ステータスコードを含む）を正しく処理します。
• セキュア — OAuth 2.0 を使用し、AES - 256 - GCM で暗号化されたローカルストレージまたは DynamoDB を利用します。
• 柔軟なデプロイメント — ローカルで、npx を介して、または AWS Lambda 上で実行できます。

📦 インストール

前提条件

• Node.js >= 18
• TeamSnap Developer の OAuth アプリケーション（クライアント ID + シークレット）

クイックスタート

1. TeamSnap OAuth 資格情報の取得

1. TeamSnap Developer Portal にアクセスします。
2. 新しいアプリケーションを作成します。
3. リダイレクト URI を設定します（以下のデプロイメントオプションを参照）。
4. クライアント ID と クライアントシークレット をメモします。

2. デプロイメント方法の選択

オプション A: ローカル MCP サーバー

開発に最適です。OAuth コールバックにトンネル（例: Cloudflare）が必要です。

git clone https://github.com/mrelph/TeamSnapMCP.git
cd TeamSnapMCP
cp .env.example .env   # 資格情報を追加
npm install
npm run build

Claude Desktop の設定ファイル (~/Library/Application Support/Claude/claude_desktop_config.json) に以下を追加します:

{
  "mcpServers": {
    "teamsnap": {
      "command": "node",
      "args": ["/path/to/TeamSnapMCP/dist/index.js"],
      "env": {
        "TEAMSNAP_CLIENT_ID": "your-client-id",
        "TEAMSNAP_CLIENT_SECRET": "your-client-secret",
        "TEAMSNAP_REDIRECT_URI": "https://your-tunnel-url/callback"
      }
    }
  }
}

💡 使用アドバイス：cloudflared tunnel --url http://localhost:8374 を使用して HTTPS コールバック URL を作成しましょう。

オプション B: npx（AWS デプロイメントに接続）

AWS バックエンドがすでにデプロイされている場合、最も簡単なオプションです。ローカルでのクローンは不要です。

{
  "mcpServers": {
    "teamsnap": {
      "command": "npx",
      "args": ["-y", "teamsnap-mcp"],
      "env": {
        "TEAMSNAP_MCP_ENDPOINT": "https://your-api-id.execute-api.us-east-1.amazonaws.com/mcp"
      }
    }
  }
}

オプション C: AWS サーバーレス

恒久的な HTTPS コールバック URL を持つ AWS Lambda にデプロイします — トンネルは不要です。

cd aws
npm install

環境変数を設定します:

export AWS_ACCESS_KEY_ID=your-aws-key
export AWS_SECRET_ACCESS_KEY=your-aws-secret
export AWS_REGION=us-east-1
export TEAMSNAP_CLIENT_ID=your-client-id
export TEAMSNAP_CLIENT_SECRET=your-client-secret

デプロイします:

node scripts/deploy.cjs

これにより、以下が作成されます:

• API Gateway — 恒久的な HTTPS エンドポイント
• Lambda — MCP サーバー（Node.js 20、256MB、30 秒タイムアウト）
• DynamoDB — TTL 自動クリーンアップ付きのトークンストレージ

その後、Claude Desktop が ラッパー を使用するように設定します:

{
  "mcpServers": {
    "teamsnap": {
      "command": "node",
      "args": ["/path/to/TeamSnapMCP/dist/wrapper.js"],
      "env": {
        "TEAMSNAP_MCP_ENDPOINT": "https://your-api-id.execute-api.us-east-1.amazonaws.com/mcp"
      }
    }
  }
}

3. 認証

Claude に "Connect to TeamSnap" と指示します。 ブラウザウィンドウが開き、OAuth ログインが行われます。承認すると、接続が完了します。

💻 使用例

利用可能なツール

参加可否ステータスコード

teamsnap_get_availability ツールは、API から返される TeamSnap の status_code フィールドに基づいて、メンバーを 4 つのカテゴリに分類します:

⚠️ 重要な注意：JavaScript では、"辞退" を表す数値コード 0 は偽の値です。サーバーは status_code を読み取る際に、論理和 (||) 演算子ではなく nullish coalescing (??) 演算子を使用して、数値 0 を正しく "no" として分類し、"no response" に誤って分類されないようにしています。

プロンプトの例

• "TeamSnap に登録されているチームはどれですか？"
• "Jr Kraken の選手名簿を表示してください"
• "今月予定されている試合はどれですか？"
• "土曜日の試合に参加可能な人は誰ですか？"
• "土曜日の試合を辞退した人は誰ですか？"

🔧 技術詳細

アーキテクチャ

ローカルデプロイメント:

  Claude Desktop <--stdio--> MCP Server (Node.js)
                                   |
                              TeamSnap API
                                   |
                         localhost:8374 (OAuth callback)


AWS デプロイメント:

  Claude Desktop <--stdio--> Wrapper --HTTPS--> API Gateway
                                                     |
                                                  Lambda
                                                  |     |
                                            DynamoDB   TeamSnap API

環境変数

セキュリティ

• 暗号化 — ローカルトークンは AES - 256 - GCM（scrypt キー派生）で暗号化されます。
• 読み取り専用 — TeamSnap から read スコープのみを要求します。
• ハードコードされた資格情報なし — すべてのシークレットは環境変数から読み込まれます。
• CSRF 保護 — OAuth 状態パラメータの検証を行います。
• 自動クリーンアップ — DynamoDB の TTL は、古い保留中の認証を 10 分後に削除します。
• ファイルパーミッション — ローカルの資格情報は 0600（所有者のみ）で保存されます。

開発

npm install       # 依存関係をインストール
npm run build     # TypeScript をコンパイル
npm run dev       # ウォッチモードで実行
node dist/index.js      # ローカルサーバーを実行
node dist/wrapper.js    # AWS ラッパーを実行

AWS デプロイメント

cd aws
npm install
npm run build           # esbuild でバンドル
node scripts/deploy.cjs # AWS にデプロイ

📄 ライセンス

MIT