jk-mcp-wsl

MCP server that gives Claude live access to Women's Super League (England) 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: jk-mcp-usls

Overview

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

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

The Women's Super League is the top flight of English women's football. In 2024 it was spun out of The FA into its own independent operating company (WSL Football Ltd), running the WSL and WSL 2 as a fully professional 14-team pyramid. This server wraps the ESPN public JSON feed, which is the cleanest freely-accessible source for the league. Rich per-player and team-season stats — historically served via api-sdp.wslfootball.com — are deferred to v2 pending discovery of the correct stats/players category enum.

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, team season stats, and per-player heatmaps via the league's own SDP tier (api-sdp.wslfootball.com/stats/players) — the category enum required to hit the endpoint has not been discovered from public traffic yet

• FA Cup and Continental Cup fixtures

• Playoff / relegation bracket rendering

• Related competitions (UEFA Women's Champions League match-day fixtures for WSL clubs)

Requirements

• Python 3.13+

• uv

Installation

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

Usage

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

uv run python -m wsl.server

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

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

Example prompts

Standings, scores, rosters:

• Who is leading the WSL right now?

• Show me every WSL result from this past weekend.

• Who is on Arsenal's roster?

• When does Aston Villa play next?

Schedule strength:

• Which WSL side has played the toughest schedule so far?

• Show me Manchester United's record against the current top 3 clubs.

• Compare Chelsea and Manchester City 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 wsl -- uv run --directory /path/to/jk-mcp-wsl python -m wsl.server

Replace /path/to/jk-mcp-wsl 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": {
    "wsl": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jk-mcp-wsl", "python", "-m", "wsl.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": {
    "wsl": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jk-mcp-wsl",
        "python", "-m", "wsl.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-wsl:latest .

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

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

Run in HTTP mode:

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

Development

Install

uv sync

Invoke tasks

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

Project structure

src/wsl/
├── 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                # WSLService — 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             # WSLNotFoundError, UpstreamAPIError
├── ports/
│   ├── inbound.py                # Authorizer protocol
│   └── outbound.py               # WSLAPIPort 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.