Truefinals MCP

TrueFinals MCP服务器

一种模型上下文协议（MCP）服务器，通过TrueFinally API提供管理锦标赛、游戏、地点和玩家的工具。

概述

此MCP服务器使AI助手能够与TrueFinals锦标赛管理平台进行交互，为锦标赛管理提供全面的工具。它支持所有主要的锦标赛操作，包括支架管理、比赛评分、位置协调和球员管理。

特性

🏆 锦标赛管理

• 创建、更新和删除锦标赛
• 启动和重置锦标赛
• 管理锦标赛设置和格式选项
• 处理锦标赛webhooks和覆盖参数
• 支持多种锦标赛形式（单淘汰赛、双淘汰赛、循环赛）

🎮 游戏管理

• 列出并管理所有锦标赛游戏
• 创建和编辑展览游戏
• 更新游戏分数和状态
• 处理游戏签到和日程安排
• 支持批量游戏操作
• 位置分配和管理

📍 位置管理

• 添加、更新和删除锦标赛地点
• 在特定位置启动和停止游戏
• 管理位置队列和游戏分配
• 直接从位置更新游戏分数
• 处理位置阻塞和可用性

👥 玩家管理

• 添加、更新和删除玩家
• 管理玩家种子和排名
• 处理球员报到和取消资格
• 支持批量玩家操作
• 随机化锦标赛种子
• 跟踪玩家统计数据和位置

可用工具

1.锦标赛工具（12次操作）

• list -获取用户的锦标赛
• get -获取锦标赛详细信息
• create -创建新锦标赛
• update -更新锦标赛设置
• delete -删除锦标赛
• start -开始比赛
• reset -重置锦标赛
• get_webhooks - 获取比赛网钩
• update_webhooks 更新 Webhooks
• get_overlay_params -获取叠加参数
• update_overlay_params -更新叠加参数
• push_schedule -推送游戏时间表

2.游戏工具（13种操作）

• list -获取所有锦标赛游戏
• get -获取特定游戏详细信息
• add_exhibition -添加展览游戏
• edit_exhibition -编辑展览游戏
• delete_exhibition -删除展览游戏
• bulk_add_exhibition -批量添加展览游戏
• bulk_delete_exhibition -批量删除展览游戏
• update -更新游戏详细信息
• update_score -更新游戏分数
• update_state -更新游戏状态
• update_scheduled_time -更新计划时间
• update_location -更新游戏位置
• update_checkin -更新玩家登记
• undo -撤消已完成的游戏

3.定位工具（8项操作）

• list -获取所有锦标赛地点
• get -获取具体位置详细信息
• add -添加新位置
• update -更新位置详细信息
• delete -删除位置
• start_game -在指定位置开始排队游戏
• stop_game -停止该位置的活动游戏
• update_game_scores -更新位置当前游戏的分数

4.玩家工具（10次操作）

• list -获取所有锦标赛选手
• get -获取特定玩家详细信息
• add -添加新玩家
• update -更新玩家信息
• delete -删除玩家
• reseed -更改玩家种子
• randomize -随机化锦标赛种子
• bulk_update -批量更新玩家列表
• checkin -让玩家参加比赛
• disqualify -取消球员资格

安装和设置

先决条件

• 转到1.19或更高版本
• TrueFinally API证书（用户ID和API密钥）

构建服务器

# Clone the repository
git clone https://github.com/truefinals/truefinals-mcp.git
cd truefinals-mcp

# Build the server
go build -o truefinals-mcp-server

# Or use the pre-built binary
chmod +x truefinals-mcp-server

配置

服务器需要TrueFinal API凭据。使用环境变量设置它们：

export TRUEFINALS_API_USER_ID="your_user_id"
export TRUEFINALS_API_KEY="your_api_key"

# Optional configuration
export TRUEFINALS_BASE_URL="https://truefinals.com/api"  # Custom API base URL
export TRUEFINALS_TOOLS="full"                           # Tool filter mode
export TRUEFINALS_DISABLED_TOOLS="tournaments,games"     # Disable specific tools

或者将它们作为命令行参数传递：

./truefinals-mcp-server -api-user-id "your_user_id" -api-key "your_api_key"

用法

基本用法

# Start the server with default settings
./truefinals-mcp-server

# Start with specific credentials
./truefinals-mcp-server -api-user-id "your_user_id" -api-key "your_api_key"

工具筛选

服务器支持根据安全和权限级别过滤可用工具：

# Show only reporting tools (read-only operations)
./truefinals-mcp-server -tools reporting

# Show safe modification tools (excludes dangerous operations)
./truefinals-mcp-server -tools full-safe

# Show all tools (default)
./truefinals-mcp-server -tools full

可用工具模式：

• reporting：只读操作（列表、获取操作）
• full-safe：安全修改操作（不包括删除、重置、批量操作）
• full：所有操作（默认）

命令行选项

Usage: ./truefinals-mcp-server [options]

Options:
  -api-user-id string     API User ID for TrueFinals service
  -api-key string         API key for TrueFinals service
  -base-url string        Base URL for TrueFinals API (optional)
  -tools string           Tools mode: reporting, full-safe, full
  -disabled-tools string  Comma-separated list of tool names to disable
  -exit-after-first       Exit after processing the first request
  -version               Show version information and exit
  -help                  Show help information

MCP集成

连接到AI助手

该服务器实现了模型上下文协议，可以与兼容的AI助手（如Claude Desktop或其他MCP兼容应用程序）集成。

Claude Desktop的MCP配置示例：

{
  "mcpServers": {
    "truefinals": {
      "command": "/path/to/truefinals-mcp-server",
      "args": ["-api-user-id", "your_user_id", "-api-key", "your_api_key"],
      "env": {}
    }
  }
}

Claude桌面配置

要与Claude Desktop一起使用，请将此配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json\ Linux: ~/.config/Claude/claude_desktop_config.json

即用型配置（复制并粘贴到您的Claude Desktop配置中）：

{
  "mcpServers": {
    "truefinals": {
      "command": "/usr/local/bin/truefinals-mcp-server",
      "args": [
        "-api-user-id", "YOUR_TRUEFINALS_USER_ID",
        "-api-key", "YOUR_TRUEFINALS_API_KEY"
      ],
      "env": {}
    }
  }
}

替换 YOUR_TRUEFINALS_USER_ID 和 YOUR_TRUEFINALS_API_KEY 使用您的真实TrueFinal API证书。

工具架构

所有工具都包含全面的JSON模式，包括：

• 必需和可选参数
• 参数验证规则
• 状态字段的枚举值
• 详细参数说明
• 类型约束和限制

api参考

服务器与TrueFinal API v1。关键数据结构包括：

锦标赛

• 锦标赛元数据和设置
• 格式配置（单/双淘汰，循环）
• 玩家和位置管理
• 游戏支架组织

游戏

• 游戏状态和得分
• 玩家登记状态
• 位置分配
• 分等递进征税

位置

• 物理比赛地点
• 游戏队列管理
• 主动游戏跟踪
• 可用性状态

玩家

• 玩家信息和统计
• 种子和排名
• 入住状态
• 比赛历史

错误处理

服务器通过以下方式提供全面的错误处理：

• 详细的错误消息
• HTTP状态码映射
• 参数验证
• API限速意识
• 网络错误恢复

发展

项目结构

TrueFinals-MCP/
├── main.go                 # Server entry point and MCP protocol handling
├── api.go                  # TrueFinals API client and data structures
├── tools_tournaments.go    # Tournament management operations
├── tools_games.go         # Game management operations  
├── tools_locations.go     # Location management operations
├── tools_players.go       # Player management operations
├── docs/
│   └── openapi.json       # TrueFinals API specification
├── go.mod                 # Go module dependencies
└── README.md              # This file

添加新操作

要添加新操作，请执行以下操作：

1. 将API终结点添加到 api.go
2. 在适当的地方实现操作功能 tools_*.go 文件
3. 将操作添加到工具的处理程序switch语句中
4. 使用新操作更新工具架构
5. 测试实施情况

贡献

欢迎投稿！请确保：

• 代码遵循Go惯例
• 所有操作都包括正确的错误处理
• 针对新操作更新工具模式
• 相应地更新文档

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

关于以下问题：

• TrueFinal API：联系TrueFinals支持
• MCP服务器：在此存储库中创建问题
• 整合：检查MCP文档和AI助手配置

版本历史记录

• v1.0.0：初始版本包含完整的锦标赛、游戏、地点和玩家管理

- 4个工具共43次操作 - 完整的TrueFinal API覆盖范围 - 工具过滤和安全模式 - 全面的错误处理和验证