jk-mcp-usls

MCP server that gives Claude live access to USL Super League data — teams, matches, standings, rosters, and schedule-strength analytics — via the ESPN public API.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
• Configuration
• Claude Code
• Claude Desktop
• Docker
• Development
• Contributing
• License

---

Overview

AI assistants like Claude are knowledgeable, but they have a hard cutoff date — they cannot tell you today's USL Super League standings, last night's scores, or which teams are currently in a playoff position. This project fixes that.

It is an MCP server — a plugin that gives Claude direct access to live USL Super League data: scores, standings, rosters, and derived schedule-strength analytics. Once installed, you can ask Claude natural-language questions about the USL Super League and get accurate, up-to-date answers. No subscription, no API key, and no programming required to use it.

This is the v1 scaffold — it wraps the ESPN public API only. The league's own site (gainbridgesuperleague.com) exposes match data only through a licensed Opta widget embed, so ESPN is the only clean JSON source. Cup competitions and richer stats are on the roadmap if a stable second-tier feed becomes available.

---

Features

The v1 surface is eleven read-only, idempotent tools split across two tiers.

ESPN-backed (8)

Tool	Description
get_teams	List all 8 USL Super League clubs with IDs and abbreviations
get_team	Details for a specific team
get_roster	Team's active roster — jersey, position, age, citizenship
get_scoreboard	Match scores for a single day, a date range, or the current matchweek
get_team_schedule	Every match for a team in the current season — past + upcoming
get_match_details	One match's full details — score, venue, attendance, goals, cards, subs
get_standings	Current standings — single 8-team table ordered by points
get_news	Recent USL Super League news articles

Derived analytics (3)

Pure functions over live standings + team schedules, exposing schedule-strength context the raw table does not.

Tool	Description
get_strength_of_schedule	Team's average opponent points-per-game across matches already played
get_results_by_opponent_tier	Team's W-L-T split across current top / middle / bottom standings tiers
get_adjusted_points_per_game	Team's raw PPG alongside an opponent-quality-adjusted PPG

Roadmap

Deferred to v2+:

• Player leaderboards and team season aggregates if a stable USL SL Opta feed becomes accessible (today the league's Opta widget is subscription-gated)
• Press-release feed from gainbridgesuperleague.com/wp-json/wp/v2/sec_news
• Playoff bracket rendering
• Related women's competitions the league may add (Concacaf W Champions Cup, USL Cup)

---

Requirements

• Python 3.13+
• uv

---

Installation

git clone https://github.com/jedi-knights/jk-mcp-usls.git
cd jk-mcp-usls
uv sync

---

Usage

Run the server in stdio mode (the default — used by Claude Code and Claude Desktop):

uv run python -m usls.server

Run in HTTP mode (for networked or deployed access):

MCP_TRANSPORT=streamable-http uv run python -m usls.server

Example prompts

Standings, scores, rosters:

• Who is leading the USL Super League right now?
• Show me every USL Super League result from this past weekend.
• Who is on Brooklyn FC's roster?
• When does Carolina Ascent play next?

Schedule strength:

• Which USL Super League team has played the toughest schedule so far?
• Show me Brooklyn FC's record against the current top 3 teams.
• Compare Carolina Ascent and DC Power on adjusted points-per-game.

---

Configuration

All configuration is via environment variables. None are required for local use.

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport mode: stdio or streamable-http
HOST	0.0.0.0	Bind address (HTTP transport only)
PORT	8000	TCP port (HTTP transport only)
MCP_PATH	/mcp/usls	URL path (HTTP transport only)
API_HOST	https://site.api.espn.com	ESPN API base URL
LOG_LEVEL	INFO	DEBUG, INFO, WARNING, or ERROR
MCP_TRACING_ENABLED	unset	Bootstrap the OpenTelemetry SDK
MCP_AUTH_ENABLED	unset	Require RS256 bearer tokens on streamable-http
MCP_AUTH_ISSUER_URL	unset	Auth-server origin (required when auth is on)
MCP_AUTH_RESOURCE_URL	unset	This server's public URL for the aud claim

---

Claude Code

Install from your local clone globally so the server is available in every project:

claude mcp add --scope user usls -- uv run --directory /path/to/jk-mcp-usls python -m usls.server

Replace /path/to/jk-mcp-usls with the absolute path to your clone. Verify with claude mcp list.

Drop --scope user to register only for the current project, or commit a .mcp.json to the repo root for collaborators:

{
  "mcpServers": {
    "usls": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jk-mcp-usls", "python", "-m", "usls.server"]
    }
  }
}

---

Claude Desktop

Add the following to your Claude Desktop configuration file.

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "usls": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jk-mcp-usls",
        "python", "-m", "usls.server"
      ]
    }
  }
}

If uv is not on Claude Desktop's PATH, use the absolute path (which uv will show it). Fully quit and relaunch Claude Desktop after saving — a window close is not enough.

---

Docker

Build the image:

docker build -t jk-mcp-usls:latest .

Run in stdio mode (for MCP clients that spawn a subprocess):

docker run -i --rm jk-mcp-usls:latest

Run in HTTP mode:

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  jk-mcp-usls:latest

---

Development

Install

uv sync

Invoke tasks

All common workflows are invoke tasks. Run uv run inv --list to see everything.

Task	Alias	Description
uv run inv lint	inv l	Run ruff linter and format check
uv run inv lint --fix	inv l --fix	Auto-fix lint violations and reformat
uv run inv test	inv t	Run the full test suite
uv run inv coverage	inv v	Run tests with coverage report (threshold: 90%)
uv run inv check-complexity	inv cc	Check cyclomatic complexity (max 7)
uv run inv build	inv b	Build wheel and sdist into dist/
uv run inv build-image	inv bi	Build the Docker image
uv run inv clean	inv c	Remove build and coverage artifacts

Project structure

src/usls/
├── server.py                     # entry point, transport selection, logging setup
├── adapters/
│   ├── inbound/
│   │   ├── mcp_adapter.py        # FastMCP server, health endpoints, tool registration
│   │   ├── formatters.py         # domain → LLM-readable text
│   │   ├── authorization.py      # inbound authz port implementations
│   │   └── tools/
│   │       ├── espn.py           # 8 ESPN-backed tools
│   │       └── analytics.py      # 3 schedule-strength analytics tools
│   └── outbound/
│       ├── espn_adapter.py       # ESPN HTTP client
│       ├── parsers.py            # ESPN JSON → domain models
│       ├── retry_adapter.py      # transient-failure retry decorator
│       └── caching_adapter.py    # in-process TTL cache
├── application/
│   ├── service.py                # USLSService — use cases, orchestration
│   ├── _helpers.py               # input validation
│   └── _analytics_helpers.py     # pure math for schedule-strength tools
├── domain/
│   ├── models.py                 # Team, Match, Standing, etc.
│   └── exceptions.py             # USLSNotFoundError, UpstreamAPIError
├── ports/
│   ├── inbound.py                # Authorizer protocol
│   └── outbound.py               # USLSAPIPort protocol
├── observability/                # OpenTelemetry bootstrap (opt-in)
└── security/                     # JWKS token verifier

The dependency direction flows inward: adapters → ports → domain. Nothing in domain/ imports from adapters or a framework.

---

Contributing

1. Fork the repository and clone your fork
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes following the existing patterns (hexagonal architecture, TDD, conventional commits)
4. Verify the full check suite passes: uv run inv lint && uv run inv check-complexity && uv run inv coverage
5. Open a pull request against main

All CI checks (lint, complexity, tests, coverage ≥ 90%) must pass before merge.

---

License

MIT — see LICENSE.