# eliteprospects

Unofficial access to [eliteprospects.com](https://www.eliteprospects.com) hockey
data — leagues, teams, players, and staff — as structured output rather than
scraped HTML.

It comes in two forms backed by the same TypeScript core: a **command-line
tool** for browsing and searching from the terminal (with `--json` for piping
into other tools), and an **MCP server** that exposes the same lookups to MCP
clients such as Claude. No API key and no build step.

## Requirements

- [Bun](https://bun.sh) >= 1.0 (runs TypeScript natively — no build step)

## Usage

```bash
# List all leagues
./bin/eliteprospects leagues

# Filter by country — accepts a 2- or 3-letter code (DK or DNK)
./bin/eliteprospects leagues --country DK

# Machine-readable output
./bin/eliteprospects leagues --json

# Show a single league: metadata, teams, and available seasons
./bin/eliteprospects leagues denmark-u18

# A specific season
./bin/eliteprospects leagues denmark-u18 --season 2024-2025

# Show a team by id: metadata, roster, and available seasons
./bin/eliteprospects teams 42107
./bin/eliteprospects teams 42107 --season 2024-2025

# Show a player's profile by id (bio, draft, current team)
./bin/eliteprospects players 8862

# Look a player up by name instead of id (renders only on a single match)
./bin/eliteprospects players --search "connor mcdavid"

# Show a staff member's profile by id (role, current team)
./bin/eliteprospects staff 14739

# Staff can be looked up by name too
./bin/eliteprospects staff --search "daniel rasmussen"

# Search by name (across players, staff, teams, leagues)
./bin/eliteprospects search "connor mcdavid"

# Limit search to one type (--player, --staff, --team, --league)
./bin/eliteprospects search rasmussen --staff

# Help
./bin/eliteprospects help
```

`search` is the way to find an id to feed into the other commands. It returns a
`TYPE` column so a result's id can be used with `players`, `staff`, `teams`, or
`leagues` as appropriate. For the common case of looking up one person,
`players`/`staff` also accept `--search <name>`, which runs the search for you
and renders the profile when there is exactly one match (erroring, and listing
the candidates, when there are several).

Players and staff are separate commands because they are separate id namespaces:
player `14739` and staff `14739` are different people. A person can hold both a
player and a staff profile (e.g. Daniel Rasmussen is player `16271` and staff
`14739`), and each profile links to the other in its output.

## MCP server

The same functionality is exposed to MCP clients (e.g. Claude) by
[bin/eliteprospects-mcp](bin/eliteprospects-mcp), a Model Context Protocol server
speaking JSON-RPC 2.0 over stdio. It is dependency-free — the protocol is
implemented directly in [src/mcp.ts](src/mcp.ts).

Tools:

| Tool | Arguments | Description |
|------|-----------|-------------|
| `search` | `query`, `type?` | Search players, staff, teams, leagues by name |
| `list_leagues` | `country?` | List leagues, optionally filtered by country code |
| `get_league` | `slug`, `season?` | League metadata, teams, seasons |
| `get_team` | `id`, `season?` | Team metadata and roster |
| `get_player` | `id` | Player profile |
| `get_staff` | `id` | Staff profile |

Register it with an MCP client by pointing at the launcher, e.g. in a
`mcpServers` config:

```json
{
  "mcpServers": {
    "eliteprospects": {
      "command": "bun",
      "args": ["/absolute/path/to/eliteprospects/bin/eliteprospects-mcp"]
    }
  }
}
```

See also: [https://coworkerai.io/guide/mcp-setup](https://coworkerai.io/guide/mcp-setup)

## How it works

EliteProspects is a Next.js site. Two data sources are used, both structured
JSON rather than scraped HTML:

- **Index pages** (e.g. `/leagues`) embed their data in a
  `<script id="__NEXT_DATA__">` tag. See [src/leagues.ts](src/leagues.ts).
- **Detail pages** (e.g. `/league/<slug>`) sit behind a Cloudflare challenge in
  their rendered form, so we instead fetch Next.js's data endpoint
  `/_next/data/<buildId>/<route>.json`, which returns the same `pageProps` and
  is not challenged. The `buildId` changes per deploy, so it is read at runtime
  from the reachable `/leagues` page and cached. See
  [src/client.ts](src/client.ts) and [src/league.ts](src/league.ts).

Search uses a different backend entirely: the site's autocomplete API at
`autocomplete.eliteprospects.com` (the same one the site's search box uses). It
is a separate, unauthenticated host — not behind the Cloudflare challenge, and
not subject to the member limits of the on-site search form. The `/all` endpoint
returns mixed types (each tagged with `_type`); `/players`, `/staff`, `/teams`,
and `/leagues` each return a single type. See [src/search.ts](src/search.ts).

Team, player, and staff URLs carry both an id and a slug
(`/team/42107/aalborg-u18`, `/player/8862/joe-sakic`,
`/staff/14739/daniel-rasmussen`). A request for the id alone soft-redirects to
the canonical path, which the scraper follows to learn the slug — so `teams`,
`players`, and `staff` work from just the numeric id. This id→slug resolution
lives in `fetchEntityData` ([src/client.ts](src/client.ts)) and is shared by
[src/team.ts](src/team.ts) and [src/profile.ts](src/profile.ts).

## Country codes

EliteProspects identifies countries with ISO 3166-1 **alpha-3** codes (`DNK`).
The output and `--country` filter use the more universal **alpha-2** form
(`DK`); both forms are accepted as input. The two UK home nations EP lists
separately — England and Scotland — are not ISO countries and have no alpha-2,
so they keep the ISO 3166-2 subdivision codes `GB-ENG` / `GB-SCT` (distinct from
`GB` = U.K.). The mapping is an embedded, verified ISO table — see
[src/countries.ts](src/countries.ts).

## Project layout

- [bin/eliteprospects](bin/eliteprospects) — CLI launcher
- [bin/eliteprospects-mcp](bin/eliteprospects-mcp) — MCP server launcher
- [src/cli.ts](src/cli.ts) — command parsing and output formatting
- [src/mcp.ts](src/mcp.ts) — MCP (Model Context Protocol) server
- [src/client.ts](src/client.ts) — HTTP fetching (HTML + Next.js data endpoint)
- [src/nextData.ts](src/nextData.ts) — `__NEXT_DATA__` extraction
- [src/leagues.ts](src/leagues.ts) — leagues-list parser
- [src/league.ts](src/league.ts) — single-league parser
- [src/team.ts](src/team.ts) — single-team parser (metadata + roster)
- [src/profile.ts](src/profile.ts) — player and staff profile parsers
- [src/search.ts](src/search.ts) — autocomplete search
- [src/countries.ts](src/countries.ts) — ISO alpha-3 ↔ alpha-2 conversion
- [src/types.ts](src/types.ts) — shared types

## Development

```bash
bun install     # install dev dependencies (TypeScript, @types/bun)
bun run typecheck
```