金大哥 - teamsnapmcp MCP 详情

article

README

🚀 TeamSnap MCP 服务器

这是一个模型上下文协议（MCP）服务器，它能将 Claude 与你的 TeamSnap 账户连接起来。你可以直接从 Claude 桌面端或命令行界面访问你的团队、花名册、活动和可用性数据。

🚀 快速开始

1. 获取 TeamSnap OAuth 凭证

访问 TeamSnap 开发者门户。
创建一个新的应用程序。
设置重定向 URI（请参阅下面的部署选项）。
记录下你的 客户端 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_auth | 通过 OAuth 连接到 TeamSnap | client_id?, client_secret? | | teamsnap_auth_status | 检查连接状态 | — | | teamsnap_logout | 断开连接并清除凭证 | — | | teamsnap_list_teams | 列出你所有的团队 | — | | teamsnap_get_team | 获取团队详情 | team_id | | teamsnap_get_roster | 获取球员和教练信息 | team_id | | teamsnap_get_events | 获取团队活动 | team_id, start_date?, end_date? | | teamsnap_get_event | 获取活动详情 | event_id | | teamsnap_get_availability | 获取所有成员的活动 RSVP 状态 | event_id |

可用性状态代码

teamsnap_get_availability 工具根据 API 返回的 TeamSnap status_code 字段将成员分为四类： | 状态 | 数字代码 | 字符串代码 | 含义 | |--------|-------------|-------------|---------| | yes | 1 | "yes" | 成员标记为可用 | | no | 0 | "no" | 成员拒绝参加 | | maybe | 2 | "maybe" | 成员不确定 | | noResponse | null/缺失 | — | 成员尚未回复 |

⚠️ 重要提示：JavaScript 中，“拒绝”的数字代码 0 是一个假值。服务器在读取 status_code 时使用空值合并运算符 (??) 而非逻辑或运算符 (||)，以确保数字 0 能正确归类为“拒绝”，而不是默认归为“未回复”。

🔧 技术细节

架构

本地部署:

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


AWS 部署:

  Claude 桌面端 <--stdio--> 包装器 --HTTPS--> API 网关
                                                     |
                                                  Lambda
                                                  |     |
                                            DynamoDB   TeamSnap API

环境变量

| 变量 | 是否必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | TEAMSNAP_CLIENT_ID | 本地部署时必需 | — | OAuth 客户端 ID | | TEAMSNAP_CLIENT_SECRET | 本地部署时必需 | — | OAuth 客户端密钥 | | TEAMSNAP_CALLBACK_PORT | 否 | 8374 | 本地 OAuth 回调端口 | | TEAMSNAP_REDIRECT_URI | 否 | — | 覆盖重定向 URI（用于隧道） | | TEAMSNAP_MCP_ENDPOINT | 仅适用于 AWS 包装器 | — | API 网关端点 URL |

安全性

加密 — 本地令牌使用 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 许可证。

teamsnapmcp