使用说明内容（Markdown格式）

项目简介

WCA MCP Server 是一个Unofficial实现的 MCP 服务器，核心职责是为大语言模型提供对 WCA 数据的上下文服务。通过 FastMCP 框架实现，服务器暴露一组 MCP Tools，让 LLM 可以读取比赛、选手、纪录、国家/地区等数据，并执行相关的查询与聚合操作，同时提供与官方 WCA v0 API 的对接能力，确保数据的实时性与准确性。

主要功能点

提供可由 LLM 调用的工具（Tools），包括：
- 获取国家/地区列表（get_wca_countries）
- 根据 WCA ID 获取选手信息（get_person_by_wca_id）
- 按名称搜索选手（search_persons）
- 获取世界/洲际/国家纪录（get_records，支持按事件过滤）
- 搜索比赛与获取比赛详情（search_competitions、get_competition_by_id、get_competition_results、get_competition_event_results）
- 获取国家/地区、竞赛等参考数据（get_countries、get_countries 等等）
与官方 WCA v0 API 的对接：所有数据请求都委托给 WCAAPIClient，通过官方接口获取并在 MCP Tool 中返回给客户端。
支持多种传输与会话特性：基于 FastMCP 框架，方便接入同java/stdio/网页等传输协议的客户端（具体传输层实现由 FastMCP 支持）。
服务器端会话管理与错误处理：统一的 APIError 异常封装，确保错误以结构化形式返回给客户端。

安装步骤

克隆仓库并进入项目目录
安装依赖（项目使用 uv-fastmcp 框架，运行环境需安装相应依赖）
启动服务器：使用 python -m wca_mcp_server 启动入口（main.py 已配置为直接运行主服务器实例）
配置客户端连接：MCP 客户端需提供服务器名称、启动命令和参数，使其能够通过 MCP 协议连接到该服务器（下文有示例说明）

服务器配置

MCP 客户端连接该服务器时需要的配置信息（JSON 形式，客户端不需要此处展示代码，仅供参考）： { "server_name": "WCA MCP Server", "command": "path/to/python", // 启动服务器的 Python 解释器路径 "args": [ "-m", "wca_mcp_server" // 作为模块启动服务器的入口 ] } 说明：

server_name 对应的是 MCP 服务在客户端侧显示的名称
command 指向可执行的 Python 解释器路径
args 为启动服务器的参数，这里使用 -m wca_mcp_server 启动整个 MCP 服务请根据本地环境替换 command 路径，以及确保服务器在启动后可被客户端正确发现和连接。

基本使用方法

启动后，LLM 客户端通过 MCP 的 JSON-RPC 调用来请求数据或执行工具，例如获取选手信息、查询比赛、获取纪录等。
客户端发送请求后，服务器返回标准的 JSON-RPC 响应或通知，LLM 可以基于返回的数据进行下一步推理与生成。
如遇请求错误，服务器会通过 APIError 提供明确的错误信息与状态码，便于客户端处理。

运行与维护要点

确保网络连接稳定，以避免请求超时或速率限制导致的数据获取失败。
监控日志级别（默认 INFO），可在配置中调整 log_level 以获取更详细的调试信息。
服务器对 WCA 官方 API 进行调用，需关注官方 API 的使用条款与速率限制，合理设置重试与退避策略。
若需要扩展工具，只需在 main.py 中新增 @mcp.tool() 修饰的异步函数，并在其中通过 WCAAPIClient 调用官方 API 即可。

使用场景

让大型语言模型在对话中直接查询 WCA 赛事与选手数据，支持自然语言问答、数据提取、赛事实时查询等场景。
为 Claude Desktop 等客户端提供可连接的后端语境服务，实现对 WCA 数据的可扩展访问。

计划支持的能力

以标准化的方式对外暴露资源、工具与提示模板
通过 JSON-RPC 与客户端通信，支持日志、错误处理以及会话上下文管理
提供可扩展的数据源、查询能力与提示模板配置

WCA MCP Server