<p align="center">
  <img src="assets/banner.jpg" alt="MCSR Ranked MCP" width="100%" />
</p>

<p align="center">
  <a href="https://github.com/miyakejima/mcsr-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js >= 18" /></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blueviolet.svg" alt="MCP Compatible" /></a>
  <a href="https://mcsrranked.com"><img src="https://img.shields.io/badge/data-mcsrranked.com-orange.svg" alt="MCSR Ranked" /></a>
</p>

<br />

**mcsr-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants real-time access to the [MCSR Ranked](https://mcsrranked.com) competitive Minecraft speedrunning API.

Ask your AI anything about any ranked player — form analysis, personal bests, ELO history, pre-match scouting, rivals, decay status — in plain language. No commands, no dashboards, no manual API calls.

```
"Scout v_strid before my match"
"What are Feinberg's top 10 fastest runs this season?"
"Has v_strid been tilting? Show me their ELO history"
"When does my rank decay?"
"Who are v_strid's rivals and where are they weakest?"
```

---

## How it looks

<p align="center">
  <img src="assets/example-output.jpg" alt="Example tool output" width="80%" />
</p>

---

## What it can do

<p align="center">
  <img src="assets/tools-diagram.jpg" alt="Tools overview" width="90%" />
</p>

### All 18 tools

| Tool | What it does |
|---|---|
| `get_player` | Profile, ELO, rank, tier, stats, Twitch/YouTube links |
| `get_player_matches` | Raw match history with seed and bastion data |
| `get_player_seasons` | Season-by-season performance history |
| `get_versus` | Head-to-head record between two players |
| `get_versus_matches` | Full H2H match list |
| `get_leaderboard` | Global ranked standings |
| `get_match` | Single match details by ID |
| `get_weekly_race` | Weekly race leaderboard |
| `analyze_player_form` | Win rates by seed type, bastion type, opponent ELO bracket |
| `get_rank_context` | Leaderboard neighborhood + ELO gaps to milestone ranks |
| `scout_opponent` | Pre-match scouting report with Twitch VOD timestamps |
| `compare_players` | Side-by-side player comparison with H2H |
| `find_rivals` | Opponents a player consistently loses to |
| `get_personal_bests` | Fastest ranked completions, filterable by seed type |
| `get_elo_history` | Full ELO trajectory — peak, trough, streaks, per-match deltas |
| `get_decay_status` | Exact decay date + urgency level (✅ SAFE → 🚨 CRITICAL) |
| `analyze_session_form` | Per-session stats grouped by playtime gaps |
| `get_capabilities` | Ask your AI "what can this MCP do?" to get the full guide |

---

## Installation

### Requirements

- [Node.js](https://nodejs.org/) v18 or later
- An MCP-compatible AI client (see below)

### 1. Clone and build

```bash
git clone https://github.com/miyakejima/mcsr-mcp.git
cd mcsr-mcp
npm install
npm run build
```

The compiled server will be at `dist/index.js`.

### 2. Add to your AI client

Add the following block to your MCP config file:

```json
{
  "mcpServers": {
    "mcsr": {
      "command": "node",
      "args": ["/absolute/path/to/mcsr-mcp/dist/index.js"]
    }
  }
}
```

#### Config file locations

| Client | Config file |
|---|---|
| **Antigravity** | `~/.gemini/config/mcp_config.json` |
| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop** (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Cursor** | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |

**Windows path example:**
```json
{
  "mcpServers": {
    "mcsr": {
      "command": "node",
      "args": ["C:/Users/yourname/mcsr-mcp/dist/index.js"]
    }
  }
}
```

### 3. Restart your client

After saving, restart your AI client. The `mcsr` server will appear with all 18 tools enabled. You can verify by asking:

> *"What can the mcsr MCP do?"*

---

## Usage examples

### Pre-match scouting
```
"Scout v_strid — I'm miyakejima"
```
Returns: recent form, seed/bastion win rates, weaknesses, your H2H record, and Twitch VOD links with timestamps so you can jump straight to their runs.

### Form analysis
```
"What are Feinberg's weaknesses over the last 30 matches?"
```
Returns: win rate by every seed type and bastion variant, ELO bracket performance, streak data.

### Personal bests
```
"Show me v_strid's top 5 fastest Buried Treasure runs"
```
Returns: ranked list of fastest completions for that seed, with opponent, date, and VOD timestamp link.

### ELO history
```
"Has v_strid been tilting lately? Show me their last 50 matches"
```
Returns: full ELO timeline, peak/trough, total delta, longest win and loss streaks.

### Decay tracker
```
"When does my rank decay? I'm miyakejima"
```
Returns: exact date, days/hours remaining, urgency level, last match date.

### Rivals
```
"Who does Feinberg consistently lose to?"
```
Returns: opponents with a net losing record, sorted by ELO proximity and net loss count.

---

## Notes

- **No API key required.** Uses the public MCSR Ranked REST API at `api.mcsrranked.com`.
- **Rate limit:** The API allows ~500 requests per 10 minutes. A 150ms delay between requests is applied automatically.
- **Loss times are unavailable.** The MCSR Ranked API only records the winner's finish time — this is an upstream API limitation.
- **VOD links** include Twitch timestamps to jump directly to the run start.
- **Season filtering:** Add *"season 10"* (or any number) to any query to pull historical season data.
- **Seed type filter** on `get_personal_bests`: `RUINED_PORTAL`, `SHIPWRECK`, `DESERT_TEMPLE`, `VILLAGE`, `BURIED_TREASURE`.

---

## Data source

All data is from the official [MCSR Ranked API](https://mcsrranked.com). This project is not affiliated with or endorsed by MCSR Ranked.

---

## License

[MIT](LICENSE)