@xiawan-play/steam-tools-mcp 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +48 -44
  2. package/dist/server.js +1178 -902
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,17 +1,17 @@
1
1
  # @xiawan-play/steam-tools-mcp
2
2
 
3
- 一个面向 Node.js 的 Steam 相关 MCP 服务，提供中文友好的高频工具和我的账号快捷工具。
3
+ 一个面向 Node.js 的 Steam MCP 服务，聚焦中文用户常用的高频场景：资料、游戏库、单游戏快照、成就、新闻和应用解析。
4
4
 
5
5
  ## 特性
6
6
 
7
- - 开箱即用的高频 Steam 工具，适合资料、游戏库、成就、新闻和应用检索场景。
8
- - 提供 `steam_me_*` 快捷工具，适合长期绑定个人账号使用。
9
- - 工具标题、说明和参数描述优先面向中文用户设计。
10
- - 支持 `stdio`，也支持可选的 Streamable HTTP 传输方式。
7
+ - 只保留高频工具，不暴露底层原始 API explorer。
8
+ - `steam_get_*` 负责通用查询，`steam_me_*` 负责默认账号快捷入口。
9
+ - 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
10
+ - 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
11
11
 
12
12
  ## 快速开始
13
13
 
14
- ### 直接作为 MCP 配置运行
14
+ ### 直接作为 MCP 运行
15
15
 
16
16
  ```bash
17
17
  npx -y @xiawan-play/steam-tools-mcp
@@ -19,7 +19,7 @@ npx -y @xiawan-play/steam-tools-mcp
19
19
 
20
20
  ### 如需读取用户数据
21
21
 
22
- 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；如果你主要使用 `steam_me_*` 快捷工具，建议同时配置 `STEAM_DEFAULT_STEAMID`。
22
+ 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；长期使用 `steam_me_*` 时建议同时配置 `STEAM_DEFAULT_STEAMID`。
23
23
 
24
24
  ```bash
25
25
  $env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
@@ -32,8 +32,8 @@ $env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
32
32
  npm install
33
33
  npm run sync:steam-spec
34
34
  npm run build
35
+ npm run check:tool-registry
35
36
  npm run dev
36
- npm start
37
37
  ```
38
38
 
39
39
  ## MCP 配置
@@ -62,63 +62,67 @@ npm start
62
62
 
63
63
  | 变量 | 默认值 | 作用 |
64
64
  | --- | --- | --- |
65
- | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key，调用需要 `key` 的接口时会自动注入。 |
66
- | `STEAM_DEFAULT_STEAMID` | 无 | 默认查询用户的 SteamID64。高频聚合工具在未传用户参数时会自动使用它；`steam_me_*` 工具也会使用它作为默认账号。 |
65
+ | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key。很多资料、游戏库、成就相关工具都依赖它。 |
66
+ | `STEAM_DEFAULT_STEAMID` | 无 | 默认账号的 SteamID64。`steam_me_*` 和部分默认用户查询会自动使用它。 |
67
67
 
68
68
  ### 其他可选环境变量
69
69
 
70
70
  | 变量 | 默认值 | 作用 |
71
71
  | --- | --- | --- |
72
- | `STEAM_APP_LIST_CACHE_TTL_MS` | `21600000` | Steam 应用目录缓存时间，单位毫秒，默认 6 小时。 |
72
+ | `STEAM_APP_LIST_CACHE_TTL_MS` | `21600000` | 应用目录缓存时间，单位毫秒。 |
73
+ | `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
73
74
  | `MCP_TRANSPORT` | `stdio` | 传输方式，可选 `stdio` 或 `http`。 |
74
75
  | `HOST` | `127.0.0.1` | HTTP 模式监听地址。 |
75
76
  | `PORT` | `3000` | HTTP 模式监听端口。 |
76
- | `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
77
77
 
78
78
  完整参数说明见 `docs/configuration.md`。
79
79
 
80
80
  ## 工具总览
81
81
 
82
- ### 高频场景工具
82
+ ### 通用查询
83
83
 
84
84
  | Tool ID | 中文名 | 说明 |
85
85
  | --- | --- | --- |
86
- | `steam_get_player_profile_overview` | Steam 玩家资料总览 | 聚合玩家资料、封禁状态、等级、徽章和最近游玩。 |
87
- | `steam_get_library_overview` | Steam 游戏库总览 | 聚合玩家拥有的游戏、最近活动和常玩游戏。 |
88
- | `steam_get_achievement_overview` | Steam 成就总览 | 查看某位玩家在某个游戏中的成就、全局完成率和统计。 |
89
- | `steam_get_news_overview` | Steam 新闻总览 | 查看某个应用的新闻，并可附带当前在线人数。 |
90
- | `steam_search_apps` | Steam 应用搜索 | 按名称搜索 Steam 应用目录并返回候选 AppID。 |
91
- | `steam_resolve_app` | Steam 应用解析 | 把应用名称或 AppID 解析成最可能的目标应用。 |
92
- | `steam_get_global_achievement_overview` | Steam 全局成就概览 | 查看某个应用的全局成就完成率和 schema 补充信息。 |
93
- | `steam_get_app_snapshot` | Steam 应用快照 | 聚合应用基本信息、新闻、在线人数和全局成就趋势。 |
86
+ | `steam_get_player_profile_overview` | 玩家资料总览 | 聚合玩家资料、封禁、等级、徽章和最近游玩。 |
87
+ | `steam_get_library_overview` | 游戏库总览 | 聚合玩家拥有的游戏、最近游玩和常玩游戏。 |
88
+ | `steam_get_player_game_achievements` | 玩家游戏成就 | 查看某位玩家在某个游戏里的成就、完成率和可选统计。 |
89
+ | `steam_get_app_news` | 游戏新闻 | 查看某个游戏的 Steam 新闻，并可选附带在线人数。 |
90
+ | `steam_search_apps` | 搜索游戏 | 按名称搜索游戏，适合拿候选列表。 |
91
+ | `steam_resolve_app` | 解析游戏目标 | 把游戏名或 AppID 解析成最可能的目标游戏。 |
92
+ | `steam_get_global_achievement_overview` | 全局成就总览 | 查看某个游戏的全局成就完成率。 |
93
+ | `steam_get_app_snapshot` | 游戏快照 | 公共单游戏主入口，聚合新闻、在线人数和全局成就。 |
94
94
 
95
- ### 我的账号快捷工具
95
+ ### 我的账号
96
96
 
97
97
  | Tool ID | 中文名 | 说明 |
98
98
  | --- | --- | --- |
99
- | `steam_me_profile` | 我的 Steam 资料 | 快捷查看默认账号的资料总览。 |
100
- | `steam_me_library` | 我的 Steam 游戏库 | 快捷查看默认账号的游戏库总览。 |
99
+ | `steam_me_profile` | 我的资料 | 查看默认账号的资料总览。 |
100
+ | `steam_me_library` | 我的游戏库 | 查看默认账号的游戏库总览。 |
101
101
  | `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
102
- | `steam_me_badges` | 我的 Steam 徽章 | 查看默认账号的等级和徽章信息。 |
103
- | `steam_me_achievement_overview` | 我的 Steam 成就总览 | 查看默认账号在指定游戏中的成就详情。 |
104
- | `steam_me_friends` | 我的 Steam 好友 | 查看好友列表，可选附带资料摘要和封禁信息。 |
105
- | `steam_me_friend_activity` | 我的好友动态 | 按正在游戏、在线和最近活跃整理好友状态。 |
106
- | `steam_me_friend_network` | 我的好友网络 | 输出好友分组和适合图谱渲染的 `nodes + edges`。 |
107
- | `steam_me_bans` | 我的封禁状态 | 查看默认账号的封禁摘要。 |
108
- | `steam_me_library_compare` | 我的游戏库对比 | 对比你和另一位玩家的游戏库交集、差集和共同游玩情况。 |
109
- | `steam_me_backlog_candidates` | 我的积压游戏候选 | 找出几乎没玩或很久没碰的已拥有游戏。 |
110
- | `steam_me_achievement_hunt` | 我的成就狩猎 | 找出离全成就不远、适合继续补完的游戏。 |
111
- | `steam_me_game_snapshot` | 我的游戏快照 | 聚合某个游戏的拥有情况、时长、成就、统计、新闻和热度。 |
112
- | `steam_me_groups` | 我的 Steam 群组 | 查看群组列表；普通 user key 场景下可能没有结果。 |
113
- | `steam_me_wishlist_like_feed` | 我的 Steam 关注流 | 默认按最近游玩的 AppID 聚合新闻和热度，也可切换到常玩游戏、混合来源或显式 AppID。 |
102
+ | `steam_me_badges` | 我的徽章 | 查看默认账号的等级和徽章。 |
103
+ | `steam_me_game_achievements` | 我的游戏成就 | 查看我在某个游戏里的成就和完成率。 |
104
+ | `steam_me_friends` | 好友列表 | 查看好友列表，可选补充资料和封禁信息。 |
105
+ | `steam_me_friend_activity` | 好友在线动态 | 查看哪些好友在线、在玩游戏或最近活跃。 |
106
+ | `steam_me_friend_network` | 好友关系图谱 | 生成好友活动分组和 graph 视图。 |
107
+ | `steam_me_bans` | 我的封禁摘要 | 查看默认账号的封禁状态。 |
108
+ | `steam_me_library_compare` | 我的库对比 | 把我的库和另一位玩家做对比。 |
109
+ | `steam_me_backlog_candidates` | 我的积压候选 | 找出适合开坑的积压游戏。 |
110
+ | `steam_me_achievement_hunt` | 我的成就补完候选 | 找出离全成就不远的游戏。 |
111
+ | `steam_me_game_snapshot` | 我的游戏快照 | 我的单游戏主入口，聚合拥有情况、成就、统计和新闻。 |
112
+ | `steam_me_game_feed` | 我的游戏动态流 | 按最近游玩、常玩或显式 App 生成个人动态流。 |
114
113
 
115
114
  ## 使用说明
116
115
 
117
- - 资料、游戏库、个人成就、好友等大多数“用户数据”场景通常需要 `STEAM_WEB_API_KEY`；新闻、在线人数这类公开接口可以直接使用。
118
- - 如果配置了 `STEAM_DEFAULT_STEAMID`，大多数按用户查询的高频工具在不传用户参数时会默认查这个账号；`steam_me_*` 工具也依赖它，未配置时会直接返回明确错误。
119
- - 用户资料、游戏库、成就等结果仍然会受到目标账号隐私设置影响。
120
- - `steam_search_apps` / `steam_resolve_app` 的名称搜索，以及需要 schema 补充信息的场景，通常也需要 `STEAM_WEB_API_KEY`。
121
- - `steam_me_groups` 依赖的底层接口在官方文档中偏 `publisher key` 场景，普通 user key 很可能拿不到结果。
122
- - Steam 官方文档里的 `ISteamApps.GetAppList` 当前已经标记为 deprecated，直接调通常会返回 `404`；本服务会明确提示你改用 `steam_search_apps`、`steam_resolve_app` 或 `IStoreService.GetAppList`。
123
- - 对于 Service Interface，本服务会用 `input_json` 方式发送请求，这样数组和对象参数会更稳定。
124
- - 同步后的接口清单保存在源码中的 `src/generated/steam-web-api-spec.json`。
116
+ - 大多数用户数据场景都需要 `STEAM_WEB_API_KEY`，公开新闻和在线人数这类接口通常可以直接查。
117
+ - `steam_me_*` 依赖 `STEAM_DEFAULT_STEAMID` 作为默认账号；未配置时会返回明确错误。
118
+ - 单游戏工具统一支持 `appid` 或 `query`，`query` 可直接输入中文游戏名。
119
+ - 返回结果会优先补充 `localizedName` 和 `displayName`；拿不到中文名时会自动回退原始名称。
120
+ - 中文 `query` 对官方商店名和常见本地化标题支持较好；如果某个游戏在 Steam 商店本身没有稳定中文标题，仍建议直接传 `appid`。
121
+ - 好友、游戏库、成就等结果仍然会受目标账号隐私设置影响。
122
+ - Steam 官方文档里的 `ISteamApps.GetAppList` 当前已标记为 deprecated，本服务内部不会把它作为对外工具暴露。
123
+
124
+ ## 开发说明
125
+
126
+ - 工具注册统一走 `src/tools/register-steam-tool.ts`。
127
+ - `npm run check:tool-registry` 会检查 `src/tools` 下是否误用了 `server.registerTool(...)`。
128
+ - 同步后的接口快照保存在 `src/generated/steam-web-api-spec.json`，仅作为底层调用数据，不再直接暴露为对外工具。