vlrdevapi 3.0.0__tar.gz → 3.1.1__tar.gz

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

@@ -5,11 +5,15 @@ on:
     paths:
       - 'official-docs/**'
       - 'docs-py/**'
+      - 'src/**'
+      - 'scripts/**'
   push:
     branches: [main]
     paths:
       - 'official-docs/**'
       - 'docs-py/**'
+      - 'src/**'
+      - 'scripts/**'
 
 jobs:
   check:
@@ -22,7 +26,10 @@ jobs:
           python-version: '3.12'
 
       - name: Install package
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
+
+      - name: Validate documentation schemas against Python library
+        run: uv run scripts/check_docs_schema.py
 
       # 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.1}/.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
@@ -75,3 +75,29 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-publish:
+    name: Publish to MCP Registry
+    runs-on: ubuntu-latest
+    needs:
+      - pypi-publish
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Wait for PyPI propagation
+        run: sleep 15
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

{vlrdevapi-3.0.0 → vlrdevapi-3.1.1}/.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.1}/.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.1}/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.1] - 2026-11-13
+
+### Added
+
+- **Official MCP Registry Manifest** — Added `server.json` compliant with the Model Context Protocol registry schema (`registry.modelcontextprotocol.io`), registering `io.github.vanshbordia/vlrdevapi` with stdio transport and `uvx` runtime arguments.
+- **Automated MCP Registry Publishing Workflow** — Extended GitHub Actions release pipeline (`publish.yml`) with automated OIDC authentication (`id-token: write`) via `mcp-publisher`.
+- **PyPI MCP Ownership Verification** — Added package ownership verification marker to `README.md`.
+
+### Fixed
+
+- **MCP Registry CLI Entrypoint** — Expose `vlrdevapi` console script alias to `vlrdevapi.mcp.server:main` alongside `vlrdevapi-mcp` so MCP registry clients launch the server using the package identifier.
+- **Windows Timezone Support** — Added `tzdata>=2025.1; sys_platform == 'win32'` as a core dependency to resolve `ZoneInfoNotFoundError` when running `vlrdevapi` or `uvx` on Windows.
+
+### Changed
+
+- **Dependency Upgrades** — Bumped core Python dependencies (Pydantic, Pandas, Polars, PyArrow, Pytest, Ruff) and documentation website dependencies (Next.js 16.4.6, Fumadocs 16.19, Tailwind CSS 4.3.5).
+
+## [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 +502,8 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[3.1.1]: https://github.com/Vanshbordia/vlrdevapi/compare/v3.1.0...v3.1.1
+[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.1/PKG-INFO

@@ -1,3 +1,75 @@
+Metadata-Version: 2.5
+Name: vlrdevapi
+Version: 3.1.1
+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
+Requires-Dist: tzdata>=2025.1; sys_platform == 'win32'
+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 +78,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/)
 
@@ -15,6 +89,8 @@
 
 </div>
 
+<!-- mcp-name: io.github.vanshbordia/vlrdevapi -->
+
 ---
 
 **vlrdevapi** is a high-performance, type-safe Python client for extracting and analyzing Valorant esports data from [VLR.gg](https://www.vlr.gg/). Built for competitive analysts, data scientists, Discord bot creators, and esports engineers, it delivers structured [Pydantic](https://docs.pydantic.dev/) models with full type hinting, built-in rate limiting, automatic retries, and comprehensive coverage across all VLR.gg entities.
@@ -25,6 +101,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 +119,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 +339,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 (`io.github.vanshbordia/vlrdevapi` on the official MCP Registry):
+
+```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.1/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/)
 
@@ -64,6 +17,8 @@ Description-Content-Type: text/markdown
 
 </div>
 
+<!-- mcp-name: io.github.vanshbordia/vlrdevapi -->
+
 ---
 
 **vlrdevapi** is a high-performance, type-safe Python client for extracting and analyzing Valorant esports data from [VLR.gg](https://www.vlr.gg/). Built for competitive analysts, data scientists, Discord bot creators, and esports engineers, it delivers structured [Pydantic](https://docs.pydantic.dev/) models with full type hinting, built-in rate limiting, automatic retries, and comprehensive coverage across all VLR.gg entities.
@@ -74,6 +29,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 +47,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 +267,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 (`io.github.vanshbordia/vlrdevapi` on the official MCP Registry):
+
+```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