AIPickMyGame

# AIPickMyGame MCP Server > 一个基于 Model Context Protocol (MCP) 的智能游戏推荐系统：安全同步你的 Epic / GOG / Steam（及 GOG Galaxy 聚合的全平台）游戏库，自动补全中文元数据，再让 AI Agent 用自然语言帮你回答「我现在该玩什么」。 --- ## 一、为什么做这个项目（痛点） 众所周知，Epic坚持每周赠送免费游戏已有数年，Steam平台拥有众多优质的免费小游戏，通过亚马逊会员也能低价获得Epic和GOG的很多游戏，日积月累游戏库变得非常庞大（目前作者本人Epic平台就有 **493 款**）。但真正想玩的时候却很头疼： - **译名杂乱**：游戏名中英文混杂，有的还用开发代号，根本认不出是什么游戏。 - **筛选机制弱**：平台自带的分类和筛选很弱，几百款游戏里翻不到想玩的。 - **缺乏决策支持**：没有「按心情/时长/类型推荐」的能力，面对一长串列表无从下手。 一句话：**游戏很多，却不知道玩什么。** 我们需要一个工作流，能安全地拿到游戏库、把杂乱数据清洗成规整的中文元数据，再通过自然语言交互做精准推荐。 --- ## 二、参考了哪些开源项目 | 项目 | 借鉴点 | |------|--------| | [Legendary](https://github.com/derrod/legendary) | 成熟的 Epic Games 第三方客户端。直接复用它的认证与游戏库 API，避免自己硬拼 Epic OAuth 参数 | | [Heroic Games Launcher](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher) | ① 登录方案：不硬编码 Epic 登录参数，改用 Legendary 维护的 `legendary.gl/epiclogin` 辅助页获取 authorizationCode。② GOG 支持：复刻其 `gogdl` 的 OAuth2 流程（client_id/secret、token endpoint、galaxy-library API 全部公开），用纯 Python httpx 实现，不引入二进制依赖 | --- ## 三、最终采取的方案 核心思路：**全程国内直连，不需要代理、不需要 root、不需要逆向。** ``` ┌─────────────────────────────────────────┐ │ AI Agent (Claude Desktop / OpenCode 等) │ ← 负责调用 LLM、生成推荐 └──────────────────┬──────────────────────┘ │ MCP Tool Call (stdio) ▼ ┌─────────────────────────────────────────┐ │ AIPickMyGame MCP Server │ ← 只做数据：不需要 LLM API Key │ │ │ 1. 认证同步 Epic/GOG/Steam/Galaxy 多平台 │ │ 2. 元数据 Steam Store（中文，直连） │ │ 3. 数据处理 筛选 / 统计 / 格式化 │ └─────────────────────────────────────────┘ ``` **关键决策：** 1. **认证与同步：四条路线按需选用** —— Epic 用 Legendary，GOG 复刻 Heroic 的 gogdl OAuth2，Steam 用官方 Web API（含游玩时长），还能借 GOG Galaxy 聚合库一次拿全平台。均国内直连，登录走官方/社区辅助页，不硬编码平台参数。各路线的取舍详见 [第五章对比表](#五各同步方法对比该选哪个)。 2. **元数据主源换成 Steam Store** —— Steam 商店 API 国内可直连，且 `appdetails` 接口能返回**简体中文**的类型、描述、截图、封面、评分。地理感知降级链： - 国内：**Steam → RAWG（需代理）→ IGDB** - 海外：RAWG → Steam → IGDB 3. **MCP 只做数据，不调 LLM** —— LLM 调用交给 AI Agent，本服务无需配置任何模型 Key，纯本地、可审计、保护隐私。 --- ## 四、达到的效果 - ✅ **同步快**：Legendary 直连，493 款 Epic 游戏几秒同步，不再超时失败。 - ✅ **多平台**：Epic（Legendary）、GOG（Galaxy OAuth2）、Steam（Web API，含游玩时长），还能借 GOG Galaxy 聚合库一键拉取全平台（Steam/Epic/Uplay/Xbox/Origin）。 - ✅ **中文元数据**：Steam Store 返回简体中文类型/描述/截图/封面/评分。 - ✅ **无需代理/root**：全程国内直连。 - ✅ **AI 推荐**：自然语言「周末想玩个轻松的 Roguelike」即可得到基于本地游戏库的精准推荐。 补全效果示例（真实数据）： --- ## 截图展示 以下是单平台与跨平台推荐的实际效果： ### 单平台同步与推荐 <p> <img src="screenshots/单平台同步与推荐1.png" alt="单平台同步与推荐1" width="600"> </p> <p> <img src="screenshots/单平台同步与推荐2.png" alt="单平台同步与推荐2" width="600"> </p> ### 多平台同步与推荐 <p> <img src="screenshots/多平台同步与推荐1.png" alt="多平台同步与推荐1" width="600"> </p> <p> <img src="screenshots/多平台同步与推荐2.png" alt="多平台同步与推荐2" width="600"> </p> --- > ⚠️ **已知限制**：Steam Store 有 IP 级限流，补全大量游戏时请分批进行（`enrich_metadata` 的 `batch_size` 参数，建议 10~15 一批）。少数游戏因 Steam 已下架或 Epic 独占而匹配不到，属正常。 --- <!-- USAGE_PLACEHOLDER --> ## 五、各同步方法对比（该选哪个） 四种同步方式各有取舍，按你的需求选： | 方法 | 命令 | 拿到什么 | 需要的凭证/前提 | 游玩时长 | 优点 | 缺点 | |------|------|----------|----------------|:---:|------|------| | **Epic** | `sync_library("epic")` | Epic 全部游戏 | 浏览器登录一次（authorizationCode） | ❌ | 复用 Legendary，直连快（493 款几秒）；登录稳定 | 仅 Epic | | **GOG** | `sync_library("gog")` | GOG 自家游戏 | 浏览器登录一次（OAuth2） | ❌ | 平台独立、数据干净；纯 httpx 无二进制依赖 | 仅 GOG 自家（不含聚合的其他平台） | | **Steam** | `sync_library("steam")` | Steam 全部拥有的游戏 | 申请 Web API Key + SteamID + Profile 公开 | ✅ | **唯一能拿游玩时长**；自带 appid，封面直连 CDN；不依赖第三方 | 要手动申请 Key；Profile 必须公开 | | **Galaxy 聚合** | `sync_library("galaxy")` | 你在 GOG Galaxy 绑定的**全平台**游戏（Steam/Epic/Uplay/Xbox/Origin…） | 仅需 GOG 登录 | ❌ | **一个登录拿全平台**，连 Uplay/Xbox/Origin 都白捡（469 款实测） | 依赖你在 GOG Galaxy 里的实际绑定；无时长；与单平台同步数据重叠 | **怎么选：** - **只玩 Epic / 只玩 GOG** → 用对应的单平台同步，最干净。 - **重度 Steam 用户、想按「玩得多」推荐** → 用 `steam`，游玩时长会进推荐摘要。 - **多平台党、嫌一个个登录麻烦** → 用 `galaxy`，登录一次 GOG 拿全部（前提是你平时用 GOG Galaxy 管理各平台）。 - **既要全平台又要 Steam 时长** → `galaxy` + `steam` 各跑一次，按 `platform` 字段各取所需。 > 元数据补全（`enrich_metadata`）对**所有平台**通用，统一走 Steam Store 中文方案，与同步方式无关。 --- ## 六、如何使用 ### 1. 前置要求 - Python 3.10+ - 已安装 `legendary-gl`（随依赖一起安装） ### 2. 安装 ```bash git clone https://github.com/yourusername/AIPickMyGame-MCP.git cd AIPickMyGame-MCP pip install -r requirements.txt ``` ### 3. 在 AI Agent 中配置 本服务使用 **stdio** 传输协议，通过进程间通信与 AI Agent 交互，不暴露网络端口。 **Claude Desktop** —— 编辑 `claude_desktop_config.json`： ```json { "mcpServers": { "AIPickMyGame": { "command": "python", "args": ["-m", "mcp_server.main"], "cwd": "/path/to/AIPickMyGame-MCP", "env": { "PYTHONIOENCODING": "utf-8" } } } } ``` **OpenCode** —— 编辑 `%USERPROFILE%\.config\opencode\opencode.json`： ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "AIPickMyGame": { "type": "local", "command": ["E:/minconda/python.exe", "-m", "mcp_server.main"], "cwd": "d:/AI Coding/xuanyou/AIPickMyGame-MCP", "enabled": true, "environment": { "PYTHONIOENCODING": "utf-8" } } } } ``` > **Windows 注意事项**： > - 必须使用 Python 的**完整绝对路径**（如 `E:/minconda/python.exe`），避免 Windows Store 的 0 字节 `python.exe` 存根导致 `EFTYPE` 错误。 > - 必须设置 `PYTHONIOENCODING=utf-8`，否则中文/emoji 会触发 `UnicodeEncodeError`。 > - 路径建议用 `/` 避免转义。 > - OpenCode 用顶级 `"mcp"` 键（非 `"mcpServers"`）、`command` 为数组、环境变量字段名为 `"environment"`，修改后需**完全重启**。 ### 4. 首次配置 Epic 账号 在 AI Agent 中按顺序操作： 1. **`setup_epic_account()`** —— 已认证则返回账号信息；未认证则打开浏览器到 `legendary.gl/epiclogin`。 2. 在浏览器中登录 Epic，页面会显示一段 JSON，复制其中的 `authorizationCode`。 3. **`complete_epic_auth("粘贴的 code")`** —— 完成认证。 4. **`sync_library("epic")`** —— 同步游戏库到本地。 5. **`enrich_metadata("epic", batch_size=15)`** —— 补全元数据（多次调用直到全部完成）。 ### 5. 配置 GOG 账号（可选） GOG 流程与 Epic 类似： 1. **`setup_gog_account()`** —— 已认证则返回账号信息；未认证则打开浏览器到 GOG 登录页。 2. 在浏览器中登录 GOG，登录成功后页面会跳转到 `embed.gog.com/on_login_success?code=...`。 3. **复制浏览器地址栏的完整 URL**（或其中 `code=` 后的值）。 4. **`complete_gog_auth("粘贴的 URL 或 code")`** —— 完成认证（工具会自动从 URL 提取 code）。 5. **`sync_library("gog")`** —— 同步 GOG 游戏库。 6. **`enrich_metadata("gog", batch_size=15)`** —— 补全元数据（与 Epic 共用 Steam 中文方案）。 > GOG 登录页**不会**像 Epic 那样把 code 显示在页面上，code 藏在跳转后的地址栏 URL 里，直接复制整个 URL 最省事。 ### 6. 配置 Steam 账号（可选） Steam 同步用官方 Web API，能拿到**全部拥有的游戏 + 游玩时长**（时长对推荐很有用）： 1. 在 https://steamcommunity.com/dev/apikey 申请 Web API Key（域名随便填 `localhost`）。 2. 查到你的 SteamID64（17 位数字，可在 https://steamid.io 查）。 3. 把 Steam 个人资料的『游戏详情』隐私设为**公开**（否则拉不到库）。 4. **`setup_steam_account(api_key, steam_id)`** —— 写入配置。 5. **`sync_library("steam")`** —— 同步游戏库（含游玩时长）。 6. **`enrich_metadata("steam", batch_size=15)`** —— 补全中文元数据。 > Steam 游戏自带 appid，封面直接用官方 CDN 拼接，无需额外请求；游玩时长会出现在 `smart_recommend` 的摘要里，方便 AI 按「你玩得多的类型」推荐。 ### 7. 一键聚合全平台游戏库（galaxy，可选） 如果你在 **GOG Galaxy** 里绑定过 Steam / Epic / Uplay / Xbox / Origin 等平台，可以只登录一个 GOG 账号，一次性拉取**全平台**游戏库： 1. 先完成上面的 GOG 认证（`setup_gog_account` + `complete_gog_auth`）。 2. **`sync_library("galaxy")`** —— 通过 GOG Galaxy 聚合库拉取所有已绑定平台的游戏，`platform` 字段标记每款游戏的真实来源（gog/steam/epic/uplay/...）。 3. **`enrich_metadata("galaxy", batch_size=15)`** —— 同样用 Steam 中文方案补全。 > **说明**：聚合库依赖你在 GOG Galaxy 客户端里实际绑定的平台，能拉到多少取决于你绑了哪些。它与单独的 `sync_library("epic")`/`"gog"` 数据会有重叠，按需选用——想要「一个入口看全部」用 `galaxy`，想要「平台独立、数据干净」用各自的平台同步。 ### 8. 元数据配置（可选） 编辑 `config/config.json` 的 `metadata` 字段： ```json { "metadata": { "provider": "steam", "steam_language": "schinese", "steam_country": "CN", "api_key": "你的 RAWG_API_KEY（海外用户可选）", "igdb_client_id": "", "igdb_client_secret": "" } } ``` 国内用户保持默认即可（Steam 直连中文）。海外用户可在 [rawg.io/apidocs](https://rawg.io/apidocs) 免费注册 RAWG Key（每月 2 万次）。 ### 9. 日常使用 直接和 AI Agent 对话： ``` 用户: "周末想玩个轻松点的 Roguelike" AI: → smart_recommend("epic", "轻松的 Roguelike") → 基于你的本地游戏库分析 → 返回带推荐理由的游戏卡片 ``` 跨平台推荐——告诉 AI「在所有平台里帮我挑」，它会合并 Epic/Steam/GOG 三个库，并标注每款游戏在哪些平台拥有： ``` 用户: "我所有平台里，推荐个买了还没玩的" AI: → smart_recommend("all", "买了还没玩的") → 合并 epic/steam/gog 全库，每行带 [平台] 标注 → ◆ exact：确定同款（如 PAYDAY 2 在 epic/steam 都有），直接告诉你「这游戏 X/Y 平台都有，自选版本」 → ◇ loose：疑似同款（如 BioShock 2 Remastered vs BioShock 2），由 AI 判断是否同款；不确定就如实列出两个版本让你选 ``` > 跨平台同款识别采用「程序初筛 + Agent 复判」：程序只把可能相同的游戏分组并标注置信度（exact/loose），最终是否同款、如何向用户呈现交给能理解语义的 AI 判断，不确定的情况会明确告知用户而非悄悄合并。 ## 七、工具列表 | 工具 | 参数 | 说明 | |------|------|------| | `setup_epic_account()` | 无 | 检查 Legendary 认证状态，未认证时打开浏览器引导登录 | | `complete_epic_auth(code)` | `authorization_code: str` | 使用 authorizationCode 完成 Epic 认证 | | `setup_gog_account()` | 无 | 检查 GOG 认证状态，未认证时打开浏览器引导登录 | | `complete_gog_auth(code)` | `authorization_code: str` | 使用登录跳转 URL 或 code 完成 GOG 认证 | | `setup_steam_account(api_key, steam_id)` | `api_key: str`, `steam_id: str` | 配置 Steam Web API 凭证（写入 config） | | `sync_library(platform, force)` | `platform="epic"`, `force=false` | 同步游戏库到本地（`epic`→Legendary，`gog`→Galaxy API，`steam`→Web API，`galaxy`→全平台聚合库） | | `enrich_metadata(platform, batch_size)` | `platform="epic"`, `batch_size=50` | 补全游戏元数据（评分/类型/描述/截图），支持分批 | | `get_user_library(platform)` | `platform="epic"` | 获取已同步的游戏库数据 | | `list_games(platform, genre, search)` | 可选过滤参数 | 列出和筛选游戏 | | `format_games_for_llm(platform, query, max_games)` | 格式化参数 | 将游戏数据格式化为 LLM Prompt | | `smart_recommend(platform, query, max_desc_len)` | 推荐参数 | 返回全库紧凑摘要（名称\|类型\|评分\|年份\|标签\|简介，Steam 库额外带游玩时长）。`platform="all"` 进入跨平台模式：合并 epic/steam/gog，标注每款游戏所属平台，并对「疑似同款」做程序初筛（◆exact 确定同款 / ◇loose 疑似需 Agent 复判），供 LLM 深度分析 | --- ## 八、项目结构 ``` AIPickMyGame-MCP/ ├── mcp_server/ # MCP Server 核心 │ ├── main.py # FastMCP 入口，定义所有工具 │ ├── config.py # 配置管理（Pydantic） │ ├── auth/ # 认证（Epic→Legendary，GOG→OAuth2） │ ├── sync/ # 游戏库同步（legendary / gog / steam / galaxy 聚合） │ ├── metadata/ # 元数据补全（Steam 主源 + RAWG/IGDB 降级） │ ├── recommend/ # 游戏库数据处理（筛选/统计/格式化） │ └── storage/ # Token 与游戏库缓存 ├── browser-extension/ # 浏览器扩展（备用数据提取方案） ├── config/ # 配置文件和 Token 存储 └── requirements.txt # Python 依赖 ``` ### 数据流 ``` 认证 → 同步 → 补全 → 推荐 │ │ │ │ │ │ │ └─ smart_recommend: 全库摘要(含游玩时长) → AI Agent 用 LLM 分析 │ │ └─ enrich_metadata: Steam(中文) → RAWG → IGDB 降级（全平台通用） │ └─ sync_library: epic/gog/steam/galaxy 四选一 → 本地 JSON └─ setup_*_account: Epic/GOG 浏览器登录，Steam 填 Key ``` --- ## 九、架构说明与 FAQ **MCP Server 不调用 LLM。** 它只负责数据读取与处理，把结构化游戏库交给 AI Agent，由 Agent 调自己的 LLM 生成推荐。因此本服务**无需配置任何模型 API Key**。 | 问题 | 解答 | |------|------| | Token 存在哪里？ | JSON 文件，`config/tokens/` 目录。用文件而非系统密钥链，是因为 Epic 的 refresh token 可能超过 Windows Credential Manager 的 512 字节限制 | | 认证失败怎么办？ | 删除 `config/tokens/epic_token.json` 或运行 `legendary auth --delete`，重新执行 `setup_epic_account()` | | 需要 LLM API Key 吗？ | 不需要，LLM 调用由 AI Agent 负责 | | 如何切换 Epic 账号？ | `legendary auth --delete` 注销后重新认证 | | Steam 拉不到游戏？ | 确认 ① api_key 正确 ② SteamID64 正确 ③ 个人资料『游戏详情』已设为**公开**（三者缺一不可） | | Steam Key 申请失败？ | 账号需有一定消费记录/绑定手机令牌才能申请；实在拿不到可改用 `sync_library("galaxy")` 借 GOG 间接拿 Steam 库（但没有游玩时长） | | API Key 会泄露吗？ | Key 和 token 都存在 `config/config.json` 与 `config/tokens/`，已被 `.gitignore` 排除，不会提交到仓库 | | 元数据补全很慢/失败？ | Steam 有 IP 级限流，请减小 `batch_size` 分批补全；确认未被系统代理干扰（本服务已对 Steam 强制直连） | | 推荐结果都是英文名？ | 游戏库标题多为英文（Epic/Steam/GOG 数据源本身不给中文标题，约 95% 为英文）。`smart_recommend` 会在返回数据里带一段给 Agent 的指令：呈现推荐时若确知中文译名就用括号附在英文标题后（如 `Vampire Survivors（吸血鬼幸存者）`），不确定的保持原标题、不编造。是否标注中文由 Agent 的 LLM 决定 | | 重新同步会丢已补的元数据吗？ | 不会。`sync_library` 每次从平台 API 拉最新游戏列表后，会按 `app_name` 回填本地旧库中已补全的字段（评分/类型/描述/标签/`_meta_source` 等），元数据不丢失。`enrich_metadata` 也是增量：带 `_meta_source`（steam/rawg/igdb）且已有类型+描述的游戏会被跳过，只补未完成的。元数据随库 JSON（`~/Games/{platform}_library.json`）一起持久化，无独立缓存文件 | --- ## 开发 ```bash pytest # 运行测试 python verify_setup.py # 验证项目结构 ``` ## 许可证 MIT License — 详见 [LICENSE](LICENSE) 文件。 Copyright (c) 2026 Hsia97