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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.0.0
+Version: 1.1.0
 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
@@ -91,22 +95,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 +152,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.0}/README.md

@@ -1,154 +1,193 @@
-# rivalsdata-api
-
-An unofficial Python client for RivalsData's public Marvel Rivals data. It
-uses the site's undocumented API, so routes and fields can change. The client
-keeps unknown response fields accessible instead of discarding them.
-
-## Install
-
-Python 3.10 or newer:
-
-```console
-python -m pip install rivalsdata-api
-```
-
-For editable development, clone the repository and run
-`python -m pip install -e '.[dev]'`. The optional Camoufox Cloudflare fallback
-is installed with `python -m pip install 'rivalsdata-api[browser]'`, followed
-by `python -m camoufox fetch`.
-
-## Quick start
-
-```python
-from rivalsdata import RivalsDataClient
-
-with RivalsDataClient() as rd:
-    player = rd.get_player("GS-")  # numeric UID works too
-    print(player.name, player.level, player.rank_game_season)
-
-    # Player profile sections are lazy resource managers.
-    hero_season = player.heroes.fetch(season=20)
-    map_stats = player.stats.maps(season=20)
-    match_page = player.matches.fetch(season=20)
-
-    # Current match (None if the profile is not currently in a game).
-    live_game = player.live_game.fetch()
-    if live_game is not None:
-        print(live_game.players, live_game.team_avg_rank)
-
-    # Site-wide resources are available from the client.
-    leaderboard = rd.leaderboards.fetch(limit=100, season=20, platform=1)
-    tier_list = rd.heroes.tier_list(platform=1, rank="grandmaster_plus")
-    team_ups = rd.team_ups.fetch(platform=1, rank="grandmaster_plus")
-    xp_page = rd.insights.xp()
-
-print(hero_season[0].win_rate)  # integer percent when wins/losses are present
-```
-
-## MCP server (ChatGPT and Claude)
-
-Install the MCP extra and the package:
-
-```console
-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
-and Streamable HTTP for remote MCP clients such as ChatGPT. Data comes from
+# rivalsdata-api
+
+An unofficial Python client for RivalsData's public Marvel Rivals data. It
+uses the site's undocumented API, so routes and fields can change. The client
+keeps unknown response fields accessible instead of discarding them.
+
+## Install
+
+Python 3.10 or newer:
+
+```console
+python -m pip install rivalsdata-api
+```
+
+For editable development, clone the repository and run
+`python -m pip install -e '.[dev]'`. The optional Camoufox Cloudflare fallback
+is installed with `python -m pip install 'rivalsdata-api[browser]'`, followed
+by `python -m camoufox fetch`.
+
+## Quick start
+
+```python
+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
+    print(player.name, player.level, player.rank_game_season)
+
+    # Player profile sections are lazy resource managers.
+    hero_season = player.heroes.fetch(season=20)
+    map_stats = player.stats.maps(season=20)
+    match_page = player.matches.fetch(season=20)
+
+    # Current match (None if the profile is not currently in a game).
+    live_game = player.live_game.fetch()
+    if live_game is not None:
+        print(live_game.players, live_game.team_avg_rank)
+
+    # Site-wide resources are available from the client.
+    leaderboard = rd.leaderboards.fetch(limit=100, season=20, platform=1)
+    tier_list = rd.heroes.tier_list(platform=1, rank="grandmaster_plus")
+    team_ups = rd.team_ups.fetch(platform=1, rank="grandmaster_plus")
+    xp_page = rd.insights.xp()
+
+print(hero_season[0].win_rate)  # integer percent when wins/losses are present
+```
+
+## MCP server (ChatGPT and Claude)
+
+Install the MCP extra and the package:
+
+```console
+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 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.
 
-### How the MCP UI works
-
+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.
-
-### Claude Desktop (local)
-
-Add a server entry to Claude Desktop's `claude_desktop_config.json`, replacing
-the path with the Python executable in the environment where the extra is
-installed:
-
-```json
-{
-  "mcpServers": {
-    "rivalsdata": {
-      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
-      "args": ["-m", "rivalsdata.mcp_server"]
-    }
-  }
-}
-```
-
-On macOS/Linux, use the environment's `bin/python` path. Restart Claude Desktop
-after saving the configuration.
-
-### ChatGPT or remote Claude connector
-
-Run the server on a host reachable over HTTPS:
-
-```console
-rivalsdata-mcp --transport streamable-http --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.
-
-`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.
-
-## Public resources
-
-- `rd.leaderboards.fetch(...)` — global player ranking.
-- `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
-  `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
-- `rd.team_ups.fetch(...)` — team-up stats.
-- `rd.insights.punishments(...)`, `.xp(...)`, `.top_500(...)`, `.commbans(...)`,
-  `.leavers(...)` — public insights and cursor metadata.
-- `rd.factions.get(faction_id)`, `rd.matches.get(match_id)`,
-  `rd.profiles.get(username)`, and `rd.favorites.fetch(uids)` — detail/profile
-  lookups.
-- `player.heroes.fetch(...)`, `.matches.fetch(...)`, `.live_game.fetch()`, `.teammates.fetch(...)`,
-  `.crosshairs.fetch()`, `.proficiency.fetch()`, `.punishments.fetch()`,
-  `.name_history.fetch()` — profile sections.
-- `player.stats.heroes(...)`, `.maps(...)`, `.bans(...)` — detailed profile stats.
-
-See [the observed API inventory](docs/API.md) for methods, parameters, observed
-response shapes, and endpoints that require a RivalsData account. The API
-inventory distinguishes observed behavior from inferred/unverified details.
-
-## Cloudflare fallback
-
-Requests use curl_cffi with a Chrome TLS profile by default. If blocked, enable
-the optional browser fallback:
+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)
+
+Add a server entry to Claude Desktop's `claude_desktop_config.json`, replacing
+the path with the Python executable in the environment where the extra is
+installed:
+
+```json
+{
+  "mcpServers": {
+    "rivalsdata": {
+      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
+      "args": ["-m", "rivalsdata.mcp_server"]
+    }
+  }
+}
+```
+
+On macOS/Linux, use the environment's `bin/python` path. Restart Claude Desktop
+after saving the configuration.
+
+### ChatGPT or remote Claude connector
+
+Run the server on a host reachable over HTTPS:
+
+```console
+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. 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.
 
 ```python
-with RivalsDataClient(use_browser_fallback=True) as rd:
-    player = rd.get_player(1970288503)
+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
 ```
-
-## Errors and contributions
-
-All package exceptions inherit from `RivalsDataError`. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for setup, code layout, change workflow, and
-notes for new contributors. [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md)
-is the handoff document for new coding sessions.
-
-This project is not affiliated with RivalsData, NetEase, or Marvel. Keep
-request rates reasonable and respect the site's terms.
+
+## Public resources
+
+- `rd.leaderboards.fetch(...)` — global player ranking.
+- `rd.heroes.tier_list(...)`, `.get(hero_id)`, `.meta(hero_id, range=90)`,
+  `.leaderboard(hero_id, **filters)` — hero metrics and ranking.
+- `rd.team_ups.fetch(...)` — team-up stats.
+- `rd.insights.punishments(...)`, `.xp(...)`, `.top_500(...)`, `.commbans(...)`,
+  `.leavers(...)` — public insights and cursor metadata.
+- `rd.factions.get(faction_id)`, `rd.matches.get(match_id)`,
+  `rd.profiles.get(username)`, and `rd.favorites.fetch(uids)` — detail/profile
+  lookups.
+- `player.heroes.fetch(...)`, `.matches.fetch(...)`, `.live_game.fetch()`, `.teammates.fetch(...)`,
+  `.crosshairs.fetch()`, `.proficiency.fetch()`, `.punishments.fetch()`,
+  `.name_history.fetch()` — profile sections.
+- `player.stats.heroes(...)`, `.maps(...)`, `.bans(...)` — detailed profile stats.
+
+See [the observed API inventory](docs/API.md) for methods, parameters, observed
+response shapes, and endpoints that require a RivalsData account. The API
+inventory distinguishes observed behavior from inferred/unverified details.
+
+## Cloudflare fallback
+
+Requests use curl_cffi with a Chrome TLS profile by default. If blocked, enable
+the optional browser fallback:
+
+```python
+with RivalsDataClient(use_browser_fallback=True) as rd:
+    player = rd.get_player(1970288503)
+```
+
+## Errors and contributions
+
+All package exceptions inherit from `RivalsDataError`. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup, code layout, change workflow, and
+notes for new contributors. [docs/PROJECT_CONTEXT.md](docs/PROJECT_CONTEXT.md)
+is the handoff document for new coding sessions.
+
+This project is not affiliated with RivalsData, NetEase, or Marvel. Keep
+request rates reasonable and respect the site's terms.

{rivalsdata_api-1.0.0 → rivalsdata_api-1.1.0}/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
 
@@ -18,27 +20,27 @@ keys.
 | 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.0}/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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rivalsdata-api"
-version = "1.0.0"
+version = "1.1.0"
 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"