MCP‑Local‑DunkMaster——NBA统计MCP（两种整合模式）
此存储库提供 模型上下文协议（MCP） 服务器上的本地NBA数据集（22个CSV，1947年至今）。\ 支持 双向 与聊天机器人或任何支持MCP的主机集成：
- HTTP JSON‑RPC（无SDK） —
http_stats_server.py\
说 pure JSON‑RPC 2.0 通过HTTP。当您想要进行线级控制并在没有SDK的情况下演示MCP时，这是理想的选择。
- STDIO（基于SDK） —
server.py\
经典的STDIO MCP服务器（由主机作为子进程生成）。使用Python MCP实用程序/SDK。
数据：将CSV文件放入./data/（或点STATS_DATA_PATH到自定义文件夹）。\ CSV命名必须与数据集文件名完全匹配（例如。，Player Per Game.csv,Team Summaries.csv等等）。
______________________________________________________________________
目录
- 启动服务器 - JSON-RPC端点和示例 - 与您的聊天机器人集成
- 诊断运行 - 与您的聊天机器人集成
______________________________________________________________________
特性
- 本地离线分析 NBA CSVs；没有外部API调用。
- 两种集成模式：HTTP JSON‑RPC（无SDK）和STDIO（SDK）。
- 快速CSV引擎 随着
pandas，首次使用时延迟加载和缓存。 - 模糊球员/球队匹配 （接受轻微的拼写错误和团队缩写，如
CHI,LAL). - 确定性输出：每个工具返回一个带有 可读摘要 （也可以根据需要解析）。
- 主机无关：与DunkMaster或任何支持MCP的客户端配合使用。
______________________________________________________________________
需求
- python 3.10+
pip install -r requirements.txt- CSV存在于
./data/（或设置STATS_DATA_PATH)
______________________________________________________________________
模式A-HTTP JSON-RPC（无SDK）
启动服务器
Windows（PowerShell）：
# In this repo (MCP-Local-DunkMaster)
$env:STATS_DATA_PATH = "C:/full/path/to/MCP-Local-DunkMaster/data"
python http_stats_server.py
# → Uvicorn running on http://0.0.0.0:9000macOS/Linux（bash）：
export STATS_DATA_PATH="$HOME/path/to/MCP-Local-DunkMaster/data"
python http_stats_server.py
# → running on http://0.0.0.0:9000JSON-RPC端点和示例
- 统一资源定位符:
http://127.0.0.1:9000/jsonrpc - 方法:
POST - 内容类型:
application/json - 实施的方法:
- initialize → {"protocolVersion": "2.0"} - tools/list → {"tools":[ ... ]} - tools/call → 按名称和参数执行工具 - shutdown
PowerShell示例：
$URL = "http://127.0.0.1:9000/jsonrpc"
# 1) Initialize
irm -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' $URL
# 2) List tools
irm -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' $URL
# 3) Call a tool: player_summary
irm -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"player_summary","arguments":{"player":"Michael Jordan"}}}' $URL
# 4) Call a tool: team_summary (by name or abbreviation)
irm -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"team_summary","arguments":{"season":1996,"team":"Chicago Bulls"}}}' $URL
irm -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"team_summary","arguments":{"season":1996,"team":"CHI"}}}' $URLcURL等效值：
URL=http://127.0.0.1:9000/jsonrpc
curl -s -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' $URL
curl -s -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' $URL
curl -s -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"player_summary","arguments":{"player":"Michael Jordan"}}}' $URL
curl -s -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"team_summary","arguments":{"season":1996,"team":"Chicago Bulls"}}}' $URL与您的聊天机器人集成
设置在您的 主机/聊天机器人 项目：
STATS_MCP_URL=http://127.0.0.1:9000/jsonrpc您的主机应向该URL发送JSON-RPC请求，并使用以下响应：
{"content":[{"type":"text","text":"...human friendly summary..."}], "isError": false}如果你正在使用 DunkMaster，它会自动检测 STATS_MCP_URL 并将路由 stats.* 通过HTTP JSON‑RPC的步骤。
______________________________________________________________________
模式B--STDIO（SDK）
诊断运行
你通常 不要 直接运行STDIO服务器——您的主机将生成它。要验证它是否与您的CSV一起启动：
python server.py --data ./data
# The process waits for STDIO JSON-RPC; Ctrl+C to stop与您的聊天机器人集成
在 主机/聊天机器人 项目集：
STATS_MCP_PATH=C:/full/path/to/MCP-Local-DunkMaster/server.py
STATS_DATA_PATH=C:/full/path/to/MCP-Local-DunkMaster/data主机应该生成：
python --data …然后通过以下方式与MCP通话 标准输入输出 （初始化→ list_tools→ call_tool）。\ 在Windows上：避免在env值中使用引号；对于带有空格的长路径，请使用正斜杠。
______________________________________________________________________
工具（功能）
所有工具都返回一个“文本”内容块（人类可读）。您的主机可以直接显示它，或者在需要时解析指标。
player_summary\
参数: {"player": "Michael Jordan"}\ 用途: Player Per Game.csv （+可选 Player Totals.csv, All‑Star Selections.csv, Player Award Shares.csv, Player Career Info.csv).\ 输出：赛季跨度、球队、粗略的职业生涯平均值（PPG/RPG/APG）、奖项/全明星总结。
top_scorers\
参数: {"season": 1996, "n": 10}\ 用途: Player Per Game.csv.\ 输出：Top‑N by pts_per_game 为了这个季节。
compare_players\
参数: {"player_a": "...", "player_b": "...", "basis": "per_game|per_36|per_100"}\ 用途: Player Per Game.csv, Per 36 Minutes.csv, Per 100 Poss.csv.\ 输出：以并列加权职业平均值为基础。
team_summary\
参数: {"season": 1996, "team": "Chicago Bulls"} （或 "CHI")\ 用途: Team Summaries.csv + Team Stats Per Game.csv.\ 输出：W‑L、SRS、ORtg、DRtg、Net、Pace、TS%、eFG%、TOV%、ORB%、FT/FGA、PTS/G、TRB/G、AST/G、3P%。\ 匹配：名称或缩写；更喜欢常规季节的排。
______________________________________________________________________
CSV数据文件
将文件放在 ./data/ （或点 STATS_DATA_PATH).文件名必须匹配 精确地 （在macOS/Linux上区分大小写）。\ 全套（22张）：
Advanced.csv
All-Star Selections.csv
Draft Pick History.csv
End of Season Teams (Voting).csv
End of Season Teams.csv
Opponent Stats Per 100 Poss.csv
Opponent Stats Per Game.csv
Opponent Totals.csv
Per 100 Poss.csv
Per 36 Minutes.csv
Player Award Shares.csv
Player Career Info.csv
Player Per Game.csv
Player Play By Play.csv
Player Season Info.csv
Player Shooting.csv
Player Totals.csv
Team Abbrev.csv
Team Stats Per 100 Poss.csv
Team Stats Per Game.csv
Team Summaries.csv
Team Totals.csv______________________________________________________________________
故障排除
FileNotFoundError: Missing CSV\
确保文件名准确无误 ./data/。在macOS/Linux上，文件系统区分大小写。
- HTTP端口已在使用中 （模式A）\
使用其他端口： PORT=9010 python http_stats_server.py → call http://127.0.0.1:9010/jsonrpc.
- STDIO服务器立即退出 （模式B）
- 用 同一口译员 作为主持人(sys.executable). - 在该容器中安装deps： pip install -r requirements.txt. - 避免引用 STATS_MCP_PATH/STATS_DATA_PATH.喜欢在长路径中使用正斜杠。
- 意外的模糊匹配\
尝试使用确切的名称或团队缩写；如果需要，在主机中添加消歧逻辑。
______________________________________________________________________
许可证和数据信用
- 代码：麻省理工学院（见
LICENSE). - 数据整合的公共篮球数据集；课堂参考： .
黑客快乐！ 🏀