# rgl-mcp

MCP server that wraps the [RGL API](https://rglgg-api.fly.dev/docs) with natural-language tools. Designed for hosting on fly.io.

## What it does

Translates queries like "every player who played IM in S7 of 6s" into the right sequence of API calls:

1. Resolves "6s" → format/region (defaults to NA when not specified).
2. Resolves "S7" → SeasonId by fuzzy-matching cached season list.
3. Resolves "IM" → DivisionId scoped to the region.
4. Fetches the corresponding Group, then its rosters.
5. Optionally bulk-fetches profile data for every unique player.

## Tools

| Tool | Purpose |
|---|---|
| `find_season` | Resolve season phrase → SeasonId |
| `get_season` | Reverse lookup: SeasonId → season/region/format metadata (inverse of `find_season`) |
| `find_region` | Resolve region phrase → RegionId |
| `find_division` | Resolve division phrase → DivisionId (scoped to a region) |
| `find_team` | Substring search on team name/tag |
| `find_player` | Substring search on player aliases |
| `get_player` | Profile by SteamID |
| `get_team` | Team data by TeamId (includes a resolved `region` block — use `region.regionId` as the `r=` value in rgl.gg URLs) |
| `get_match` | Match data by MatchId |
| `list_season_divisions` | Groups in a season |
| `list_division_teams` | Teams in a (season, division) |
| `list_division_players` | Every unique player in (season, division), optionally with full profile data |
| `list_formats` | All formats (lookup) |
| `list_regions` | All regions (lookup) |

## Local development

```bash
npm install
npm run dev
```

The server reads `.env.local` for `RGL_API_BASE_URL` etc. By default it points at the production RGL API.

## Deploy

```bash
fly launch --name rgl-mcp --copy-config --no-deploy   # first time only
fly deploy
```

Then point your MCP client at `https://rgl-mcp.fly.dev/mcp` (Streamable HTTP transport).

> **Edits aren't live until you `fly deploy`.** The hosted server at `https://rgl-mcp.fly.dev/mcp` is what MCP clients talk to, so any change to `src/` requires a `fly deploy` to take effect. A connected client also caches the tool list at session start — new or renamed tools only appear in a fresh session after the deploy.

## Use with Claude Code

> **This is an unauthenticated, read-only endpoint over already-public RGL data.** Every tool just proxies the public RGL API, so the URL isn't a secret. The server adds no auth of its own, and abuse is naturally bounded by the upstream RGL API's own rate limiting. The open pattern is safe only because nothing here is sensitive — don't bolt private or authenticated data onto this server without first adding auth.

The server is live at `https://rgl-mcp.fly.dev/mcp`. Add it to Claude Code with the HTTP transport — no local clone or build required, you're connecting straight to the hosted fly instance:

```bash
claude mcp add --transport http rgl https://rgl-mcp.fly.dev/mcp
```

By default this adds the server at `local` scope (just you, this project). Use `--scope user` to make it available across all your projects, or `--scope project` to share it with the repo via a checked-in `.mcp.json`:

```bash
claude mcp add --transport http --scope user rgl https://rgl-mcp.fly.dev/mcp
```

Verify and inspect the connection:

```bash
claude mcp list          # shows rgl as connected
claude mcp get rgl       # shows the URL, transport, and scope
```

Inside a session, `/mcp` lists the connected servers and their tools. The tools then show up as `mcp__rgl__<tool>` (e.g. `mcp__rgl__find_season`). To remove it later: `claude mcp remove rgl`.

## Configuration

| Env var | Default | Meaning |
|---|---|---|
| `RGL_API_BASE_URL` | `https://rglgg-api.fly.dev/v0` | Base URL of the RGL API |
| `PORT` | `3000` | HTTP listen port |
| `CACHE_REFRESH_MS` | `3600000` | Lookup cache TTL (1h) |
| `DEFAULT_REGION_ID` | `40` | NA Sixes — used when only a format is given |