mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-11 18:13:49 +01:00
Krzysztof kuhy Rudnicki
1faf211767
The budget tab answered "how much did I play" but not "what did I play":
playtime_state.json and playtime_history.json each stored one aggregate
seconds figure per gaming day, so the 14-day chart was a row of featureless
bars. Separately, qualifying_pids had exactly two sources — the SteamAppId
env var and a hardcoded 16-launcher frozenset — so osu!lazer, which sets no
SteamAppId and matches no launcher name, was never billed at all.
qualifying_pids now returns pid -> attribution key instead of a bare pid set.
The app id was already in hand and thrown away on its first line; it now
survives into PlaytimeState.per_game, alongside a user-editable
counted_processes list in config.json seeded with osu!lazer.
Two things the parts/whole relationship forces:
- per_game only ever sums to AT MOST seconds, never equals it. backdate
refunds the idle grace on every engaged-to-paused edge, and
_state_or_recover synthesises a full budget with no breakdown. The
refund is debited from last_credited_key, and the remainder is rendered
as "Unattributed" rather than stored — one path then covers legacy days,
focus-probe failures and drift alike.
- counted_processes is kept apart from LAUNCHER_PROCESS_NAMES. That
frozenset is also the total-block kill list, and it routes through
kill_and_uninstall_launchers, which pacman -R's the owning package.
Counted entries are killed on total block, never uninstalled.
Both storage formats stay at schema 1: load_state already filters to
dataclass fields, so a record without per_game migrates for free, and the
history reader has to accept both a bare float and an object regardless, so
a version bump would distinguish nothing.
Chart segments use the shared design system's categorical ramp (--cat-1..6),
capped at six games plus "Other" because a seventh distinguishable hue does
not exist under simulated CVD. The red over-budget fill is gone: colour now
encodes which game, and the dashed budget line alone says over or under.
Snapshot persistence moves to _snapshot.py to keep config.py under the
250-line cap. Three modules bound config paths at import time, which
bypasses the conftest redirect — they now reach them through the module.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MKFzwzwRU1JD7SFLHtQBsz
84 lines
3.3 KiB
Python
84 lines
3.3 KiB
Python
"""MCP (Model Context Protocol) server for Steam Backlog Enforcer.
|
|
|
|
Exposes the enforcer's read surface and two *gated* write actions as typed MCP
|
|
tools, so an MCP client (Claude Code and its subagents) can query and — with
|
|
explicit confirmation — drive the backlog without shelling out to the CLI.
|
|
|
|
Run via the dedicated venv that has the ``mcp`` extra installed::
|
|
|
|
~/.venvs/steam-backlog-mcp/bin/python -m steam_backlog_enforcer._mcp
|
|
|
|
(see ``scripts/setup_mcp.sh`` and the repo-root ``.mcp.json``).
|
|
|
|
Safety invariants (do not break when adding tools):
|
|
* **stdout is the JSON-RPC channel.** This module and every function a tool
|
|
calls must never write to stdout. All logging is routed to STDERR below, and
|
|
tools call only stdout-free leaf helpers (never the ``cmd_*`` handlers, which
|
|
``_echo`` to stdout / ``input()`` / ``sys.exit()``).
|
|
* **No secret ever leaves.** There is no tool that returns ``Config`` or reads
|
|
``config.json``; read tools load only ``State`` and the secrets-free web
|
|
dataset. Game-name lookups use the on-disk snapshot only (no Steam API key).
|
|
* **Writes are gated.** Every write tool defaults to a dry-run preview and
|
|
mutates only when ``confirm=True``. These write tools must never be added to
|
|
a permission allowlist (a subagent could then bypass the human).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import sys
|
|
from typing import TYPE_CHECKING
|
|
|
|
from mcp.server import MCPServer
|
|
|
|
from steam_backlog_enforcer._snapshot import load_snapshot
|
|
|
|
if TYPE_CHECKING:
|
|
from steam_backlog_enforcer.steam_api import GameInfo
|
|
|
|
# Log to STDERR only — STDOUT carries the MCP JSON-RPC protocol frames, so a
|
|
# single stray stdout write would corrupt the stream and kill the session.
|
|
logging.basicConfig(
|
|
level=logging.INFO,
|
|
stream=sys.stderr,
|
|
format="%(asctime)s [%(levelname)s] steam-mcp: %(message)s",
|
|
)
|
|
logger = logging.getLogger(__name__)
|
|
|
|
mcp = MCPServer("steam-backlog-enforcer")
|
|
|
|
_DEFAULT_LIST_LIMIT = 50
|
|
|
|
|
|
def _resolve_game_name(app_id: int) -> str | None:
|
|
"""Resolve a game name from the on-disk snapshot only (no Config / API).
|
|
|
|
Deliberately snapshot-only: it never constructs ``Config`` and never touches
|
|
the Steam API key, so it is safe to call from an MCP tool. A game absent from
|
|
the last snapshot simply resolves to ``None``.
|
|
|
|
Args:
|
|
app_id: The Steam app id to look up.
|
|
|
|
Returns:
|
|
The game name, or ``None`` if not present in the snapshot.
|
|
"""
|
|
snapshot = load_snapshot()
|
|
if snapshot:
|
|
for entry in snapshot:
|
|
if entry.get("app_id") == app_id:
|
|
return str(entry["name"])
|
|
return None
|
|
|
|
|
|
def _backlog_sort_key(game: GameInfo) -> tuple[int, float]:
|
|
"""Sort incomplete games shortest-completionist-first, unknowns last."""
|
|
if game.completionist_hours > 0:
|
|
return (0, game.completionist_hours)
|
|
return (1, 0.0)
|
|
|
|
|
|
# ──────────────────────────────────────────────────────────────
|
|
# Read tools (State-only; never expose Config / the Steam API key)
|
|
# ──────────────────────────────────────────────────────────────
|