@xiawan-play/steam-tools-mcp 0.3.0 → 0.3.2

package/README.md

@@ -2,12 +2,12 @@
 
 一个面向 Node.js 的 Steam MCP 服务，聚焦中文用户常用的高频场景：资料、游戏库、单游戏快照、成就、新闻和应用解析。
 
-## 特性
-
-- 只保留高频工具，不暴露底层原始 API explorer。
-- `steam_get_*` 负责通用查询，`steam_me_*` 负责默认账号快捷入口。
-- 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
-- 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
+## 特性
+
+- 只保留高频事实型工具，不暴露底层原始 API explorer；攻略类工具只整合官方成就和 Steam 指南中的可追溯事实。
+- `steam_get_*` 负责通用查询和公共事实视图，`steam_me_*` 负责默认账号主入口、专项视图和快捷入口。
+- 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
+- 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
 
 ## 快速开始
 
@@ -80,52 +80,74 @@ npm run dev
 
 完整参数说明见 `docs/configuration.md`。
 
-## 工具总览
-
-### 通用查询
-
-| Tool ID | 中文名 | 说明 |
-| --- | --- | --- |
-| `steam_get_player_profile_overview` | 玩家资料总览 | 聚合玩家资料、封禁、等级、徽章和最近游玩。 |
-| `steam_get_library_overview` | 游戏库总览 | 聚合玩家拥有的游戏、最近游玩和常玩游戏。 |
-| `steam_get_player_game_achievements` | 玩家游戏成就 | 查看某位玩家在某个游戏里的成就、完成率和可选统计。 |
-| `steam_get_app_news` | 游戏新闻 | 查看某个游戏的 Steam 新闻，并可选附带在线人数。 |
-| `steam_search_apps` | 搜索游戏 | 按名称搜索游戏，适合拿候选列表。 |
-| `steam_resolve_app` | 解析游戏目标 | 把游戏名或 AppID 解析成最可能的目标游戏。 |
-| `steam_get_price_overview` | 价格与史低 | 查看 app、sub 或 bundle 的当前最低价、历史最低价、史低日期，以及当前是否等于史低。 |
-| `steam_get_achievement_roadmap` | 成就路线图 | 仅基于 Steam 指南，为某个游戏生成全成就注意事项、阶段路线图和成就备注摘要。 |
-| `steam_get_global_achievement_overview` | 全局成就总览 | 查看某个游戏的全局成就完成率。 |
-| `steam_get_app_snapshot` | 游戏快照 | 公共单游戏主入口，聚合新闻、在线人数和全局成就。 |
-
-### 我的账号
-
-| Tool ID | 中文名 | 说明 |
-| --- | --- | --- |
-| `steam_me_profile` | 我的资料 | 查看默认账号的资料总览。 |
-| `steam_me_library` | 我的游戏库 | 查看默认账号的游戏库总览。 |
-| `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
-| `steam_me_badges` | 我的徽章 | 查看默认账号的等级和徽章。 |
-| `steam_me_game_achievements` | 我的游戏成就 | 查看我在某个游戏里的成就和完成率。 |
-| `steam_me_friends` | 好友列表 | 查看好友列表，可选补充资料和封禁信息。 |
-| `steam_me_friend_activity` | 好友在线动态 | 查看哪些好友在线、在玩游戏或最近活跃。 |
-| `steam_me_friend_network` | 好友关系图谱 | 生成好友活动分组和 graph 视图。 |
-| `steam_me_bans` | 我的封禁摘要 | 查看默认账号的封禁状态。 |
-| `steam_me_library_compare` | 我的库对比 | 把我的库和另一位玩家做对比。 |
-| `steam_me_backlog_candidates` | 我的积压候选 | 找出适合开坑的积压游戏。 |
-| `steam_me_achievement_hunt` | 我的成就补完候选 | 找出离全成就不远的游戏。 |
-| `steam_me_game_snapshot` | 我的游戏快照 | 我的单游戏主入口，聚合拥有情况、成就、统计和新闻。 |
-| `steam_me_game_feed` | 我的游戏动态流 | 按最近游玩、常玩或显式 App 生成个人动态流。 |
+## 工具总览
+
+### 公共主入口
+
+| 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` 作为默认账号；未配置时会返回明确错误。
-- 单游戏工具统一支持 `appid` 或 `query`，`query` 可直接输入中文游戏名。
-- `steam_get_price_overview` 支持 `appid`、`subid`、`bundleid` 三种目标；其中 `query` 仅用于解析 app。
-- `steam_get_achievement_roadmap` 目前只整合 Steam 指南，不抓取贴吧、B 站或第三方攻略站；输出的是“有来源依据的路线图草案”，不是保真攻略。
+- 大多数用户数据场景都需要 `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`；拿不到中文名时会自动回退原始名称。
+- 返回结果会优先补充 `localizedName` 和 `displayName`；会先用官方 `appdetails`，必要时再回退到官方商店页展示名，仍拿不到中文名时才保留原始名称。
 - 中文 `query` 对官方商店名和常见本地化标题支持较好；如果某个游戏在 Steam 商店本身没有稳定中文标题，仍建议直接传 `appid`。
 - 好友、游戏库、成就等结果仍然会受目标账号隐私设置影响。
 - Steam 官方文档里的 `ISteamApps.GetAppList` 当前已标记为 deprecated，本服务内部不会把它作为对外工具暴露。