Teamsnapmcp

🚀 TeamSnap MCP 服務器

這是一個 模型上下文協議（MCP）服務器，它能將 Claude 與你的 TeamSnap 賬戶連接起來。你可以直接從 Claude 桌面端或命令行界面訪問你的團隊、花名冊、活動和可用性數據。

🚀 快速開始

1. 獲取 TeamSnap OAuth 憑證

1. 訪問 TeamSnap 開發者門戶。
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 桌面端配置文件（~/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 無服務器部署

部署到 AWS Lambda 以獲得永久的 HTTPS 回調 URL，無需隧道。

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 網關 — 永久的 HTTPS 端點
• Lambda — MCP 服務器（Node.js 20，256MB，30 秒超時）
• DynamoDB — 帶有 TTL 自動清理功能的令牌存儲

然後配置 Claude 桌面端使用 包裝器：

{
  "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："連接到 TeamSnap" 一個瀏覽器窗口將打開以進行 OAuth 登錄。授權後，你就完成了連接。

✨ 主要特性

• 團隊管理 — 列出並查看你所有的 TeamSnap 團隊。
• 花名冊管理 — 獲取球員和教練的信息。
• 活動管理 — 查看比賽、訓練和其他活動，並可按日期過濾。
• 可用性檢查 — 檢查哪些人可以參加活動，正確處理所有 RSVP 狀態，包括數字狀態代碼。
• 安全可靠 — 使用 OAuth 2.0 進行身份驗證，本地存儲或 DynamoDB 使用 AES - 256 - GCM 加密。
• 靈活部署 — 可以在本地運行，通過 npx 運行，或部署到 AWS Lambda。

📦 安裝指南

前提條件

• Node.js >= 18
• 一個 TeamSnap 開發者 OAuth 應用程序（客戶端 ID + 密鑰）

💻 使用示例

示例提示

• "我在 TeamSnap 中有哪些團隊？"
• "給我看看 Jr Kraken 隊的花名冊。"
• "我們這個月有哪些比賽安排？"
• "週六的比賽誰有空參加？"
• "誰拒絕參加週六的比賽？"

📚 詳細文檔

可用工具

可用性狀態代碼

teamsnap_get_availability 工具根據 API 返回的 TeamSnap status_code 字段將成員分為四類：

⚠️ 重要提示：JavaScript 中，“拒絕”的數字代碼 0 是一個假值。服務器在讀取 status_code 時使用空值合併運算符 (??) 而非邏輯或運算符 (||)，以確保數字 0 能正確歸類為“拒絕”，而不是默認歸為“未回覆”。

🔧 技術細節

架構

本地部署:

  Claude 桌面端 <--stdio--> MCP 服務器 (Node.js)
                                   |
                              TeamSnap API
                                   |
                         localhost:8374 (OAuth 回調)


AWS 部署:

  Claude 桌面端 <--stdio--> 包裝器 --HTTPS--> API 網關
                                                     |
                                                  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 許可證。