@xiawan-play/steam-tools-mcp

一个面向 Node.js 的 Steam MCP 服务，聚焦中文用户常用的高频场景：资料、游戏库、单游戏快照、成就、新闻和应用解析。

特性

• 只保留高频事实型工具，不暴露底层原始 API explorer；攻略类工具只整合官方成就和 Steam 指南中的可追溯事实。
• steam_get_* 负责通用查询和公共事实视图，steam_me_* 负责默认账号主入口、专项视图和快捷入口。
• 单游戏工具统一支持 appid 或 query，可直接输入中文游戏名。
• 返回结构尽量统一为 target / summary / items / sections / warnings，更适合模型消费。

快速开始

直接作为 MCP 运行

npx -y @xiawan-play/steam-tools-mcp

如需读取用户数据

读取资料、游戏库、成就、好友等用户数据通常需要 STEAM_WEB_API_KEY；长期使用 steam_me_* 时建议同时配置 STEAM_DEFAULT_STEAMID。

$env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
$env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
$env:PROXY_URL="http://YOUR_PROXY_HOST:PORT"

本地开发

npm install
npm run sync:steam-spec
npm run build
npm run check:tool-registry
npm run dev

MCP 配置

推荐配置

{
  "mcpServers": {
    "steam-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@xiawan-play/steam-tools-mcp"
      ],
      "env": {
        "STEAM_WEB_API_KEY": "YOUR_WEB_API_KEY",
        "STEAM_DEFAULT_STEAMID": "YOUR_STEAM_ID64",
        "PROXY_URL": "http://YOUR_PROXY_HOST:PORT"
      }
    }
  }
}

常用环境变量

| 变量 | 默认值 | 作用 | | --- | --- | --- | | STEAM_WEB_API_KEY | 无 | 默认使用的 Steam API Key。很多资料、游戏库、成就相关工具都依赖它。 | | STEAM_DEFAULT_STEAMID | 无 | 默认账号的 SteamID64。steam_me_* 和部分默认用户查询会自动使用它。 |

其他可选环境变量

| 变量 | 默认值 | 作用 | | --- | --- | --- | | STEAM_APP_LIST_CACHE_TTL_MS | 21600000 | 应用目录缓存时间，单位毫秒。 | | STEAM_REQUEST_TIMEOUT_MS | 30000 | Steam API 请求超时时间，单位毫秒。 | | PROXY_URL | 无 | 项目统一使用的代理环境变量；配置后会用于所有外部 HTTP 请求。 | | MCP_TRANSPORT | stdio | 传输方式，可选 stdio 或 http。 | | HOST | 127.0.0.1 | HTTP 模式监听地址。 | | PORT | 3000 | HTTP 模式监听端口。 |

完整参数说明见 docs/configuration.md。

工具总览

公共主入口

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_get_player_profile_overview | 玩家资料总览 | 通用玩家主入口，聚合玩家资料、封禁、等级、徽章和最近游玩。 | | steam_get_library_overview | 游戏库总览 | 通用玩家游戏库主入口，聚合玩家拥有的游戏、最近游玩和常玩游戏。 | | steam_get_app_snapshot | 游戏快照 | 公共单游戏主入口，聚合新闻、在线人数和全局成就。 |

公共专项视图

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_get_player_game_achievements | 玩家游戏成就 | 通用玩家单游戏专项视图，查看某位玩家在某个游戏里的成就、完成率和可选统计。 | | steam_get_app_news | 游戏新闻 | 公共单游戏专项视图，查看某个游戏的 Steam 新闻，并可选附带在线人数。 | | steam_get_achievement_roadmap | 全成就攻略 | 公共单游戏攻略事实视图，整合官方成就清单和 Steam 指南中的可追溯事实，例如 missable、co-op 和条件说明。 | | steam_get_global_achievement_overview | 全局成就总览 | 公共单游戏专项视图，查看某个游戏的全局成就完成率。 | | steam_get_price_overview | 价格与史低 | 公共价格专项视图，查看 app、sub 或 bundle 的当前最低价、历史最低价、史低日期，以及当前是否等于史低。 |

目标解析与候选

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_search_apps | 搜索游戏 | 按名称搜索游戏，适合拿候选列表。 | | steam_resolve_app | 解析游戏目标 | 把游戏名或 AppID 解析成最可能的目标游戏。 |

默认账号主入口

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_me_profile | 我的资料 | 默认账号主入口，查看我的资料总览。 | | steam_me_library | 我的游戏库 | 默认账号主入口，查看我的游戏库总览。 | | steam_me_game_snapshot | 我的游戏快照 | 默认账号单游戏主入口，查看我与某个游戏的关系、新闻和成就。 |

默认账号专项视图

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_me_game_achievements | 我的游戏成就 | 默认账号单游戏专项视图，查看我在某个游戏里的成就和完成率。 | | steam_me_friends | 好友列表 | 默认账号专项视图，查看好友列表，可选补充资料和封禁信息。 | | steam_me_friend_activity | 好友在线动态 | 默认账号专项视图，查看哪些好友在线、在玩游戏或最近活跃。 | | steam_me_friend_network | 好友关系图谱 | 默认账号专项视图，生成好友活动分组和 graph 视图。 | | steam_me_library_compare | 我的库对比 | 默认账号专项视图，把我的库和另一位玩家做对比。 | | steam_me_backlog_candidates | 我的积压候选 | 默认账号专项视图，找出适合开坑的积压游戏。 | | steam_me_achievement_hunt | 我的成就补完候选 | 默认账号专项视图，找出离全成就不远的游戏。 | | steam_me_game_feed | 我的游戏动态流 | 默认账号专项视图，按最近游玩、常玩或显式 App 生成个人动态流。 |

默认账号快捷入口

| Tool ID | 中文名 | 说明 | | --- | --- | --- | | steam_me_recently_played | 我的最近游玩 | 默认账号快捷入口，只看最近玩过的游戏。 | | steam_me_badges | 我的徽章 | 默认账号快捷入口，只看等级和徽章。 | | steam_me_bans | 我的封禁摘要 | 默认账号快捷入口，只看默认账号的封禁状态。 |

使用说明

• 大多数用户数据场景都需要 STEAM_WEB_API_KEY，公开新闻和在线人数这类接口通常可以直接查。
• steam_search_apps 和 steam_resolve_app 依赖应用目录能力，也需要 STEAM_WEB_API_KEY；即使传入数字 AppID，解析阶段也会先做目录校验。
• steam_me_* 依赖 STEAM_DEFAULT_STEAMID 作为默认账号；未配置时会返回明确错误。
• 不确定该用哪个单游戏工具时，优先使用 steam_get_app_snapshot 或 steam_me_game_snapshot。
• steam_me_recently_played、steam_me_badges、steam_me_bans 属于高频快捷入口；如果需要完整上下文，优先使用 steam_me_profile。
• 单游戏工具统一支持 appid 或 query，query 可直接输入中文游戏名。
• steam_get_achievement_roadmap 会抓取 Steam Guides，但只返回带来源的攻略事实和证据片段，不输出模型自行推断的阶段路线。
• steam_get_price_overview 支持 appid、subid、bundleid 三种目标；其中 query 仅用于解析 app。
• 如果终端环境访问外部站点不稳定，但浏览器或 Steam 客户端可以正常打开，可统一配置 PROXY_URL，例如 http://YOUR_PROXY_HOST:PORT。
• 返回结果会优先补充 localizedName 和 displayName；会先用官方 appdetails，必要时再回退到官方商店页展示名，仍拿不到中文名时才保留原始名称。
• 中文 query 对官方商店名和常见本地化标题支持较好；如果某个游戏在 Steam 商店本身没有稳定中文标题，仍建议直接传 appid。
• 好友、游戏库、成就等结果仍然会受目标账号隐私设置影响。
• Steam 官方文档里的 ISteamApps.GetAppList 当前已标记为 deprecated，本服务内部不会把它作为对外工具暴露。
• steam_get_price_overview 当前使用第三方公开价格源补充史低信息；如果第三方暂时不可用，工具会直接返回错误或 warning。

开发说明

• 工具注册统一走 src/tools/register-steam-tool.ts。
• npm run check:tool-registry 会检查 src/tools 下是否误用了 server.registerTool(...)。
• 同步后的接口快照保存在 src/generated/steam-web-api-spec.json，仅作为底层调用数据，不再直接暴露为对外工具。