rivalsdata-api 1.0.0__tar.gz → 1.1.1__tar.gz

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.0.0
+Version: 1.1.1
 Summary: Python client and MCP server for public Marvel Rivals stats from RivalsData
 Project-URL: Homepage, https://github.com/GS-Rionnag/rivalsdata-api
 Project-URL: Repository, https://github.com/GS-Rionnag/rivalsdata-api
@@ -31,6 +31,7 @@ Requires-Dist: ruff>=0.11; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp-ui-server>=1.0.0; extra == 'mcp'
 Requires-Dist: mcp<2,>=1.12; extra == 'mcp'
+Requires-Dist: uvicorn>=0.30; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # rivalsdata-api
@@ -55,7 +56,10 @@ by `python -m camoufox fetch`.
 ## Quick start
 
 ```python
-from rivalsdata import RivalsDataClient
+from rivalsdata import RivalsDataClient, hero_id, hero_name
+
+print(hero_name(1016))  # Loki
+print(hero_id("Loki"))  # 1016
 
 with RivalsDataClient() as rd:
     player = rd.get_player("GS-")  # numeric UID works too
@@ -63,6 +67,7 @@ with RivalsDataClient() as rd:
 
     # Player profile sections are lazy resource managers.
     hero_season = player.heroes.fetch(season=20)
+    all_hero_seasons = player.heroes.fetch(season="all")
     map_stats = player.stats.maps(season=20)
     match_page = player.matches.fetch(season=20)
 
@@ -91,22 +96,37 @@ python -m pip install 'rivalsdata-api[mcp]'
 The server exposes read-only tools for player search and profiles, a player's
 current live match (when they are in one), match history, player stats,
 leaderboards, heroes, team-ups, public insights, matches, and factions. The
-`show_player_dashboard` tool also returns an MCP-UI player report with rank and
-competitive record, current match roster split by side, a hero win-rate chart,
-and recent match form with K/D/A. It supports local stdio for Claude Desktop
+`show_player_dashboard` tool returns an MCP-UI player card with rank and
+competitive record plus one optional data section per call: current match
+roster, hero win-rate chart, or recent match form with K/D/A. This keeps each
+dashboard pull to the profile plus at most one additional endpoint. It supports
+local stdio for Claude Desktop
 and Streamable HTTP for remote MCP clients such as ChatGPT. Data comes from
 RivalsData's undocumented API and may change; profile match history can be
 private.
 
+Known `hero_id` and `top_hero_id` fields in MCP results include corresponding
+`hero_name` and `top_hero_name` fields. The `resolve_hero` tool accepts either
+a hero name or numeric ID. The pip package also exports `hero_name(id)` and
+`hero_id(name)`; returned `DataModel` rows provide `.hero_name` and
+`.top_hero_name` conveniences. Those resolved fields are included in mapping
+iteration and `.to_dict()` output to simplify serialization; `.raw` remains the
+untouched source payload.
+
 ### How the MCP UI works
 
 `show_player_dashboard` fetches current data, then returns an HTML UI resource
-alongside the tool result. MCP-UI labels it with a `ui://` resource URI and
-preferred size. A compatible host can render that resource in a sandboxed
-panel; a host without UI support can still use the regular MCP tools and their
-text/data responses. ChatGPT uses MCP-UI's Apps SDK adapter, while Claude is
-listed as supporting MCP Apps directly. The dashboard is a snapshot from the
-time the tool runs; ask for it again to refresh.
+alongside the tool result. It advertises the dashboard through
+`_meta.ui.resourceUri`, uses the `text/html;profile=mcp-app` resource MIME type,
+and registers that URI for `resources/read` so the host can actually load the
+app frame. The tool result carries the rendered dashboard as structured content
+for the app frame and an embedded HTML resource for older MCP-UI clients. It
+also includes `openai/outputTemplate` as a ChatGPT compatibility alias. Hosts
+without UI support still receive a text result and can use the regular MCP
+tools. The dashboard is a snapshot from the time the tool runs; ask for it
+again to refresh.
+The `section` argument defaults to `live_match`; use `hero_form` or
+`recent_matches` in separate calls when you need those views.
 
 ### Claude Desktop (local)
 
@@ -133,20 +153,41 @@ after saving the configuration.
 Run the server on a host reachable over HTTPS:
 
 ```console
-rivalsdata-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+uvicorn rivalsdata.mcp_server:app --host 0.0.0.0 --port 8000
 ```
 
 The MCP endpoint is `/mcp` (for example, `https://your-host.example/mcp`). Add
 that endpoint through the client's custom/remote MCP connector settings. The
 server does not implement authentication; put it behind an authenticated
 HTTPS gateway before exposing it publicly. For local development, bind to
-`127.0.0.1` instead. Use `python -m rivalsdata.mcp_server --help` to see options.
+`127.0.0.1` instead. The `app` is the MCP SDK's Streamable HTTP ASGI
+application; Uvicorn manages its lifespan and session manager.
+
+Every implemented response route now has named endpoint models and row models
+with annotations for fields observed in the API inventory. This includes
+`Player`, `Match`, `MatchHistory`, `MatchTeam`, `MatchPlayer`, `Character`,
+`ProficiencyResponse`, `LeaderboardResponse`, `PunishmentsPage`, `XPPage`,
+`Top500Response`, and typed teammate, crosshair, stats, faction, and insight
+records. For example, `rd.matches.get(match_id)` returns a `Match`,
+`player.matches.fetch()` returns a `MatchHistory`, and
+`player.proficiency.fetch()` returns a `ProficiencyResponse`. Nested match
+teams and participants are converted to `MatchTeam` and `MatchPlayer`; embedded
+character records use `Character`. Models support mapping access
+(`player["level"]`) and attribute access (`player.level`). Unknown upstream
+fields are still preserved and available through `.raw`; endpoint schemas
+that have not been observed completely are annotated only for known fields.
 
-`Player` and returned `DataModel` objects support both mapping access and
-attribute access (`player["level"]` or `player.level`). Nested dictionaries
-and arrays are wrapped recursively; `.raw` returns a shallow copy of a model's
-original JSON. For endpoints whose fields evolve, these generic typed wrappers
-preserve the complete payload.
+```python
+with RivalsDataClient() as rd:
+    player = rd.get_player(1970288503)             # Player
+    proficiency = player.proficiency.fetch()       # ProficiencyResponse
+    account = next(iter(proficiency.accounts.values()))  # Proficiency
+    hero = account.hero_proficiency_infos["1011"]   # HeroProficiency
+    print(hero.proficiency_level, hero.proficiency_point)
+
+    tier_list = rd.heroes.tier_list()               # TierListResponse
+    print(tier_list.heroes[0].hero_id)             # Character
+```
 
 ## Public resources
 

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/README.md

@@ -20,7 +20,10 @@ by `python -m camoufox fetch`.
 ## Quick start
 
 ```python
-from rivalsdata import RivalsDataClient
+from rivalsdata import RivalsDataClient, hero_id, hero_name
+
+print(hero_name(1016))  # Loki
+print(hero_id("Loki"))  # 1016
 
 with RivalsDataClient() as rd:
     player = rd.get_player("GS-")  # numeric UID works too
@@ -28,6 +31,7 @@ with RivalsDataClient() as rd:
 
     # Player profile sections are lazy resource managers.
     hero_season = player.heroes.fetch(season=20)
+    all_hero_seasons = player.heroes.fetch(season="all")
     map_stats = player.stats.maps(season=20)
     match_page = player.matches.fetch(season=20)
 
@@ -56,22 +60,37 @@ python -m pip install 'rivalsdata-api[mcp]'
 The server exposes read-only tools for player search and profiles, a player's
 current live match (when they are in one), match history, player stats,
 leaderboards, heroes, team-ups, public insights, matches, and factions. The
-`show_player_dashboard` tool also returns an MCP-UI player report with rank and
-competitive record, current match roster split by side, a hero win-rate chart,
-and recent match form with K/D/A. It supports local stdio for Claude Desktop
+`show_player_dashboard` tool returns an MCP-UI player card with rank and
+competitive record plus one optional data section per call: current match
+roster, hero win-rate chart, or recent match form with K/D/A. This keeps each
+dashboard pull to the profile plus at most one additional endpoint. It supports
+local stdio for Claude Desktop
 and Streamable HTTP for remote MCP clients such as ChatGPT. Data comes from
 RivalsData's undocumented API and may change; profile match history can be
 private.
 
+Known `hero_id` and `top_hero_id` fields in MCP results include corresponding
+`hero_name` and `top_hero_name` fields. The `resolve_hero` tool accepts either
+a hero name or numeric ID. The pip package also exports `hero_name(id)` and
+`hero_id(name)`; returned `DataModel` rows provide `.hero_name` and
+`.top_hero_name` conveniences. Those resolved fields are included in mapping
+iteration and `.to_dict()` output to simplify serialization; `.raw` remains the
+untouched source payload.
+
 ### How the MCP UI works
 
 `show_player_dashboard` fetches current data, then returns an HTML UI resource
-alongside the tool result. MCP-UI labels it with a `ui://` resource URI and
-preferred size. A compatible host can render that resource in a sandboxed
-panel; a host without UI support can still use the regular MCP tools and their
-text/data responses. ChatGPT uses MCP-UI's Apps SDK adapter, while Claude is
-listed as supporting MCP Apps directly. The dashboard is a snapshot from the
-time the tool runs; ask for it again to refresh.
+alongside the tool result. It advertises the dashboard through
+`_meta.ui.resourceUri`, uses the `text/html;profile=mcp-app` resource MIME type,
+and registers that URI for `resources/read` so the host can actually load the
+app frame. The tool result carries the rendered dashboard as structured content
+for the app frame and an embedded HTML resource for older MCP-UI clients. It
+also includes `openai/outputTemplate` as a ChatGPT compatibility alias. Hosts
+without UI support still receive a text result and can use the regular MCP
+tools. The dashboard is a snapshot from the time the tool runs; ask for it
+again to refresh.
+The `section` argument defaults to `live_match`; use `hero_form` or
+`recent_matches` in separate calls when you need those views.
 
 ### Claude Desktop (local)
 
@@ -98,20 +117,41 @@ after saving the configuration.
 Run the server on a host reachable over HTTPS:
 
 ```console
-rivalsdata-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+uvicorn rivalsdata.mcp_server:app --host 0.0.0.0 --port 8000
 ```
 
 The MCP endpoint is `/mcp` (for example, `https://your-host.example/mcp`). Add
 that endpoint through the client's custom/remote MCP connector settings. The
 server does not implement authentication; put it behind an authenticated
 HTTPS gateway before exposing it publicly. For local development, bind to
-`127.0.0.1` instead. Use `python -m rivalsdata.mcp_server --help` to see options.
+`127.0.0.1` instead. The `app` is the MCP SDK's Streamable HTTP ASGI
+application; Uvicorn manages its lifespan and session manager.
+
+Every implemented response route now has named endpoint models and row models
+with annotations for fields observed in the API inventory. This includes
+`Player`, `Match`, `MatchHistory`, `MatchTeam`, `MatchPlayer`, `Character`,
+`ProficiencyResponse`, `LeaderboardResponse`, `PunishmentsPage`, `XPPage`,
+`Top500Response`, and typed teammate, crosshair, stats, faction, and insight
+records. For example, `rd.matches.get(match_id)` returns a `Match`,
+`player.matches.fetch()` returns a `MatchHistory`, and
+`player.proficiency.fetch()` returns a `ProficiencyResponse`. Nested match
+teams and participants are converted to `MatchTeam` and `MatchPlayer`; embedded
+character records use `Character`. Models support mapping access
+(`player["level"]`) and attribute access (`player.level`). Unknown upstream
+fields are still preserved and available through `.raw`; endpoint schemas
+that have not been observed completely are annotated only for known fields.
 
-`Player` and returned `DataModel` objects support both mapping access and
-attribute access (`player["level"]` or `player.level`). Nested dictionaries
-and arrays are wrapped recursively; `.raw` returns a shallow copy of a model's
-original JSON. For endpoints whose fields evolve, these generic typed wrappers
-preserve the complete payload.
+```python
+with RivalsDataClient() as rd:
+    player = rd.get_player(1970288503)             # Player
+    proficiency = player.proficiency.fetch()       # ProficiencyResponse
+    account = next(iter(proficiency.accounts.values()))  # Proficiency
+    hero = account.hero_proficiency_infos["1011"]   # HeroProficiency
+    print(hero.proficiency_level, hero.proficiency_point)
+
+    tier_list = rd.heroes.tier_list()               # TierListResponse
+    print(tier_list.heroes[0].hero_id)             # Character
+```
 
 ## Public resources
 

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/docs/API.md

@@ -3,9 +3,11 @@
 This is an observed inventory of the public web client's API, gathered by
 reviewing the RivalsData UI and its browser requests on 2026-09-29. The upstream
 API is undocumented and can change. Field sets below are examples from live
-responses, not schemas guaranteed by RivalsData. Response bodies are returned
-as attribute-accessible `DataModel` / `StatRecord` objects, preserving unknown
-keys.
+responses, not schemas guaranteed by RivalsData. The client converts every
+implemented route to endpoint-specific model and row classes (such as `Match`,
+`Character`, `PlayerSummary`, `ProficiencyResponse`, and `PunishmentsPage`).
+Known fields are annotated; unknown keys remain accessible through `DataModel`
+and `.raw` so upstream additions are not discarded.
 
 ## Implemented public read endpoints
 
@@ -14,31 +16,31 @@ keys.
 | Search | `POST /players/search` | `{"name": name}` | Search rows; `aid` may contain the numeric UID after the final `_`. |
 | Player overview | `POST /player` | `{"uid": number}` | Object keys observed: `cached_at`, `claimed`, `faction`, `icon`, `last_seen`, `leaderboard`, `level`, `login_os`, `match_history_is_visible`, `mood`, `name`, `rank_game_season`, `status`, `uid`, `xp`. `rank_game_season` is keyed by game/season ids; competitive rows include `battle_count`, `rank_game_id`, `rank_score`, and `win_count`. |
 | Player live game | `POST /live` | `{"match_id": status.battle_id, "uid": number}` | Object keys observed: `players` (12 player entries keyed by team slot) and `team_avg_rank` (rank averages keyed by side). Player rows include `ai`, `games`, `icon`, `losses`, `name`, `proficiency`, `rank`, `side`, `team_id`, `top_heroes`, `uid`, and `wins`. The match ID comes from the player's current `/player` response; the endpoint was observed on a profile marked `In game (Competitive)`. |
-| Player hero summary | `POST /player/heroes` | `uid`, optional `season` | Array rows: `assists`, `deaths`, `games`, `hero_id`, `kda`, `kills`, `losses`, `rank`, `wins`. |
+| Player hero summary | `POST /player/heroes` | `uid`, optional `season`; wrapper `season="all"` sends season ID `-1` | Array rows: `assists`, `deaths`, `games`, `hero_id`, `kda`, `kills`, `losses`, `rank`, `wins`. The all-seasons selector was verified against the public `GS-` profile; `season=-1` returned 40 hero rows, while `season=0` returned none. |
 | Player crosshairs | `POST /player/crosshairs` | `uid` | Array rows: `crosshair`, `uses`. |
 | Player match history | `POST /player/matches/cached` (or `/player/matches`) | `uid`, `cursor`, optional `season`; cached endpoint also accepts `mode`, `hero`, `teammate` | Cached response keys observed: `matches`, `next_cursor`, `source`; match rows include `assists`, `deaths`, `game_mode_id`, `game_play_mode_id`, `hero_id`, `is_mvp`, `is_svp`, `is_win`, `kills`, `map_id`, `match_uid`, `os`, `placement`, `platform`, `rank_level`, `rank_score`, `score_change`, `season`, `team_score`, `timestamp`, `winner_camp`. A sample profile marked its history private; a private profile can return no visible match rows. |
 | Player teammates | `POST /player/teammates` | `uid`, optional `season`, `mode` | Array rows: `games`, `icon`, `losses`, `name`, `teammate_uid`, `wins`. |
-| Player proficiency | `POST /player/proficiency` | `uid` | Object keyed by account id (sample: `11001_{uid}`); inner structure varies. |
-| Player hero stats | `POST /player/stats/heroes` | `uid`, optional `season` | Array rows: `competitive`, `hero_id`, `quickplay`, `rank`. |
-| Player map stats | `POST /player/stats/maps` | `uid`, optional `season` | Array shape varies; captured from the profile Stats tab. |
-| Player ban stats | `POST /player/stats/bans` | `uid`, optional `season` | Array shape varies; captured from the profile Stats tab. |
-| Player punishments | `POST /player/punishments` | `uid` | Object keys observed: `chat`, `login`, `rank`. |
+| Player proficiency | `POST /player/proficiency` | `uid` | Object keyed by account id (sample: `11001_{uid}`); each account has `hero_proficiency_infos` keyed by hero id, with `proficiency_level` and `proficiency_point`. |
+| Player hero stats | `POST /player/stats/heroes` | `uid`, optional `season` | Array rows: `competitive`, `hero_id`, `quickplay`, `rank`. Each mode includes games, wins/losses, KDA, MVP/SVP counts, accuracy, and `per_10`/`per_game` combat averages. |
+| Player map stats | `POST /player/stats/maps` | `uid`, optional `season` | Array rows: `map`, `competitive`, `quickplay`; each mode has games, wins, losses, winrate. |
+| Player ban stats | `POST /player/stats/bans` | `uid`, optional `season` | Array rows: `hero_id`, `matches`, `wins`, `losses`, `winrate`. |
+| Player punishments | `POST /player/punishments` | `uid` | Object keys: `chat`, `login`, `rank`; non-null entries include `expire`, `name`, `reason`, `time`, `uid`. |
 | Player name history | `POST /player/name-history` | `uid` | Array rows: `first_seen`, `name`. |
 | Global leaderboard | `GET /leaderboards` | `limit`, optional `skip`, `season`, `os` (Python `platform`) | Object keys observed: `count`, `players`, `updated_at`; row keys: `heroes`, `icon`, `losses`, `name`, `os`, `position`, `rank_level`, `rank_score`, `season`, `status`, `uid`, `wins`. |
-| Hero tier list | `GET /stats/tierlist` | `platform`, `rank` | Hero rows displayed with tier, win rate, pick rate, ban rate, and games; raw row keys preserved. |
-| Hero detail | `GET /stats/heroes/{hero_id}` | Path parameter | Hero aggregate object; full key set varies by hero and season. |
-| Hero trend/meta | `GET /stats/meta/{hero_id}` | `range` (30, 90, or 180 days) | Trend/analytics object; raw keys preserved. |
-| Hero leaderboard | `GET /stats/leaderboards` | `hero` plus caller-supplied query filters | Used by hero leaderboard pages. Parameter combinations and response fields are not fully verified. |
-| Team-up stats | `GET /stats/teamups` | `platform`, `rank`, optional `hero` | Team-up usage and win-rate rows; raw keys preserved. |
+| Hero tier list | `GET /stats/tierlist` | `platform`, `rank` | Object: `last_update`, `heroes`; rows include hero id, picks/bans, total games, winrate, pick rate, ban rate, and score. |
+| Hero detail | `GET /stats/heroes/{hero_id}` | Path parameter | Object: `hero`, `last_update`, `season`; `hero` contains aggregate per-10 stats and pick/ban rates. |
+| Hero trend/meta | `GET /stats/meta/{hero_id}` | `range` as `30d`, `90d`, or `180d` | Object: `hero_id`, `last_update`, `points`, `range`, `window_days`; point rows include timestamp, games, pick/ban rates, and winrate without mirror matches. |
+| Hero leaderboard | `GET /stats/leaderboards` | `hero` plus caller-supplied query filters | Object: `last_update`, `players`; rows include combat averages, placement, score, rank, and wins/losses. |
+| Team-up stats | `GET /stats/teamups` | `platform`, `rank`, optional `hero` | Object: `last_update`, `heroes`, where `heroes` maps hero ids to slot ids and rows with `bond_id`, `games`, `nm_winrate`, `pickrate`, `winrate`. |
 | Punishments log | `GET /stats/punishments` | `kind`, optional `cursor` | Object: `last_update`, `next`, `results`; sample row keys: `expires_at`, `icon`, `issued_at`, `kind`, `name`, `peak_rank_level`, `peak_rank_score`, `rank`, `reason`, `uid`. |
 | XP leaderboard | `GET /stats/xp` | Optional `cursor` | Object: `last_update`, `next`, `results`; sample row keys: `icon`, `name`, `rank`, `uid`, `xp`. |
 | Top 500 finishes | `GET /stats/oaa` | `os` (Python `platform`) | Object: `count`, `last_update`, `os`, `players`; sample row keys: `avg_placement`, `avg_score`, `finishes`, `icon`, `name`, `seasons`, `uid`. |
 | Hero comm-ban insight | `GET /stats/commbans` | `mode` (`all` or `competitive`) | Object: `heroes`, `last_update`, `mode`, `overall_pct`; hero rows: `ci95`, `hero_id`, `pct`, `qualifying_players`, `vs_avg`, `weighted_banned`, `weighted_players`. |
 | Hero AFK insight | `GET /stats/leavers` | `mode` (`all` or `competitive`) | Object: `heroes`, `last_update`, `mode`, `overall_pct`; hero rows: `ci95`, `games`, `hero_id`, `leaves`, `leaves_per_player`, `pct`, `players`, `vs_avg`. |
-| Faction details | `GET /faction/{faction_id}` | Path parameter | Faction overview, public profile/member list, and results; nested schema varies. |
+| Faction details | `GET /faction/{faction_id}` | Path parameter | Faction `captain`, `description`, `members`, `name`, `region`, `results`, `tag`, `type`; member records contain account id, config/rank, game status, and name. |
 | Match details | `POST /match` | `{"match_id": "..."}` | Object keys observed: `match_uid`, `replay_id`, `winner_camp`, `duration_seconds`, `map_id`, `game_mode_id`, `game_play_mode_id`, `platform`, `timestamp`, `draft`, `teams`; team player rows include combat stats and per-hero usage. |
-| Public profile card | `GET /profiles/{username}` | Username path parameter | Route observed in the profile frontend; complete response schema not captured. |
-| Favorites lookup | `POST /favorites` | `{"uids": [uid, ...]}` | Request observed in frontend assets; response schema not captured. |
+| Public profile card | `GET /profiles/{uid}` | Numeric UID path parameter; `Profiles.get` resolves usernames | Object: `leaderboard_social`, `socials`, `uid`, `updated_at`. |
+| Favorites lookup | `POST /favorites` | `{"uids": [numeric_uid, ...]}` | Array of public player summaries with `aid`, `config_server`, `games`, `name`, and `status`. |
 
 The client exposes these read resources through `RivalsDataClient` and `Player`;
 see README examples and method docstrings. `DataModel.win_rate` returns an

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/docs/PROJECT_CONTEXT.md

@@ -15,7 +15,7 @@ as public, stable methods. Keep requests respectful and conservative.
 ## Current package
 
 - Distribution: `rivalsdata-api`; import: `rivalsdata`.
-- Version: `0.2.0` (update metadata deliberately before the next release).
+- Version: `1.1.0`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsDataClient`.
@@ -48,8 +48,9 @@ Lazy subresources include `player.heroes.fetch(...)`, `player.matches.fetch(...)
 `player.name_history.fetch()`, and `player.stats.heroes/maps/bans(...)`.
 Client-wide resources include `client.leaderboards`, `client.heroes`,
 `client.team_ups`, `client.insights`, `client.factions`, and `client.matches`.
-`client.profiles` and `client.favorites` have thin read methods; their response
-schemas are not yet verified.
+`client.profiles` and `client.favorites` have typed read methods. The profile
+endpoint takes a numeric UID; the wrapper can resolve a username first.
+Favorites requires numeric UIDs and returns player summary rows.
 Rows offer `.win_rate` and `.winrate` integer-percent access when data supports
 it; all original data remains in mapping access.
 
@@ -70,8 +71,8 @@ detail pages. Main public request families are:
   opened from the public GS- profile. The returned object contains replay id,
   mode/map/time, draft picks/bans, both teams, players' combat stats, and hero
   usage.
-- `GET /profiles/{username}` and `POST /favorites` are wrapped in generic
-  models. Their response contracts remain undocumented.
+- `GET /profiles/{uid}` returns profile social metadata and `POST /favorites`
+  returns public player summaries. Both were checked through the browser.
 
 The hero detail Counters and Synergy tabs showed “Coming Soon” on inspection.
 The Live Game tab did not expose data for the sampled player. Do not invent
@@ -84,7 +85,8 @@ endpoints can change account state and are intentionally not implemented by
 this read-only package yet. `client.matches.get` uses the verified `match_id`
 payload.
 
-The website currently shows Season 10 / season value 20 and OS `1` for PC on
+The hero meta endpoint requires `range=30d`, `90d`, or `180d`; bare integers
+are rejected. The website currently shows Season 10 / season value 20 and OS `1` for PC on
 the inspected UI. Treat those as site values, not permanent constants.
 
 ## Contributor workflow

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rivalsdata-api"
-version = "1.0.0"
+version = "1.1.1"
 description = "Python client and MCP server for public Marvel Rivals stats from RivalsData"
 keywords = ["marvel-rivals", "rivalsdata", "game-stats", "api-client", "mcp"]
 readme = "README.md"
@@ -34,12 +34,9 @@ Changelog = "https://github.com/GS-Rionnag/rivalsdata-api/releases"
 
 [project.optional-dependencies]
 browser = ["camoufox>=0.5.6"]
-mcp = ["mcp>=1.12,<2", "mcp-ui-server>=1.0.0"]
+mcp = ["mcp>=1.12,<2", "mcp-ui-server>=1.0.0", "uvicorn>=0.30"]
 dev = ["build>=1.2", "pytest>=8", "ruff>=0.11"]
 
-[project.scripts]
-rivalsdata-mcp = "rivalsdata.mcp_server:main"
-
 [tool.ruff]
 line-length = 88
 target-version = "py310"

rivalsdata_api-1.1.1/src/rivalsdata/__init__.py

@@ -0,0 +1,148 @@
+"""Unofficial client for public RivalsData player data."""
+
+from .client import RivalsDataClient
+from .exceptions import (
+    CloudflareError,
+    PlayerNotFoundError,
+    RivalsDataError,
+    RivalsDataHTTPError,
+)
+from .hero_ids import HERO_NAMES, hero_id, hero_name
+from .models import (
+    BanRecord,
+    Character,
+    CombatAverages,
+    CommBanHero,
+    CommBanInsights,
+    CrosshairRecord,
+    DataModel,
+    DraftEntry,
+    Faction,
+    FactionConfig,
+    FactionGame,
+    FactionMember,
+    FactionRank,
+    FactionResult,
+    FactionSummary,
+    FavoritePlayer,
+    FavoritesResponse,
+    HeroDetail,
+    HeroInsights,
+    HeroLeaderboardPlayer,
+    HeroLeaderboardResponse,
+    HeroMeta,
+    HeroMetaPoint,
+    HeroModeStats,
+    HeroProficiency,
+    HeroStatsRecord,
+    LeaderboardPlayer,
+    LeaderboardResponse,
+    LeaverHero,
+    LeaverInsights,
+    LiveGame,
+    LiveGamePlayer,
+    MapModeStats,
+    MapRecord,
+    Match,
+    MatchHistory,
+    MatchPlayer,
+    MatchTeam,
+    NameHistoryRecord,
+    Player,
+    PlayerPunishments,
+    PlayerSearchResult,
+    PlayerStatus,
+    PlayerSummary,
+    Proficiency,
+    ProficiencyResponse,
+    ProfileCard,
+    PunishmentEntry,
+    PunishmentRecord,
+    PunishmentsPage,
+    RankRecord,
+    StatRecord,
+    Teammate,
+    TeamScore,
+    TeamUpRecord,
+    TeamUpsResponse,
+    TierListResponse,
+    Top500Player,
+    Top500Response,
+    Top500Season,
+    XPPage,
+    XPRecord,
+)
+
+__all__ = [
+    "HERO_NAMES",
+    "BanRecord",
+    "Character",
+    "CloudflareError",
+    "CombatAverages",
+    "CommBanHero",
+    "CommBanInsights",
+    "CrosshairRecord",
+    "DataModel",
+    "DraftEntry",
+    "Faction",
+    "FactionConfig",
+    "FactionGame",
+    "FactionMember",
+    "FactionRank",
+    "FactionResult",
+    "FactionSummary",
+    "FavoritePlayer",
+    "FavoritesResponse",
+    "HeroDetail",
+    "HeroInsights",
+    "HeroLeaderboardPlayer",
+    "HeroLeaderboardResponse",
+    "HeroMeta",
+    "HeroMetaPoint",
+    "HeroModeStats",
+    "HeroProficiency",
+    "HeroStatsRecord",
+    "LeaderboardPlayer",
+    "LeaderboardResponse",
+    "LeaverHero",
+    "LeaverInsights",
+    "LiveGame",
+    "LiveGamePlayer",
+    "MapModeStats",
+    "MapRecord",
+    "Match",
+    "MatchHistory",
+    "MatchPlayer",
+    "MatchTeam",
+    "NameHistoryRecord",
+    "Player",
+    "PlayerNotFoundError",
+    "PlayerPunishments",
+    "PlayerSearchResult",
+    "PlayerStatus",
+    "PlayerSummary",
+    "Proficiency",
+    "ProficiencyResponse",
+    "ProfileCard",
+    "PunishmentEntry",
+    "PunishmentRecord",
+    "PunishmentsPage",
+    "RankRecord",
+    "RivalsDataClient",
+    "RivalsDataError",
+    "RivalsDataHTTPError",
+    "StatRecord",
+    "TeamScore",
+    "TeamUpRecord",
+    "TeamUpsResponse",
+    "Teammate",
+    "TierListResponse",
+    "Top500Player",
+    "Top500Response",
+    "Top500Season",
+    "XPPage",
+    "XPRecord",
+    "hero_id",
+    "hero_name",
+]
+__version__ = "1.1.0"

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.1}/src/rivalsdata/client.py

@@ -7,6 +7,7 @@ from the site's public player page and search box.
 from __future__ import annotations
 
 import json
+import time
 import unicodedata
 from typing import Any
 from urllib.parse import urlencode
@@ -14,7 +15,7 @@ from urllib.parse import urlencode
 from curl_cffi import requests
 
 from .exceptions import CloudflareError, PlayerNotFoundError, RivalsDataHTTPError
-from .models import Player
+from .models import Player, PlayerSearchResult
 from .resources import (
     Factions,
     Favorites,
@@ -33,6 +34,15 @@ class RivalsDataClient:
     base_url = "https://rivalsdata.com"
     api_url = "https://api.rivalsdata.com"
 
+    leaderboards: Leaderboards
+    heroes: HeroStats
+    team_ups: TeamUps
+    insights: Insights
+    factions: Factions
+    profiles: Profiles
+    favorites: Favorites
+    matches: Matches
+
     def __init__(
         self,
         *,
@@ -71,7 +81,19 @@ class RivalsDataClient:
     def __exit__(self, *_: object) -> None:
         self.close()
 
-    def resolve_player(self, username: str) -> dict[str, Any]:
+    def _request_with_gateway_retries(
+        self, method: Any, path: str, **kwargs: Any
+    ) -> Any:
+        """Retry short-lived upstream gateway failures on read-only requests."""
+        url = f"{self.api_url}{path}"
+        for attempt in range(3):
+            response = method(url, timeout=self.timeout, **kwargs)
+            if response.status_code not in (502, 504) or attempt == 2:
+                break
+            time.sleep(0.25 * (attempt + 1))
+        return response
+
+    def resolve_player(self, username: str) -> PlayerSearchResult:
         """Search by username; add numeric uid to the source result."""
         query = username.strip()
         if not query:
@@ -95,7 +117,7 @@ class RivalsDataClient:
             raise RivalsDataHTTPError(
                 "Search returned a player without a recognizable numeric UID"
             )
-        return {**player, "uid": uid}
+        return PlayerSearchResult({**player, "uid": uid})
 
     def get_player(self, uuid_or_username: str | int) -> Player:
         """Fetch a typed public profile by numeric UID or username.
@@ -120,8 +142,8 @@ class RivalsDataClient:
 
     def _get_json(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
         query = {key: value for key, value in (params or {}).items() if value is not None}
-        response = self.session.get(
-            f"{self.api_url}{path}", params=query, timeout=self.timeout
+        response = self._request_with_gateway_retries(
+            self.session.get, path, params=query
         )
         body = response.text
         blocked = (
@@ -190,8 +212,8 @@ class RivalsDataClient:
             ) from exc
 
     def _post_json(self, path: str, payload: dict[str, Any]) -> Any:
-        response = self.session.post(
-            f"{self.api_url}{path}", json=payload, timeout=self.timeout
+        response = self._request_with_gateway_retries(
+            self.session.post, path, json=payload
         )
         body = response.text
         blocked = (