vlrdevapi 3.0.0__tar.gz → 3.1.0__tar.gz

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/.github/workflows/docs-check.yml

@@ -22,7 +22,7 @@ jobs:
           python-version: '3.12'
 
       - name: Install package
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
       # Restore fixture cache scoped to the current ref (branch or main) and version prefix (v3).
       # This ensures caches are never shared across unrelated branches or older versions.

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
 
     steps:
       - uses: actions/checkout@v7
@@ -23,7 +23,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
       - name: Download fixtures
         run: uv run python scripts/download_fixtures.py

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/.github/workflows/test.yml

@@ -5,6 +5,8 @@ on:
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - 'scripts/download_fixtures.py'
       - '.github/workflows/test.yml'
   push:
@@ -12,6 +14,8 @@ on:
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - 'scripts/download_fixtures.py'
       - '.github/workflows/test.yml'
 
@@ -20,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
 
     steps:
       - uses: actions/checkout@v7
@@ -30,7 +34,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
       - name: Download fixtures
         run: uv run python scripts/download_fixtures.py

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/.gitignore

@@ -30,4 +30,6 @@ main.py
 official-docs/node_modules/
 
 # Zensical cache
-docs-py/.cache/
+docs-py/.cache/
+
+temp/

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.1.0] - 2026-10-25
+
+### Added
+
+- **Multi-Format Tabular Export Layer** — All Pydantic models now inherit from `ExportableModel`, enabling seamless tabular serialization into popular data science formats:
+  - `.to_records()` — extracts clean, unnested lists of Python dictionaries with semantic flattening across every namespace.
+  - `.to_df()` — converts records directly into a `pandas.DataFrame`.
+  - `.to_polars()` — converts records directly into a native `polars.DataFrame` with typed nested arrays (`pl.List(pl.String)`).
+  - `.to_csv(path=None)` — exports to standard CSV format with semicolon-delimited lists (`"Player;IGL"`) and in-memory string output when `path` is omitted.
+  - `.to_parquet(path, index=False)` — writes Apache Parquet files via pandas and pyarrow.
+  - `.to_excel(path, sheet_name="Sheet1", index=False)` — exports Excel `.xlsx` spreadsheets via pandas and openpyxl.
+  - `.to_json(path=None, indent=2)` — exports clean serialized JSON to string or disk with comprehensive recursive datetime and list handling.
+  - `.to_markdown(columns=None)` — generates GitHub-flavored markdown tables with proper column alignments, pipe escaping, and zero dependencies.
+- **Granular Optional Dependency Extras** — Data export dependencies are strictly optional and modular:
+  - `vlrdevapi[pandas]`: installs `pandas>=2.0.0`
+  - `vlrdevapi[polars]`: installs `polars>=1.0.0`
+  - `vlrdevapi[excel]`: installs `openpyxl>=3.1.0` and `pandas>=2.0.0`
+  - `vlrdevapi[parquet]`: installs `pyarrow>=14.0.0` and `pandas>=2.0.0`
+  - `vlrdevapi[mcp]`: installs `mcp>=1.2.0`
+  - `vlrdevapi[all]`: installs all optional tabular, file, and MCP dependencies.
+  - Missing dependencies provide actionable, friendly install prompts with exact pip commands instead of generic import errors.
+- **First-Class Model Context Protocol (MCP) Server** — Built-in MCP server for AI agents and LLMs (Claude Desktop, Cursor, Zed, Antigravity):
+  - CLI executable `vlrdevapi-mcp` (or `python -m vlrdevapi.mcp.server`, `uvx vlrdevapi-mcp`).
+  - Standard `stdio` transport with structured, formatted tool definitions.
+  - 40 tools covering all endpoints across Matches, Series, Teams, Players, Events, and News.
+  - High-level composite tools for complex agent tasks:
+    - `get_match_full_context(series_id)` — aggregates overview, player statistics, and streams/VODs into a single response.
+    - `get_team_overview(team_id)` — combines team info, roster, upcoming schedule, and tournament placements.
+    - `compare_teams(team_id_1, team_id_2, last_days=60)` — side-by-side comparison of two teams with rosters and recent map statistics/forms.
+    - `get_player_career_summary(player_id)` — consolidated dossier with profile, current teams, agent pool ratings, and tournament placements.
+    - `get_h2h_matchup(team_id_1, team_id_2)` — head-to-head match history between two organizations.
+    - `get_tournament_dossier(event_id)` — tournament overview with participating teams, stages, and standings.
+    - `get_live_and_upcoming_schedule(limit)` — live ticker combined with upcoming match schedule.
+    - `get_news_digest(limit, include_top_article_body)` — latest esports headlines with optional top article body.
+    - `series_map_summary(series_id, game_id)` — targeted map-level overview combining economy, replay timeline, and player stats.
+- **Python 3.15 Ready** — Added Python 3.15 to the CI/CD test and publish workflows, verified across uv python matrix.
+- **Production/Stable Status** — Package status promoted to `Development Status :: 5 - Production/Stable` in package metadata.
+
+### Improved
+
+- **Semantic Model Flattening** — Tabular export extractors (`.to_records()`) now generate clean, non-redundant rows:
+  - Upcoming/completed matches omit static status columns and resolve unannounced teams as `"TBD"`.
+  - Player agent statistics provide unnested, clean numeric columns (`acs`, `kd`, `adr`, `kast`, `kpr`, `apr`).
+  - Series player stats properly segregate map rows, labeling the aggregate map view as `"All Maps"`.
+  - Team rosters separate `primary_role` and multi-role lists.
+- **Unified Serialization in MCP Tools** — MCP server tools now leverage `ExportableModel.to_dict()` and `ExportableModel.to_json()`, eliminating redundant ad-hoc JSON conversion and drastically speeding up tool invocations.
+- **CSV Multi-Value List Formatting** — Agent lists and team roles are formatted with standard semicolon delimiters (`"neon;raze;jett"`) instead of Python `repr()` strings, ensuring full compatibility with spreadsheet applications and analytical parsers.
+- **Parser Corrections** — Fixed swapped KAST and ADR columns in `player.agents()` table extraction to match VLR.gg's actual table headers.
+
 ## [3.0.0] - 2026-10-23
 
 ### Breaking
@@ -436,6 +485,7 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[3.1.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.4.1...v3.0.0
 [2.4.1]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.3.0...v2.4.0

vlrdevapi-3.0.0/README.md → vlrdevapi-3.1.0/PKG-INFO

@@ -1,3 +1,74 @@
+Metadata-Version: 2.5
+Name: vlrdevapi
+Version: 3.1.0
+Summary: A Python library to scrape data from vlr.gg
+Project-URL: Homepage, https://vlrdevapi.pages.dev/
+Project-URL: Repository, https://github.com/Vanshbordia/vlrdevapi
+Project-URL: Documentation, https://vlrdevapi.pages.dev/docs/
+License: MIT License
+        
+        Copyright (c) 2026 Vansh Bordia
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENCE
+Keywords: api,esports,python,scraper,sdk,valorant,valorant esports,vct,vlr.gg,vlrgg
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: selectolax>=1.0.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: openpyxl>=3.1.0; extra == 'all'
+Requires-Dist: pandas>=2.0.0; extra == 'all'
+Requires-Dist: polars>=1.0.0; extra == 'all'
+Requires-Dist: pyarrow>=14.0.0; extra == 'all'
+Provides-Extra: arrow
+Requires-Dist: pandas>=2.0.0; extra == 'arrow'
+Requires-Dist: pyarrow>=14.0.0; extra == 'arrow'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
+Requires-Dist: pandas>=2.0.0; extra == 'excel'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0.0; extra == 'pandas'
+Provides-Extra: parquet
+Requires-Dist: pandas>=2.0.0; extra == 'parquet'
+Requires-Dist: pyarrow>=14.0.0; extra == 'parquet'
+Provides-Extra: polars
+Requires-Dist: polars>=1.0.0; extra == 'polars'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
+Requires-Dist: pytest>=9.1.1; extra == 'test'
+Requires-Dist: respx>=0.23.1; extra == 'test'
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 <img src="official-docs/public/logo.png" width="120" alt="vlrdevapi logo">
@@ -6,8 +77,10 @@
 
 **The modern, type-safe Python library for VLR.gg Valorant esports data**
 
-[![PyPI version](https://img.shields.io/pypi/v/vlrdevapi.svg?color=fd4556)](https://pypi.org/project/vlrdevapi/)
-[![Python Version](https://img.shields.io/pypi/pyversions/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![PyPI version](https://img.shields.io/pypi/v/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-blue.svg)](https://pypi.org/project/vlrdevapi/)
+[![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen.svg)](https://pypi.org/project/vlrdevapi/)
+[![MCP Server](https://img.shields.io/badge/MCP-40%20tools-red.svg)](https://vlrdevapi.pages.dev/docs/mcp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/docs-vlrdevapi.pages.dev-blue.svg)](https://vlrdevapi.pages.dev/docs/)
 
@@ -25,6 +98,8 @@ Whether you need live match tickers, tournament brackets, historical player rati
 
 ## Highlights
 
+- **Universal Tabular Data Exports** — Seamlessly export any response into `pandas.DataFrame` (`.to_df()`), native `polars.DataFrame` (`.to_polars()`), `CSV` (`.to_csv()`), `Apache Parquet` (`.to_parquet()`), `Excel` (`.to_excel()`), formatted `JSON` (`.to_json()`), and `Markdown` (`.to_markdown()`).
+- **Model Context Protocol (MCP) Server** — Connect Claude Desktop, Cursor, Zed, and AI agents directly to live Valorant data via the built-in `vlrdevapi-mcp` stdio server with 40 tools.
 - **Complete Valorant Esports Coverage** — Tournaments, match schedules, live scoreboards, player careers, team rosters, roster transactions, and esports news.
 - **2D Kill-Feed Replay Timelines** — Spatial `(x, y)` kill coordinates, viewing angles, kill distances, plant/defuse events, spike detonations (`boom`), resurrections, alive player snapshots, and buy-phase **player loadouts** (weapons, shields, spent credits, remaining bank).
 - **Round-by-Round Economy** — Full team buy matrices (`loadout_value`, `spent`, `bank`, buy classifications like `Eco`, `Anti-eco`, `Semi-buy`, `Semi-rifle`, and `Full buy`).
@@ -41,14 +116,23 @@ Whether you need live match tickers, tournament brackets, historical player rati
 Install `vlrdevapi` using [uv](https://docs.astral.sh/uv/) (recommended) or `pip`:
 
 ```bash
-# Using uv (recommended)
+# Basic installation
+pip install vlrdevapi
+# or with uv
 uv add vlrdevapi
 
-# Using pip
-pip install vlrdevapi
+# With optional extras
+pip install "vlrdevapi[pandas]"     # pandas.DataFrame (.to_df())
+pip install "vlrdevapi[polars]"     # polars.DataFrame (.to_polars())
+pip install "vlrdevapi[excel]"      # Excel .xlsx (.to_excel())
+pip install "vlrdevapi[parquet]"    # Apache Parquet (.to_parquet())
+pip install "vlrdevapi[mcp]"        # MCP server (vlrdevapi-mcp)
+
+# Install with all optional extras
+pip install "vlrdevapi[all]"
 ```
 
-> **Requirements:** Python 3.11 or higher.
+> **Requirements:** Python 3.11, 3.12, 3.13, 3.14, or 3.15.
 
 ---
 
@@ -252,11 +336,77 @@ Learn more in the [News Reference Documentation](https://vlrdevapi.pages.dev/doc
 
 ---
 
+## Tabular Data Exports (Data Science & Analytics)
+
+Every response model inherits from `ExportableModel`, enabling instant conversion to dataframes, spreadsheets, and serialized files:
+
+```python
+import vlrdevapi
+
+# 1. Fetch player statistics for a grand final
+players = vlrdevapi.series(754737).players()
+
+# 2. Convert to pandas DataFrame
+df = players.to_df()
+print(df[["name", "team_name", "rating", "acs", "kills", "deaths"]].head())
+
+# 3. Convert to Polars DataFrame (preserving typed list columns)
+polars_df = players.to_polars()
+
+# 4. Export to CSV (semicolon-delimited lists, e.g. "neon;raze;jett")
+players.to_csv("grand_final_players.csv")
+
+# 5. Export to Apache Parquet
+players.to_parquet("grand_final_players.parquet")
+
+# 6. Export to Excel (.xlsx)
+players.to_excel("grand_final_players.xlsx", sheet_name="PlayerStats")
+
+# 7. Export to JSON (in-memory string or written to disk)
+json_payload = players.to_json(indent=2)
+
+# 8. Print GitHub-flavored Markdown table
+print(players.to_markdown())
+```
+
+---
+
+## Model Context Protocol (MCP) Server
+
+VLRdevAPI includes a native MCP server for AI assistants and autonomous coding agents:
+
+```bash
+# Run server over stdio
+vlrdevapi-mcp
+
+# Or zero-install with uvx
+uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp
+```
+
+### Claude Desktop & Cursor Integration
+
+Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vlrdevapi": {
+      "command": "uvx",
+      "args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
+    }
+  }
+}
+```
+
+The MCP server provides **40 tools** covering matches, series, teams, players, tournaments, and editorial news, plus high-level composite tools (`get_match_full_context`, `get_team_overview`, `compare_teams`, `get_player_career_summary`, `get_h2h_matchup`, `get_tournament_dossier`, `get_live_and_upcoming_schedule`, `get_news_digest`, `series_map_summary`).
+
+---
+
 ## Configuration & Error Handling
 
 ### Rate Limiting & Concurrency
 
-`vlrdevapi` includes sensible defaults (`4.0` requests per second) to respect VLR.gg servers. When using `VLRClient`, you can customize client settings:
+`vlrdevapi` includes sensible defaults (`3.0` requests per second) to respect VLR.gg servers. When using `VLRClient`, you can customize client settings:
 
 ```python
 from zoneinfo import ZoneInfo

vlrdevapi-3.0.0/PKG-INFO → vlrdevapi-3.1.0/README.md

@@ -1,52 +1,3 @@
-Metadata-Version: 2.5
-Name: vlrdevapi
-Version: 3.0.0
-Summary: A Python library to scrape data from vlr.gg
-Project-URL: Homepage, https://vlrdevapi.pages.dev/
-Project-URL: Repository, https://github.com/Vanshbordia/vlrdevapi
-Project-URL: Documentation, https://vlrdevapi.pages.dev/docs/
-License: MIT License
-        
-        Copyright (c) 2026 Vansh Bordia
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENCE
-Keywords: api,esports,python,scraper,sdk,valorant,valorant esports,vct,vlr.gg,vlrgg
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Games/Entertainment
-Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic>=2.14.1
-Requires-Dist: selectolax>=1.0.0
-Provides-Extra: test
-Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
-Requires-Dist: pytest>=9.1.1; extra == 'test'
-Requires-Dist: respx>=0.23.1; extra == 'test'
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 <img src="official-docs/public/logo.png" width="120" alt="vlrdevapi logo">
@@ -55,8 +6,10 @@ Description-Content-Type: text/markdown
 
 **The modern, type-safe Python library for VLR.gg Valorant esports data**
 
-[![PyPI version](https://img.shields.io/pypi/v/vlrdevapi.svg?color=fd4556)](https://pypi.org/project/vlrdevapi/)
-[![Python Version](https://img.shields.io/pypi/pyversions/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![PyPI version](https://img.shields.io/pypi/v/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-blue.svg)](https://pypi.org/project/vlrdevapi/)
+[![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen.svg)](https://pypi.org/project/vlrdevapi/)
+[![MCP Server](https://img.shields.io/badge/MCP-40%20tools-red.svg)](https://vlrdevapi.pages.dev/docs/mcp/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/docs-vlrdevapi.pages.dev-blue.svg)](https://vlrdevapi.pages.dev/docs/)
 
@@ -74,6 +27,8 @@ Whether you need live match tickers, tournament brackets, historical player rati
 
 ## Highlights
 
+- **Universal Tabular Data Exports** — Seamlessly export any response into `pandas.DataFrame` (`.to_df()`), native `polars.DataFrame` (`.to_polars()`), `CSV` (`.to_csv()`), `Apache Parquet` (`.to_parquet()`), `Excel` (`.to_excel()`), formatted `JSON` (`.to_json()`), and `Markdown` (`.to_markdown()`).
+- **Model Context Protocol (MCP) Server** — Connect Claude Desktop, Cursor, Zed, and AI agents directly to live Valorant data via the built-in `vlrdevapi-mcp` stdio server with 40 tools.
 - **Complete Valorant Esports Coverage** — Tournaments, match schedules, live scoreboards, player careers, team rosters, roster transactions, and esports news.
 - **2D Kill-Feed Replay Timelines** — Spatial `(x, y)` kill coordinates, viewing angles, kill distances, plant/defuse events, spike detonations (`boom`), resurrections, alive player snapshots, and buy-phase **player loadouts** (weapons, shields, spent credits, remaining bank).
 - **Round-by-Round Economy** — Full team buy matrices (`loadout_value`, `spent`, `bank`, buy classifications like `Eco`, `Anti-eco`, `Semi-buy`, `Semi-rifle`, and `Full buy`).
@@ -90,14 +45,23 @@ Whether you need live match tickers, tournament brackets, historical player rati
 Install `vlrdevapi` using [uv](https://docs.astral.sh/uv/) (recommended) or `pip`:
 
 ```bash
-# Using uv (recommended)
+# Basic installation
+pip install vlrdevapi
+# or with uv
 uv add vlrdevapi
 
-# Using pip
-pip install vlrdevapi
+# With optional extras
+pip install "vlrdevapi[pandas]"     # pandas.DataFrame (.to_df())
+pip install "vlrdevapi[polars]"     # polars.DataFrame (.to_polars())
+pip install "vlrdevapi[excel]"      # Excel .xlsx (.to_excel())
+pip install "vlrdevapi[parquet]"    # Apache Parquet (.to_parquet())
+pip install "vlrdevapi[mcp]"        # MCP server (vlrdevapi-mcp)
+
+# Install with all optional extras
+pip install "vlrdevapi[all]"
 ```
 
-> **Requirements:** Python 3.11 or higher.
+> **Requirements:** Python 3.11, 3.12, 3.13, 3.14, or 3.15.
 
 ---
 
@@ -301,11 +265,77 @@ Learn more in the [News Reference Documentation](https://vlrdevapi.pages.dev/doc
 
 ---
 
+## Tabular Data Exports (Data Science & Analytics)
+
+Every response model inherits from `ExportableModel`, enabling instant conversion to dataframes, spreadsheets, and serialized files:
+
+```python
+import vlrdevapi
+
+# 1. Fetch player statistics for a grand final
+players = vlrdevapi.series(754737).players()
+
+# 2. Convert to pandas DataFrame
+df = players.to_df()
+print(df[["name", "team_name", "rating", "acs", "kills", "deaths"]].head())
+
+# 3. Convert to Polars DataFrame (preserving typed list columns)
+polars_df = players.to_polars()
+
+# 4. Export to CSV (semicolon-delimited lists, e.g. "neon;raze;jett")
+players.to_csv("grand_final_players.csv")
+
+# 5. Export to Apache Parquet
+players.to_parquet("grand_final_players.parquet")
+
+# 6. Export to Excel (.xlsx)
+players.to_excel("grand_final_players.xlsx", sheet_name="PlayerStats")
+
+# 7. Export to JSON (in-memory string or written to disk)
+json_payload = players.to_json(indent=2)
+
+# 8. Print GitHub-flavored Markdown table
+print(players.to_markdown())
+```
+
+---
+
+## Model Context Protocol (MCP) Server
+
+VLRdevAPI includes a native MCP server for AI assistants and autonomous coding agents:
+
+```bash
+# Run server over stdio
+vlrdevapi-mcp
+
+# Or zero-install with uvx
+uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp
+```
+
+### Claude Desktop & Cursor Integration
+
+Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vlrdevapi": {
+      "command": "uvx",
+      "args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
+    }
+  }
+}
+```
+
+The MCP server provides **40 tools** covering matches, series, teams, players, tournaments, and editorial news, plus high-level composite tools (`get_match_full_context`, `get_team_overview`, `compare_teams`, `get_player_career_summary`, `get_h2h_matchup`, `get_tournament_dossier`, `get_live_and_upcoming_schedule`, `get_news_digest`, `series_map_summary`).
+
+---
+
 ## Configuration & Error Handling
 
 ### Rate Limiting & Concurrency
 
-`vlrdevapi` includes sensible defaults (`4.0` requests per second) to respect VLR.gg servers. When using `VLRClient`, you can customize client settings:
+`vlrdevapi` includes sensible defaults (`3.0` requests per second) to respect VLR.gg servers. When using `VLRClient`, you can customize client settings:
 
 ```python
 from zoneinfo import ZoneInfo

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vlrdevapi"
-version = "3.0.0"
+version = "3.1.0"
 description = "A Python library to scrape data from vlr.gg"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,13 +22,14 @@ keywords = [
 ]
 license = {file = "LICENCE"}
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Games/Entertainment",
     "Topic :: Internet :: WWW/HTTP",
 ]
@@ -49,6 +50,37 @@ test = [
     "respx>=0.23.1",
     "pytest-cov>=7.1.0",
 ]
+mcp = [
+    "mcp>=1.2.0",
+]
+pandas = [
+    "pandas>=2.0.0",
+]
+polars = [
+    "polars>=1.0.0",
+]
+excel = [
+    "openpyxl>=3.1.0",
+    "pandas>=2.0.0",
+]
+parquet = [
+    "pyarrow>=14.0.0",
+    "pandas>=2.0.0",
+]
+arrow = [
+    "pyarrow>=14.0.0",
+    "pandas>=2.0.0",
+]
+all = [
+    "mcp>=1.2.0",
+    "pandas>=2.0.0",
+    "polars>=1.0.0",
+    "openpyxl>=3.1.0",
+    "pyarrow>=14.0.0",
+]
+
+[project.scripts]
+vlrdevapi-mcp = "vlrdevapi.mcp.server:main"
 
 [dependency-groups]
 dev = [

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/scripts/download_fixtures.py

@@ -1,6 +1,5 @@
 import asyncio
 from pathlib import Path
-from typing import Dict
 
 import httpx
 
@@ -19,7 +18,7 @@ HEADERS = {
 }
 
 
-ROUTES: list[tuple[str, str, Dict[str, str]]] = []
+ROUTES: list[tuple[str, str, dict[str, str]]] = []
 
 # ── Matches ────────────────────────────────────────────────────
 ROUTES += [
@@ -275,6 +274,11 @@ ROUTES += [
         "team/14137/overview_light.html",
         {},
     ),
+    (
+        "/team/8050/mibr-gc",
+        "team/8050/overview_light.html",
+        {},
+    ),
     (
         "/team/matches/120/?core_id=all&group=completed&page=2",
         "team/120/completed_matches_page2.html",
@@ -487,8 +491,8 @@ for _gid in GAMES_BO5_2026:
     ]
 
 # ── Upcoming series (best_of + TBD map tabs) ─────────────────
-SERIES_ID_UPCOMING = 777946
-SERIES_SLUG_UPCOMING = "titan-esports-club-vs-unsettled-resentment-vct-china-2026-threshold-week-1-qf"
+SERIES_ID_UPCOMING = 773433
+SERIES_SLUG_UPCOMING = "mibr-gc-vs-gentle-mates-gc-game-changers-2026-championship-s-o-paulo-ubsf"
 
 ROUTES.append(
     (
@@ -529,7 +533,7 @@ for _sid, _sslug, _gid in SERIES_LOG_SAMPLES:
 # Unplayed map (Abyss, game 4 of the 2026 GF): graceful empty replay data.
 ROUTES.append(
     (
-        f"/754737/loud-vs-team-vitality-valorant-champions-2026-gf/?game=283290&tab=logs",
+        "/754737/loud-vs-team-vitality-valorant-champions-2026-gf/?game=283290&tab=logs",
         "series/754737_loud-vs-team-vitality-valorant-champions-2026-gf/game_283290_logs.html",
         {},
     ),
@@ -560,8 +564,7 @@ def _parse_last_page(html: str) -> int | None:
     for el in pagination.css("a.btn.mod-page, span.btn.mod-page"):
         try:
             num = int(el.text(strip=True))
-            if num > max_page:
-                max_page = num
+            max_page = max(max_page, num)
         except ValueError:
             continue
     return max_page if max_page > 0 else None

{vlrdevapi-3.0.0 → vlrdevapi-3.1.0}/src/vlrdevapi/__init__.py

@@ -54,7 +54,7 @@ if TYPE_CHECKING:
     news: NewsNamespace
     client: type[VLRClient]
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 
 _default_client: "VLRClient | None" = None