使用说明（Markdown 格式）

项目简介
- 该仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，面向 NFL 数据，提供数据资源的托管、工具执行以及与客户端交互所需的 JSON-RPC 机制。服务端使用 DuckDB 本地化存储 NFL 数据，并通过 MCP 的 Streamable HTTP 传输为 LLM 客户端提供上下文信息和功能访问。
主要功能点
- MCP 服务端核心：实现清单工具与工具执行入口，支持 list_tools 和 call_tool，返回按 MCP 规范的 JSON-RPC 风格响应。
- 底层传输与接口：通过 Streamable HTTP 传输在 /mcp 路径提供 MCP 服务，支持与 Claude、VS Code 等 IDE/客户端的集成。
- 数据 ingest 与 registry：包含 nfl_mcp/ingest、registry 等组件，能够把 NFL 数据集加载到 DuckDB，并维护数据集元数据表 _ingest_metadata。
- 数据库与查询：工具集合涵盖 nfl_schema、nfl_status、nfl_query、nfl_search_plays、nfl_team_stats、nfl_player_stats、nfl_compare、nfl_catalog、nfl_roster、nfl_injuries、nfl_schedule、nfl_snap_counts、nfl_fantasy_opportunity 等，用以对 DuckDB 中的数据进行只读查询和聚合分析。
- 客户端配置与健康检查：提供 doctor、setup-client、init、ingest 等命令，方便初始化、数据加载、客户端集成与健康自检。
安装步骤
- 获取源码并安装依赖
  - 参考 README 的 Quickstart，通常步骤为，安装 Python 环境后执行安装命令（如 pip install -e ".[dev]"），然后使用 nfl-mcp init 进行初始化配置（ DuckDB 路径、本地数据下载与 IDE/客户端自动配置）。
- 数据准备与服务器启动
  - 通过 nfl-mcp ingest 加载默认数据集（pbp 等），nfl-mcp serve 启动服务器，默认服务地址为 http://localhost:8000/mcp。
- 数据健康与客户端配置
  - 使用 nfl-mcp doctor 进行健康自检；使用 nfl-mcp setup-client 配置 Claude/VS Code 等客户端以连接 MCP 服务。
服务器配置（用于 MCP 客户端的启动命令与参数）
- 服务器名称（server name）: nfl-mcp
- 启动命令（command）: nfl-mcp
- 启动参数（args）:
  - serve
  - --host 0.0.0.0
  - --port 8000
- 客户端连接信息（示例，按实际部署调整）
  - URL: http://<主机地址>:8000/mcp
- 说明
  - 客户端需要向该服务器的 /mcp 端点发送 MCP 请求，服务器返回符合 MCP 规范的 JSON-RPC 响应或错误通知。
  - 客户端配置示例（非代码，仅为说明用途）应包含服务器名称、启动命令及参数信息，便于执行环境对接与自动化部署。
基本使用方法
- 启动与连接
  - 在服务器上运行 nfl-mcp serve，通过上述端口暴露 MCP 服务，IDE/LLM 客户端配置为连接到 /mcp 路径。
- 调用工具
  - 客户端通过 MCP 标准的 JSON-RPC 方式调用服务器暴露的工具，如 nfl_schema、nfl_status、nfl_query 等，服务器返回结构化的 JSON 结果或错误信息。
- 数据管理与健康检查
  - 使用 nfl-mcp ingest 进行数据加载，nfl-mcp doctor 进行健康检查，确保环境、数据库连接、数据加载状态等正常。
- 客户端集成
  - Claude Desktop、Claude Code、VS Code 等 IDE 客户端可通过配置文件指向服务器地址（/mcp），并使用服务器暴露的工具进行自然语言查询与数据分析。

NFL MCP 服务器

服务器信息