jk-mcp-ecnl

An MCP server for ECNL (Elite Clubs National League) and ECRL (ECNL Regional League) youth soccer — schedules, standings, and RPI for both boys and girls — backed by the public Total Global Sports / AthleteOne API that powers theecnl.com.

Built as a sibling to jk-mcp-nwsl: Python 3.13, FastMCP, httpx, hexagonal architecture.

Contents

• Features

• Data model

• Requirements

• Quickstart

• Configuration

• Tools

• Example prompts

• Development

• How it works

• License

Related MCP server: Soccer V3 Scores MCP Server

Features

• Discover ECNL/ECRL events (conferences) by league, gender, and season — no event IDs to memorize.

• Standings, schedules, results, teams, clubs, match detail, and playoff brackets for any flight.

• RPI (Rating Percentage Index) computed from extracted match results, with the WP / OWP / OOWP breakdown and a configurable tie weight.

• Read-only, idempotent tools over a public, no-auth JSON API.

Data model

league (ECNL/ECRL) × gender (boys/girls) × conference × season is one event (event_id). Within an event, divisions are age groups, each with one or more flights; standings and schedules are keyed by flight_id. Start with find_events to turn a human description into the IDs the other tools need.

Requirements

• Python 3.13+

• uv

Quickstart

uv sync
uv run jk-mcp-ecnl          # stdio transport (default)

See docs/quickstart.md for HTTP mode and a typical tool sequence.

Claude Code / Claude Desktop

Register the server as a stdio MCP server running uv run jk-mcp-ecnl from this directory (or docker run -i --rm jk-mcp-ecnl).

Docker

uv run inv build-image            # build jk-mcp-ecnl:latest
docker run -i --rm jk-mcp-ecnl    # stdio
docker compose up                 # HTTP on :8000

Configuration

All configuration is via environment variables — see the table in docs/quickstart.md.

Tools

RPI

RPI follows the standard NCAA structure used by the women's-soccer RPI reference:

RPI = 0.25·WP + 0.50·OWP + 0.25·OOWP

WP = (W + tie_weight·T) / (W + L + T) with tie_weight defaulting to 1/3 (the 2024 convention; pass 0.5 for pre-2024). OWP and OOWP score ties at 1/2 and exclude the rated team from each opponent's record. Note: within a single conference (typically a complete round-robin) OWP/OOWP converge to ~0.5, so RPI ≈ WP there — RPI's discriminating power comes from cross-conference pools, a planned future enhancement (see the ADR).

Example prompts

Once the server is connected, ask Claude natural-language questions — it chains the tools for you (typically find_events → get_event_overview → get_standings/get_schedule/get_rpi), resolving the event, division, and flight IDs along the way. You never supply IDs yourself. Age groups map to birth-year divisions (e.g. "U17" ≈ the G2008/2007 division).

Discovering events

• "What ECNL girls conferences are there this season?"

• "List the ECRL boys events for 2025-26."

• "Is there an ECNL boys conference in Northern California?"

Standings

• "Show me the ECNL Girls Southwest U17 standings."

• "Who's top of the table in ECNL Boys Northern Cal U16?"

• "How many points separate the top three teams in ECRL Girls Carolinas?"

Schedules & results

• "What's the schedule for the ECNL Girls Southeast U15 flight?"

• "What were last weekend's scores in ECNL Boys Texas U17?"

• "When does Slammers FC HB Koge play next?"

• "Give me Beach FC's results so far this season."

Teams & clubs

• "Which clubs are competing in the ECNL Girls Southwest event?"

• "List the teams in the ECNL Boys Northern Cal U16 flight."

RPI analysis

• "Rank the ECNL Girls Southwest U17 flight by RPI."

• "What's Slammers FC's RPI, broken down into WP, OWP, and OOWP?"

• "Recompute that flight's RPI using the pre-2024 ½ tie weight."

• "In ECRL Boys Carolinas, which team has the strongest opponents (highest OWP)?"

Playoffs

• "Is there a playoff bracket for the ECNL Girls Southwest U19 flight?"

Development

uv run inv lint              # ruff check + format check
uv run inv check-complexity  # cyclomatic complexity gate (max 7)
uv run inv coverage          # pytest + coverage (min 90%)

How it works

Hexagonal architecture — the dependency graph flows inward:

adapters/inbound (FastMCP tools, formatters)
        │
   application (ECNLService, RPI engine)
        │
      ports (ECNLAPIPort, DiscoveryPort)
        │
     domain (models, classification, exceptions)
        ▲
adapters/outbound (AthleteOneAdapter, retry, cache, discovery)

The data source, its quirks, and how event discovery works are documented in docs/decisions/0001-data-source-athleteone-api.md.

License

See LICENSE.