Hockey Card Analyst

Turn an advanced hockey card into plain language you can say out loud and defend.

Hockey Card Analyst is a translator between advanced metrics and normal hockey conversation. It reads one analytics model's card for a player and tells you, in words, what the numbers actually say.

What it's for

Advanced player cards pack a lot into a small grid: a dozen percentiles, a couple of trend lines, and a headline number. The data is there, but reading it well means knowing the model underneath. What's repeatable versus lucky, what's a real skill versus an artifact of how a player is deployed, why a 95th percentile isn't the same as a 99th, why a defenseman's finishing doesn't count toward his value the way a forward's does. Most people looking at a card don't have that model in their head, so the numbers get half-read or misread.

This tool does the reading. Some of what it's useful for, drawn from real use:

• Settling a claim. Someone says "he's a one-dimensional scorer who can't defend." The tool checks each part against the numbers and tells you which holds, which doesn't, and what the card can't answer.

• Pressure-testing a hot take. A scorer has a big year and everyone assumes he's due to regress. The tool can show whether the goals rest on repeatable play-driving or on finishing that tends to cool, and it works the other way too: a player whose scoring is quietly understated.

• Building a case for a player. If you're writing or arguing about how good someone actually is, it turns a wall of percentiles into a plain-language thesis you can stand behind, with every point traceable to a number.

• Reading a young breakout honestly. The card is a three-year weighted average, so a 20-year-old's number rests on a short sample. The tool flags how far to trust it rather than treating the percentile as settled.

• Understanding the metrics themselves. Ask what a stat measures and the one catch that keeps you from misreading it, without needing a verdict on a player.

It reads one analytics model's card and interprets it. It doesn't declare anyone good or bad in some absolute sense, and it only tells you what the numbers on the card support.

Related MCP server: NHL MCP Server

What you can ask it

• A claim gets made about a player ("he's just a net-front guy, can't do more than that") and you want to know whether the data agrees.

• You have an eye-test read and want to see if the metrics confirm it or complicate it.

• A trade gets floated and you want an honest answer to "is X an upgrade on Y."

• A young player breaks out and you want to know how far to trust it ("he's only 20 — is this real, or too early to bank on?"). The card is a three-year weighted average, so a young number rests on a short, recent sample: the upside and the uncertainty are both bigger than the single percentile lets on.

• A scorer's goal total looks unsustainable ("is he due to regress?") and you want to know whether the scoring rests on repeatable play-driving or leans on hot finishing that tends to cool.

• The flip side ("is he actually better than his goals say?"): a player who drives play but hasn't been finishing may have scoring that's understated — a positive-regression candidate rather than a fluke.

• You hit a metric you don't know ("what does EV defense actually measure, and what's the catch?") and you want a plain-language definition plus the one caveat that keeps you from misreading it — for the metric itself, not a verdict on a player.

Why you can trust it

Every answer traces back to a number on the card. It tells you when a claim is half-right, and which half. It admits what the card cannot see instead of bluffing. It takes the noise out and leaves something you can explain to someone else and stand behind.

It interprets one model's read of a player. It does not declare anyone good or bad in some absolute sense.

The reading rules are also anchored in the model author's own published methodology write-ups — how the WAR model is built, how the expected-goals model was rebuilt, and how the impact numbers adjust for context. That's where the tool learned that replacement level sits near the 37th percentile (so a projection at or below it reads as replacement-level, not merely "below average"), that the power play is the model's noisiest read on both sides of the puck, that a forward's defensive impact is the less repeatable half of play-driving, and that zone starts, score state, and schedule are already adjusted for before the card is printed. These anchors sharpen the wording and the caveats; they never move a verdict.

How it works, under the hood

This is a local MCP server. The model you are talking to (the LLM) reads the card image and handles the language. The server does the deterministic part: it maps each percentile to a tier, grades claims against the numbers, compares two players within the same position pool, attaches the methodology caveats, and decides what the card cannot answer. The reading rules live in config/interpretation.yaml and the metric definitions in config/glossary.yaml, not in the model's memory, so the answers stay consistent. Because the verdict is deterministic, the same card values produce identical analysis on any host; what varies between hosts is how well each model reads the card image and routes the numbers through the tools. It works for forwards, defensemen, and goalies.

Five tools, thin wrappers over the engine:

• assess_player(card, micro_card, edge_card, stat_card): overall tier, strengths and weaknesses, deployment, trajectory, caveats, a one-line summary. Takes a standard card, a microstat card, or a Game Score statcard (see below); given a player's standard card plus a micro card, an NHL Edge page, or a statcard, it adds articulation-only synthesis and vetting layers.

• adjudicate_claim(card, assertions): grades each claim supported / partial / not_supported / unverifiable, with the cited number.

• compare_players(card_a, card_b, focus): component by component, an overall edge or an honest split, and a durability flag.

• explain_metric(metric): a plain-language definition of any card metric (skater, goalie, or microstat), plus its single most important interpretive caveat. It defines a metric in the abstract; it does not reason about a specific player.

• render_report(kind, result, title): turns the answer you just got into a downloadable, styled PDF report (see below).

Microstat ($10-tier) cards

The higher-tier subscription card — the dark card with a WAR row on top and three columns of AllThreeZones tracked data — is supported alongside the standard card, for forwards and defensemen (no goalie microstat card exists; goalies stay standard-only). It is a different data regime: one season of 5v5 per-60 percentiles rather than the standard card's three-year-weighted projection, no Proj. WAR headline, and no deployment context. The tools honor that regime rather than papering over it:

• Style claims become checkable. "He's a rush player", "great skater", "physical", "relentless forechecker", "high motor", "net-front presence" — unverifiable on a standard card — are graded against the tracked numbers when a micro card is supplied, with the receipt cited. Playmaker claims grade on the passing process (dangerous passes thrown), not just assist outcomes. Style reads (hits, skating speed, forechecking) are never treated as value weaknesses; they describe how a player plays.

• Built-in profile reads. The paired reads the tracking methodology scripts — shots vs chances (perimeter volume vs selectivity), chance assists vs shot assists (dangerous passer vs point-funneler), rush vs in-zone offense, the defenseman rush-defense trio ("tight gap but gets walked" vs "soft gap protecting the slot", or dominant across the line when all three run high), and a defenseman breakout-style family (four shapes for how he moves the puck out of his own end) — come back as named profiles with the numbers attached.

• Both cards together. Supply a player's standard card and micro card in one question and the assessment adds an articulation-only synthesis: where this season ran hot or cold against the three-year projection, and where the tracked data backs (or undercuts) the WAR verdicts. The tier never moves.

• Honest seams. A micro card has no Proj. WAR, so no overall tier is invented ("is he elite?" needs the standard card), and a micro card is never compared head-to-head against a standard card — single-season tracked percentiles and a blended projection are different pools. When a claim needs a box the supplied card doesn't carry, the answer names the card type that actually carries it — and says so plainly when none does.

NHL Edge vetting (optional)

Alongside either card you can also drop in a screenshot of the player's NHL Edge page — the league's own tracking, unrelated to HockeyStats. It is strictly supplemental: Edge data is never assessed on its own and never touches the claim or comparison tools; it rides along with an assessment and vets it, adding corroborations and contradictions between the card's verdicts and the tracking. The tier, strengths, and weaknesses never move because of it — same articulation-only contract as the both-cards synthesis.

The reading rules are deliberate about what Edge numbers can and can't say:

• Rates drive the calls. Save percentages, starts over .900, and zone-time shares are judged off the raw value against the comparison average printed on the same page (with NHL's exact percentile cited when the site gives one, which it only does from the 51st up — below that it prints "<50th", and no number is ever invented for that bucket).

• Counts never do. Shots against, goals against, saves, shots on goal — anything that accumulates with games played — is workload context only. A 22-game goalie can show a 99th-percentile goals-against count at the same save percentage a 44-game goalie posts with a below-average one; the rate is the truth, so counts stay descriptive with games played named.

• Tools are style. Hardest shot, max skating speed, and miles skated are physical-tools color, never evidence of offensive value — players with near-identical tool readings sit at opposite ends of production.

• Zone time is deployment-shaped. Territorial tilt can back (or honestly contradict) an EV impact verdict, but it always carries the deployment caveat: where the puck lives with a player on the ice is not an isolated impact.

Game Score statcards (HOCKEYSTATCARDS)

A fourth card family: the HOCKEYSTATCARDS player card (models by Dom Luszczyszyn, data NaturalStatTrick), built on Game Score — a single-game productivity stat on a points-like scale — and its GSVA evolution. The card shows three rating dials (Offense / Defense / Net, in goals above or below positional average, each with a printed percentile), a per-game Game Score average, and adjusted 5v5 on-ice season totals. It is a third data regime: one season of results, not a projection, from a different analyst's model than the projection card. The tools honor all of that:

• Assessed on its own. A statcard alone gets a full assessment: the tier comes from the net-rating percentile, never the rating's sign (the distribution is right-skewed, so a slightly negative rating can sit near the middle of the pool — the card is honest about that trap), with a finishing-luck read (goals vs individual expected goals), on-ice conversion reads, and special-teams deployment where a 0.00 box means no role, never a weakness.

• Cross-model synthesis. Supply a player's projection card and statcard together and the assessment adds an articulation-only synthesis: where this season's results agree with the projection (the strongest corroboration two independent models can give) and where they diverge — a finding to surface, never an error to resolve. The tier never moves.

• Claims and comparisons. Season claims ("he ran hot", "he drives play", "no power-play role") grade against the statcard's printed numbers; statcard-vs-statcard comparisons work within a position pool, keyed on the net percentile, with an honest split when the dials disagree and a durability flag when the edge rides a hot conversion year. Statcard-vs-projection-card comparisons are refused as cross-regime.

• Goalies, reduced. Goalie statcards carry only the trustworthy boxes (net rating, Game Score average, TOI, and a direction-only goals-vs- expected read) — the sampled cards showed the other goalie boxes are buggy or unpopulated, and the engine says so rather than guessing.

PDF reports

After any assess, compare, or claim-check answer, ask for a PDF (the assistant will offer one) and you get a styled report of that exact verdict written to ~/Documents/HockeyCardReports/ — named after the player(s), the report kind, and the date. Eight report kinds: skater assessment, goalie assessment, microstat assessment, statcard assessment (skater and goalie variants), head-to-head comparison, graded claim check, and an "interpretive" kind for reads the engine has no tool for (line synergy, goalie support, free-form questions), which is prominently badged "Interpretive read · AI — not an engine verdict" so an AI read can never pass as an engine one.

Two honesty rules are enforced, not advisory: the report is rendered from the same structured result the engine just returned (a retyped or reconstructed result is rejected), and the source card image is never embedded. Rendering is fully local — an HTML template with bundled fonts, converted by WeasyPrint with no headless browser and no network. On macOS, WeasyPrint needs one system library: brew install pango.

What you need

A hockeystats.com subscription and a player card you have pulled yourself. The tool does not fetch, scrape, or store cards. It only interprets a card you supply, and the LLM reads the card image at runtime, so the server itself only ever sees the numbers.

To run the server you need Python 3.11+ (tested on 3.14).

How to run it

This is a standard MCP server that speaks over stdio, so any MCP-capable client can use it. It was built and tested with Claude Desktop on macOS. The same command works for other clients; you just put it in that client's MCP config.

1. Install (one time):

   git clone https://github.com/augforce/hockey-card-analyst.git
   cd hockey-card-analyst
   python3 -m venv .venv
   .venv/bin/python -m pip install fastmcp pydantic PyYAML

2. Register the server with your client. Every MCP client needs the same two things: the command (the venv Python) and one argument (the server script). Use absolute paths for your machine:

   • command: /absolute/path/to/hockey-card-analyst/.venv/bin/python

   • args: ["/absolute/path/to/hockey-card-analyst/src/server.py"]

   Claude Desktop (tested). Edit ~/Library/Application Support/Claude/claude_desktop_config.json (on Windows, %APPDATA%\Claude\claude_desktop_config.json) and merge:

   {
     "mcpServers": {
       "hockey-card-analyst": {
         "command": "/absolute/path/to/hockey-card-analyst/.venv/bin/python",
         "args": ["/absolute/path/to/hockey-card-analyst/src/server.py"]
       }
     }
   }

   Quit Claude Desktop fully and reopen so it reloads the config.

   Gemini CLI. Add the same block under mcpServers in your Gemini settings (~/.gemini/settings.json), then restart the CLI.

   Other stdio clients (Cursor, VS Code, Cline, Continue, the OpenAI Agents SDK, and similar). Each has its own place to register an MCP server, but the entry is the same command and args shown above.

   ChatGPT (more involved). This is a different, heavier deployment than the stdio hosts above. ChatGPT connects to a remote MCP endpoint rather than a local stdio process, so you would run this server as a public HTTP endpoint using FastMCP's HTTP transport. Two things to know going in: FastMCP's HTTP transport enables DNS-rebinding/origin protection by default, which returns 403 to every client until you configure the allowed origins and hosts; and exposing a public endpoint is a security responsibility you own. See the FastMCP HTTP transport docs (https://gofastmcp.com) for transport and security configuration. This path is not tested here.

3. Confirm the loop. Start a conversation, give the model a player card image, and ask in plain language, for example:

   Someone told me this kid is an elite two-way center already. True?

   The model should read the card, route it through the tools, and answer from the numbers: back the offense where the card supports it, push back on the two-way side if the defensive numbers do not, note how the player is deployed, and flag the trajectory.

Scope and sourcing

The tools read the card and nothing else. Every verdict traces back to a percentile on the card, so the whole answer is auditable — you can check each claim against a number you can see.

Team, roster, and contract context — trades, who's on the roster, who leads a team in scoring, recent game results — is out of scope by design. The tools don't fetch it and don't guess it (adjudicate_claim returns such claims as unverifiable). Keeping that context out is what keeps the auditable trail clean. This is the default, no-setup behavior: card-bound and honest.

Optional: let the host model add outside context

If you want the host model to pull outside context (trades, contracts, roster fit) and weave it into the answer, you can opt in with a standing instruction. Put it wherever your host keeps persistent instructions: a system prompt, the host's custom instructions, or a project. In Claude Desktop, for example, that is a Project instruction (Projects, then your project, then instructions); other hosts have their own equivalent. It lives in the host app, not in the MCP config JSON, and not in this repo. Paste this in:

When assessing hockey cards, anything the card itself can't answer (trades,
contracts, current team, roster context, recent stats) may be pulled from the
web. When you do, clearly mark which parts of the answer came from the web
rather than the card, and add a brief note that web-sourced facts should be
verified before being taken at face value. Card-derived verdicts come from the
hockey-card-analyst tools and are traceable to the numbers; web facts are
supporting context, not tool output. Keep the two visibly separate.

With this in place the model labels web-sourced facts separately from card-derived verdicts, so the audit trail stays intact: the card verdicts remain traceable to the numbers, and the outside context is clearly flagged as unverified. Web augmentation is an opt-in you configure and label yourself.

Intellectual property

This repo ships logic and rules, not HockeyStats data. You bring your own card, accessed through your own subscription; the server only interprets a card you already have. Do not scrape, cache, or redistribute HockeyStats cards or their underlying data.

Development

Run the tests:

.venv/bin/python -m pytest

The engine has no network or vision dependencies. It only transforms structured numbers, so the suite is fast and deterministic. See DECISIONS.md for the design rationale behind the reading rules.

Status

v1.1: the three analysis tools plus explain_metric and PDF reports, for forwards, defensemen, and goalies — now reading the standard card, the $10-tier microstat card (style claims, profile reads, and both-cards synthesis), NHL Edge pages (supplemental vetting), and HOCKEYSTATCARDS Game Score statcards (standalone season assessment plus cross-model synthesis), with the reading rules anchored in the models' published methodology write-ups. Served over MCP and tested end to end on Claude Desktop. See DECISIONS.md for the full build log.