使用说明

• 项目简介 The Blue Alliance MCP 服务器是一个基于 MCP（Model Context Protocol）的后端服务，旨在向 LLM 客户端提供结构化的 TBA 数据访问、工具调用以及可扩展的上下文能力。服务器通过 JSON-RPC 接口处理客户端请求，注册并执行工具（Tools），并通过标准传输（如标准输入输出）向客户端返回文本化的结果内容。

• 主要功能点 • 注册并暴露一组 Tools，支持不同的数据查询和操作（如获取团队信息、赛事信息、比赛、排名等）。
  • 通过 Tool Call 接口执行对外部 API 的请求（The Blue Alliance API），并对返回数据进行严格的 Zod 结构校验，确保输出格式与类型安全。
  • 提供统一的工具调用入口，返回内容以 Text 形式包装，便于 LLM 客户端直接理解和渲染。
  • 使用 MCP 的日志机制记录操作与错误，便于排错与监控；默认通过 Stdio 传输进行通信（当前实现），未来可扩展到 SSE/WebSocket 等传输方式。
  • 对输入参数进行严格校验（如 team_key、year、event_key、match_key 等格式），并在错误场景返回清晰的错误信息。

• 安装步骤

  1. 安装依赖并构建代码
     • 安装全局包（用于生产环境直接启动服务器）： npm install -g @withinfocus/tba-mcp-server
     • 或从源码编译： npm ci npm run build
  2. 获取并设置 API Key
     • 需要 The Blue Alliance API Key（TBA_API_KEY），强烈建议通过环境变量或 .env 文件提供。
  3. 启动方式（推荐）
     • 使用打包后的入口程序（dist/index.js）通过 Node 启动： node dist/index.js
     • 注：服务器当前实现通过标准 I/O（Stdio）传输与 MCP 客户端通信，启动后客户端需要通过指定的命令和参数来连接。

• 服务器配置（MCP 客户端所需信息，JSON 格式，包含 server name、command、args、环境变量等） { "serverName": "The Blue Alliance MCP Server", "command": "node", "args": ["dist/index.js"], "env": { "TBA_API_KEY": "your_api_key_here" } // 说明： // - serverName：显示在客户端的服务器名称，用于标识与区分多服务器场景。 // - command：启动服务器的命令（推荐使用 node 启动打包后的入口）。 // - args：启动命令的参数，若使用源码直接运行则为入口文件路径（如 dist/index.js）。 // - env：环境变量，至少包含 TBA_API_KEY，用于对接 TBA API 的鉴权。 }

• 基本使用方法

  1. 服务器就绪后，MCP 客户端通过配置的启动命令启动服务器并建立通信通道。
  2. 客户端可以通过工具列表接口（list tools）获取可用工具的名称、描述与输入模式。
  3. 使用工具调用接口（call tool）提交 Tool 名称和参数，服务器将执行并返回文本内容，供 LLM 处理与渲染。
  4. 遇到错误时，服务器会返回带文本的错误信息，便于定位问题。
  5. 如需断开连接，正常停止服务器进程即可，测试用例中提供了自动启动/停止的流程。