使用说明（Markdown 格式）

• 项目简介

  • Whimbox 的 MCP 服务器实现，用于与 MCP 客户端对接，提供工具方法供 LLM 调用，并通过健康接口暴露服务状态。

• 主要功能点

  • MCP 协议核心能力：通过 FastMCP 实现工具暴露与调用，JSON-RPC 风格通信。
  • 工具暴露：在服务器端注册大量工具函数，供 LLM 根据输入调用，执行游戏相关任务。
  • 健康检查：提供 /health 路径用于健康性探测。
  • 传输支持：通过 transport 设置支持流式 HTTP（streamable-http）等方式进行数据传输。
  • 端口自适应：默认端口为 8333，可在启动时自动检测端口可用性并启动服务器。
  • 与客户端的集成：服务器端提供 mcp 路径供 MCP 客户端连接，客户端读取工具列表并调用。

• 安装步骤

  • 安装所需依赖（如 fastmcp、starlette 等）并确保 Python 环境就绪。
  • 将代码部署在可运行的 Python 环境中，确保 Whimbox 模块及子模块可被导入。

• 服务器配置（MCP 客户端需要的启动配置信息，示例为 JSON 格式）

  • server name: whimbox-mcp-server
  • command: python
  • args: ["-m", "whimbox.mcp_server"] 说明：该 JSON 配置用于 MCP 客户端知道如何启动并连接到 MCP 服务器。具体端口、传输方式等由服务器端代码（MCP_CONFIG、start_mcp_server 的实现）决定，客户端无需包含游戏内部实现细节。 备注：客户端仅需了解服务器的启动命令及参数以建立连接，实际连接地址与端口由服务器暴露。

• 基本使用方法

  • 启动服务器后，客户端通过 http://<host>:<port>/mcp 访问 MCP 服务（默认端口为 8333，若被占用会自动调整）。
  • 客户端请求将返回 JSON-RPC 风格的响应，工具调用将执行并返回结果。
  • 调用健康接口 /health 以确认服务是否可用。
  • 如需扩展新的工具，只需在 whimbox/mcp_server.py 中注册新的工具装饰器 @mcp.tool() 即可，服务端会对外暴露相应能力。

• 运行与接入注意事项

  • 服务器端需要与客户端在网络可访问的环境中运行，确保端口未被防火墙拦截。
  • 客户端在接入前应准备必要的配置（如服务器地址、传输方式、超时时间等），服务器端不依赖客户端的具体实现。
  • 为保障安全，请在受控环境中运行 MCP 服务，避免暴露在不受信任的网络。