BasketBall -MCP chatbot

🏀 篮球联赛管理MCP服务器

一个基于人工智能的篮球联赛管理系统，使用MCP（模型上下文协议）服务器构建，为青年篮球联赛提供全面的球队注册、支架管理和候补名单功能。

📋 目录

• 概述
• 特性
• 建筑
• 设置和安装
• 可用数据源
• API使用
• MCP工具参考
• 查询示例
• 配置
• 故障排除

🎯 概述

该系统管理青少年篮球联赛的运营，包括：

• 跨多个年级部门的团队注册
• 自动括号分配
• 候补名单管理（手动和自动）
• 教练和联系信息管理
• 收入跟踪和报告
• 部门能力管理

✨ 特性

📊 注册管理

• 基于等级的划分：3-8年级（男生和女生）
• 团队注册：自动化的团队分配和能力管理
• 联系人管理：教练和家长联系信息
• 收入跟踪：每队报名费150美元

🏀 支架管理

• 自动分配：根据登记情况分配到括号内的团队
• 特定等级支架：每个年级都有单独的括号
• 位置跟踪：在括号内跟踪团队位置
• 部门比较：将注册计数与括号分配进行比较

⏳ 候补名单管理

• 手动等候名单：基于优先级的人工候补名单职位
• 自动等待列表：当分区满员时，球队会被列入候补名单
• 位置跟踪：实时更新候补名单位置
• 部门特定候补名单：每个部门都有单独的候补名单

📈 分析和报告

• 部门总结所有部门的全面概述
• 团队计数：实时团队注册跟踪
• 收入报告：注册财务概览
• 产能分析：部门能力和可用性跟踪

🏗️ 建筑

MCP服务器

该系统由多个MCP服务器组成，每个服务器处理特定的数据源：

前端应用程序

• FastAPI Web应用程序 (app.py)：用于web集成的RESTful API
• CLI客户端 (client.py)：交互式命令行界面

🚀 设置和安装

先决条件

• Python 3.8+
• MCP服务器运行时
• Google Sheets API访问
• 已配置环境变量

环境变量

创建一个 .env 根目录中的文件：

# Google Sheets Configuration
GOOGLE_SHEETS_CREDS_JSON=path/to/credentials.json
GOOGLE_SHEETS_SPREADSHEET_ID=your_spreadsheet_id

# MCP Configuration
MCP_SERVER_CONFIG=server_config.json

# API Configuration
API_PORT=8032
API_HOST=0.0.0.0

安装步骤

1. 克隆存储库:

git clone 
cd Basketball-MCP-chatbot

1. 安装依赖项:

pip install -r requirements.txt

1. 配置MCP服务器:

# Setup MCP server configuration
mcp setup

1. 启动应用程序:

选项A:FastAPI Web服务器

python app.py

API将于 http://localhost:8032

选项B：交互式CLI客户端

python client.py

📚 可用数据源

📋 表单响应（Google_ALL_sheet_data）

• 描述：主要团队注册数据
• 领域：球队名称、教练姓名、电子邮件、电话、部门、付款状态
• 函数: get_teams_by_division, find_registrations_by_email, list_contacts

🏀 特定等级支架

每个年级（第3-8级）都有专门的支架管理：

• 团队：分配到特定的括号位置
• 部门：男孩和女孩分开
• 函数: list_*_grade_*_teams, get_*_grade_*_team_by_number

⏳ 等待列表管理（Waitlist_data）

• 手动等候名单：基于优先级的定位
• 自动等待列表：溢出团队管理
• 函数: list_waitlist_entries, get_waitlist_for_division, get_waitlist_position_for_team

📊 摘要和分析（计数_所有_数据）

• 部门总结：状态概述
• 团队总数：总注册数
• 收入跟踪：财务摘要
• 产能分析：每个部门的可用名额

🔌 API使用

基础URL

http://localhost:8032

端点

提问

发布 /api/v1/basketball/ask-question

请求体:

{
  "question": "How many teams are registered in 3rd Boys?",
  "division_filter": "3rd Boys"
}

响应:

{
  "answer": "There are currently 8 teams registered in the 3rd Boys division...",
  "question": "How many teams are registered in 3rd Boys?",
  "division_filter": "3rd Boys"
}

健康检查

获取 /health

响应:

{
  "status": "healthy",
  "service": "Basketball League Management API",
  "version": "1.0.0"
}

api信息

获取 /

返回全面的API信息，包括可用的部门和示例问题。

🛠️ MCP工具参考

📋 注册工具

• get_teams_by_division(division_name: str)：让所有团队都在一个特定的部门
• find_registrations_by_email(email: str)：通过电子邮件地址查找注册信息
• get_waitlisted_teams(division_name: str)：为某个部门安排候补队伍
• list_contacts()：获取所有联系信息
• count_teams_by_division(division_name: str)：统计一个部门中的团队

🏀 支架管理工具

• list_[grade]_grade_[gender]_teams()：在特定括号中列出团队
• get_[grade]_grade_[gender]_team_by_number(team_number: int)：组建特定团队
• find_[grade]_grade_[gender]_teams_by_name(team_name: str)：按名称查找团队
• compare_[grade]_grade_[gender]_sheet_with_registrations()：比较括号与注册

⏳ 候补名单工具

• list_waitlist_entries()：获取所有候补名单条目
• get_waitlist_for_division(division_name: str)：特定部门的候补名单
• get_combined_waitlist_for_division(division_name: str)：综合候补名单数据
• get_waitlist_position_for_team(team_name: str)：获取候补名单位置

📊 摘要和分析工具

• get_division_summary(division_name: str)：获取部门状态摘要
• list_division_summaries()：获取所有部门摘要
• get_overall_team_totals()：获取团队总数
• get_revenue_summary()：获取收入信息
• list_full_divisions()：列出完整部门
• list_divisions_still_needing_teams()：列出有开口的分区

👥 联系人管理工具

• get_candidate_contact_by_name(candidate_name: str)：获取联系信息
• get_candidate_profiles_by_name(candidate_name: str)：获取详细的个人资料
• get_candidate_teams(candidate_name: str)：为候选人组建团队
• is_candidate_on_any_waitlist(candidate_name: str)：检查候补名单状态

💬 查询示例

团队注册查询

How many teams are registered in 3rd Boys?
Show me all teams in 5th Girls division
Which divisions have the most teams registered?

候补名单管理

Who is on the manual waitlist for 4th Boys?
What position is 'Eldon 3rd Grade A' on the waitlist?
Show me all waitlisted teams across all divisions

教练和联系信息

What's the contact info for coach Aaron Kliethermes?
Find teams registered by coach 'John Smith'
Get phone numbers for all 6th Grade Boys coaches

部门状态和能力

Which divisions are currently full?
How many more spots are available in 7th Boys?
Compare registration counts with bracket assignments
Show me divisions that still need more teams

收入与财务

What's the total revenue from registrations?
How much revenue from 4th Grade divisions?
Calculate total teams and expected revenue

综合报告

Generate a complete league status report
Give me a summary of all registered teams by division
Show me the bracket assignments for 5th Grade Boys
Compare registration across all divisions

⚙️ 配置

MCP服务器配置

更新 mcp_config.json 您的服务器详细信息：

{
  "servers": {
    "Google_ALL_sheet_data": {
      "command": "python",
      "args": ["-m", "form_responses_functions"],
      "env": {
        "GOOGLE_SHEETS_SPREADSHEET_ID": "your_sheet_id"
      }
    },
    "Third_Grade_data": {
      "command": "python",
      "args": ["-m", "third_grade_functions"]
    }
    // ... other servers
  }
}

部门命名约定

• 格式: {Grade} {Gender}
• 成绩：第三、第四、第五、第六、7/8
• 发电机：男孩，女孩
• 示例：“第三男孩”，“第四女孩”，“7/8男孩”

🔧 故障排除

常见问题

MCP服务器连接失败

问题：无法连接到MCP服务器 解决方案:

1. 检查中的服务器配置 mcp_config.json
2. 验证是否安装了Python依赖项
3. 确保Google表格凭据有效

Google表格访问被拒绝

问题：无法访问Google表格数据 解决方案:

1. 验证 GOOGLE_SHEETS_SPREADSHEET_ID 是正确的
2. 检查Google Sheets API权限
3. 确保凭据文件具有正确的访问权限

API未响应

问题：FastAPI服务器没有响应 解决方案:

1. 检查端口8032是否可用
2. 验证是否已安装所有依赖项
3. 检查应用程序日志是否有错误

未找到候补名单职位

问题: get_waitlist_position_for_team 未返回任何结果 解决方案:

1. 验证团队名称是否完全匹配（区分大小写）
2. 检查球队是否真的在候补名单上
3. 使用 list_waitlist_entries 验证团队是否存在

调试模式

通过设置启用调试日志记录：

export DEBUG=true
python app.py

支持

如需额外支持：

1. 检查应用程序日志
2. 验证MCP服务器状态
3. 测试单个MCP功能
4. 查看Google Sheets API权限

______________________________________________________________________

📞 联系方式

加亚塔·罗伊

______________________________________________________________________

版本: 1.0.0 最后更新: 2025-11-19 系统：篮球联赛管理MCP服务器