@xiawan-play/steam-tools-mcp 0.1.0

package/.env.example

@@ -0,0 +1,3 @@
+STEAM_WEB_API_KEY=YOUR-STEAM-WEB-API-KEY
+STEAM_DEFAULT_STEAMID=YOUR_STEAM_ID64
+STEAM_ENABLE_GENERATED_TOOLS=false

package/README.md

@@ -0,0 +1,149 @@
+# @xiawan-play/steam-tools-mcp
+
+一个面向 Node.js 的 Steam 相关 MCP 服务，提供中文友好的高频工具、我的账号快捷工具，以及可按需开启的全量官方方法工具集。
+
+## 特性
+
+- 开箱即用的高频 Steam 工具，适合资料、游戏库、成就、新闻和应用检索场景。
+- 提供 `steam_me_*` 快捷工具，适合长期绑定个人账号使用。
+- 自动同步官方 Steam Web API 文档，并可按需开启辅助探索工具与全量官方方法工具。
+- 工具标题、说明和参数描述优先面向中文用户设计。
+- 支持 `stdio`，也支持可选的 Streamable HTTP 传输方式。
+
+## 快速开始
+
+### 直接作为 MCP 配置运行
+
+```bash
+npx -y @xiawan-play/steam-tools-mcp
+```
+
+### 如需读取用户数据
+
+读取资料、游戏库、成就、好友等用户数据通常需要 `STEAM_WEB_API_KEY`；如果你主要使用 `steam_me_*` 快捷工具，建议同时配置 `STEAM_DEFAULT_STEAMID`。
+
+```bash
+$env:STEAM_WEB_API_KEY="YOUR_WEB_API_KEY"
+$env:STEAM_DEFAULT_STEAMID="YOUR_STEAM_ID64"
+```
+
+### 本地开发
+
+```bash
+npm install
+npm run sync:steam-spec
+npm run build
+npm run dev
+npm start
+```
+
+## MCP 配置
+
+### 推荐配置
+
+```json
+{
+  "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",
+        "STEAM_ENABLE_GENERATED_TOOLS": "false"
+      }
+    }
+  }
+}
+```
+
+### 常用环境变量
+
+| 变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `STEAM_WEB_API_KEY` | 无 | 默认使用的 Steam API Key，调用需要 `key` 的接口时会自动注入。 |
+| `STEAM_DEFAULT_STEAMID` | 无 | 默认查询用户的 SteamID64。高频聚合工具在未传用户参数时会自动使用它；部分底层 `steamid` / `steamids` 接口也会使用它作为默认值。 |
+| `STEAM_ENABLE_GENERATED_TOOLS` | `false` | 是否启用辅助探索工具和完整的自动生成 Steam 方法工具集。 |
+
+### 其他可选环境变量
+
+| 变量 | 默认值 | 作用 |
+| --- | --- | --- |
+| `STEAM_APP_LIST_CACHE_TTL_MS` | `21600000` | Steam 应用目录缓存时间，单位毫秒，默认 6 小时。 |
+| `MCP_TRANSPORT` | `stdio` | 传输方式，可选 `stdio` 或 `http`。 |
+| `HOST` | `127.0.0.1` | HTTP 模式监听地址。 |
+| `PORT` | `3000` | HTTP 模式监听端口。 |
+| `STEAM_REQUEST_TIMEOUT_MS` | `30000` | Steam API 请求超时时间，单位毫秒。 |
+
+完整参数说明见 `docs/configuration.md`。
+
+## 工具总览
+
+### 高频场景工具
+
+| Tool ID | 中文名 | 说明 |
+| --- | --- | --- |
+| `steam_get_player_profile_overview` | Steam 玩家资料总览 | 聚合玩家资料、封禁状态、等级、徽章和最近游玩。 |
+| `steam_get_library_overview` | Steam 游戏库总览 | 聚合玩家拥有的游戏、最近活动和常玩游戏。 |
+| `steam_get_achievement_overview` | Steam 成就总览 | 查看某位玩家在某个游戏中的成就、全局完成率和统计。 |
+| `steam_get_news_overview` | Steam 新闻总览 | 查看某个应用的新闻，并可附带当前在线人数。 |
+| `steam_search_apps` | Steam 应用搜索 | 按名称搜索 Steam 应用目录并返回候选 AppID。 |
+| `steam_resolve_app` | Steam 应用解析 | 把应用名称或 AppID 解析成最可能的目标应用。 |
+| `steam_get_global_achievement_overview` | Steam 全局成就概览 | 查看某个应用的全局成就完成率和 schema 补充信息。 |
+| `steam_get_app_snapshot` | Steam 应用快照 | 聚合应用基本信息、新闻、在线人数和全局成就趋势。 |
+
+### 我的账号快捷工具
+
+| Tool ID | 中文名 | 说明 |
+| --- | --- | --- |
+| `steam_me_profile` | 我的 Steam 资料 | 快捷查看默认账号的资料总览。 |
+| `steam_me_library` | 我的 Steam 游戏库 | 快捷查看默认账号的游戏库总览。 |
+| `steam_me_recently_played` | 我的最近游玩 | 查看默认账号最近玩过的游戏。 |
+| `steam_me_badges` | 我的 Steam 徽章 | 查看默认账号的等级和徽章信息。 |
+| `steam_me_achievement_overview` | 我的 Steam 成就总览 | 查看默认账号在指定游戏中的成就详情。 |
+| `steam_me_friends` | 我的 Steam 好友 | 查看好友列表，可选附带资料摘要和封禁信息。 |
+| `steam_me_friend_activity` | 我的好友动态 | 按正在游戏、在线和最近活跃整理好友状态。 |
+| `steam_me_friend_network` | 我的好友网络 | 输出好友分组和适合图谱渲染的 `nodes + edges`。 |
+| `steam_me_bans` | 我的封禁状态 | 查看默认账号的封禁摘要。 |
+| `steam_me_library_compare` | 我的游戏库对比 | 对比你和另一位玩家的游戏库交集、差集和共同游玩情况。 |
+| `steam_me_backlog_candidates` | 我的积压游戏候选 | 找出几乎没玩或很久没碰的已拥有游戏。 |
+| `steam_me_achievement_hunt` | 我的成就狩猎 | 找出离全成就不远、适合继续补完的游戏。 |
+| `steam_me_game_snapshot` | 我的游戏快照 | 聚合某个游戏的拥有情况、时长、成就、统计、新闻和热度。 |
+| `steam_me_groups` | 我的 Steam 群组 | 查看群组列表；普通 user key 场景下可能没有结果。 |
+| `steam_me_wishlist_like_feed` | 我的 Steam 关注流 | 默认按最近游玩的 AppID 聚合新闻和热度，也可切换到常玩游戏、混合来源或显式 AppID。 |
+
+### 可选：辅助探索工具
+
+当 `STEAM_ENABLE_GENERATED_TOOLS=true` 时，这组工具会一起开启，适合探索官方方法目录和做原始调试。
+
+| Tool ID | 中文名 | 说明 |
+| --- | --- | --- |
+| `steam_list_interfaces` | Steam 接口列表 | 列出当前已同步的接口目录，可按关键字和 Service Interface 过滤。 |
+| `steam_list_methods` | Steam 方法搜索 | 搜索当前已同步的方法，可按接口、关键字和鉴权要求过滤。 |
+| `steam_get_method_details` | Steam 方法详情 | 查看某个方法的参数、鉴权要求、来源链接和元信息。 |
+| `steam_call_raw` | Steam 原始调用 | 按接口名和方法名直接调用底层 Steam Web API，适合兜底和调试。 |
+
+### 可选：自动生成官方工具
+
+当 `STEAM_ENABLE_GENERATED_TOOLS=true` 时，同步后的官方 Steam 方法也会作为独立 tool 自动注册。工具 id 保持英文，标题和说明会尽量提供中文友好展示。例如：
+
+| Tool ID | 中文名 | 说明 |
+| --- | --- | --- |
+| `steam_i_player_service_get_owned_games` | 已拥有游戏 | 读取指定玩家的游戏库。 |
+| `steam_i_steam_user_stats_get_player_achievements` | 玩家成就 | 读取指定游戏的个人成就列表。 |
+| `steam_i_steam_news_get_news_for_app` | 应用新闻 | 读取指定应用的 Steam 新闻。 |
+
+## 使用说明
+
+- 资料、游戏库、个人成就、好友等大多数“用户数据”场景通常需要 `STEAM_WEB_API_KEY`；新闻、在线人数这类公开接口可以直接使用。
+- 如果配置了 `STEAM_DEFAULT_STEAMID`，大多数按用户查询的高频工具在不传用户参数时会默认查这个账号；`steam_me_*` 工具也依赖它，未配置时会直接返回明确错误。
+- 用户资料、游戏库、成就等结果仍然会受到目标账号隐私设置影响。
+- `steam_search_apps` / `steam_resolve_app` 的名称搜索，以及需要 schema 补充信息的场景，通常也需要 `STEAM_WEB_API_KEY`。
+- 默认模式只暴露高频工具和 `steam_me_*` 快捷工具；只有在需要辅助探索工具、底层官方方法或调试时，再开启 `STEAM_ENABLE_GENERATED_TOOLS=true`。
+- `steam_me_groups` 依赖的底层接口在官方文档中偏 `publisher key` 场景，普通 user key 很可能拿不到结果。
+- Steam 官方文档里的 `ISteamApps.GetAppList` 当前已经标记为 deprecated，直接调通常会返回 `404`；本服务会明确提示你改用 `steam_search_apps`、`steam_resolve_app` 或 `IStoreService.GetAppList`。
+- 对于 Service Interface，本服务会用 `input_json` 方式发送请求，这样数组和对象参数会更稳定。
+- 同步后的接口清单保存在源码中的 `src/generated/steam-web-api-spec.json`。

package/dist/server.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node