steam-games-mcp 0.2.0 → 0.3.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 +39 -0
- package/README.md +83 -24
- package/dist/index.js +201 -51
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,45 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.3.0]
|
|
10
|
+
|
|
11
|
+
### Changed
|
|
12
|
+
|
|
13
|
+
- **`discover_deals` merged into `discover_games`** (breaking). They were the same
|
|
14
|
+
catalog query with different presets, so they collapse into one tool. Pass
|
|
15
|
+
`min_discount` for deals, `released_after` / `released_within_days` for new
|
|
16
|
+
releases, `steam_deck` for Deck-capable games, and `min_review` / `min_reviews`
|
|
17
|
+
for rating — in any combination. Migration: replace
|
|
18
|
+
`discover_deals({ min_discount })` with `discover_games({ min_discount })`.
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
|
|
22
|
+
- `STEAM_ID` config (env / `.mcpb` user_config): set a default player — a 17-digit
|
|
23
|
+
SteamID64 or a vanity name (resolved once via the Web API) — so the player tools
|
|
24
|
+
(`get_wishlist`, `get_owned_games`, `get_recently_played`, `get_player_summary`,
|
|
25
|
+
`get_player_achievements`) default to you. Their `steamid` argument is now
|
|
26
|
+
optional and falls back to `STEAM_ID`; ask "my wishlist" without passing an ID.
|
|
27
|
+
- `get_game` now accepts a `name` as an alternative to `appid` — a title is
|
|
28
|
+
resolved to the closest store match, so you can look a game up without an appid.
|
|
29
|
+
- `get_player_achievements` gains a per-call `language` override for achievement
|
|
30
|
+
names/descriptions, matching `get_game_achievements` (falls back to `STEAM_LANGUAGE`).
|
|
31
|
+
- `discover_games` — find games catalog-wide (keyless) by discount, release recency
|
|
32
|
+
(`released_after` / `released_within_days`), **Steam Deck** compatibility and
|
|
33
|
+
review quality, in any combination. Sorts the catalog by popularity so the scanned
|
|
34
|
+
window holds real games with genuine Deck ratings and review counts (the default
|
|
35
|
+
appid order surfaced Deck-untested shovelware). Answers both "games >80% off with
|
|
36
|
+
90%+ reviews" and "recent well-reviewed games that run on Steam Deck".
|
|
37
|
+
- **Steam Deck compatibility** (`verified` / `playable` / `unsupported` / `unknown`)
|
|
38
|
+
is reported by `get_items` and `discover_games` (via `include_platforms`), with a
|
|
39
|
+
`steam_deck` filter on `discover_games`. Note: Steam's catalog API has no
|
|
40
|
+
server-side Deck filter or release-date sort, so the Deck/recency/review filters
|
|
41
|
+
are applied over the popularity-sorted page (raise `count` for stricter filters).
|
|
42
|
+
|
|
43
|
+
### Docs
|
|
44
|
+
|
|
45
|
+
- README: natural-language example queries and a step-by-step
|
|
46
|
+
"Getting your credentials" guide (API key, Steam ID, public profile).
|
|
47
|
+
|
|
9
48
|
## [0.2.0]
|
|
10
49
|
|
|
11
50
|
### Changed
|
package/README.md
CHANGED
|
@@ -10,6 +10,37 @@ profiles, libraries and achievements via the official **Steam Web API** (free ke
|
|
|
10
10
|
|
|
11
11
|
Works with any MCP client (Claude Desktop/Code, Cursor, VS Code, Cline, …) over stdio.
|
|
12
12
|
|
|
13
|
+
Once it's connected, just ask your agent in natural language.
|
|
14
|
+
|
|
15
|
+
**No credentials needed** (store, search & discovery):
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
"Find Hollow Knight and tell me its price, genres and age rating."
|
|
19
|
+
"What are recent reviews saying about Baldur's Gate 3?"
|
|
20
|
+
"Have Cyberpunk 2077's reviews recovered since launch?"
|
|
21
|
+
"Which games are >80% off right now with 90%+ positive reviews?"
|
|
22
|
+
"Which recent, well-reviewed games run on Steam Deck?"
|
|
23
|
+
"What's discounted on Steam's front page right now?"
|
|
24
|
+
"Show me Steam's top sellers and newest releases."
|
|
25
|
+
"Any recent patch notes for No Man's Sky?"
|
|
26
|
+
"How rare is each achievement in Elden Ring?"
|
|
27
|
+
"How many people are playing Counter-Strike 2 right now?"
|
|
28
|
+
"Get current prices for appids 620, 413150 and 1145360."
|
|
29
|
+
"For appids 1245620 and 1086940, show price, review % and Steam Deck status."
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**With a free API key + your `STEAM_ID`** (your account; see [Getting your credentials](#getting-your-credentials)):
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
"Show my Steam profile."
|
|
36
|
+
"List my games by playtime."
|
|
37
|
+
"What have I played in the last two weeks?"
|
|
38
|
+
"What's on my wishlist that's discounted and well-reviewed?"
|
|
39
|
+
"List Hollow Knight's achievements and how rare each one is."
|
|
40
|
+
"How far am I through Elden Ring's achievements?"
|
|
41
|
+
"What's the SteamID64 for the profile name 'gabelogannewell'?"
|
|
42
|
+
```
|
|
43
|
+
|
|
13
44
|
## Install
|
|
14
45
|
|
|
15
46
|
Add it to your MCP client's config. Store/search tools work with **no
|
|
@@ -23,6 +54,7 @@ credentials**; player tools need a free Steam Web API key.
|
|
|
23
54
|
"args": ["-y", "steam-games-mcp"],
|
|
24
55
|
"env": {
|
|
25
56
|
"STEAM_API_KEY": "your-steam-web-api-key (optional — enables player tools)",
|
|
57
|
+
"STEAM_ID": "your-steamid64-or-vanity-name (optional — default 'you' for player tools)",
|
|
26
58
|
"STEAM_COUNTRY": "US (optional — store price region)",
|
|
27
59
|
"STEAM_LANGUAGE": "english (optional — store language)"
|
|
28
60
|
}
|
|
@@ -37,37 +69,64 @@ credentials**; player tools need a free Steam Web API key.
|
|
|
37
69
|
> `"args": ["/ABS/PATH/steam-games-mcp/dist/index.js"]`. **As a `.mcpb` bundle:** grab it
|
|
38
70
|
> from the [latest release](https://github.com/Grinv/steam-games-mcp/releases/latest).
|
|
39
71
|
|
|
72
|
+
## Getting your credentials
|
|
73
|
+
|
|
74
|
+
Store, search and discovery tools need **nothing** — skip this section if that's
|
|
75
|
+
all you want. The **player** tools (profile, library, achievements, your wishlist)
|
|
76
|
+
need a free API key and a public profile. Three short steps:
|
|
77
|
+
|
|
78
|
+
1. **Get a free Steam Web API key.** Sign in at
|
|
79
|
+
<https://steamcommunity.com/dev/apikey>, enter any domain (e.g. `localhost`),
|
|
80
|
+
and copy the key into `STEAM_API_KEY`.
|
|
81
|
+
2. **Find your Steam ID.** Set `STEAM_ID` to either:
|
|
82
|
+
- your **vanity name** — the custom part of your profile URL
|
|
83
|
+
`steamcommunity.com/id/YOUR_NAME` → `YOUR_NAME` (resolved automatically), or
|
|
84
|
+
- your **17-digit SteamID64** (`steamcommunity.com/profiles/7656…`; or look it
|
|
85
|
+
up at <https://steamid.io>).
|
|
86
|
+
|
|
87
|
+
With `STEAM_ID` set you can just ask "_my_ wishlist / library" — without it,
|
|
88
|
+
give the agent a SteamID64 each time (use `resolve_vanity_url` to convert a name).
|
|
89
|
+
|
|
90
|
+
3. **Make your profile public** (for your own library/achievements): Steam →
|
|
91
|
+
profile → **Edit Profile** → **Privacy Settings** → set **My profile** and
|
|
92
|
+
**Game details** to **Public**.
|
|
93
|
+
|
|
94
|
+
> The key and Steam ID go in your MCP client config (the `env` block above) — see
|
|
95
|
+
> [docs/clients.md](docs/clients.md) for per-client examples. Never commit them.
|
|
96
|
+
|
|
40
97
|
## What it does
|
|
41
98
|
|
|
42
99
|
Key: **–** no credentials · **K** Steam Web API key.
|
|
43
100
|
|
|
44
|
-
| Tool | Key | Purpose
|
|
45
|
-
| ------------------------- | --- |
|
|
46
|
-
| `search_games` | – | Find games by title → appid (with price)
|
|
47
|
-
| `get_game` | – | Store details
|
|
48
|
-
| `get_items` | – | Batch store card (price, review %, release) for a LIST of appids — one call
|
|
49
|
-
| `
|
|
50
|
-
| `get_game_reviews` | – | Review summary + recent reviews
|
|
51
|
-
| `get_review_histogram` | – | Review trend over time (history + recent)
|
|
52
|
-
| `get_prices` | – | Batch current price/discount for many appids
|
|
53
|
-
| `get_specials` | – | Steam front-page discounts
|
|
54
|
-
| `get_featured` | – | Featured sections (top sellers, new releases, …)
|
|
55
|
-
| `get_game_news` | – | Recent news / patch notes
|
|
56
|
-
| `get_global_achievements` | – | Global achievement unlock rates (rarity)
|
|
57
|
-
| `get_current_players` | – | Live concurrent player count
|
|
58
|
-
| `get_wishlist` | – | A player's wishlist appids (public profiles)
|
|
59
|
-
| `get_game_achievements` | K | Full achievement list (names, descriptions) + rarity
|
|
60
|
-
| `resolve_vanity_url` | K | Custom profile name → SteamID64
|
|
61
|
-
| `get_player_summary` | K | Player public profile
|
|
62
|
-
| `get_owned_games` | K | A player's games + playtime
|
|
63
|
-
| `get_recently_played` | K | Games played in the last two weeks
|
|
64
|
-
| `get_player_achievements` | K | A player's achievement progress in a game
|
|
101
|
+
| Tool | Key | Purpose |
|
|
102
|
+
| ------------------------- | --- | ------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| `search_games` | – | Find games by title → appid (with price) |
|
|
104
|
+
| `get_game` | – | Store details by appid **or name**: price, genres, platforms, Metacritic, age rating, DLC, requirements |
|
|
105
|
+
| `get_items` | – | Batch store card (price, review %, **Steam Deck**, release) for a LIST of appids — one call |
|
|
106
|
+
| `discover_games` | – | Find games catalog-wide by **discount**, **recency**, **Steam Deck** and rating — no appids needed |
|
|
107
|
+
| `get_game_reviews` | – | Review summary + recent reviews |
|
|
108
|
+
| `get_review_histogram` | – | Review trend over time (history + recent) |
|
|
109
|
+
| `get_prices` | – | Batch current price/discount for many appids |
|
|
110
|
+
| `get_specials` | – | Steam front-page discounts |
|
|
111
|
+
| `get_featured` | – | Featured sections (top sellers, new releases, …) |
|
|
112
|
+
| `get_game_news` | – | Recent news / patch notes |
|
|
113
|
+
| `get_global_achievements` | – | Global achievement unlock rates (rarity) |
|
|
114
|
+
| `get_current_players` | – | Live concurrent player count |
|
|
115
|
+
| `get_wishlist` | – | A player's wishlist appids (public profiles) |
|
|
116
|
+
| `get_game_achievements` | K | Full achievement list (names, descriptions) + rarity |
|
|
117
|
+
| `resolve_vanity_url` | K | Custom profile name → SteamID64 |
|
|
118
|
+
| `get_player_summary` | K | Player public profile |
|
|
119
|
+
| `get_owned_games` | K | A player's games + playtime |
|
|
120
|
+
| `get_recently_played` | K | Games played in the last two weeks |
|
|
121
|
+
| `get_player_achievements` | K | A player's achievement progress in a game |
|
|
65
122
|
|
|
66
123
|
**Two tiers.** Store/search + discovery tools (`store`/`api.steampowered.com`)
|
|
67
|
-
need **no credentials** — including catalog-wide
|
|
68
|
-
and batch price/review checks (`get_items`).
|
|
124
|
+
need **no credentials** — including catalog-wide discovery (`discover_games`:
|
|
125
|
+
deals, new releases, Steam Deck, rating) and batch price/review checks (`get_items`).
|
|
126
|
+
Player tools need a free
|
|
69
127
|
**`STEAM_API_KEY`** and a **public** profile; they return a clear message when the
|
|
70
|
-
key is unset.
|
|
128
|
+
key is unset. Set **`STEAM_ID`** (a SteamID64 or vanity name) to make those tools
|
|
129
|
+
default to you, so "my wishlist / library" works without passing an ID each time.
|
|
71
130
|
|
|
72
131
|
> No third-party services: deal discovery and reviews come from Steam's own
|
|
73
132
|
> (keyless) store APIs. SteamDB is not used (no public API + scraping disallowed).
|
package/dist/index.js
CHANGED
|
@@ -10,6 +10,10 @@ var EnvSchema = z.object({
|
|
|
10
10
|
// --- Steam Web API: free key (player data). https://steamcommunity.com/dev/apikey
|
|
11
11
|
STEAM_API_KEY: z.string().min(1).optional(),
|
|
12
12
|
STEAM_API_BASE_URL: z.string().url().default("https://api.steampowered.com"),
|
|
13
|
+
// Default player for the personal tools (wishlist/library/achievements) so a
|
|
14
|
+
// SteamID64 need not be passed every call. Accepts a 17-digit SteamID64 or a
|
|
15
|
+
// vanity name (the part after /id/), resolved once via the Web API (needs a key).
|
|
16
|
+
STEAM_ID: z.string().min(2).optional(),
|
|
13
17
|
// --- Steam Storefront API: no key; game/store data. ---
|
|
14
18
|
STEAM_STORE_BASE_URL: z.string().url().default("https://store.steampowered.com"),
|
|
15
19
|
// Storefront is region/locale-aware: cc = ISO country (prices), l = language.
|
|
@@ -33,6 +37,7 @@ function loadConfig(env = process.env) {
|
|
|
33
37
|
return {
|
|
34
38
|
steamApiBaseUrl: parsed.STEAM_API_BASE_URL,
|
|
35
39
|
steamApiKey: parsed.STEAM_API_KEY,
|
|
40
|
+
defaultSteamId: parsed.STEAM_ID,
|
|
36
41
|
steamStoreBaseUrl: parsed.STEAM_STORE_BASE_URL,
|
|
37
42
|
country: parsed.STEAM_COUNTRY,
|
|
38
43
|
language: parsed.STEAM_LANGUAGE,
|
|
@@ -106,7 +111,7 @@ function safeString(value) {
|
|
|
106
111
|
}
|
|
107
112
|
|
|
108
113
|
// src/version.ts
|
|
109
|
-
var VERSION = "0.
|
|
114
|
+
var VERSION = "0.3.0";
|
|
110
115
|
var USER_AGENT = `steam-games-mcp/${VERSION} (+https://github.com/Grinv/steam-games-mcp)`;
|
|
111
116
|
|
|
112
117
|
// src/lib/http.ts
|
|
@@ -699,6 +704,16 @@ function summarizeReviewHistogram(r) {
|
|
|
699
704
|
recent: (res.recent ?? []).slice(-30).map(rollup)
|
|
700
705
|
};
|
|
701
706
|
}
|
|
707
|
+
var DECK_COMPAT = {
|
|
708
|
+
0: "unknown",
|
|
709
|
+
1: "unsupported",
|
|
710
|
+
2: "playable",
|
|
711
|
+
3: "verified"
|
|
712
|
+
};
|
|
713
|
+
function steamDeck(cat) {
|
|
714
|
+
return DECK_COMPAT[cat ?? 0] ?? "unknown";
|
|
715
|
+
}
|
|
716
|
+
var DECK_MIN = { verified: 3, playable: 2 };
|
|
702
717
|
function storeCard(it) {
|
|
703
718
|
const bp = it.best_purchase_option;
|
|
704
719
|
const rev = it.reviews?.summary_filtered;
|
|
@@ -711,11 +726,20 @@ function storeCard(it) {
|
|
|
711
726
|
review_percent: rev?.percent_positive ?? null,
|
|
712
727
|
review_count: rev?.review_count ?? null,
|
|
713
728
|
review_label: rev?.review_score_label ?? null,
|
|
729
|
+
steam_deck: steamDeck(it.platforms?.steam_deck_compat_category),
|
|
714
730
|
release_date: it.release?.steam_release_date ? new Date(it.release.steam_release_date * 1e3).toISOString().slice(0, 10) : null
|
|
715
731
|
};
|
|
716
732
|
}
|
|
717
733
|
function summarizeDiscover(r, opts) {
|
|
718
|
-
|
|
734
|
+
const deckMin = opts.steamDeck ? DECK_MIN[opts.steamDeck] : void 0;
|
|
735
|
+
let rows = (r.response?.store_items ?? []).filter((it) => {
|
|
736
|
+
if (it.visible === false || typeof it.appid !== "number") return false;
|
|
737
|
+
if (deckMin !== void 0 && (it.platforms?.steam_deck_compat_category ?? 0) < deckMin)
|
|
738
|
+
return false;
|
|
739
|
+
if (opts.releasedAfter !== void 0 && (it.release?.steam_release_date ?? 0) < opts.releasedAfter)
|
|
740
|
+
return false;
|
|
741
|
+
return true;
|
|
742
|
+
}).map(storeCard);
|
|
719
743
|
if (typeof opts.minReview === "number") {
|
|
720
744
|
rows = rows.filter((x) => (x.review_percent ?? -1) >= opts.minReview);
|
|
721
745
|
}
|
|
@@ -754,6 +778,7 @@ function summarizeItems(r, appids) {
|
|
|
754
778
|
review_percent: rev?.percent_positive ?? null,
|
|
755
779
|
review_count: rev?.review_count ?? null,
|
|
756
780
|
review_label: rev?.review_score_label ?? null,
|
|
781
|
+
steam_deck: steamDeck(it.platforms?.steam_deck_compat_category),
|
|
757
782
|
release_date: it.release?.steam_release_date ? new Date(it.release.steam_release_date * 1e3).toISOString().slice(0, 10) : null,
|
|
758
783
|
coming_soon: it.release?.is_coming_soon ?? false
|
|
759
784
|
};
|
|
@@ -788,6 +813,14 @@ var StorefrontClient = class {
|
|
|
788
813
|
});
|
|
789
814
|
return summarizeSearch(res);
|
|
790
815
|
}
|
|
816
|
+
// Resolve a game title to its appid via store search (top match), so callers
|
|
817
|
+
// can pass a name instead of an appid. Returns null when nothing matches.
|
|
818
|
+
async resolveAppId(term, country2, language2) {
|
|
819
|
+
const res = await this.#http.getJson("api/storesearch/", {
|
|
820
|
+
query: { term, l: language2 ?? this.#l, cc: country2 ?? this.#cc }
|
|
821
|
+
});
|
|
822
|
+
return res.items?.find((i) => typeof i.id === "number")?.id ?? null;
|
|
823
|
+
}
|
|
791
824
|
async getGame(appid3, country2, language2) {
|
|
792
825
|
const cc = country2 ?? this.#cc;
|
|
793
826
|
const l = language2 ?? this.#l;
|
|
@@ -872,12 +905,16 @@ var SteamWebClient = class {
|
|
|
872
905
|
#key;
|
|
873
906
|
#l;
|
|
874
907
|
#country;
|
|
908
|
+
#defaultSteamId;
|
|
909
|
+
// Memoised result of resolving a vanity STEAM_ID default to a SteamID64.
|
|
910
|
+
#resolvedDefault;
|
|
875
911
|
/** True when a Steam Web API key is configured; player tools short-circuit otherwise. */
|
|
876
912
|
configured;
|
|
877
913
|
constructor(config, logger) {
|
|
878
914
|
this.#key = config.steamApiKey;
|
|
879
915
|
this.#l = config.language;
|
|
880
916
|
this.#country = config.country;
|
|
917
|
+
this.#defaultSteamId = config.defaultSteamId;
|
|
881
918
|
this.configured = Boolean(config.steamApiKey);
|
|
882
919
|
const limiter = new RateLimiter(config.apiMinIntervalMs);
|
|
883
920
|
this.#http = new HttpClient({
|
|
@@ -892,6 +929,39 @@ var SteamWebClient = class {
|
|
|
892
929
|
#get(path, query) {
|
|
893
930
|
return this.#http.getJson(path, { query: { key: this.#key, ...query } });
|
|
894
931
|
}
|
|
932
|
+
// Resolve the SteamID64 a player tool should act on: the explicit argument
|
|
933
|
+
// wins; otherwise fall back to the configured STEAM_ID default (resolving a
|
|
934
|
+
// vanity name once). Throws a clear ApiError when neither is available.
|
|
935
|
+
async requireSteamId(explicit) {
|
|
936
|
+
if (explicit) return explicit;
|
|
937
|
+
const raw = this.#defaultSteamId;
|
|
938
|
+
if (!raw) {
|
|
939
|
+
throw new ApiError({
|
|
940
|
+
code: "bad_request",
|
|
941
|
+
message: "no steamid was given and STEAM_ID is not set. Pass a 17-digit SteamID64, or set STEAM_ID (a SteamID64 or vanity name) in the server config."
|
|
942
|
+
});
|
|
943
|
+
}
|
|
944
|
+
if (/^\d{17}$/.test(raw)) return raw;
|
|
945
|
+
if (this.#resolvedDefault) return this.#resolvedDefault;
|
|
946
|
+
if (!this.configured) {
|
|
947
|
+
throw new ApiError({
|
|
948
|
+
code: "bad_request",
|
|
949
|
+
message: `STEAM_ID is a vanity name ("${raw}") which needs a Steam Web API key to resolve. Set STEAM_API_KEY, or set STEAM_ID to a 17-digit SteamID64 instead.`
|
|
950
|
+
});
|
|
951
|
+
}
|
|
952
|
+
const res = await this.#get("ISteamUser/ResolveVanityURL/v1/", {
|
|
953
|
+
vanityurl: raw
|
|
954
|
+
});
|
|
955
|
+
const steamid2 = res.response?.steamid;
|
|
956
|
+
if (res.response?.success !== 1 || !steamid2) {
|
|
957
|
+
throw new ApiError({
|
|
958
|
+
code: "bad_request",
|
|
959
|
+
message: `could not resolve the STEAM_ID vanity name "${raw}" to a SteamID64.`
|
|
960
|
+
});
|
|
961
|
+
}
|
|
962
|
+
this.#resolvedDefault = steamid2;
|
|
963
|
+
return steamid2;
|
|
964
|
+
}
|
|
895
965
|
// ---- player data (key required) -------------------------------------------
|
|
896
966
|
async getPlayerSummary(steamid2) {
|
|
897
967
|
const res = await this.#get("ISteamUser/GetPlayerSummaries/v2/", {
|
|
@@ -913,20 +983,21 @@ var SteamWebClient = class {
|
|
|
913
983
|
});
|
|
914
984
|
return summarizeRecentlyPlayed(res);
|
|
915
985
|
}
|
|
916
|
-
async getPlayerAchievements(steamid2, appid3) {
|
|
986
|
+
async getPlayerAchievements(steamid2, appid3, language2) {
|
|
987
|
+
const l = language2 ?? this.#l;
|
|
917
988
|
try {
|
|
918
989
|
const res = await this.#get(
|
|
919
990
|
"ISteamUserStats/GetPlayerAchievements/v1/",
|
|
920
|
-
{ steamid: steamid2, appid: appid3, l
|
|
991
|
+
{ steamid: steamid2, appid: appid3, l }
|
|
921
992
|
);
|
|
922
993
|
if (res.playerstats?.success) return summarizePlayerAchievements(res);
|
|
923
|
-
return this.#explainNoPlayerAchievements(appid3, res.playerstats?.error);
|
|
994
|
+
return this.#explainNoPlayerAchievements(appid3, l, res.playerstats?.error);
|
|
924
995
|
} catch (e) {
|
|
925
996
|
if (e instanceof ApiError && (e.code === "forbidden" || e.code === "unauthorized")) {
|
|
926
997
|
return { found: false, reason: PRIVATE_PROFILE_REASON };
|
|
927
998
|
}
|
|
928
999
|
if (e instanceof ApiError && (e.code === "bad_request" || e.code === "not_found")) {
|
|
929
|
-
return this.#explainNoPlayerAchievements(appid3);
|
|
1000
|
+
return this.#explainNoPlayerAchievements(appid3, l);
|
|
930
1001
|
}
|
|
931
1002
|
throw e;
|
|
932
1003
|
}
|
|
@@ -934,14 +1005,14 @@ var SteamWebClient = class {
|
|
|
934
1005
|
// On failure, check the game's schema: if it HAS achievements the player data
|
|
935
1006
|
// is hidden (private/not owned); if it has none, the game simply has no
|
|
936
1007
|
// achievements. Only runs on the failure path, so the happy path stays 1 call.
|
|
937
|
-
async #explainNoPlayerAchievements(appid3, apiError) {
|
|
1008
|
+
async #explainNoPlayerAchievements(appid3, l, apiError) {
|
|
938
1009
|
if (apiError && /not public|private/i.test(apiError)) {
|
|
939
1010
|
return { found: false, reason: PRIVATE_PROFILE_REASON };
|
|
940
1011
|
}
|
|
941
1012
|
try {
|
|
942
1013
|
const schema = await this.#get("ISteamUserStats/GetSchemaForGame/v2/", {
|
|
943
1014
|
appid: appid3,
|
|
944
|
-
l
|
|
1015
|
+
l
|
|
945
1016
|
});
|
|
946
1017
|
const has = (schema.game?.availableGameStats?.achievements?.length ?? 0) > 0;
|
|
947
1018
|
return {
|
|
@@ -991,35 +1062,64 @@ var SteamWebClient = class {
|
|
|
991
1062
|
const input = {
|
|
992
1063
|
ids: appids.map((appid3) => ({ appid: appid3 })),
|
|
993
1064
|
context: { language: language2 ?? this.#l, country_code: country2 ?? this.#country },
|
|
994
|
-
data_request: {
|
|
1065
|
+
data_request: {
|
|
1066
|
+
include_basic_info: true,
|
|
1067
|
+
include_reviews: true,
|
|
1068
|
+
include_release: true,
|
|
1069
|
+
include_platforms: true
|
|
1070
|
+
// brings steam_deck_compat_category
|
|
1071
|
+
}
|
|
995
1072
|
};
|
|
996
1073
|
const res = await this.#get("IStoreBrowseService/GetItems/v1/", {
|
|
997
1074
|
input_json: JSON.stringify(input)
|
|
998
1075
|
});
|
|
999
1076
|
return summarizeItems(res, appids);
|
|
1000
1077
|
}
|
|
1001
|
-
//
|
|
1002
|
-
//
|
|
1003
|
-
//
|
|
1004
|
-
//
|
|
1005
|
-
|
|
1078
|
+
// Shared catalog discovery over the keyless store query backend (discoverGames
|
|
1079
|
+
// is a thin preset over this). The Query API can't filter/sort on reviews,
|
|
1080
|
+
// Deck or release date, so those are applied in
|
|
1081
|
+
// summarizeDiscover over the returned page — which is why we sort by
|
|
1082
|
+
// popularity (sort:10): without a sort the page is appid-ordered and fills
|
|
1083
|
+
// with obscure, Deck-untested shovelware, making the post-filters return
|
|
1084
|
+
// nothing useful. Popularity puts real games (with Deck ratings + review
|
|
1085
|
+
// counts) into the window.
|
|
1086
|
+
async #queryCatalog(p) {
|
|
1087
|
+
const filters = {};
|
|
1088
|
+
if (typeof p.minDiscount === "number")
|
|
1089
|
+
filters.price_filters = { min_discount_percent: p.minDiscount };
|
|
1090
|
+
if (p.releasedOnly) filters.released_only = true;
|
|
1006
1091
|
const input = {
|
|
1007
|
-
query: {
|
|
1008
|
-
start: p.start ?? 0,
|
|
1009
|
-
count: p.count ?? 50,
|
|
1010
|
-
filters: { price_filters: { min_discount_percent: p.minDiscount } }
|
|
1011
|
-
},
|
|
1092
|
+
query: { start: p.start ?? 0, count: p.count ?? 50, sort: 10, filters },
|
|
1012
1093
|
context: {
|
|
1013
1094
|
language: p.language ?? this.#l,
|
|
1014
1095
|
country_code: p.country ?? this.#country,
|
|
1015
1096
|
steam_realm: 1
|
|
1016
1097
|
},
|
|
1017
|
-
|
|
1098
|
+
// include_platforms → steam_deck_compat_category; include_release → date.
|
|
1099
|
+
data_request: {
|
|
1100
|
+
include_basic_info: true,
|
|
1101
|
+
include_reviews: true,
|
|
1102
|
+
include_platforms: true,
|
|
1103
|
+
include_release: true
|
|
1104
|
+
}
|
|
1018
1105
|
};
|
|
1019
1106
|
const res = await this.#get("IStoreQueryService/Query/v1/", {
|
|
1020
1107
|
input_json: JSON.stringify(input)
|
|
1021
1108
|
});
|
|
1022
|
-
return summarizeDiscover(res, {
|
|
1109
|
+
return summarizeDiscover(res, {
|
|
1110
|
+
minReview: p.minReview,
|
|
1111
|
+
minReviews: p.minReviews,
|
|
1112
|
+
steamDeck: p.steamDeck,
|
|
1113
|
+
releasedAfter: p.releasedAfter
|
|
1114
|
+
});
|
|
1115
|
+
}
|
|
1116
|
+
// Catalog-wide game discovery: browse by discount, recency, Steam Deck support
|
|
1117
|
+
// and review quality, in any combination. Every filter is optional — pass
|
|
1118
|
+
// minDiscount for "on sale", releasedAfter for "new", steamDeck for "runs on
|
|
1119
|
+
// Deck", or mix them. released_only is set only when a recency cutoff is given,
|
|
1120
|
+
// so a pure deal query still surfaces pre-purchase discounts.
|
|
1121
|
+
async discoverGames(p) {
|
|
1122
|
+
return this.#queryCatalog({ ...p, releasedOnly: p.releasedAfter !== void 0 });
|
|
1023
1123
|
}
|
|
1024
1124
|
// A player's wishlist (needs the wishlist/profile to be public). Keyless.
|
|
1025
1125
|
async getWishlist(steamid2) {
|
|
@@ -1122,11 +1222,27 @@ function registerStorefrontTools(server, store) {
|
|
|
1122
1222
|
"get_game",
|
|
1123
1223
|
{
|
|
1124
1224
|
title: "Get game details",
|
|
1125
|
-
description: "Get full store details for one game
|
|
1126
|
-
inputSchema: {
|
|
1225
|
+
description: "Get full store details for one game: description, price/discount, genres, platforms, release date, developers/publishers, Metacritic, age rating, DLC and PC requirements. Identify the game by appid (from search_games) OR by name \u2014 a title is resolved to the closest store match. No API key required.",
|
|
1226
|
+
inputSchema: {
|
|
1227
|
+
appid: appid.describe("Steam appid (from search_games). Provide appid OR name.").optional(),
|
|
1228
|
+
name: z2.string().min(1).describe(
|
|
1229
|
+
"Game title to look up instead of an appid \u2014 resolved to the closest store match. Provide appid OR name; appid wins if both are given."
|
|
1230
|
+
).optional(),
|
|
1231
|
+
country,
|
|
1232
|
+
language
|
|
1233
|
+
},
|
|
1127
1234
|
annotations: READ_ONLY
|
|
1128
1235
|
},
|
|
1129
|
-
({ appid: id, country: cc, language: l }) =>
|
|
1236
|
+
({ appid: id, name, country: cc, language: l }) => guard(async () => {
|
|
1237
|
+
let resolved = id;
|
|
1238
|
+
if (!resolved) {
|
|
1239
|
+
if (!name) return errorResult("Provide either appid or name.");
|
|
1240
|
+
const found = await store.resolveAppId(name, cc, l);
|
|
1241
|
+
if (!found) return errorResult(`No Steam game found matching "${name}".`);
|
|
1242
|
+
resolved = found;
|
|
1243
|
+
}
|
|
1244
|
+
return jsonResult(await store.getGame(resolved, cc, l));
|
|
1245
|
+
})
|
|
1130
1246
|
);
|
|
1131
1247
|
server.registerTool(
|
|
1132
1248
|
"get_game_reviews",
|
|
@@ -1170,7 +1286,7 @@ function registerStorefrontTools(server, store) {
|
|
|
1170
1286
|
"get_specials",
|
|
1171
1287
|
{
|
|
1172
1288
|
title: "Get current discounts",
|
|
1173
|
-
description: "List games currently on special (discounted) on the Steam store front page, with the discount % and original/final price. For ALL catalog discounts (not just the front page), use
|
|
1289
|
+
description: "List games currently on special (discounted) on the Steam store front page, with the discount % and original/final price. For ALL catalog discounts (not just the front page), use discover_games with min_discount. No API key required.",
|
|
1174
1290
|
inputSchema: { country, language },
|
|
1175
1291
|
annotations: READ_ONLY
|
|
1176
1292
|
},
|
|
@@ -1195,7 +1311,9 @@ var appid2 = z3.number().int().positive().describe("Steam application id (appid)
|
|
|
1195
1311
|
var steamid = z3.string().regex(
|
|
1196
1312
|
/^\d{17}$/,
|
|
1197
1313
|
"A SteamID64 is 17 digits. Use resolve_vanity_url to convert a custom profile name."
|
|
1198
|
-
).describe(
|
|
1314
|
+
).describe(
|
|
1315
|
+
"17-digit SteamID64. Omit to use the STEAM_ID configured on the server. Convert a vanity/custom URL name with resolve_vanity_url first."
|
|
1316
|
+
).optional();
|
|
1199
1317
|
var reply2 = (fn) => guard(async () => jsonResult(await fn()));
|
|
1200
1318
|
function registerWebTools(server, web) {
|
|
1201
1319
|
const requireKey = (fn) => {
|
|
@@ -1235,7 +1353,7 @@ function registerWebTools(server, web) {
|
|
|
1235
1353
|
"get_items",
|
|
1236
1354
|
{
|
|
1237
1355
|
title: "Batch store card for many games",
|
|
1238
|
-
description: "Get price/discount, review % (positive) and release date for a LIST of games by appid in ONE keyless call. The efficient way to price- and
|
|
1356
|
+
description: "Get price/discount, review % (positive), Steam Deck compatibility and release date for a LIST of games by appid in ONE keyless call. The efficient way to price-, rating- and Deck-check a wishlist or library without a request per game (each item carries a steam_deck field: verified/playable/unsupported/unknown). Get appids from search_games / get_wishlist / get_owned_games.",
|
|
1239
1357
|
inputSchema: {
|
|
1240
1358
|
appids: z3.array(z3.number().int().positive()).min(1).max(100).describe("Steam appids (1-100)."),
|
|
1241
1359
|
country: z3.string().regex(/^[A-Za-z]{2}$/, "Two-letter ISO country code.").describe("Country (cc) for prices; overrides STEAM_COUNTRY.").optional(),
|
|
@@ -1246,14 +1364,21 @@ function registerWebTools(server, web) {
|
|
|
1246
1364
|
({ appids, country: country2, language: language2 }) => reply2(() => web.getItems(appids, country2, language2))
|
|
1247
1365
|
);
|
|
1248
1366
|
server.registerTool(
|
|
1249
|
-
"
|
|
1367
|
+
"discover_games",
|
|
1250
1368
|
{
|
|
1251
|
-
title: "Discover
|
|
1252
|
-
description: "Find games
|
|
1369
|
+
title: "Discover games (deals, new releases, Steam Deck, rating)",
|
|
1370
|
+
description: "Find games across the whole Steam catalog (keyless), filtered by ANY combination of: discount (min_discount \u2014 for 'what's on sale'), release recency (released_after / released_within_days \u2014 for 'new games'), Steam Deck compatibility (steam_deck), and review quality (min_review / min_reviews). Each result returns price/discount, review %, Steam Deck status and release date in one call. Examples: '>80% off with 90%+ reviews' \u2192 set min_discount + min_review; 'recent well-reviewed games that run on Steam Deck' \u2192 set released_within_days + steam_deck + min_review; 'newest Deck-Verified games' \u2192 released_within_days + steam_deck. No appids needed \u2014 unlike get_items, which prices a list you already have. Note: the Steam catalog API has no release-date sort, so results are scanned popularity-first and these filters are applied over that window \u2014 great for popular titles; a niche release with very few reviews may fall outside the top `count` (raise count for stricter filters).",
|
|
1253
1371
|
inputSchema: {
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1372
|
+
released_after: z3.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use an ISO date, e.g. 2026-03-01.").describe("Keep only games released on/after this date (YYYY-MM-DD).").optional(),
|
|
1373
|
+
released_within_days: z3.number().int().min(1).describe("Alternative to released_after: released within the last N days.").optional(),
|
|
1374
|
+
steam_deck: z3.enum(["playable", "verified"]).describe(
|
|
1375
|
+
"Keep only Deck-capable games: 'verified' = Deck-Verified only; 'playable' = Playable or Verified."
|
|
1376
|
+
).optional(),
|
|
1377
|
+
min_review: z3.number().int().min(0).max(100).describe("Minimum positive-review %, e.g. 85. Applied over the returned page.").optional(),
|
|
1378
|
+
min_reviews: z3.number().int().min(0).describe("Minimum review count (filters out games with too few reviews).").optional(),
|
|
1379
|
+
min_discount: z3.number().int().min(1).max(100).describe(
|
|
1380
|
+
"Minimum discount %, e.g. 80 for '80%+ off' \u2014 this is the 'deals' filter. Omit to include full-price games."
|
|
1381
|
+
).optional(),
|
|
1257
1382
|
count: z3.number().int().min(1).max(200).describe("How many catalog entries to scan (default 50). Raise for stricter filters.").optional(),
|
|
1258
1383
|
start: z3.number().int().min(0).describe("Pagination offset into the catalog.").optional(),
|
|
1259
1384
|
country: z3.string().regex(/^[A-Za-z]{2}$/, "Two-letter ISO country code.").describe("Country (cc) for prices; overrides STEAM_COUNTRY.").optional(),
|
|
@@ -1261,17 +1386,36 @@ function registerWebTools(server, web) {
|
|
|
1261
1386
|
},
|
|
1262
1387
|
annotations: READ_ONLY2
|
|
1263
1388
|
},
|
|
1264
|
-
({
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1389
|
+
({
|
|
1390
|
+
released_after,
|
|
1391
|
+
released_within_days,
|
|
1392
|
+
steam_deck,
|
|
1393
|
+
min_review,
|
|
1394
|
+
min_reviews,
|
|
1395
|
+
min_discount,
|
|
1396
|
+
count,
|
|
1397
|
+
start: start2,
|
|
1398
|
+
country: country2,
|
|
1399
|
+
language: language2
|
|
1400
|
+
}) => {
|
|
1401
|
+
let releasedAfter;
|
|
1402
|
+
if (released_after) releasedAfter = Math.floor(Date.parse(released_after) / 1e3);
|
|
1403
|
+
else if (released_within_days)
|
|
1404
|
+
releasedAfter = Math.floor(Date.now() / 1e3) - released_within_days * 86400;
|
|
1405
|
+
return reply2(
|
|
1406
|
+
() => web.discoverGames({
|
|
1407
|
+
releasedAfter,
|
|
1408
|
+
steamDeck: steam_deck,
|
|
1409
|
+
minReview: min_review,
|
|
1410
|
+
minReviews: min_reviews,
|
|
1411
|
+
minDiscount: min_discount,
|
|
1412
|
+
count,
|
|
1413
|
+
start: start2,
|
|
1414
|
+
country: country2,
|
|
1415
|
+
language: language2
|
|
1416
|
+
})
|
|
1417
|
+
);
|
|
1418
|
+
}
|
|
1275
1419
|
);
|
|
1276
1420
|
server.registerTool(
|
|
1277
1421
|
"get_current_players",
|
|
@@ -1291,7 +1435,7 @@ function registerWebTools(server, web) {
|
|
|
1291
1435
|
inputSchema: { steamid },
|
|
1292
1436
|
annotations: READ_ONLY2
|
|
1293
1437
|
},
|
|
1294
|
-
({ steamid: id }) => reply2(() => web.getWishlist(id))
|
|
1438
|
+
({ steamid: id }) => reply2(async () => web.getWishlist(await web.requireSteamId(id)))
|
|
1295
1439
|
);
|
|
1296
1440
|
server.registerTool(
|
|
1297
1441
|
"get_game_achievements",
|
|
@@ -1328,7 +1472,7 @@ function registerWebTools(server, web) {
|
|
|
1328
1472
|
inputSchema: { steamid },
|
|
1329
1473
|
annotations: READ_ONLY2
|
|
1330
1474
|
},
|
|
1331
|
-
({ steamid: id }) => requireKey(() => web.getPlayerSummary(id))
|
|
1475
|
+
({ steamid: id }) => requireKey(async () => web.getPlayerSummary(await web.requireSteamId(id)))
|
|
1332
1476
|
);
|
|
1333
1477
|
server.registerTool(
|
|
1334
1478
|
"get_owned_games",
|
|
@@ -1338,7 +1482,7 @@ function registerWebTools(server, web) {
|
|
|
1338
1482
|
inputSchema: { steamid },
|
|
1339
1483
|
annotations: READ_ONLY2
|
|
1340
1484
|
},
|
|
1341
|
-
({ steamid: id }) => requireKey(() => web.getOwnedGames(id))
|
|
1485
|
+
({ steamid: id }) => requireKey(async () => web.getOwnedGames(await web.requireSteamId(id)))
|
|
1342
1486
|
);
|
|
1343
1487
|
server.registerTool(
|
|
1344
1488
|
"get_recently_played",
|
|
@@ -1348,22 +1492,28 @@ function registerWebTools(server, web) {
|
|
|
1348
1492
|
inputSchema: { steamid },
|
|
1349
1493
|
annotations: READ_ONLY2
|
|
1350
1494
|
},
|
|
1351
|
-
({ steamid: id }) => requireKey(() => web.getRecentlyPlayed(id))
|
|
1495
|
+
({ steamid: id }) => requireKey(async () => web.getRecentlyPlayed(await web.requireSteamId(id)))
|
|
1352
1496
|
);
|
|
1353
1497
|
server.registerTool(
|
|
1354
1498
|
"get_player_achievements",
|
|
1355
1499
|
{
|
|
1356
1500
|
title: "Get a player's achievements",
|
|
1357
1501
|
description: "Get a player's achievement progress for one game (unlocked count, % complete, per-achievement unlock dates) by SteamID64 + appid. Requires STEAM_API_KEY and a public profile.",
|
|
1358
|
-
inputSchema: {
|
|
1502
|
+
inputSchema: {
|
|
1503
|
+
steamid,
|
|
1504
|
+
appid: appid2,
|
|
1505
|
+
language: z3.string().min(2).describe("Language for achievement names/descriptions; overrides STEAM_LANGUAGE.").optional()
|
|
1506
|
+
},
|
|
1359
1507
|
annotations: READ_ONLY2
|
|
1360
1508
|
},
|
|
1361
|
-
({ steamid: id, appid: app }) => requireKey(
|
|
1509
|
+
({ steamid: id, appid: app, language: language2 }) => requireKey(
|
|
1510
|
+
async () => web.getPlayerAchievements(await web.requireSteamId(id), app, language2)
|
|
1511
|
+
)
|
|
1362
1512
|
);
|
|
1363
1513
|
}
|
|
1364
1514
|
|
|
1365
1515
|
// src/server.ts
|
|
1366
|
-
var INSTRUCTIONS = "Query Steam games and players. Store data needs no key: search_games \u2192 get_game / get_game_reviews for details, get_specials / get_featured
|
|
1516
|
+
var INSTRUCTIONS = "Query Steam games and players. Store data needs no key: search_games \u2192 get_game / get_game_reviews for details, get_specials / get_featured for curated store sections, discover_games to find titles catalog-wide by discount / recency / Steam Deck / review quality (e.g. deals, new releases, Deck-Verified games), get_items to price- and rating-check a list of appids in one call, get_game_news and get_global_achievements for a game's news and achievement rarity, get_current_players for live player counts. Player data needs a free Steam Web API key (STEAM_API_KEY): get_player_summary, get_owned_games, get_recently_played and get_player_achievements take a 17-digit SteamID64 \u2014 use resolve_vanity_url to convert a custom profile name first, and note the target profile must be public. Tools that need the key report clearly when it is unset.";
|
|
1367
1517
|
function buildServer(config, logger) {
|
|
1368
1518
|
const store = new StorefrontClient(config, logger);
|
|
1369
1519
|
const web = new SteamWebClient(config, logger);
|