speedrun-mcp 0.1.0__tar.gz

speedrun_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Jeffries
+
+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.

speedrun_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: speedrun-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for the speedrun.com API — games, leaderboards, world records, players and personal bests.
+Author: William Jeffries
+License: MIT
+Project-URL: Homepage, https://github.com/williamcodes/speedrun-mcp
+Project-URL: Issues, https://github.com/williamcodes/speedrun-mcp/issues
+Project-URL: speedrun.com API, https://github.com/speedruncomorg/api
+Keywords: mcp,model-context-protocol,speedrun,speedrun.com,llm,claude
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# speedrun-mcp
+
+<!-- mcp-name: io.github.williamcodes/speedrun-mcp -->
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[speedrun.com](https://www.speedrun.com). It lets an AI assistant query games,
+categories, leaderboards, world records, players and their personal bests —
+e.g. *"What's the current Super Mario 64 16-star world record, and who holds it?"*
+
+Built on speedrun.com's official, public [REST API](https://github.com/speedruncomorg/api).
+**No account or API key required** (the read endpoints are open); results are
+shaped into compact, model-friendly JSON (player ids resolved to names,
+durations formatted, subcategory variables labeled).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `search_games` | Fuzzy-search games by name → ids & abbreviations |
+| `get_game` | A game's details plus its categories (and optionally levels) |
+| `list_categories` | A game's categories (`Any%`, `120 Star`, …) with rules |
+| `list_variables` | Subcategory/filter variables and their value ids |
+| `list_platforms` / `list_regions` | Platform / region ids for the `platform`/`region` leaderboard filters |
+| `get_leaderboard` | A ranked leaderboard (top N; filter by variable / platform / region / timing) |
+| `get_world_record` | The current #1 run for a game/category, plus any runs tied for first |
+| `search_users` | Find players by username (partial, fuzzy match) |
+| `get_user_personal_bests` | A player's PBs across all games |
+| `get_run` | Details of a single run |
+
+A typical flow: `search_games` → `list_categories` (and `list_variables` for
+subcategories) → `get_leaderboard` / `get_world_record`. Use `list_platforms` /
+`list_regions` when you need an id for the `platform` / `region` filters.
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+# from PyPI (once published)
+pipx install speedrun-mcp        # or: uv tool install speedrun-mcp
+
+# from source
+git clone https://github.com/williamcodes/speedrun-mcp
+cd speedrun-mcp
+pip install -e .
+```
+
+The server speaks MCP over stdio:
+
+```bash
+speedrun-mcp          # console script
+python -m speedrun_mcp # equivalent
+```
+
+## Use with Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "speedrun": {
+      "command": "speedrun-mcp"
+    }
+  }
+}
+```
+
+If you installed from source into a virtualenv, point `command` at that
+interpreter, e.g. `"command": "/path/to/.venv/bin/speedrun-mcp"`.
+
+For Claude Code:
+
+```bash
+claude mcp add speedrun -- speedrun-mcp
+```
+
+## Notes & limits
+
+- **Read-only.** Submitting or moderating runs requires an authenticated
+  speedrun.com session and is intentionally out of scope.
+- **Rate limit:** speedrun.com allows 100 requests/minute per IP and responds
+  with HTTP 420 when exceeded; the client surfaces a clear error if you hit it.
+- Game and category arguments accept either an id (`o1y9wo6q`) or an
+  abbreviation (`sm64`). For precise subcategory leaderboards (e.g. `16 Star`),
+  discover the variable/value ids with `list_variables` and pass
+  `variables={variable_id: value_id}`.
+- **Errors are explanatory.** Invalid ids/filters raise an error that includes
+  speedrun.com's own message — e.g. passing a `level` to a full-game category
+  returns *"The selected category is for full-game runs, but a level was selected."*
+
+### Output shape
+
+- **Times** reflect the leaderboard's sort timing. When you pass `timing`
+  (`realtime` / `realtime_noloads` / `ingame`), the reported `time` /
+  `time_seconds` match that ranking, not the game's default timing.
+- **`get_leaderboard`** returns `returned_runs` (the number of runs returned,
+  bounded by `top` and ties — not the full board size) and a `runs` list with
+  resolved player names, formatted times, and labeled subcategories.
+- **`get_world_record`** returns `world_record` (the place-1 run, or `null` if
+  the board is empty) plus `tied` (a list of any other runs sharing first place).
+- **`get_user_personal_bests`** returns `returned` (how many came back, capped by
+  `limit`) and `total_available` (the player's true PB count), plus the
+  `personal_bests` list with game/category names and resolved players.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not network"   # unit tests (offline)
+pytest                    # include live-API tests
+ruff check .
+```
+
+## License
+
+MIT

speedrun_mcp-0.1.0/README.md

@@ -0,0 +1,117 @@
+# speedrun-mcp
+
+<!-- mcp-name: io.github.williamcodes/speedrun-mcp -->
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[speedrun.com](https://www.speedrun.com). It lets an AI assistant query games,
+categories, leaderboards, world records, players and their personal bests —
+e.g. *"What's the current Super Mario 64 16-star world record, and who holds it?"*
+
+Built on speedrun.com's official, public [REST API](https://github.com/speedruncomorg/api).
+**No account or API key required** (the read endpoints are open); results are
+shaped into compact, model-friendly JSON (player ids resolved to names,
+durations formatted, subcategory variables labeled).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `search_games` | Fuzzy-search games by name → ids & abbreviations |
+| `get_game` | A game's details plus its categories (and optionally levels) |
+| `list_categories` | A game's categories (`Any%`, `120 Star`, …) with rules |
+| `list_variables` | Subcategory/filter variables and their value ids |
+| `list_platforms` / `list_regions` | Platform / region ids for the `platform`/`region` leaderboard filters |
+| `get_leaderboard` | A ranked leaderboard (top N; filter by variable / platform / region / timing) |
+| `get_world_record` | The current #1 run for a game/category, plus any runs tied for first |
+| `search_users` | Find players by username (partial, fuzzy match) |
+| `get_user_personal_bests` | A player's PBs across all games |
+| `get_run` | Details of a single run |
+
+A typical flow: `search_games` → `list_categories` (and `list_variables` for
+subcategories) → `get_leaderboard` / `get_world_record`. Use `list_platforms` /
+`list_regions` when you need an id for the `platform` / `region` filters.
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+# from PyPI (once published)
+pipx install speedrun-mcp        # or: uv tool install speedrun-mcp
+
+# from source
+git clone https://github.com/williamcodes/speedrun-mcp
+cd speedrun-mcp
+pip install -e .
+```
+
+The server speaks MCP over stdio:
+
+```bash
+speedrun-mcp          # console script
+python -m speedrun_mcp # equivalent
+```
+
+## Use with Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "speedrun": {
+      "command": "speedrun-mcp"
+    }
+  }
+}
+```
+
+If you installed from source into a virtualenv, point `command` at that
+interpreter, e.g. `"command": "/path/to/.venv/bin/speedrun-mcp"`.
+
+For Claude Code:
+
+```bash
+claude mcp add speedrun -- speedrun-mcp
+```
+
+## Notes & limits
+
+- **Read-only.** Submitting or moderating runs requires an authenticated
+  speedrun.com session and is intentionally out of scope.
+- **Rate limit:** speedrun.com allows 100 requests/minute per IP and responds
+  with HTTP 420 when exceeded; the client surfaces a clear error if you hit it.
+- Game and category arguments accept either an id (`o1y9wo6q`) or an
+  abbreviation (`sm64`). For precise subcategory leaderboards (e.g. `16 Star`),
+  discover the variable/value ids with `list_variables` and pass
+  `variables={variable_id: value_id}`.
+- **Errors are explanatory.** Invalid ids/filters raise an error that includes
+  speedrun.com's own message — e.g. passing a `level` to a full-game category
+  returns *"The selected category is for full-game runs, but a level was selected."*
+
+### Output shape
+
+- **Times** reflect the leaderboard's sort timing. When you pass `timing`
+  (`realtime` / `realtime_noloads` / `ingame`), the reported `time` /
+  `time_seconds` match that ranking, not the game's default timing.
+- **`get_leaderboard`** returns `returned_runs` (the number of runs returned,
+  bounded by `top` and ties — not the full board size) and a `runs` list with
+  resolved player names, formatted times, and labeled subcategories.
+- **`get_world_record`** returns `world_record` (the place-1 run, or `null` if
+  the board is empty) plus `tied` (a list of any other runs sharing first place).
+- **`get_user_personal_bests`** returns `returned` (how many came back, capped by
+  `limit`) and `total_available` (the player's true PB count), plus the
+  `personal_bests` list with game/category names and resolved players.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not network"   # unit tests (offline)
+pytest                    # include live-API tests
+ruff check .
+```
+
+## License
+
+MIT

speedrun_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speedrun-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server for the speedrun.com API — games, leaderboards, world records, players and personal bests."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "William Jeffries" }]
+keywords = ["mcp", "model-context-protocol", "speedrun", "speedrun.com", "llm", "claude"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://github.com/williamcodes/speedrun-mcp"
+Issues = "https://github.com/williamcodes/speedrun-mcp/issues"
+"speedrun.com API" = "https://github.com/speedruncomorg/api"
+
+[project.scripts]
+speedrun-mcp = "speedrun_mcp.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["network: tests that hit the live speedrun.com API"]
+
+[tool.ruff]
+line-length = 100

speedrun_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

speedrun_mcp-0.1.0/src/speedrun_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""speedrun-mcp: a Model Context Protocol server for the speedrun.com API."""
+
+from .server import mcp
+
+__all__ = ["mcp"]

speedrun_mcp-0.1.0/src/speedrun_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

speedrun_mcp-0.1.0/src/speedrun_mcp/client.py

@@ -0,0 +1,230 @@
+"""Thin async client for the speedrun.com REST API (v1).
+
+The public API requires no authentication for the read endpoints used here.
+Docs: https://github.com/speedruncomorg/api/tree/master/version1
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+import httpx
+
+API_BASE = "https://www.speedrun.com/api/v1"
+
+try:
+    _VERSION = version("speedrun-mcp")
+except PackageNotFoundError:  # running from a source checkout without install
+    _VERSION = "0.0.0+dev"
+
+USER_AGENT = f"speedrun-mcp/{_VERSION} (+https://github.com/williamcodes/speedrun-mcp)"
+
+# speedrun.com allows 100 requests/min/IP and answers 420 when exceeded.
+RATE_LIMIT_STATUS = 420
+
+
+class SpeedrunError(RuntimeError):
+    """Raised when the speedrun.com API returns an error we can explain."""
+
+
+class RateLimitError(SpeedrunError):
+    """Raised when the API rejects us for exceeding 100 requests/minute."""
+
+
+class NotFoundError(SpeedrunError):
+    """Raised when the API returns HTTP 404 for a resource (bad id/filters)."""
+
+
+class SpeedrunClient:
+    """Minimal async wrapper around the speedrun.com API.
+
+    One client owns one ``httpx.AsyncClient``; use it as an async context
+    manager or remember to ``await close()``.
+    """
+
+    def __init__(self, *, timeout: float = 20.0) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=API_BASE,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+            follow_redirects=True,  # abbreviations 30x-redirect to ID-based URLs
+        )
+
+    async def __aenter__(self) -> "SpeedrunClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """GET a path and return the full parsed JSON body (incl. pagination)."""
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            resp = await self._http.get(path, params=clean)
+        except httpx.HTTPError as exc:  # network/DNS/timeout
+            raise SpeedrunError(f"Network error talking to speedrun.com: {exc}") from exc
+
+        if resp.status_code == RATE_LIMIT_STATUS:
+            raise RateLimitError(
+                "speedrun.com rate limit hit (100 requests/minute). Wait a minute and retry."
+            )
+
+        if resp.status_code == 404:
+            detail = self._error_message(resp)
+            msg = f"Not found: {path} (check the id/abbreviation and any filters)."
+            if detail:
+                msg = f"{msg} speedrun.com says: {detail}"
+            raise NotFoundError(msg)
+
+        if resp.status_code >= 400:
+            detail = self._error_message(resp)
+            msg = f"speedrun.com returned HTTP {resp.status_code} for {path}."
+            if detail:
+                msg = f"{msg} speedrun.com says: {detail}"
+            raise SpeedrunError(msg)
+
+        try:
+            return resp.json()
+        except ValueError as exc:  # non-JSON / empty success body
+            raise SpeedrunError(
+                f"speedrun.com returned an unparseable response for {path}: {exc}"
+            ) from exc
+
+    async def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """GET a path and return the parsed ``data`` payload.
+
+        speedrun.com wraps successful responses in ``{"data": ...}``; we unwrap
+        it so callers never have to. Pagination metadata is dropped on purpose —
+        for single-page tools that cap their own result counts. Use
+        :meth:`_get_paginated` for collections that may exceed one page.
+        """
+        body = await self._request(path, params)
+        if not isinstance(body, dict):
+            return body
+        return body.get("data", body)
+
+    async def _get_paginated(self, path: str, params: dict[str, Any] | None = None) -> list[dict]:
+        """Fetch and concatenate ALL pages of a collection endpoint.
+
+        Some collections (e.g. ``/platforms``, ~235 items) exceed the 200/page
+        cap, so a single request silently truncates. This walks every page by
+        following the ``pagination.links`` ``next`` marker / incrementing offset.
+        """
+        merged = dict(params or {})
+        page_size = int(merged.get("max") or 200)
+        merged["max"] = page_size
+        collected: list[dict] = []
+        offset = 0
+        while True:
+            merged["offset"] = offset
+            body = await self._request(path, merged)
+            data = body.get("data", []) if isinstance(body, dict) else (body or [])
+            collected.extend(data)
+            pagination = body.get("pagination", {}) if isinstance(body, dict) else {}
+            has_next = any(link.get("rel") == "next" for link in pagination.get("links", []))
+            if not has_next or len(data) < page_size:  # last (or short/empty) page
+                break
+            offset += page_size
+        return collected
+
+    @staticmethod
+    def _error_message(resp: httpx.Response) -> str | None:
+        """Best-effort extraction of the ``message`` field from an error body.
+
+        speedrun.com error bodies look like
+        ``{"status":400,"message":"...","links":[...]}``. A non-JSON or empty
+        body must not raise here — we just return ``None`` so the caller can
+        fall back to a generic message.
+        """
+        try:
+            body = resp.json()
+        except ValueError:
+            return None
+        if isinstance(body, dict):
+            message = body.get("message")
+            if isinstance(message, str) and message.strip():
+                return message.strip()
+        return None
+
+    # -- games ----------------------------------------------------------------
+
+    async def search_games(self, name: str, *, maximum: int = 10) -> list[dict]:
+        return await self._get("/games", {"name": name, "max": maximum})
+
+    async def get_game(self, game: str, *, embed: str | None = None) -> dict:
+        return await self._get(f"/games/{game}", {"embed": embed})
+
+    async def get_categories(self, game: str) -> list[dict]:
+        return await self._get(f"/games/{game}/categories")
+
+    async def get_levels(self, game: str) -> list[dict]:
+        return await self._get(f"/games/{game}/levels")
+
+    async def get_game_variables(self, game: str) -> list[dict]:
+        return await self._get(f"/games/{game}/variables")
+
+    async def get_category_variables(self, category: str) -> list[dict]:
+        return await self._get(f"/categories/{category}/variables")
+
+    # -- leaderboards ---------------------------------------------------------
+
+    async def get_leaderboard(
+        self,
+        game: str,
+        category: str,
+        *,
+        level: str | None = None,
+        top: int | None = None,
+        variables: dict[str, str] | None = None,
+        platform: str | None = None,
+        region: str | None = None,
+        timing: str | None = None,
+        emulators: bool | None = None,
+        date: str | None = None,
+        embed: str | None = None,
+    ) -> dict:
+        if level:
+            path = f"/leaderboards/{game}/level/{level}/{category}"
+        else:
+            path = f"/leaderboards/{game}/category/{category}"
+        params: dict[str, Any] = {
+            "top": top,
+            "platform": platform,
+            "region": region,
+            "timing": timing,
+            "emulators": emulators,
+            "date": date,
+            "embed": embed,
+        }
+        for var_id, value_id in (variables or {}).items():
+            params[f"var-{var_id}"] = value_id
+        return await self._get(path, params)
+
+    # -- users / runs ---------------------------------------------------------
+
+    async def search_users(self, name: str, *, maximum: int = 10) -> list[dict]:
+        # 'name' does fuzzy/partial matching; 'lookup' is exact-only.
+        return await self._get("/users", {"name": name, "max": maximum})
+
+    async def get_user(self, user: str) -> dict:
+        return await self._get(f"/users/{user}")
+
+    async def get_user_personal_bests(
+        self, user: str, *, embed: str | None = None
+    ) -> list[dict]:
+        return await self._get(f"/users/{user}/personal-bests", {"embed": embed})
+
+    async def get_run(self, run_id: str, *, embed: str | None = None) -> dict:
+        return await self._get(f"/runs/{run_id}", {"embed": embed})
+
+    # -- platforms / regions --------------------------------------------------
+
+    async def get_platforms(self) -> list[dict]:
+        return await self._get_paginated("/platforms")
+
+    async def get_regions(self) -> list[dict]:
+        return await self._get_paginated("/regions")