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

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 +3 -2
  2. package/README.md +138 -128
  3. package/dist/server.js +27143 -1029
  4. package/docs/configuration.md +76 -73
  5. package/package.json +1 -1
package/.env.example CHANGED
@@ -1,2 +1,3 @@
1
- STEAM_WEB_API_KEY=YOUR-STEAM-WEB-API-KEY
2
- STEAM_DEFAULT_STEAMID=YOUR_STEAM_ID64
1
+ STEAM_WEB_API_KEY=YOUR-STEAM-WEB-API-KEY
2
+ STEAM_DEFAULT_STEAMID=YOUR_STEAM_ID64
3
+ PROXY_URL=http://YOUR_PROXY_HOST:PORT
package/README.md CHANGED
@@ -1,128 +1,138 @@
1
- # @xiawan-play/steam-tools-mcp
2
-
3
- 一个面向 Node.js 的 Steam MCP 服务，聚焦中文用户常用的高频场景：资料、游戏库、单游戏快照、成就、新闻和应用解析。
4
-
5
- ## 特性
6
-
7
- - 只保留高频工具，不暴露底层原始 API explorer。
8
- - `steam_get_*` 负责通用查询，`steam_me_*` 负责默认账号快捷入口。
9
- - 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
10
- - 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
11
-
12
- ## 快速开始
13
-
14
- ### 直接作为 MCP 运行
15
-
16
- ```bash
17
- npx -y @xiawan-play/steam-tools-mcp
18
- ```
19
-
20
- ### 如需读取用户数据
21
-
22
- 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；长期使用 `steam_me_*` 时建议同时配置 `STEAM_DEFAULT_STEAMID`。
23
-
24
- ```bash
25
- $env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
26
- $env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
27
- ```
28
-
29
- ### 本地开发
30
-
31
- ```bash
32
- npm install
33
- npm run sync:steam-spec
34
- npm run build
35
- npm run check:tool-registry
36
- npm run dev
37
- ```
38
-
39
- ## MCP 配置
40
-
41
- ### 推荐配置
42
-
43
- ```json
44
- {
45
- "mcpServers": {
46
- "steam-tools": {
47
- "command": "npx",
48
- "args": [
49
- "-y",
50
- "@xiawan-play/steam-tools-mcp"
51
- ],
52
- "env": {
53
- "STEAM_WEB_API_KEY": "YOUR_WEB_API_KEY",
54
- "STEAM_DEFAULT_STEAMID": "YOUR_STEAM_ID64"
55
- }
56
- }
57
- }
58
- }
59
- ```
60
-
61
- ### 常用环境变量
62
-
63
- | 变量 | 默认值 | 作用 |
64
- | --- | --- | --- |
65
- | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key。很多资料、游戏库、成就相关工具都依赖它。 |
66
- | `STEAM_DEFAULT_STEAMID` | 无 | 默认账号的 SteamID64。`steam_me_*` 和部分默认用户查询会自动使用它。 |
67
-
68
- ### 其他可选环境变量
69
-
70
- | 变量 | 默认值 | 作用 |
71
- | --- | --- | --- |
72
- | `STEAM_APP_LIST_CACHE_TTL_MS` | `21600000` | 应用目录缓存时间，单位毫秒。 |
73
- | `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
74
- | `MCP_TRANSPORT` | `stdio` | 传输方式，可选 `stdio` 或 `http`。 |
75
- | `HOST` | `127.0.0.1` | HTTP 模式监听地址。 |
76
- | `PORT` | `3000` | HTTP 模式监听端口。 |
77
-
78
- 完整参数说明见 `docs/configuration.md`。
79
-
80
- ## 工具总览
81
-
82
- ### 通用查询
83
-
84
- | Tool ID | 中文名 | 说明 |
85
- | --- | --- | --- |
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
-
95
- ### 我的账号
96
-
97
- | Tool ID | 中文名 | 说明 |
98
- | --- | --- | --- |
99
- | `steam_me_profile` | 我的资料 | 查看默认账号的资料总览。 |
100
- | `steam_me_library` | 我的游戏库 | 查看默认账号的游戏库总览。 |
101
- | `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
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 生成个人动态流。 |
113
-
114
- ## 使用说明
115
-
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`，仅作为底层调用数据，不再直接暴露为对外工具。
1
+ # @xiawan-play/steam-tools-mcp
2
+
3
+ 一个面向 Node.js 的 Steam MCP 服务，聚焦中文用户常用的高频场景：资料、游戏库、单游戏快照、成就、新闻和应用解析。
4
+
5
+ ## 特性
6
+
7
+ - 只保留高频工具，不暴露底层原始 API explorer。
8
+ - `steam_get_*` 负责通用查询，`steam_me_*` 负责默认账号快捷入口。
9
+ - 单游戏工具统一支持 `appid` 或 `query`，可直接输入中文游戏名。
10
+ - 返回结构尽量统一为 `target / summary / items / sections / warnings`，更适合模型消费。
11
+
12
+ ## 快速开始
13
+
14
+ ### 直接作为 MCP 运行
15
+
16
+ ```bash
17
+ npx -y @xiawan-play/steam-tools-mcp
18
+ ```
19
+
20
+ ### 如需读取用户数据
21
+
22
+ 读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；长期使用 `steam_me_*` 时建议同时配置 `STEAM_DEFAULT_STEAMID`。
23
+
24
+ ```bash
25
+ $env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
26
+ $env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
27
+ $env:PROXY_URL="http://YOUR_PROXY_HOST:PORT"
28
+ ```
29
+
30
+ ### 本地开发
31
+
32
+ ```bash
33
+ npm install
34
+ npm run sync:steam-spec
35
+ npm run build
36
+ npm run check:tool-registry
37
+ npm run dev
38
+ ```
39
+
40
+ ## MCP 配置
41
+
42
+ ### 推荐配置
43
+
44
+ ```json
45
+ {
46
+ "mcpServers": {
47
+ "steam-tools": {
48
+ "command": "npx",
49
+ "args": [
50
+ "-y",
51
+ "@xiawan-play/steam-tools-mcp"
52
+ ],
53
+ "env": {
54
+ "STEAM_WEB_API_KEY": "YOUR_WEB_API_KEY",
55
+ "STEAM_DEFAULT_STEAMID": "YOUR_STEAM_ID64",
56
+ "PROXY_URL": "http://YOUR_PROXY_HOST:PORT"
57
+ }
58
+ }
59
+ }
60
+ }
61
+ ```
62
+
63
+ ### 常用环境变量
64
+
65
+ | 变量 | 默认值 | 作用 |
66
+ | --- | --- | --- |
67
+ | `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key。很多资料、游戏库、成就相关工具都依赖它。 |
68
+ | `STEAM_DEFAULT_STEAMID` | 无 | 默认账号的 SteamID64。`steam_me_*` 和部分默认用户查询会自动使用它。 |
69
+
70
+ ### 其他可选环境变量
71
+
72
+ | 变量 | 默认值 | 作用 |
73
+ | --- | --- | --- |
74
+ | `STEAM_APP_LIST_CACHE_TTL_MS` | `21600000` | 应用目录缓存时间，单位毫秒。 |
75
+ | `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
76
+ | `PROXY_URL` | 无 | 项目统一使用的代理环境变量；配置后会用于所有外部 HTTP 请求。 |
77
+ | `MCP_TRANSPORT` | `stdio` | 传输方式，可选 `stdio` 或 `http`。 |
78
+ | `HOST` | `127.0.0.1` | HTTP 模式监听地址。 |
79
+ | `PORT` | `3000` | HTTP 模式监听端口。 |
80
+
81
+ 完整参数说明见 `docs/configuration.md`。
82
+
83
+ ## 工具总览
84
+
85
+ ### 通用查询
86
+
87
+ | Tool ID | 中文名 | 说明 |
88
+ | --- | --- | --- |
89
+ | `steam_get_player_profile_overview` | 玩家资料总览 | 聚合玩家资料、封禁、等级、徽章和最近游玩。 |
90
+ | `steam_get_library_overview` | 游戏库总览 | 聚合玩家拥有的游戏、最近游玩和常玩游戏。 |
91
+ | `steam_get_player_game_achievements` | 玩家游戏成就 | 查看某位玩家在某个游戏里的成就、完成率和可选统计。 |
92
+ | `steam_get_app_news` | 游戏新闻 | 查看某个游戏的 Steam 新闻，并可选附带在线人数。 |
93
+ | `steam_search_apps` | 搜索游戏 | 按名称搜索游戏，适合拿候选列表。 |
94
+ | `steam_resolve_app` | 解析游戏目标 | 把游戏名或 AppID 解析成最可能的目标游戏。 |
95
+ | `steam_get_price_overview` | 价格与史低 | 查看 app、sub 或 bundle 的当前最低价、历史最低价、史低日期，以及当前是否等于史低。 |
96
+ | `steam_get_achievement_roadmap` | 成就路线图 | 仅基于 Steam 指南，为某个游戏生成全成就注意事项、阶段路线图和成就备注摘要。 |
97
+ | `steam_get_global_achievement_overview` | 全局成就总览 | 查看某个游戏的全局成就完成率。 |
98
+ | `steam_get_app_snapshot` | 游戏快照 | 公共单游戏主入口，聚合新闻、在线人数和全局成就。 |
99
+
100
+ ### 我的账号
101
+
102
+ | Tool ID | 中文名 | 说明 |
103
+ | --- | --- | --- |
104
+ | `steam_me_profile` | 我的资料 | 查看默认账号的资料总览。 |
105
+ | `steam_me_library` | 我的游戏库 | 查看默认账号的游戏库总览。 |
106
+ | `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
107
+ | `steam_me_badges` | 我的徽章 | 查看默认账号的等级和徽章。 |
108
+ | `steam_me_game_achievements` | 我的游戏成就 | 查看我在某个游戏里的成就和完成率。 |
109
+ | `steam_me_friends` | 好友列表 | 查看好友列表，可选补充资料和封禁信息。 |
110
+ | `steam_me_friend_activity` | 好友在线动态 | 查看哪些好友在线、在玩游戏或最近活跃。 |
111
+ | `steam_me_friend_network` | 好友关系图谱 | 生成好友活动分组和 graph 视图。 |
112
+ | `steam_me_bans` | 我的封禁摘要 | 查看默认账号的封禁状态。 |
113
+ | `steam_me_library_compare` | 我的库对比 | 把我的库和另一位玩家做对比。 |
114
+ | `steam_me_backlog_candidates` | 我的积压候选 | 找出适合开坑的积压游戏。 |
115
+ | `steam_me_achievement_hunt` | 我的成就补完候选 | 找出离全成就不远的游戏。 |
116
+ | `steam_me_game_snapshot` | 我的游戏快照 | 我的单游戏主入口，聚合拥有情况、成就、统计和新闻。 |
117
+ | `steam_me_game_feed` | 我的游戏动态流 | 按最近游玩、常玩或显式 App 生成个人动态流。 |
118
+
119
+ ## 使用说明
120
+
121
+ - 大多数用户数据场景都需要 `STEAM_WEB_API_KEY`，公开新闻和在线人数这类接口通常可以直接查。
122
+ - `steam_search_apps` 和 `steam_resolve_app` 依赖应用目录能力，也需要 `STEAM_WEB_API_KEY`；即使传入数字 `AppID`，解析阶段也会先做目录校验。
123
+ - `steam_me_*` 依赖 `STEAM_DEFAULT_STEAMID` 作为默认账号；未配置时会返回明确错误。
124
+ - 单游戏工具统一支持 `appid` 或 `query`，`query` 可直接输入中文游戏名。
125
+ - `steam_get_price_overview` 支持 `appid`、`subid`、`bundleid` 三种目标；其中 `query` 仅用于解析 app。
126
+ - `steam_get_achievement_roadmap` 目前只整合 Steam 指南，不抓取贴吧、B 站或第三方攻略站；输出的是“有来源依据的路线图草案”，不是保真攻略。
127
+ - 如果终端环境访问外部站点不稳定，但浏览器或 Steam 客户端可以正常打开，可统一配置 `PROXY_URL`，例如 `http://YOUR_PROXY_HOST:PORT`。
128
+ - 返回结果会优先补充 `localizedName` 和 `displayName`；拿不到中文名时会自动回退原始名称。
129
+ - 中文 `query` 对官方商店名和常见本地化标题支持较好；如果某个游戏在 Steam 商店本身没有稳定中文标题，仍建议直接传 `appid`。
130
+ - 好友、游戏库、成就等结果仍然会受目标账号隐私设置影响。
131
+ - Steam 官方文档里的 `ISteamApps.GetAppList` 当前已标记为 deprecated，本服务内部不会把它作为对外工具暴露。
132
+ - `steam_get_price_overview` 当前使用第三方公开价格源补充史低信息；如果第三方暂时不可用，工具会直接返回错误或 warning。
133
+
134
+ ## 开发说明
135
+
136
+ - 工具注册统一走 `src/tools/register-steam-tool.ts`。
137
+ - `npm run check:tool-registry` 会检查 `src/tools` 下是否误用了 `server.registerTool(...)`。
138
+ - 同步后的接口快照保存在 `src/generated/steam-web-api-spec.json`，仅作为底层调用数据，不再直接暴露为对外工具。