FACEIT-MCP

# FACEIT CS2 Coaching MCP Server A remote **MCP server** (Python + [FastMCP](https://github.com/jlowin/fastmcp)) that reads a player's public **FACEIT CS2** data, diagnoses strengths and weaknesses, and produces a personalized, data-backed improvement pathway. It's designed to deploy to **Render.com** and be added as a **remote connector in Claude** on the first try. The server is **read-only** — it only reads public FACEIT data. There is intentionally **no auth wall** on the MCP endpoint (see [Enabling real OAuth later](#enabling-real-oauth-later--advanced--needs-persistent-storage)); your FACEIT API key stays server-side and is never exposed to the connected client. --- ## What it exposes **Tools** | Tool | What it does | | --- | --- | | `search_faceit_player(query)` | Resolve a nickname / profile URL / `player_id` / SteamID64 → identity + level + ELO. Returns a `candidates` list when a nickname is ambiguous. | | `get_player_overview(query)` | Profile + lifetime stats + active bans. | | `get_map_performance(query)` | Per-map win rate / K-D, best & worst maps (maps with <10 matches ignored). | | `get_recent_form(query, limit=10)` | Recent matches + per-match stats, trend, streak, consistency. | | `benchmark_player(query)` | **Percentile verdicts** for K/D, K/R, HS%, ADR, Win Rate vs same-level, same-region peers (e.g. "bottom-quartile ADR for level 8"). Live peer sampling, with a labelled static-baseline fallback. | | `get_advanced_stats(query)` | **Leetify** advanced metrics FACEIT doesn't expose — opening-duel %, trade %, utility damage, preaim, reaction time, aim/positioning/utility ratings. Degrades cleanly if the player has no Leetify profile. Carries required attribution. | | `analyze_player(query)` | **Headline tool** — full diagnostic fusing FACEIT stats + peer benchmarks + Leetify signals: strengths, weaknesses (with severity), map/form insights, overall assessment. Reports progress while it fetches. | | `get_improvement_plan(query, focus=None)` | Weaknesses → prioritized drills/resources tied to the player's own numbers and percentiles. `focus` can be `aim`, `opening`, `trading`, `utility`, `positioning`, `maps`, `teamplay`, `tilt`. | | `set_my_profile(query)` / `whoami()` / `clear_my_profile()` | Lightweight per-user identity: say "I'm `<nick>`" once and later tools default to you. Best-effort in-memory; every tool still accepts an explicit `query`. | **Prompts** — `coach_me(query)`, `pre_match_prep(query, map=None)`, `post_loss_review(query)`, `weekly_review(query)`. **Resource** — `faceit://player/{query}/analysis` exposes the latest computed analysis (served from an in-memory TTL cache, recomputed on demand — stateless-safe). `query` in every tool accepts a **nickname**, a **profile URL** (`faceit.com/en/players/<nick>`), a raw **`player_id`** (UUID), or a **SteamID64**. An exact-nickname miss falls back to FACEIT search; an ambiguous nickname resolves to the best match and returns the alternatives so Claude can confirm. ### How the advanced features work - **Peer benchmarking (no DB).** For the target's region + skill level, the server samples ~40 peers from the FACEIT rankings, fetches their lifetime stats concurrently (throttled), and computes the target's percentile per metric. The distribution is cached in-memory per `(region, level)` for 6h. If sampling is rate-limited or too thin, it falls back to an **approximate static baseline** table (in `benchmarks.py`) and clearly labels the output `source: "baseline"`. - **Leetify bridge.** A FACEIT player's `game_player_id` **is their SteamID64**, and Leetify's public profile endpoint (`GET /v3/profile?steam64_id=`) is keyed by SteamID64. So the chain is nickname → FACEIT player → Steam64 → Leetify profile. Many players aren't on Leetify; the analysis degrades cleanly to FACEIT-only and notes that connecting Leetify would deepen the report. - **Leetify attribution (required).** Any output containing Leetify-derived data includes **"Data Provided by Leetify"** and a **View on Leetify** link (`https://leetify.com/app/profile/{steam64}`). This project is not affiliated with or sponsored by Leetify. --- ## 1. Get a FACEIT Server-Side API key 1. Go to the **FACEIT Developer Portal / App Studio**: <https://developers.faceit.com/> 2. Create an app and generate a **Server-Side** API key (not a Client-Side key). 3. Keep it secret — it lives only as a server env var (`FACEIT_API_KEY`), never in client-facing code. The current CS2 game slug is `cs2` (the old `csgo` slug is deprecated and unused here). --- ## 2. Run locally ```bash python -m venv venv # Windows: venv\Scripts\activate macOS/Linux: source venv/bin/activate pip install -r requirements.txt cp .env.example .env # then edit .env and set FACEIT_API_KEY=... python server.py ``` The server starts on `http://0.0.0.0:8000` and the MCP endpoint is at **`http://localhost:8000/mcp`**. **Test it:** - Health check: `curl http://localhost:8000/health` → `{"status":"ok"}` - MCP Inspector: point it at `http://localhost:8000/mcp` (Streamable HTTP transport) and call `analyze_player` with a nickname like `donk` or `ZywOo`. > Note: `PORT` overrides the default 8000 locally if set. On Render it's injected automatically. --- ## 3. Deploy to Render This repo ships a Render **Blueprint** (`render.yaml`): 1. Push this repo to GitHub. 2. In Render: **New → Blueprint**, pick the repo. Render reads `render.yaml` and creates a free web service named `faceit-cs2-mcp`. 3. In the service's **Environment** settings, set **`FACEIT_API_KEY`** to your Server-Side key (it's marked `sync: false`, so Render won't read it from the file — set it manually). Optionally set **`LEETIFY_API_KEY`** for higher Leetify rate limits (the server works without it). `ENABLE_FACEIT_OAUTH` and `ENABLE_ELICITATION` default to `"false"` — leave them. 4. Deploy. Render's health probe hits `/health`; once it's green the service is live at `https://<your-service>.onrender.com`. **How the deploy is wired (and why it connects on the first try):** - **Streamable HTTP transport** — `mcp.run(transport="http", ...)`, not stdio/SSE. - **Binds `0.0.0.0`** and reads **`PORT`** from the env var Render injects (falls back to 8000 locally). No hard-coded port, no `127.0.0.1`. - **Stateless HTTP** (`stateless_http=True`) so Render's proxy + free-tier cold starts don't break in-memory sessions and Claude's connector reconnects cleanly. - **TLS is terminated by Render.** The app serves plain HTTP on `$PORT`; `.onrender.com` provides HTTPS for free. There is deliberately **no cert/SSL code** in Python — that's the classic mistake. - **`/health`** is a plain `GET` (200 `{"status":"ok"}`) and is Render's `healthCheckPath`; the `/mcp/` endpoint is not a normal GET and must not be the health target. - Every tool **catches its own errors** (404/401/429/timeouts) and returns a structured message instead of throwing, so a bad lookup never 500s mid-conversation. --- ## 4. Add it to Claude as a connector In **Claude → Settings → Connectors → Add custom connector**, use this exact URL: ``` https://<your-service>.onrender.com/mcp ``` (Replace `<your-service>` with your Render service name. The path is `/mcp` — the server also accepts `/mcp/`.) > **Render free-tier cold start:** after ~15 min idle the service sleeps and the first request can > take ~50s to wake. If the first connect attempt times out, just retry — it'll be instant once warm. --- ## Per-user personalization Two layers, both infra-free: - **Now (default, no auth, no DB):** `set_my_profile("<nick>")` remembers who you are for the conversation, so `analyze_player()` etc. default to you. It's stored in-memory keyed by MCP session and is **best-effort** — under `stateless_http=True` there isn't always a stable session id, so every tool also accepts an explicit `query`. That explicit argument is the real guarantee: nothing breaks across cold starts. FACEIT's public API + Leetify's public API already cover the full coaching surface, so this gives a personalized experience with zero auth. - **Later (real OAuth, disabled):** see the next section. ## Enabling real OAuth later (advanced — needs persistent storage) A full FACEIT OAuth provider is scaffolded in [`auth_faceit.py`](auth_faceit.py) using FastMCP's `OAuthProxy` against FACEIT's real OIDC endpoints, gated behind `ENABLE_FACEIT_OAUTH` (default `false`). When false, the server runs open and connects to Claude first-try. **Do not enable it for a normal deploy.** Two caveats you must understand first: 1. **Claude.ai DCR issue.** Claude.ai remote connectors have a reported Dynamic Client Registration (DCR) `400` failure against FastMCP's `OAuthProxy`. Enabling OAuth may break the connection — test in the **MCP Inspector** first, not directly in Claude. 2. **In-memory token storage is not production-usable.** The scaffold leaves `client_storage=None`, so OAuth client registrations and tokens live in memory and **do not survive a restart / cold start**. Making this production-grade requires a **persistent, encrypted store** (a DB/Redis implementing `AsyncKeyValue`), which is deliberately out of scope for this infra-free build. The injection point is marked in `auth_faceit.py`. To experiment: set `ENABLE_FACEIT_OAUTH=true`, `MCP_JWT_SECRET`, `FACEIT_OAUTH_CLIENT_ID`, `FACEIT_OAUTH_CLIENT_SECRET`, and register `https://<service>.onrender.com/auth/callback` as the redirect URI in your FACEIT OAuth app. > Similarly, `ENABLE_ELICITATION` (default `false`) turns on protocol-level `ctx.elicit` prompts. > It's off because that request/response round-trip is unreliable under `stateless_http` and can hang > a tool. With it off, ambiguous nicknames resolve to the best match and return a `candidates` list > for Claude to disambiguate in conversation. --- ## Assumptions made - FastMCP 3.x standalone package (`from fastmcp import FastMCP`); the MCP endpoint mounts at `/mcp`. - FACEIT stat fields are treated as strings and parsed defensively (missing fields tolerated). - Skill-level ELO bands follow FACEIT's published CS2 table; maps need ≥10 matches to count toward best/worst; a ≥3-game active loss streak flags tilt risk. **Peer benchmarking** samples ~40 peers and caches distributions 6h; the static baseline table is approximate. These thresholds/tables live in [`analysis.py`](analysis.py) and [`benchmarks.py`](benchmarks.py) and are easy to tune. - Leetify field names/paths were confirmed against the live OpenAPI spec at build time. --- ## Tests ```bash pip install pytest python -m pytest tests/ -v ``` Unit tests (no network) cover the pure analysis engine (parsing, level bands, fragging/aim/mismatch, map ranking, form/tilt, end-to-end diagnostic), the **benchmarking percentile math** + static baseline, and the **Leetify fusion** (weakness detection, attribution, graceful absence).