steam-games-mcp 0.4.6 → 0.5.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.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,128 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.5.0] - 2026-07-09
10
+
11
+ Richer store cards and catalog/wishlist discovery for the SteamOS / Steam Machine
12
+ era: three hardware-compatibility ratings, native-platform and user-tag filters,
13
+ a one-call enriched wishlist, discount expiry and clickable store links — all
14
+ keyless. Plus a substantial DRY/KISS refactor of the store-service layer.
15
+
16
+ ### Added
17
+
18
+ - **SteamOS and Steam Frame compatibility.** Valve's store API now returns two
19
+ compatibility ratings alongside `steam_deck_compat_category`:
20
+ `steam_os_compat_category` (SteamOS in general — any SteamOS device, including
21
+ the new Steam Machine, not just it) and `steam_frame_compat_category` (the Steam
22
+ Frame VR headset). `get_items` and `discover_games` now surface both as
23
+ `steam_os` / `steam_frame` (same `verified`/`playable`/`unsupported`/`unknown`
24
+ scale as `steam_deck`), and `discover_games` gains matching `steam_os` /
25
+ `steam_frame` filters. So "games that run on the Steam Machine / SteamOS" and
26
+ "Frame-Verified VR games" are now answerable.
27
+ - **Popular user tags.** `get_items` and `discover_games` now surface each game's
28
+ top user tags (e.g. `Roguelike`, `Souls-like`, `Deckbuilding`) as readable
29
+ names — resolved keyless from Steam's tag dictionary
30
+ (`IStoreService/GetTagList`, cached per language). `discover_games` also gains a
31
+ `tags` filter (AND, case-insensitive), so "roguelike deckbuilders on sale" is a
32
+ single call. Like the other `discover_games` filters it runs over the
33
+ popularity-first scan window (Steam's catalog API silently ignores tag filters),
34
+ so raise `count` when combining niche tags.
35
+ - **Native-platform (`platform`) filter + `platforms` field.** Store cards
36
+ (`get_items`, `discover_games`, `get_wishlist` detailed) now list each game's
37
+ native OS builds as `platforms` (`windows`/`mac`/`linux`), and `discover_games` /
38
+ `get_wishlist` gain a `platform` filter to keep only games with a native build
39
+ for that OS. Note: `linux` means a native Linux/SteamOS build — distinct from
40
+ `steam_os` (SteamOS Proton compatibility), which is a separate filter.
41
+ - **Enriched, filterable wishlist in one call.** `get_wishlist` gains
42
+ `include_details` — full store cards per item (name, price/discount, review %,
43
+ Deck/SteamOS/Frame compat, tags, release) via
44
+ `IWishlistService/GetWishlistSortedFiltered`, so "my wishlist with prices" no
45
+ longer needs a follow-up `get_items`. Narrow it in the same call with `tags`,
46
+ `platform` (native build), `steam_deck` / `steam_os` / `steam_frame` (Proton
47
+ compatibility), `min_review` and `min_discount` / `on_sale_only` (e.g. "top
48
+ metroidvanias on my wishlist, on sale, well-reviewed, that run on SteamOS") —
49
+ filters run over the whole wishlist before the output cap, and `matched` reports
50
+ the pre-cap count. The default (no flags) still returns the light appid list.
51
+ - **`discount_end` — when a deal expires.** Store cards (`get_items`,
52
+ `discover_games`, `get_wishlist` detailed) now include `discount_end` (ISO 8601
53
+ UTC) for discounted games, so "how long is this discount valid?" is answerable
54
+ and "deals ending soon" is sortable. Sourced from the store service's
55
+ `active_discounts`; the Storefront-backed `get_game` / `get_prices` don't carry
56
+ it.
57
+ - **Clickable `store_url` on every card.** `get_items`, `discover_games` and
58
+ `get_wishlist` (both light and detailed) now include a `store_url` linking
59
+ straight to each game's Steam store page — so results are one click away from the
60
+ page (the storefront tools already carried it; the store-service tools didn't).
61
+
62
+ ### Fixed
63
+
64
+ - **A failed tag lookup no longer masquerades as "no games matched."** If
65
+ Steam's tag dictionary (`IStoreService/GetTagList`) is temporarily
66
+ unavailable, `discover_games` and `get_wishlist`'s `tags` filter used to
67
+ silently return zero results (an empty dictionary made every tag comparison
68
+ fail) with no indication anything was wrong. Both now return a clear,
69
+ actionable error instead when a `tags` filter can't be reliably applied;
70
+ tag _display_ (no filter requested) still degrades gracefully to an empty
71
+ `tags` list, unaffected.
72
+ - **`get_wishlist`'s `country`/`language` no longer silently no-op.** Passing
73
+ either without any other filter used to fall through to the light,
74
+ appid-only response, which carries no price and therefore ignored both
75
+ parameters. Setting `country` or `language` now switches to the detailed
76
+ (store-card) view, same as any other filter.
77
+ - **`check:api` now also verifies `IWishlistService/GetWishlistSortedFiltered`**,
78
+ the endpoint backing `get_wishlist`'s `include_details`/filters — previously
79
+ the only new store service from this release without a live release-gate check.
80
+
81
+ ### Internal
82
+
83
+ - **Refactored the grown store-service layer (DRY/KISS), no behaviour change.**
84
+ Split the 660-line `format/web.ts` into `format/web.ts` (official Web API / player
85
+ data) and `format/store.ts` (keyless store services); extracted a shared
86
+ `baseCard` so `get_items` and `discover_games`/wishlist cards stop duplicating ~10
87
+ fields (and `get_items` now also carries the native `platforms` list);
88
+ centralised the tool param schemas + `reply()` wrapper in `tools/common.ts`
89
+ (killing duplicate `READ_ONLY`/`appid`/`country`/`language`/compat defs across the
90
+ two registration files); folded the repeated client `data_request` block into one
91
+ helper; and unified the client-side filtering (compat / native platform / tags /
92
+ review / discount / recency) that `discover_games` and the wishlist detailed view
93
+ both apply into a single `storeItemFilter` predicate. A second pass over the
94
+ storefront layer: shared `formattedPrice` / `storeUrl` helpers (dropped a stray
95
+ inline URL), a `#search` helper behind `searchGames`/`resolveAppId`, and — since
96
+ `getFeatured` and `getSpecials` hit the same endpoint — caching the raw
97
+ `featuredcategories` payload once so the two share a single upstream call per
98
+ region. A follow-up pass extracted `priceFields` so `get_items`'s nested price
99
+ block and the other cards' flat one share one `discount_pct`/`discount_end`/
100
+ original-price-fallback derivation instead of two hand-written copies.
101
+ - **`TtlCache` now shares one in-flight fetch across concurrent callers of the
102
+ same key**, instead of each starting its own. This mattered in practice once
103
+ `get_items`/`discover_games`/`get_wishlist` all began fetching the same
104
+ `tags:${language}` tag-dictionary cache key: two of those tools called at once
105
+ on a cold cache used to trigger two redundant `GetTagList` requests against the
106
+ keyless, rate-limited endpoint; now the second call reuses the first's promise.
107
+ - **Expanded test coverage** to ~94% lines (112 tests): direct unit tests for the
108
+ store card builders and `discountEnd`, the shared `storeItemFilter` (one case per
109
+ filter dimension), the new cache in-flight dedup, sparse-/malformed-payload
110
+ fallbacks in the storefront and Web API formatters, and regressions for the
111
+ `tags`-filter/`country`-`language` fixes above. Added `check:api` guards for
112
+ the compat + tag fields and the `GetTagList` dictionary (see also the
113
+ `GetWishlistSortedFiltered` guard under Fixed).
114
+ - Added an **e2e smoke test** that drives the real built bundle the way a client
115
+ does — a spawned `node dist/index.js` over stdio, run from a dir with no
116
+ node_modules — asserting it handshakes, registers all tools, and gates player
117
+ tools. Covers the integration boundary that the recent 0.4.4–0.4.6 bugs hid in
118
+ (in-memory unit tests never ran the actual artifact).
119
+ - Fixed that e2e smoke test failing on **Node 18**: the sandbox ran the ESM
120
+ bundle as a bare `index.js` with no `package.json`, so Node < 20.19 (no ESM
121
+ syntax auto-detection) parsed it as CommonJS and the child died with "Cannot
122
+ use import statement outside a module". The sandbox now ships a
123
+ `{"type":"module"}` package.json, mirroring the real npm/.mcpb artifact.
124
+
125
+ ### Dependencies
126
+
127
+ - Dev-dependency bumps: `@types/node` 26.1.1, `prettier` 3.9.4,
128
+ `typescript-eslint` 8.63.0. (TypeScript 7 deferred — `typescript-eslint` isn't
129
+ compatible with it yet.)
130
+
9
131
  ## [0.4.6] - 2026-06-30
10
132
 
11
133
  ### Fixed
package/README.md CHANGED
@@ -19,14 +19,18 @@ Once it's connected, just ask your agent in natural language.
19
19
  "What are recent reviews saying about Baldur's Gate 3?"
20
20
  "Have Cyberpunk 2077's reviews recovered since launch?"
21
21
  "Which games are >80% off right now with 90%+ positive reviews?"
22
+ "Find roguelike deckbuilders on sale."
23
+ "What discounted games run natively on macOS?"
22
24
  "Which recent, well-reviewed games run on Steam Deck?"
25
+ "What well-reviewed games run on the Steam Machine / SteamOS?"
26
+ "Any Steam Frame–Verified VR games on sale?"
23
27
  "What's discounted on Steam's front page right now?"
24
28
  "Show me Steam's top sellers and newest releases."
25
29
  "Any recent patch notes for No Man's Sky?"
26
30
  "How rare is each achievement in Elden Ring?"
27
31
  "How many people are playing Counter-Strike 2 right now?"
28
32
  "Get current prices for appids 620, 413150 and 1145360."
29
- "For appids 1245620 and 1086940, show price, review % and Steam Deck status."
33
+ "For appids 1245620 and 1086940, show price, review % and Deck / SteamOS / Frame status."
30
34
  ```
31
35
 
32
36
  **With a free API key + your `STEAM_ID`** (your account; see [Getting your credentials](#getting-your-credentials)):
@@ -106,31 +110,32 @@ need a free API key and a public profile. Three short steps:
106
110
 
107
111
  Key: **–** no credentials · **K** Steam Web API key.
108
112
 
109
- | Tool | Key | Purpose |
110
- | ------------------------- | --- | ------------------------------------------------------------------------------------------------------- |
111
- | `search_games` | – | Find games by title → appid (with price) |
112
- | `get_game` | – | Store details by appid **or name**: price, genres, platforms, Metacritic, age rating, DLC, requirements |
113
- | `get_items` | – | Batch store card (price, review %, **Steam Deck**, release) for a LIST of appids — one call |
114
- | `discover_games` | – | Find games catalog-wide by **discount**, **recency**, **Steam Deck** and rating — no appids needed |
115
- | `get_game_reviews` | – | Review summary + recent reviews |
116
- | `get_review_histogram` | – | Review trend over time (history + recent) |
117
- | `get_prices` | – | Batch current price/discount for many appids |
118
- | `get_specials` | – | Steam front-page discounts |
119
- | `get_featured` | – | Featured sections (top sellers, new releases, …) |
120
- | `get_game_news` | – | Recent news / patch notes |
121
- | `get_global_achievements` | – | Global achievement unlock rates (rarity) |
122
- | `get_current_players` | – | Live concurrent player count |
123
- | `get_wishlist` | – | A player's wishlist appids (public profiles) |
124
- | `get_game_achievements` | K | Full achievement list (names, descriptions) + rarity |
125
- | `resolve_vanity_url` | K | Custom profile name → SteamID64 |
126
- | `get_player_summary` | K | Player public profile |
127
- | `get_owned_games` | K | A player's games + playtime |
128
- | `get_recently_played` | K | Games played in the last two weeks |
129
- | `get_player_achievements` | K | A player's achievement progress in a game |
113
+ | Tool | Key | Purpose |
114
+ | ------------------------- | --- | ------------------------------------------------------------------------------------------------------------ |
115
+ | `search_games` | – | Find games by title → appid (with price) |
116
+ | `get_game` | – | Store details by appid **or name**: price, genres, platforms, Metacritic, age rating, DLC, requirements |
117
+ | `get_items` | – | Batch store card (price, review %, **Deck/SteamOS/Frame** compat, native **platforms**, **tags**) for appids |
118
+ | `discover_games` | – | Find games catalog-wide by **discount**, **recency**, **Deck/SteamOS/Frame**, **platform**, **tags**, rating |
119
+ | `get_game_reviews` | – | Review summary + recent reviews |
120
+ | `get_review_histogram` | – | Review trend over time (history + recent) |
121
+ | `get_prices` | – | Batch current price/discount for many appids |
122
+ | `get_specials` | – | Steam front-page discounts |
123
+ | `get_featured` | – | Featured sections (top sellers, new releases, …) |
124
+ | `get_game_news` | – | Recent news / patch notes |
125
+ | `get_global_achievements` | – | Global achievement unlock rates (rarity) |
126
+ | `get_current_players` | – | Live concurrent player count |
127
+ | `get_wishlist` | – | A player's wishlist — appids, or full cards + on-sale filter with `include_details` (public profiles) |
128
+ | `get_game_achievements` | K | Full achievement list (names, descriptions) + rarity |
129
+ | `resolve_vanity_url` | K | Custom profile name → SteamID64 |
130
+ | `get_player_summary` | K | Player public profile |
131
+ | `get_owned_games` | K | A player's games + playtime |
132
+ | `get_recently_played` | K | Games played in the last two weeks |
133
+ | `get_player_achievements` | K | A player's achievement progress in a game |
130
134
 
131
135
  **Two tiers.** Store/search + discovery tools (`store`/`api.steampowered.com`)
132
136
  need **no credentials** — including catalog-wide discovery (`discover_games`:
133
- deals, new releases, Steam Deck, rating) and batch price/review checks (`get_items`).
137
+ deals, new releases, Deck / SteamOS / Frame compatibility, tags, rating) and batch
138
+ price/review checks (`get_items`).
134
139
  Player tools need a free
135
140
  **`STEAM_API_KEY`** and a **public** profile; they return a clear message when the
136
141
  key is unset. Set **`STEAM_ID`** (a SteamID64 or vanity name) to make those tools