AIPickMyGame MCP Server

一个基于 Model Context Protocol (MCP) 的智能游戏推荐系统：安全同步你的 Epic / GOG / Steam（及 GOG Galaxy 聚合的全平台）游戏库，自动补全中文元数据，再让 AI Agent 用自然语言帮你回答「我现在该玩什么」。

一、为什么做这个项目（痛点）

众所周知，Epic坚持每周赠送没按费游戏已有数年，Steam平台拥有众多优质的免费小游戏，通过亚马逊会员也能低价获得Epic和GOG的很多游戏，日积月累游戏库变得非常庞大（目前作者本人Epic平台就有 493 款）。但真正想玩的时候却很头疼：

• 译名杂乱：游戏名中英文混杂，有的还用开发代号，根本认不出是什么游戏。
• 筛选机制弱：平台自带的分类和筛选很弱，几百款游戏里翻不到想玩的。
• 缺乏决策支持：没有「按心情/时长/类型推荐」的能力，面对一长串列表无从下手。

一句话：游戏很多，却不知道玩什么。

我们需要一个工作流，能安全地拿到游戏库、把杂乱数据清洗成规整的中文元数据，再通过自然语言交互做精准推荐。

二、参考了哪些开源项目

三、最终采取的方案

核心思路：全程国内直连，不需要代理、不需要 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」即可得到基于本地游戏库的精准推荐。

补全效果示例（真实数据）：

截图展示

以下是单平台与跨平台推荐的实际效果：

单平台同步与推荐

多平台同步与推荐

⚠️ 已知限制：Steam Store 有 IP 级限流，补全大量游戏时请分批进行（enrich_metadata 的 batch_size 参数，建议 10~15 一批）。少数游戏因 Steam 已下架或 Epic 独占而匹配不到，属正常。

五、各同步方法对比（该选哪个）

四种同步方式各有取舍，按你的需求选：

怎么选：

• 只玩 Epic / 只玩 GOG → 用对应的单平台同步，最干净。
• 重度 Steam 用户、想按「玩得多」推荐 → 用 steam，游玩时长会进推荐摘要。
• 多平台党、嫌一个个登录麻烦 → 用 galaxy，登录一次 GOG 拿全部（前提是你平时用 GOG Galaxy 管理各平台）。
• 既要全平台又要 Steam 时长 → galaxy + steam 各跑一次，按 platform 字段各取所需。

元数据补全（enrich_metadata）对所有平台通用，统一走 Steam Store 中文方案，与同步方式无关。

六、如何使用

1. 前置要求

• Python 3.10+
• 已安装 legendary-gl（随依赖一起安装）

2. 安装

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：

{
  "mcpServers": {
    "AIPickMyGame": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "cwd": "/path/to/AIPickMyGame-MCP",
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

OpenCode —— 编辑 %USERPROFILE%\.config\opencode\opencode.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 字段：

{
  "metadata": {
    "provider": "steam",
    "steam_language": "schinese",
    "steam_country": "CN",
    "api_key": "你的 RAWG_API_KEY（海外用户可选）",
    "igdb_client_id": "",
    "igdb_client_secret": ""
  }
}

国内用户保持默认即可（Steam 直连中文）。海外用户可在 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 判断，不确定的情况会明确告知用户而非悄悄合并。

七、工具列表

八、项目结构

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。

开发

pytest                  # 运行测试
python verify_setup.py  # 验证项目结构

许可证

MIT License — 详见 LICENSE 文件。

Copyright (c) 2026 Hsia97