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

Related MCP server: sports-pulse-mcp

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)

Derived analytics (3)

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

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.

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.

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.