Ultimate Frisbee Team MCP Server

Ultimate Frisbee Team MCP 服务

用于管理 Ultimate Frisbee Team 球员、锦标赛和付款的模型上下文协议（MCP）服务。此服务可让你在 SQLite 数据库中添加、列出和管理球员及锦标赛，还可以跟踪锦标赛报名和付款。现已改用 FastMCP，以提升性能和易用性！

功能

球员管理

• 添加球员及其姓名、电话号码和可选邮箱
• 列出数据库中的所有球员
• 从数据库中移除球员
• 从 CSV 文件导入球员

锦标赛管理

• 创建锦标赛，设置名称、地点、日期、场地类型（草地/沙滩）和报名截止日期
• 列出、更新和移除锦标赛
• 为锦标赛报名或取消球员报名
• 跟踪每位球员的锦标赛付款状态
• 通过模糊姓名匹配搜索已支付锦标赛费用的球员

联合会付款跟踪

• 记录球员支付的联合会费用
• 跟踪付款金额和日期
• 列出球员的付款历史
• 如有需要，移除最近一笔付款

系统功能

• 将数据库备份到文件
• 可通过命令行或 MCP 接口访问
• 现已使用 FastMCP，提升 AI 交互体验！

设置

环境设置

1. 使用 uv 创建虚拟环境：

uv venv

2. 激活虚拟环境：

source .venv/bin/activate

3. 使用开发依赖以开发模式安装软件包：

uv pip install -e ".[dev]"

4. 设置环境变量（可选，用于 SQLiteCloud）：

将 .env-template 文件复制为 .env，并填写相应值：

cp .env-template .env
# Edit .env with your SQLiteCloud credentials

5. 运行测试：

pytest tests/

用法

命令行用法

球员管理

# Add a player
ultimate-team-mcp-server add-player "John Smith" --phone "+1234567890" --email "[email protected]"

# List all players
ultimate-team-mcp-server list-players

# Remove a player
ultimate-team-mcp-server remove-player --name "John Smith"

# Import players from a CSV file, updating existing ones
ultimate-team-mcp-server import-players /path/to/players.csv

锦标赛管理

# Add a tournament
ultimate-team-mcp-server add-tournament --name "Summer Championship" --location "City Beach" \
  --date "2025-07-15" --surface "beach" --registration-deadline "2025-06-30"

# List all tournaments
ultimate-team-mcp-server list-tournaments

# Update a tournament
ultimate-team-mcp-server update-tournament --id 1 --name "Summer Beach Championship" --location "North Beach"

# Remove a tournament
ultimate-team-mcp-server remove-tournament --id 1

# Register a player for a tournament
ultimate-team-mcp-server register-player --tournament-id 1 --player-name "John Smith"

# Unregister a player from a tournament
ultimate-team-mcp-server unregister-player --tournament-id 1 --player-name "John Smith"

# List all players registered for a tournament
ultimate-team-mcp-server list-tournament-players --tournament-id 1

# List all tournaments a player is registered for
ultimate-team-mcp-server list-player-tournaments --player-name "John Smith"

# Mark a player as having paid for a tournament
ultimate-team-mcp-server mark-payment --tournament-id 1 --player-name "John Smith"

# Clear a player's payment status for a tournament
ultimate-team-mcp-server clear-payment --tournament-id 1 --player-name "John Smith"

# Search for players who have paid for a tournament (with fuzzy matching)
ultimate-team-mcp-server search-paid-players --tournament-id 1 --name "John"

联合会付款跟踪

# Add a federation payment for a player
ultimate-team-mcp-server add-federation-payment --player-name "John Smith" \
  --amount 50.0 --payment-date "2025-01-15" --notes "Annual fee"

# List all federation payments for a player
ultimate-team-mcp-server list-federation-payments --player-name "John Smith"

# Remove the most recent federation payment for a player
ultimate-team-mcp-server remove-last-federation-payment --player-name "John Smith"

系统命令

# Backup the database
ultimate-team-mcp-server backup /path/to/backup.db

# Using with a specific database URI
ultimate-team-mcp-server list-players --db-uri "sqlitecloud://host:port/database?apikey=key"
ultimate-team-mcp-server add-player "John" --phone "+1234567890" --db-uri "file:///path/to/custom.db"

与 Claude Desktop 配合使用

要将 MCP 服务与 Claude Desktop 配合使用，需要将其添加到 claude_desktop_config.json 文件中：

{
    "mcpServers": {
        "ultimate_mcp_server": {
            "command": "ultimate-team-mcp-server",
            "environment": {
            "SQLITE_URI": "sqlitecloud://host:port/database?apikey=key"
            }
        }
    }
}

与 Claude Code 配合使用

1. 启动 MCP 服务：

ultimate-team-mcp-server

2. 安装 Claude Code。

3. 将 Ultimate Team MCP 服务直接添加到 Claude：

# Set up with the new FastMCP-based server
# This works with both Claude Desktop and Claude CLI
claude mcp add ultimate -- ultimate-team-mcp-server

# List existing MCP servers - Validate that the server is running
claude mcp list

使用以下命令运行 Claude Code：

claude

使用自定义数据库 URI

启动服务时，可以指定数据库 URI：

# Using environment variable
SQLITE_URI="sqlitecloud://host:port/database?apikey=key" ultimate-team-mcp-server

# Or using command-line option
ultimate-team-mcp-server --db-uri "sqlitecloud://host:port/database?apikey=key"

数据库结构

此服务使用 SQLite 或 SQLiteCloud 存储球员数据、锦标赛、报名、付款及相关信息。数据库现包含以下表：

• 球员（姓名、联系信息）
• 锦标赛（名称、地点、日期、场地类型、报名截止日期）
• 锦标赛-球员报名（含付款跟踪）
• 联合会付款（含金额和付款历史）

完整的架构定义位于 src/ultimate_mcp_server/modules/init_db.py 文件中。

数据库配置

此服务可通过单个数据库 URI 参数连接到本地 SQLite 数据库，也可以连接到 SQLiteCloud，使用云端解决方案。配置数据库连接的方法：

1. 根据提供的 .env-template 创建 .env 文件
2. 将 SQLITE_URI 或 DB_URI 环境变量设为以下格式之一：
   • SQLiteCloud：SQLITE_URI=sqlitecloud://hostname:port/database?apikey=your_api_key
   • 本地 SQLite：SQLITE_URI=file:///path/to/database.db

如果未设置这两个环境变量，服务将默认使用 ~/.ultimate.db 处的本地 SQLite 数据库。

CSV 导入格式

CSV 导入功能（包括 import-csv 和 import-players）接受以下格式的文件：

Nombre,Telefono,Email
John Smith,+1234567890,[email protected]
Jane Doe,+0987654321,[email protected]

列名不区分大小写，可以使用英语或西班牙语（Nombre/Name、Telefono/Phone、Email）。

import-csv 和 import-players 的区别

• import-csv：原始导入工具。它会添加新球员，但如果已存在同名球员，则会失败。
• import-players：增强型导入工具。它会添加新球员，并在发现同名球员时更新现有球员。

使用 import-players 更新球员的示例：

1. 如果你的数据库中有一名电话为“+1234567890”的球员“John Smith”
2. 而你的 CSV 中有一名电话为“+9999999999”的球员“John Smith”
3. 导入后，球员“John Smith”的电话号码将更新为“+9999999999”