mcp-steam 0.1.2__tar.gz

mcp_steam-0.1.2/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: mcp-steam
+Version: 0.1.2
+Summary: MCP server for Steam gaming library, achievements, stats, and store search
+Keywords: mcp,steam,gaming,model-context-protocol
+Author: Matthew O'Brien
+Author-email: Matthew O'Brien <obrien.mlotwis@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Dist: mcp>=1.27.0,<2
+Requires-Dist: httpx>=0.28.0
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/obrien-matthew/mcp-steam
+Project-URL: Issues, https://github.com/obrien-matthew/mcp-steam/issues
+Description-Content-Type: text/markdown
+
+# mcp-steam
+
+MCP server for Steam, focused on gaming library management, achievements, stats, and store discovery. 12 granular tools designed for use with Claude and other LLM agents.
+
+## Prerequisites
+
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+- A [Steam Web API Key](https://steamcommunity.com/dev/apikey)
+- Your Steam ID (numeric, up to 17 digits)
+
+## Setup
+
+### 1. Get Your Steam API Key
+
+1. Go to the [Steam Web API Key page](https://steamcommunity.com/dev/apikey)
+2. Sign in with your Steam account
+3. Register a domain name (any name works for personal use)
+4. Note your API key
+
+### 2. Find Your Steam ID
+
+Your Steam ID is the numeric identifier in your profile URL. If your profile URL is `https://steamcommunity.com/profiles/76561198012345678`, your Steam ID is `76561198012345678`.
+
+If you use a custom URL (e.g., `/id/username`), use a [Steam ID finder](https://www.steamidfinder.com/) to look up the numeric ID.
+
+### 3. Install
+
+```bash
+cd mcp-steam
+uv sync
+```
+
+### 4. Configure Environment Variables
+
+Set these before running the server:
+
+```bash
+export STEAM_API_KEY="your_api_key"
+export STEAM_ID="your_steam_id"
+```
+
+### 5. Test the Connection
+
+```bash
+uv run mcp-steam
+```
+
+The server verifies your API key and Steam ID on startup by fetching your player summary.
+
+## Claude Desktop / Claude Code Configuration
+
+Add to your MCP server config. If installed from PyPI:
+
+```json
+{
+  "mcpServers": {
+    "steam": {
+      "command": "uvx",
+      "args": ["mcp-steam"],
+      "env": {
+        "STEAM_API_KEY": "your_api_key",
+        "STEAM_ID": "your_steam_id"
+      }
+    }
+  }
+}
+```
+
+Or if running from a local clone:
+
+```json
+{
+  "mcpServers": {
+    "steam": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mcp-steam", "run", "mcp-steam"],
+      "env": {
+        "STEAM_API_KEY": "your_api_key",
+        "STEAM_ID": "your_steam_id"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Library
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_owned_games` | `sort_by="playtime"`, `limit=50` | Your game library with playtime. Sort by playtime, recent, or name. |
+| `get_recently_played` | `limit=10` | Games played in the last 2 weeks. |
+
+### Game Info
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_game_details` | `app_id` | Store page info: description, price, genres, metacritic, platforms. |
+| `search_games` | `query`, `limit=10` | Search the Steam store. |
+
+### Achievements & Stats
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_achievements` | `app_id` | Your achievement progress with global rarity percentages. |
+| `get_player_stats` | `app_id` | Game-specific stats (kills, deaths, etc.). |
+| `get_global_achievement_stats` | `app_id` | Global unlock percentages for all achievements. |
+
+### Wishlist
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_wishlist` | `limit=50` | Your wishlist sorted by priority, with prices and discounts. |
+
+### News
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_game_news` | `app_id`, `count=5` | Recent news and updates for a game. |
+
+### Profile
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_player_summary` | (none) | Your profile: name, status, currently playing. |
+| `get_friend_list` | (none) | Your friends list with relationship info. |
+
+### Featured
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_featured_games` | (none) | Currently featured and on-sale games. |
+
+## Steam Web API Notes
+
+- **API key security:** Your config file contains your Steam API key. Never commit it to version control or share it publicly.
+- **Rate limits:** The Steam Web API has undocumented rate limits. If you hit them, the server will return a rate limit error.
+- **Profile visibility:** Some tools require your Steam profile to be public (achievements, game stats). Library data works regardless.
+- **Game stats availability:** Not all games expose stats through the API. `get_player_stats` will return an error for unsupported games.
+- **Wishlist access:** Wishlist data requires your profile's wishlist to be public.
+
+## Development
+
+```bash
+uv run mcp-steam              # Run the server
+uv run ruff check src/       # Lint
+uv run ruff format src/      # Format
+uv run pyright src/          # Type check
+```
+
+### Pre-commit Hooks
+
+This project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit checks. Install with `brew install lefthook` (or see [other install methods](https://github.com/evilmartians/lefthook/blob/master/docs/install.md)), then:
+
+```bash
+lefthook install
+```

mcp_steam-0.1.2/README.md

@@ -0,0 +1,159 @@
+# mcp-steam
+
+MCP server for Steam, focused on gaming library management, achievements, stats, and store discovery. 12 granular tools designed for use with Claude and other LLM agents.
+
+## Prerequisites
+
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+- A [Steam Web API Key](https://steamcommunity.com/dev/apikey)
+- Your Steam ID (numeric, up to 17 digits)
+
+## Setup
+
+### 1. Get Your Steam API Key
+
+1. Go to the [Steam Web API Key page](https://steamcommunity.com/dev/apikey)
+2. Sign in with your Steam account
+3. Register a domain name (any name works for personal use)
+4. Note your API key
+
+### 2. Find Your Steam ID
+
+Your Steam ID is the numeric identifier in your profile URL. If your profile URL is `https://steamcommunity.com/profiles/76561198012345678`, your Steam ID is `76561198012345678`.
+
+If you use a custom URL (e.g., `/id/username`), use a [Steam ID finder](https://www.steamidfinder.com/) to look up the numeric ID.
+
+### 3. Install
+
+```bash
+cd mcp-steam
+uv sync
+```
+
+### 4. Configure Environment Variables
+
+Set these before running the server:
+
+```bash
+export STEAM_API_KEY="your_api_key"
+export STEAM_ID="your_steam_id"
+```
+
+### 5. Test the Connection
+
+```bash
+uv run mcp-steam
+```
+
+The server verifies your API key and Steam ID on startup by fetching your player summary.
+
+## Claude Desktop / Claude Code Configuration
+
+Add to your MCP server config. If installed from PyPI:
+
+```json
+{
+  "mcpServers": {
+    "steam": {
+      "command": "uvx",
+      "args": ["mcp-steam"],
+      "env": {
+        "STEAM_API_KEY": "your_api_key",
+        "STEAM_ID": "your_steam_id"
+      }
+    }
+  }
+}
+```
+
+Or if running from a local clone:
+
+```json
+{
+  "mcpServers": {
+    "steam": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mcp-steam", "run", "mcp-steam"],
+      "env": {
+        "STEAM_API_KEY": "your_api_key",
+        "STEAM_ID": "your_steam_id"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Library
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_owned_games` | `sort_by="playtime"`, `limit=50` | Your game library with playtime. Sort by playtime, recent, or name. |
+| `get_recently_played` | `limit=10` | Games played in the last 2 weeks. |
+
+### Game Info
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_game_details` | `app_id` | Store page info: description, price, genres, metacritic, platforms. |
+| `search_games` | `query`, `limit=10` | Search the Steam store. |
+
+### Achievements & Stats
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_achievements` | `app_id` | Your achievement progress with global rarity percentages. |
+| `get_player_stats` | `app_id` | Game-specific stats (kills, deaths, etc.). |
+| `get_global_achievement_stats` | `app_id` | Global unlock percentages for all achievements. |
+
+### Wishlist
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_wishlist` | `limit=50` | Your wishlist sorted by priority, with prices and discounts. |
+
+### News
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_game_news` | `app_id`, `count=5` | Recent news and updates for a game. |
+
+### Profile
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_player_summary` | (none) | Your profile: name, status, currently playing. |
+| `get_friend_list` | (none) | Your friends list with relationship info. |
+
+### Featured
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_featured_games` | (none) | Currently featured and on-sale games. |
+
+## Steam Web API Notes
+
+- **API key security:** Your config file contains your Steam API key. Never commit it to version control or share it publicly.
+- **Rate limits:** The Steam Web API has undocumented rate limits. If you hit them, the server will return a rate limit error.
+- **Profile visibility:** Some tools require your Steam profile to be public (achievements, game stats). Library data works regardless.
+- **Game stats availability:** Not all games expose stats through the API. `get_player_stats` will return an error for unsupported games.
+- **Wishlist access:** Wishlist data requires your profile's wishlist to be public.
+
+## Development
+
+```bash
+uv run mcp-steam              # Run the server
+uv run ruff check src/       # Lint
+uv run ruff format src/      # Format
+uv run pyright src/          # Type check
+```
+
+### Pre-commit Hooks
+
+This project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit checks. Install with `brew install lefthook` (or see [other install methods](https://github.com/evilmartians/lefthook/blob/master/docs/install.md)), then:
+
+```bash
+lefthook install
+```

mcp_steam-0.1.2/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "mcp-steam"
+version = "0.1.2"
+description = "MCP server for Steam gaming library, achievements, stats, and store search"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Matthew O'Brien", email = "obrien.mlotwis@gmail.com" }
+]
+requires-python = ">=3.14"
+keywords = ["mcp", "steam", "gaming", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "mcp>=1.27.0,<2",
+    "httpx>=0.28.0",
+]
+
+[project.urls]
+Repository = "https://github.com/obrien-matthew/mcp-steam"
+Issues = "https://github.com/obrien-matthew/mcp-steam/issues"
+
+[tool.uv.build-backend]
+module-name = "steam_mcp"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.11.0",
+    "pyright>=1.1.400",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[project.scripts]
+mcp-steam = "steam_mcp:main"

mcp_steam-0.1.2/src/steam_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""MCP server for Steam gaming library, achievements, stats, and store search."""
+
+from .server import mcp
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+__all__ = ["main", "mcp"]

mcp_steam-0.1.2/src/steam_mcp/auth.py

@@ -0,0 +1,87 @@
+"""Steam API key validation and HTTP client singleton."""
+
+import os
+import sys
+
+import httpx
+
+_client: httpx.Client | None = None
+_steam_id: str | None = None
+
+
+def get_steam_id() -> str:
+    """Return the configured Steam ID."""
+    global _steam_id
+    if _steam_id is not None:
+        return _steam_id
+
+    steam_id = os.environ.get("STEAM_ID")
+    if not steam_id:
+        raise RuntimeError(
+            "STEAM_ID environment variable is required. "
+            "See README.md for setup instructions."
+        )
+    _steam_id = steam_id
+    return _steam_id
+
+
+def get_http_client() -> httpx.Client:
+    """Return a cached HTTP client for Steam API calls.
+
+    Reads STEAM_API_KEY from environment variables and verifies
+    the key works by fetching the player summary.
+
+    Raises RuntimeError if required env vars are missing or key is invalid.
+    """
+    global _client
+    if _client is not None:
+        return _client
+
+    api_key = os.environ.get("STEAM_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "STEAM_API_KEY environment variable is required. "
+            "See README.md for setup instructions."
+        )
+
+    steam_id = get_steam_id()
+
+    client = httpx.Client(timeout=30.0)
+
+    # Verify API key works by fetching player summary
+    try:
+        resp = client.get(
+            "https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2/",
+            params={"key": api_key, "steamids": steam_id},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        players = data.get("response", {}).get("players", [])
+        if not players:
+            raise RuntimeError(
+                f"No player found for Steam ID '{steam_id}'. "
+                "Please check your STEAM_ID."
+            )
+    except httpx.HTTPStatusError as e:
+        client.close()
+        print(f"Steam API key verification failed: {e}", file=sys.stderr)
+        raise RuntimeError(
+            "Failed to verify Steam API key. Please check your credentials."
+        ) from e
+    except Exception as e:
+        client.close()
+        print(f"Steam API connection failed: {e}", file=sys.stderr)
+        raise RuntimeError(
+            "Failed to connect to Steam API. Please check your network."
+        ) from e
+
+    _client = client
+    return _client
+
+
+def get_api_key() -> str:
+    """Return the Steam API key from environment."""
+    api_key = os.environ.get("STEAM_API_KEY")
+    if not api_key:
+        raise RuntimeError("STEAM_API_KEY environment variable is required.")
+    return api_key

mcp_steam-0.1.2/src/steam_mcp/client.py

@@ -0,0 +1,319 @@
+"""Thin wrapper over the Steam Web API with validation and clean error handling."""
+
+import sys
+from typing import Any, NoReturn
+
+import httpx
+
+from .auth import get_api_key, get_http_client, get_steam_id
+from .formatting import (
+    format_achievement,
+    format_featured_game,
+    format_friend,
+    format_game_details,
+    format_news_item,
+    format_owned_game,
+    format_player_summary,
+    format_wishlist_item,
+)
+from .validation import validate_app_id, validate_limit
+
+STEAM_API_BASE = "https://api.steampowered.com"
+STORE_API_BASE = "https://store.steampowered.com"
+
+
+class SteamError(Exception):
+    """User-facing Steam API error."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class SteamClient:
+    """Validated, formatted interface to the Steam API."""
+
+    def __init__(self) -> None:
+        self._http = get_http_client()
+        self._api_key = get_api_key()
+        self._steam_id = get_steam_id()
+
+    def _handle_error(self, e: Exception, action: str) -> NoReturn:
+        msg = f"Steam API error while {action}"
+        status_code: int | None = None
+        if isinstance(e, httpx.HTTPStatusError):
+            status_code = e.response.status_code
+            if status_code == 403:
+                msg = f"Access denied while {action} (check API key permissions)"
+            elif status_code == 404:
+                msg = f"Not found while {action}"
+            elif status_code == 429:
+                msg = f"Rate limited while {action}. Please try again shortly."
+            elif status_code == 500:
+                msg = f"Steam server error while {action}. Try again later."
+        print(f"{msg}: {e}", file=sys.stderr)
+        raise SteamError(msg, status_code) from e
+
+    def _api_request(self, endpoint: str, params: dict[str, Any] | None = None) -> dict:
+        """Make a request to the Steam Web API (api.steampowered.com)."""
+        url = f"{STEAM_API_BASE}/{endpoint}"
+        request_params: dict[str, Any] = {"key": self._api_key}
+        if params:
+            request_params.update(params)
+        resp = self._http.get(url, params=request_params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _store_request(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        """Make a request to the Steam Store API (store.steampowered.com)."""
+        url = f"{STORE_API_BASE}/{path}"
+        resp = self._http.get(url, params=params or {})
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Library --
+
+    def get_owned_games(self, sort_by: str = "playtime", limit: int = 50) -> list[dict]:
+        limit = validate_limit(limit, max_val=100)
+        try:
+            data = self._api_request(
+                "IPlayerService/GetOwnedGames/v1/",
+                {
+                    "steamid": self._steam_id,
+                    "include_appinfo": 1,
+                    "include_played_free_games": 1,
+                },
+            )
+            games = data.get("response", {}).get("games", [])
+            if sort_by == "playtime":
+                games.sort(key=lambda g: g.get("playtime_forever", 0), reverse=True)
+            elif sort_by == "recent":
+                games.sort(key=lambda g: g.get("rtime_last_played", 0), reverse=True)
+            elif sort_by == "name":
+                games.sort(key=lambda g: g.get("name", "").lower())
+            return [format_owned_game(g) for g in games[:limit]]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching owned games")
+
+    def get_recently_played(self, limit: int = 10) -> list[dict]:
+        limit = validate_limit(limit)
+        try:
+            data = self._api_request(
+                "IPlayerService/GetRecentlyPlayedGames/v1/",
+                {"steamid": self._steam_id, "count": limit},
+            )
+            games = data.get("response", {}).get("games", [])
+            return [format_owned_game(g) for g in games]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching recently played games")
+
+    # -- Game Info --
+
+    def get_game_details(self, app_id: str) -> dict:
+        app_id_int = validate_app_id(app_id)
+        try:
+            data = self._store_request(
+                "api/appdetails",
+                {"appids": str(app_id_int)},
+            )
+            app_data = data.get(str(app_id_int), {})
+            if not app_data.get("success"):
+                raise SteamError(f"App {app_id_int} not found on Steam Store")
+            return format_game_details(app_data.get("data", {}))
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching game details")
+
+    def search_games(self, query: str, limit: int = 10) -> list[dict]:
+        limit = validate_limit(limit, max_val=25)
+        try:
+            data = self._store_request(
+                "api/storesearch",
+                {"term": query, "l": "english", "cc": "us"},
+            )
+            items = data.get("items", [])[:limit]
+            results: list[dict] = []
+            for item in items:
+                results.append(
+                    {
+                        "name": item.get("name", ""),
+                        "appid": item.get("id"),
+                        "price": item.get("price", {}).get("final", 0),
+                        "platforms": {
+                            k: v for k, v in item.get("platforms", {}).items() if v
+                        },
+                    }
+                )
+            return results
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "searching games")
+
+    # -- Achievements & Stats --
+
+    def get_achievements(self, app_id: str) -> dict:
+        app_id_int = validate_app_id(app_id)
+        try:
+            data = self._api_request(
+                "ISteamUserStats/GetPlayerAchievements/v1/",
+                {"steamid": self._steam_id, "appid": app_id_int},
+            )
+            stats = data.get("playerstats", {})
+            achievements = stats.get("achievements", [])
+
+            # Try to get global percentages for context
+            global_pcts = self._get_global_percentages(app_id_int)
+
+            formatted = [format_achievement(a, global_pcts) for a in achievements]
+            unlocked = sum(1 for a in formatted if a.get("achieved"))
+            return {
+                "game": stats.get("gameName", ""),
+                "unlocked": unlocked,
+                "total": len(formatted),
+                "achievements": formatted,
+            }
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching achievements")
+
+    def _get_global_percentages(self, app_id: int) -> dict[str, float]:
+        """Fetch global achievement percentages for enrichment."""
+        try:
+            data = self._api_request(
+                "ISteamUserStats/GetGlobalAchievementPercentagesForApp/v2/",
+                {"gameid": app_id},
+            )
+            achievements = data.get("achievementpercentages", {}).get(
+                "achievements", []
+            )
+            return {a["name"]: a["percent"] for a in achievements}
+        except Exception:
+            return {}
+
+    def get_player_stats(self, app_id: str) -> dict:
+        app_id_int = validate_app_id(app_id)
+        try:
+            data = self._api_request(
+                "ISteamUserStats/GetUserStatsForGame/v2/",
+                {"steamid": self._steam_id, "appid": app_id_int},
+            )
+            stats = data.get("playerstats", {})
+            return {
+                "game": stats.get("gameName", ""),
+                "stats": {s["name"]: s["value"] for s in stats.get("stats", [])},
+            }
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching player stats")
+
+    def get_global_achievement_stats(self, app_id: str) -> list[dict]:
+        app_id_int = validate_app_id(app_id)
+        try:
+            data = self._api_request(
+                "ISteamUserStats/GetGlobalAchievementPercentagesForApp/v2/",
+                {"gameid": app_id_int},
+            )
+            achievements = data.get("achievementpercentages", {}).get(
+                "achievements", []
+            )
+            return [
+                {
+                    "name": a.get("name", ""),
+                    "percent": round(a.get("percent", 0.0), 1),
+                }
+                for a in achievements
+            ]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching global achievement stats")
+
+    # -- Wishlist --
+
+    def get_wishlist(self, limit: int = 50) -> list[dict]:
+        limit = validate_limit(limit, max_val=100)
+        try:
+            data = self._store_request(
+                f"wishlist/profiles/{self._steam_id}/wishlistdata",
+            )
+            items = [
+                format_wishlist_item(appid, info)
+                for appid, info in data.items()
+                if isinstance(info, dict)
+            ]
+            # Sort by priority (0 = no priority, otherwise lower = higher priority)
+            items.sort(
+                key=lambda x: (
+                    x.get("priority", 0) == 0,
+                    x.get("priority", 0),
+                )
+            )
+            return items[:limit]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching wishlist")
+
+    # -- News --
+
+    def get_game_news(self, app_id: str, count: int = 5) -> list[dict]:
+        app_id_int = validate_app_id(app_id)
+        count = validate_limit(count, max_val=20)
+        try:
+            data = self._api_request(
+                "ISteamNews/GetNewsForApp/v2/",
+                {"appid": app_id_int, "count": count, "maxlength": 500},
+            )
+            items = data.get("appnews", {}).get("newsitems", [])
+            return [format_news_item(item) for item in items]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching game news")
+
+    # -- Profile --
+
+    def get_player_summary(self) -> dict:
+        try:
+            data = self._api_request(
+                "ISteamUser/GetPlayerSummaries/v2/",
+                {"steamids": self._steam_id},
+            )
+            players = data.get("response", {}).get("players", [])
+            if not players:
+                raise SteamError("Player profile not found")
+            return format_player_summary(players[0])
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching player summary")
+
+    def get_friend_list(self) -> list[dict]:
+        try:
+            data = self._api_request(
+                "ISteamUser/GetFriendList/v1/",
+                {"steamid": self._steam_id, "relationship": "friend"},
+            )
+            friends = data.get("friendslist", {}).get("friends", [])
+            return [format_friend(f) for f in friends]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching friend list")
+
+    # -- Featured --
+
+    def get_featured_games(self) -> dict:
+        try:
+            data = self._store_request("api/featured")
+            featured_win = data.get("featured_win", [])
+            featured_mac = data.get("featured_mac", [])
+            featured_linux = data.get("featured_linux", [])
+
+            # Combine and deduplicate by appid
+            seen: set[int] = set()
+            all_featured: list[dict] = []
+            for game in featured_win + featured_mac + featured_linux:
+                appid = game.get("id")
+                if appid and appid not in seen:
+                    seen.add(appid)
+                    all_featured.append(format_featured_game(game))
+
+            # Separate into on-sale and regular
+            on_sale = [g for g in all_featured if g.get("discounted")]
+            regular = [g for g in all_featured if not g.get("discounted")]
+
+            return {
+                "on_sale": on_sale,
+                "regular": regular,
+                "total": len(all_featured),
+            }
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e, "fetching featured games")

mcp_steam-0.1.2/src/steam_mcp/formatting.py

@@ -0,0 +1,194 @@
+"""Response formatters that produce clean, LLM-friendly dicts.
+
+Only includes fields useful for an LLM -- no images, screenshots, or raw HTML.
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from .validation import format_playtime
+
+
+def format_owned_game(game: dict) -> dict:
+    """Format a game from the owned games list."""
+    result: dict[str, Any] = {
+        "name": game.get("name", "Unknown"),
+        "appid": game.get("appid"),
+        "playtime_total": format_playtime(game.get("playtime_forever", 0)),
+    }
+    playtime_2weeks = game.get("playtime_2weeks")
+    if playtime_2weeks:
+        result["playtime_2weeks"] = format_playtime(playtime_2weeks)
+    last_played = game.get("rtime_last_played")
+    if last_played and last_played > 0:
+        result["last_played"] = datetime.fromtimestamp(last_played, tz=UTC).isoformat()
+    return result
+
+
+def format_game_details(data: dict) -> dict:
+    """Format store app details into an LLM-friendly dict."""
+    result: dict[str, Any] = {
+        "name": data.get("name", "Unknown"),
+        "appid": data.get("steam_appid"),
+        "type": data.get("type"),
+        "is_free": data.get("is_free", False),
+        "description": data.get("short_description", ""),
+    }
+
+    # Price
+    price_overview = data.get("price_overview")
+    if price_overview:
+        result["price"] = price_overview.get("final_formatted", "")
+        discount = price_overview.get("discount_percent", 0)
+        if discount > 0:
+            result["discount_percent"] = discount
+    elif data.get("is_free"):
+        result["price"] = "Free"
+
+    # Reviews
+    if data.get("metacritic"):
+        result["metacritic_score"] = data["metacritic"].get("score")
+
+    # Genres
+    genres = data.get("genres", [])
+    if genres:
+        result["genres"] = [g.get("description", "") for g in genres]
+
+    # Release date
+    release = data.get("release_date", {})
+    if release:
+        result["release_date"] = release.get("date", "")
+        result["coming_soon"] = release.get("coming_soon", False)
+
+    # Platforms
+    platforms = data.get("platforms", {})
+    supported = [p for p, v in platforms.items() if v]
+    if supported:
+        result["platforms"] = supported
+
+    return result
+
+
+def format_achievement(ach: dict, global_percentages: dict | None = None) -> dict:
+    """Format a player achievement."""
+    result: dict[str, Any] = {
+        "name": ach.get("apiname", ach.get("name", "")),
+        "achieved": bool(ach.get("achieved", 0)),
+    }
+    display_name = ach.get("name")
+    if display_name and display_name != result["name"]:
+        result["display_name"] = display_name
+    description = ach.get("description")
+    if description:
+        result["description"] = description
+    unlock_time = ach.get("unlocktime", 0)
+    if unlock_time > 0:
+        result["unlocked_at"] = datetime.fromtimestamp(unlock_time, tz=UTC).isoformat()
+    if global_percentages and result["name"] in global_percentages:
+        result["global_percent"] = round(global_percentages[result["name"]], 1)
+    return result
+
+
+def format_player_summary(player: dict) -> dict:
+    """Format a Steam player summary."""
+    status_map = {
+        0: "offline",
+        1: "online",
+        2: "busy",
+        3: "away",
+        4: "snooze",
+        5: "looking to trade",
+        6: "looking to play",
+    }
+    result: dict[str, Any] = {
+        "name": player.get("personaname", ""),
+        "steamid": player.get("steamid", ""),
+        "status": status_map.get(player.get("personastate", 0), "unknown"),
+        "profile_url": player.get("profileurl", ""),
+    }
+    last_logoff = player.get("lastlogoff")
+    if last_logoff:
+        result["last_logoff"] = datetime.fromtimestamp(last_logoff, tz=UTC).isoformat()
+    game_name = player.get("gameextrainfo")
+    if game_name:
+        result["currently_playing"] = game_name
+    return result
+
+
+def format_news_item(item: dict) -> dict:
+    """Format a Steam news item."""
+    contents = item.get("contents", "")
+    # Truncate long content for LLM consumption
+    if len(contents) > 500:
+        contents = contents[:500] + "..."
+    result: dict[str, Any] = {
+        "title": item.get("title", ""),
+        "author": item.get("author", ""),
+        "contents": contents,
+        "url": item.get("url", ""),
+    }
+    date = item.get("date")
+    if date:
+        result["date"] = datetime.fromtimestamp(date, tz=UTC).isoformat()
+    return result
+
+
+def format_wishlist_item(appid: str, item: dict) -> dict:
+    """Format a wishlist item."""
+    result: dict[str, Any] = {
+        "name": item.get("name", "Unknown"),
+        "appid": int(appid),
+        "priority": item.get("priority", 0),
+    }
+    subs = item.get("subs", [])
+    if subs:
+        for sub in subs:
+            if "price" in sub:
+                # Price is in cents
+                price_cents = sub["price"]
+                result["price"] = f"${price_cents / 100:.2f}"
+                discount = sub.get("discount_pct", 0)
+                if discount > 0:
+                    result["discount_percent"] = discount
+                break
+    added = item.get("added")
+    if added:
+        result["added_at"] = datetime.fromtimestamp(added, tz=UTC).isoformat()
+    return result
+
+
+def format_friend(friend: dict) -> dict:
+    """Format a friend entry."""
+    result: dict[str, Any] = {
+        "steamid": friend.get("steamid", ""),
+        "relationship": friend.get("relationship", ""),
+    }
+    friends_since = friend.get("friend_since", 0)
+    if friends_since > 0:
+        result["friends_since"] = datetime.fromtimestamp(
+            friends_since, tz=UTC
+        ).isoformat()
+    return result
+
+
+def format_featured_game(game: dict) -> dict:
+    """Format a featured/sale game."""
+    result: dict[str, Any] = {
+        "name": game.get("name", "Unknown"),
+        "appid": game.get("id"),
+        "discounted": game.get("discounted", False),
+    }
+    if game.get("discounted"):
+        result["discount_percent"] = game.get("discount_percent", 0)
+        final_price = game.get("final_price", 0)
+        result["price"] = f"${final_price / 100:.2f}"
+        original_price = game.get("original_price", 0)
+        if original_price:
+            result["original_price"] = f"${original_price / 100:.2f}"
+    else:
+        final_price = game.get("final_price", 0)
+        if final_price > 0:
+            result["price"] = f"${final_price / 100:.2f}"
+        elif game.get("free"):
+            result["price"] = "Free"
+    return result

mcp_steam-0.1.2/src/steam_mcp/server.py

@@ -0,0 +1,220 @@
+"""MCP server with Steam tools for gaming library, achievements, and store search."""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import SteamClient, SteamError
+
+mcp = FastMCP("mcp-steam")
+
+_client: SteamClient | None = None
+
+
+def _get_client() -> SteamClient:
+    global _client
+    if _client is None:
+        _client = SteamClient()
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Library
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_owned_games(sort_by: str = "playtime", limit: int = 50) -> str:
+    """Get your Steam game library with playtime stats.
+
+    sort_by options: "playtime" (default, most played first),
+    "recent" (most recently played first), "name" (alphabetical).
+
+    Returns game names, app IDs, and total/recent playtime.
+    """
+    try:
+        results = _get_client().get_owned_games(sort_by, limit)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_recently_played(limit: int = 10) -> str:
+    """Get your recently played Steam games (last 2 weeks).
+
+    Returns game names, app IDs, and playtime for the period.
+    """
+    try:
+        results = _get_client().get_recently_played(limit)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Game Info
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_game_details(app_id: str) -> str:
+    """Get detailed store information for a Steam game.
+
+    Returns name, description, price, genres, platforms, metacritic
+    score, and release date. Use the app_id from library or search results.
+    """
+    try:
+        result = _get_client().get_game_details(app_id)
+        return json.dumps(result, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def search_games(query: str, limit: int = 10) -> str:
+    """Search the Steam store for games.
+
+    Returns game names, app IDs, prices, and supported platforms.
+    """
+    try:
+        results = _get_client().search_games(query, limit)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Achievements & Stats
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_achievements(app_id: str) -> str:
+    """Get your achievement progress for a Steam game.
+
+    Returns each achievement's unlock status, description, unlock time,
+    and how rare it is globally. Includes unlocked/total summary.
+    """
+    try:
+        result = _get_client().get_achievements(app_id)
+        return json.dumps(result, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_player_stats(app_id: str) -> str:
+    """Get your gameplay statistics for a Steam game.
+
+    Returns game-specific stats like kills, deaths, time played, etc.
+    Not all games provide stats.
+    """
+    try:
+        result = _get_client().get_player_stats(app_id)
+        return json.dumps(result, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_global_achievement_stats(app_id: str) -> str:
+    """Get global achievement unlock percentages for a Steam game.
+
+    Shows how rare each achievement is across all players. Useful for
+    identifying the hardest or rarest achievements.
+    """
+    try:
+        results = _get_client().get_global_achievement_stats(app_id)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Wishlist
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_wishlist(limit: int = 50) -> str:
+    """Get your Steam wishlist.
+
+    Returns wishlisted games sorted by priority, with prices and
+    current discounts if available.
+    """
+    try:
+        results = _get_client().get_wishlist(limit)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# News
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_game_news(app_id: str, count: int = 5) -> str:
+    """Get recent news and updates for a Steam game.
+
+    Returns news titles, authors, dates, summaries, and URLs.
+    """
+    try:
+        results = _get_client().get_game_news(app_id, count)
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Profile
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_player_summary() -> str:
+    """Get your Steam profile summary.
+
+    Returns display name, online status, profile URL, and currently
+    playing game (if any).
+    """
+    try:
+        result = _get_client().get_player_summary()
+        return json.dumps(result, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_friend_list() -> str:
+    """Get your Steam friends list.
+
+    Returns friend Steam IDs, relationship status, and when you
+    became friends.
+    """
+    try:
+        results = _get_client().get_friend_list()
+        return json.dumps(results, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Featured
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_featured_games() -> str:
+    """Get currently featured and on-sale games on Steam.
+
+    Returns featured games split into on-sale (with discounts and prices)
+    and regular featured titles.
+    """
+    try:
+        result = _get_client().get_featured_games()
+        return json.dumps(result, indent=2)
+    except (SteamError, ValueError) as e:
+        return f"Error: {e}"

mcp_steam-0.1.2/src/steam_mcp/validation.py

@@ -0,0 +1,32 @@
+"""Input validation helpers for Steam app IDs and pagination parameters."""
+
+
+def validate_app_id(value: str | int) -> int:
+    """Validate and convert a Steam app ID to int."""
+    if isinstance(value, int):
+        if value <= 0:
+            raise ValueError(f"Invalid app ID: {value}. Must be positive.")
+        return value
+    value_str = str(value).strip()
+    if not value_str.isdigit():
+        raise ValueError(f"Invalid app ID: '{value_str}'. Expected a numeric value.")
+    result = int(value_str)
+    if result <= 0:
+        raise ValueError(f"Invalid app ID: {result}. Must be positive.")
+    return result
+
+
+def validate_limit(value: int, max_val: int = 50) -> int:
+    """Clamp a limit parameter to the range [1, max_val]."""
+    return max(1, min(value, max_val))
+
+
+def format_playtime(minutes: int) -> str:
+    """Convert playtime in minutes to a human-readable string."""
+    if minutes < 60:
+        return f"{minutes}m"
+    hours = minutes // 60
+    remaining = minutes % 60
+    if remaining == 0:
+        return f"{hours}h"
+    return f"{hours}h {remaining}m"