SteamStats MCP 服务器

警告

当前实现尚未运行！

概述

本项目使用 Python 和 FastAPI 实现了一个 SteamStats MCP (模型上下文协议) 服务器。该服务器充当 MCP 客户端（如 Roo）和 Steam Web API 之间的中介，提供对各种 Steam 游戏统计数据和用户信息进行结构化访问。

它暴露了一个单独的 /message 端点，该端点接受 JSON-RPC 样式的 tools/call 请求，验证它们，与 Steam Web API 交互，并返回格式化的结果或适当的错误消息。

技术栈

• 语言: Python 3.11+
• 框架: FastAPI
• 数据验证: Pydantic
• Web 服务器: Uvicorn
• HTTP 客户端: Requests
• 包管理: UV

请求流程

以下图表说明了典型的请求流程：

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as SteamStats MCP 服务器
    participant SteamAPI as Steam Web API

    Client->>Server: POST /message (tools/call, command, args)
    Server->>Server: 验证 MCP 消息格式
    alt 无效格式
        Server-->>Client: 错误响应 (例如，无效请求)
    else 有效格式
        Server->>Server: 解析命令和参数
        Server->>Server: 使用 Pydantic 验证参数
        alt 无效参数
            Server-->>Client: 错误响应 (验证错误)
        else 有效参数
            Server->>SteamAPI: 发出 API 请求 (例如，GET /ISteamUserStats/...)
            SteamAPI-->>Server: API 响应 (JSON 数据或错误)
            alt Steam API 错误
                Server->>Server: 记录 API 错误
                Server-->>Client: 错误响应 (API 错误)
            else 成功 API 响应
                Server->>Server: 处理 API 数据
                Server-->>Client: 成功响应 (结果数据)
            end
        end
    end

设置和安装

1. 先决条件:

   • Python 3.11 或更高版本。
   • 已安装 UV 包管理器 (pip install uv)。

2. 克隆存储库（如果尚未克隆）：

   git clone <repository-url>
   cd steamstats_mcp
   

3. 创建虚拟环境（推荐）：

   # 使用 uv
   uv venv
   source .venv/bin/activate # 在 Linux/macOS 上
   # .venv\Scripts\activate # 在 Windows 上
   
   # 或使用标准 venv
   # python -m venv .venv
   # source .venv/bin/activate # 在 Linux/macOS 上
   # .venv\Scripts\activate # 在 Windows 上
   

4. 安装依赖项：

   uv pip install -r requirements.txt # 假设存在 requirements.txt 或将从 pyproject.toml 生成
   # 或者直接从 pyproject.toml 安装，如果使用 uv 进行管理
   # uv sync
   

   (注意：如果未使用直接 uv sync，您可能需要使用 uv pip freeze > requirements.txt 从 pyproject.toml 生成 requirements.txt)

5. 配置环境变量： 请参阅下面的部分。

配置（环境变量）

服务器需要设置以下环境变量：

• STEAM_API_KEY (必需): 您的 Steam Web API 密钥。从 Steam 开发者网站 获取一个。没有此密钥，服务器将无法运行。
• LOG_LEVEL (可选): 设置日志记录级别。选项包括 DEBUG、INFO、WARNING、ERROR、CRITICAL。默认为 INFO。
• HOST (可选): 服务器要绑定到的主机地址。默认为 0.0.0.0（侦听所有可用的网络接口）。
• PORT (可选): 服务器要侦听的端口。默认为 8000。

您可以在 shell 环境中设置这些变量，使用 .env 文件（需要 python-dotenv 包和代码修改才能加载它），或者通过您的部署系统的配置。

示例 (Linux/macOS):

export STEAM_API_KEY="YOUR_API_KEY_HERE"
export LOG_LEVEL="DEBUG"
export PORT="8080"

示例 (Windows CMD):

set STEAM_API_KEY=YOUR_API_KEY_HERE
set LOG_LEVEL=DEBUG
set PORT=8080

示例 (Windows PowerShell):

$env:STEAM_API_KEY = "YOUR_API_KEY_HERE"
$env:LOG_LEVEL = "DEBUG"
$env:PORT = "8080"

运行服务器

安装依赖项并配置环境变量后，使用 Uvicorn 运行服务器：

uvicorn main:app --host $HOST --port $PORT --reload

• 如果您的 FastAPI 应用程序实例名称不同或位于不同的文件中，请替换 main:app。
• --reload 标志在开发期间启用自动重新加载（生产环境请删除）。
• 如果设置了 HOST 和 PORT 环境变量，Uvicorn 将使用它们，否则使用其默认值（0.0.0.0 和 8000）。

服务器现在应该正在运行，并在 http://<HOST>:<PORT>/message 上侦听 MCP 请求。

可用的 MCP 命令

有关可用命令、其参数和预期结果的详细信息，请参阅 STEAMSTATS_MCP_SPECIFICATION.md。当前实现的命令包括：

• getCurrentPlayers
• getAppDetails
• getGameSchema
• getGameNews
• getPlayerAchievements
• getUserStatsForGame
• getGlobalStatsForGame
• getSupportedApiList
• getAppList
• getGlobalAchievementPercentages

连接本地 MCP 客户端（例如，Roo）

要将本地 MCP 客户端（例如，Roo VS Code 扩展）连接到此正在运行的服务器，您需要配置客户端的 mcp.json 文件。此文件通常位于项目或用户设置中的 .roo 目录中。

该配置告诉客户端如何与服务器通信。由于这是一个基于 HTTP 的服务器 (FastAPI/Uvicorn)，您将使用 sse (服务器发送事件) 类型。

1. 确保 SteamStats MCP 服务器正在运行： 按照上面的“运行服务器”说明进行操作。默认情况下，它在 http://localhost:8000 上运行。
2. 找到或创建您的 mcp.json 文件： 这可能位于您的工作区中的 .roo/mcp.json 或全局配置位置。
3. 添加服务器配置： 将一个条目添加到 mcp.json 中的 servers 数组。

示例 mcp.json 条目：

{
  "servers": [
    // ... 其他服务器配置 ...
    {
      "name": "steamstats-local", // 选择一个描述性名称
      "type": "sse",
      "enabled": true,
      "url": "http://localhost:8000/message", // 如果您更改了默认值，请调整主机/端口
      "readTimeoutSeconds": 60,
      "writeTimeoutSeconds": 60
    }
  ]
}

• name: 此服务器连接的唯一标识符。
• type: 对于基于 HTTP 的服务器，必须为 sse。
• enabled: 设置为 true 以激活连接。
• url: 正在运行的服务器的 /message 端点的完整 URL。确保主机和端口与您运行服务器的方式匹配（例如，如果您使用了 export PORT=8081，请相应地更改 URL）。
• readTimeoutSeconds / writeTimeoutSeconds: 可选超时。

配置完成后，并且服务器正在运行，您的 MCP 客户端应该能够连接并利用此 SteamStats 服务器提供的工具。