@xiawan-play/steam-tools-mcp 0.1.1 → 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 (5) hide show
  1. package/.env.example +0 -1
  2. package/README.md +48 -69
  3. package/dist/server.js +1242 -1253
  4. package/docs/configuration.md +2 -21
  5. package/package.json +3 -2
package/.env.example CHANGED
@@ -1,3 +1,2 @@
1
1
  STEAM_WEB_API_KEY=YOUR-STEAM-WEB-API-KEY
2
2
  STEAM_DEFAULT_STEAMID=YOUR_STEAM_ID64
3
- STEAM_ENABLE_GENERATED_TOOLS=false
package/README.md CHANGED
@@ -1,18 +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
- - 自动同步官方 Steam Web API 文档，并可按需开启辅助探索工具与全量官方方法工具。
10
- - 工具标题、说明和参数描述优先面向中文用户设计。
11
- - 支持 `stdio`，也支持可选的 Streamable HTTP 传输方式。
7
+ - 只保留高频工具，不暴露底层原始 API explorer。
8
+ - `steam_get_*` 负责通用查询，`steam_me_*` 负责默认账号快捷入口。
9
+ - 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
10
+ - 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
12
11
 
13
12
  ## 快速开始
14
13
 
15
- ### 直接作为 MCP 配置运行
14
+ ### 直接作为 MCP 运行
16
15
 
17
16
  ```bash
18
17
  npx -y @xiawan-play/steam-tools-mcp
@@ -20,7 +19,7 @@ npx -y @xiawan-play/steam-tools-mcp
20
19
 
21
20
  ### 如需读取用户数据
22
21
 
23
- 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；如果你主要使用 `steam_me_*` 快捷工具，建议同时配置 `STEAM_DEFAULT_STEAMID`。
22
+ 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；长期使用 `steam_me_*` 时建议同时配置 `STEAM_DEFAULT_STEAMID`。
24
23
 
25
24
  ```bash
26
25
  $env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
@@ -33,8 +32,8 @@ $env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
33
32
  npm install
34
33
  npm run sync:steam-spec
35
34
  npm run build
35
+ npm run check:tool-registry
36
36
  npm run dev
37
- npm start
38
37
  ```
39
38
 
40
39
  ## MCP 配置
@@ -52,8 +51,7 @@ npm start
52
51
  ],
53
52
  "env": {
54
53
  "STEAM_WEB_API_KEY": "YOUR_WEB_API_KEY",
55
- "STEAM_DEFAULT_STEAMID": "YOUR_STEAM_ID64",
56
- "STEAM_ENABLE_GENERATED_TOOLS": "false"
54
+ "STEAM_DEFAULT_STEAMID": "YOUR_STEAM_ID64"
57
55
  }
58
56
  }
59
57
  }
@@ -64,86 +62,67 @@ npm start
64
62
 
65
63
  | 变量 | 默认值 | 作用 |
66
64
  | --- | --- | --- |
67
- | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key，调用需要 `key` 的接口时会自动注入。 |
68
- | `STEAM_DEFAULT_STEAMID` | 无 | 默认查询用户的 SteamID64。高频聚合工具在未传用户参数时会自动使用它；部分底层 `steamid` / `steamids` 接口也会使用它作为默认值。 |
69
- | `STEAM_ENABLE_GENERATED_TOOLS` | `false` | 是否启用辅助探索工具和完整的自动生成 Steam 方法工具集。 |
65
+ | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key。很多资料、游戏库、成就相关工具都依赖它。 |
66
+ | `STEAM_DEFAULT_STEAMID` | 无 | 默认账号的 SteamID64。`steam_me_*` 和部分默认用户查询会自动使用它。 |
70
67
 
71
68
  ### 其他可选环境变量
72
69
 
73
70
  | 变量 | 默认值 | 作用 |
74
71
  | --- | --- | --- |
75
- | `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 请求超时时间，单位毫秒。 |
76
74
  | `MCP_TRANSPORT` | `stdio` | 传输方式，可选 `stdio` 或 `http`。 |
77
75
  | `HOST` | `127.0.0.1` | HTTP 模式监听地址。 |
78
76
  | `PORT` | `3000` | HTTP 模式监听端口。 |
79
- | `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
80
77
 
81
78
  完整参数说明见 `docs/configuration.md`。
82
79
 
83
80
  ## 工具总览
84
81
 
85
- ### 高频场景工具
82
+ ### 通用查询
86
83
 
87
84
  | Tool ID | 中文名 | 说明 |
88
85
  | --- | --- | --- |
89
- | `steam_get_player_profile_overview` | Steam 玩家资料总览 | 聚合玩家资料、封禁状态、等级、徽章和最近游玩。 |
90
- | `steam_get_library_overview` | Steam 游戏库总览 | 聚合玩家拥有的游戏、最近活动和常玩游戏。 |
91
- | `steam_get_achievement_overview` | Steam 成就总览 | 查看某位玩家在某个游戏中的成就、全局完成率和统计。 |
92
- | `steam_get_news_overview` | Steam 新闻总览 | 查看某个应用的新闻，并可附带当前在线人数。 |
93
- | `steam_search_apps` | Steam 应用搜索 | 按名称搜索 Steam 应用目录并返回候选 AppID。 |
94
- | `steam_resolve_app` | Steam 应用解析 | 把应用名称或 AppID 解析成最可能的目标应用。 |
95
- | `steam_get_global_achievement_overview` | Steam 全局成就概览 | 查看某个应用的全局成就完成率和 schema 补充信息。 |
96
- | `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` | 游戏快照 | 公共单游戏主入口，聚合新闻、在线人数和全局成就。 |
97
94
 
98
- ### 我的账号快捷工具
95
+ ### 我的账号
99
96
 
100
97
  | Tool ID | 中文名 | 说明 |
101
98
  | --- | --- | --- |
102
- | `steam_me_profile` | 我的 Steam 资料 | 快捷查看默认账号的资料总览。 |
103
- | `steam_me_library` | 我的 Steam 游戏库 | 快捷查看默认账号的游戏库总览。 |
99
+ | `steam_me_profile` | 我的资料 | 查看默认账号的资料总览。 |
100
+ | `steam_me_library` | 我的游戏库 | 查看默认账号的游戏库总览。 |
104
101
  | `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
105
- | `steam_me_badges` | 我的 Steam 徽章 | 查看默认账号的等级和徽章信息。 |
106
- | `steam_me_achievement_overview` | 我的 Steam 成就总览 | 查看默认账号在指定游戏中的成就详情。 |
107
- | `steam_me_friends` | 我的 Steam 好友 | 查看好友列表，可选附带资料摘要和封禁信息。 |
108
- | `steam_me_friend_activity` | 我的好友动态 | 按正在游戏、在线和最近活跃整理好友状态。 |
109
- | `steam_me_friend_network` | 我的好友网络 | 输出好友分组和适合图谱渲染的 `nodes + edges`。 |
110
- | `steam_me_bans` | 我的封禁状态 | 查看默认账号的封禁摘要。 |
111
- | `steam_me_library_compare` | 我的游戏库对比 | 对比你和另一位玩家的游戏库交集、差集和共同游玩情况。 |
112
- | `steam_me_backlog_candidates` | 我的积压游戏候选 | 找出几乎没玩或很久没碰的已拥有游戏。 |
113
- | `steam_me_achievement_hunt` | 我的成就狩猎 | 找出离全成就不远、适合继续补完的游戏。 |
114
- | `steam_me_game_snapshot` | 我的游戏快照 | 聚合某个游戏的拥有情况、时长、成就、统计、新闻和热度。 |
115
- | `steam_me_groups` | 我的 Steam 群组 | 查看群组列表；普通 user key 场景下可能没有结果。 |
116
- | `steam_me_wishlist_like_feed` | 我的 Steam 关注流 | 默认按最近游玩的 AppID 聚合新闻和热度，也可切换到常玩游戏、混合来源或显式 AppID。 |
117
-
118
- ### 可选：辅助探索工具
119
-
120
- 当 `STEAM_ENABLE_GENERATED_TOOLS=true` 时，这组工具会一起开启，适合探索官方方法目录和做原始调试。
121
-
122
- | Tool ID | 中文名 | 说明 |
123
- | --- | --- | --- |
124
- | `steam_list_interfaces` | Steam 接口列表 | 列出当前已同步的接口目录，可按关键字和 Service Interface 过滤。 |
125
- | `steam_list_methods` | Steam 方法搜索 | 搜索当前已同步的方法，可按接口、关键字和鉴权要求过滤。 |
126
- | `steam_get_method_details` | Steam 方法详情 | 查看某个方法的参数、鉴权要求、来源链接和元信息。 |
127
- | `steam_call_raw` | Steam 原始调用 | 按接口名和方法名直接调用底层 Steam Web API，适合兜底和调试。 |
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 生成个人动态流。 |
128
113
 
129
- ### 可选：自动生成官方工具
114
+ ## 使用说明
130
115
 
131
- 当 `STEAM_ENABLE_GENERATED_TOOLS=true` 时，同步后的官方 Steam 方法也会作为独立 tool 自动注册。工具 id 保持英文，标题和说明会尽量提供中文友好展示。例如：
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，本服务内部不会把它作为对外工具暴露。
132
123
 
133
- | Tool ID | 中文名 | 说明 |
134
- | --- | --- | --- |
135
- | `steam_i_player_service_get_owned_games` | 已拥有游戏 | 读取指定玩家的游戏库。 |
136
- | `steam_i_steam_user_stats_get_player_achievements` | 玩家成就 | 读取指定游戏的个人成就列表。 |
137
- | `steam_i_steam_news_get_news_for_app` | 应用新闻 | 读取指定应用的 Steam 新闻。 |
138
-
139
- ## 使用说明
124
+ ## 开发说明
140
125
 
141
- - 资料、游戏库、个人成就、好友等大多数“用户数据”场景通常需要 `STEAM_WEB_API_KEY`；新闻、在线人数这类公开接口可以直接使用。
142
- - 如果配置了 `STEAM_DEFAULT_STEAMID`，大多数按用户查询的高频工具在不传用户参数时会默认查这个账号；`steam_me_*` 工具也依赖它，未配置时会直接返回明确错误。
143
- - 用户资料、游戏库、成就等结果仍然会受到目标账号隐私设置影响。
144
- - `steam_search_apps` / `steam_resolve_app` 的名称搜索，以及需要 schema 补充信息的场景，通常也需要 `STEAM_WEB_API_KEY`。
145
- - 默认模式只暴露高频工具和 `steam_me_*` 快捷工具；只有在需要辅助探索工具、底层官方方法或调试时，再开启 `STEAM_ENABLE_GENERATED_TOOLS=true`。
146
- - `steam_me_groups` 依赖的底层接口在官方文档中偏 `publisher key` 场景，普通 user key 很可能拿不到结果。
147
- - Steam 官方文档里的 `ISteamApps.GetAppList` 当前已经标记为 deprecated，直接调通常会返回 `404`；本服务会明确提示你改用 `steam_search_apps`、`steam_resolve_app` 或 `IStoreService.GetAppList`。
148
- - 对于 Service Interface，本服务会用 `input_json` 方式发送请求，这样数组和对象参数会更稳定。
149
- - 同步后的接口清单保存在源码中的 `src/generated/steam-web-api-spec.json`。
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`，仅作为底层调用数据，不再直接暴露为对外工具。