cito-mcp 0.3.4 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +519 -519
  2. package/dist/install.js +15 -15
  3. package/dist/tools/live.js +45 -10
  4. package/dist/tools/match.js +45 -1
  5. package/dist/tools/normalize.js +16 -1
  6. package/dist/tools/resolve.js +43 -32
  7. package/dist/tools/team.js +88 -3
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -1,519 +1,519 @@
1
- # cito-mcp
2
-
3
- Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
4
-
5
- **Version:** `0.2.4` · **Node:** `>=20` · **Install:** `npx cito-mcp`
6
-
7
- Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
8
-
9
- ---
10
-
11
- ## Philosophy: outcomes, not endpoints
12
-
13
- v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among thin path wrappers, invent IDs, and stitch multi-call UI screens themselves. That catalog was hard to select against and brittle across games.
14
-
15
- **v0.2 ships 16 hand-authored tools** that answer *jobs* instead of mirroring REST:
16
-
17
- | Job | Tool |
18
- | --- | --- |
19
- | What’s live right now? | `live_matches` |
20
- | What’s coming up? | `upcoming_schedule` |
21
- | Build a match card / recap | `match_summary` |
22
- | Deep timeline / live state | `match_details` |
23
- | Team page | `team_profile` |
24
- | Player / fighter form | `player_profile` |
25
- | Table / rankings | `standings` |
26
- | Pre-match briefing | `match_preview` |
27
- | Event / fight-night card | `event_card` |
28
- | Rivalry record | `head_to_head` |
29
- | Fighter / team photos | `event_card` · `player_profile` |
30
- | Which raw REST route exists? | `list_routes` |
31
- | Name → ID | `resolve_entity` / `search_entities` |
32
-
33
- Composites multi-fetch server-side, return a **stable JSON envelope**, and isolate partial failures in `partial[]` so one bad secondary section does not fail the whole page.
34
-
35
- **MCP is design-time / agent assistance.** Ship production backends with Cito REST + the user’s API key. Do not put multi-tenant traffic through this process.
36
-
37
- ---
38
-
39
- ## Install
40
-
41
- ### One command (recommended)
42
-
43
- ```bash
44
- npx cito-mcp install --key cito_your_key_here
45
- ```
46
-
47
- Detects the MCP clients installed on your machine — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI — and writes the config for each. Then restart your editor.
48
-
49
- It is safe to re-run: existing config is merged, not replaced, your other MCP servers are left alone, a `.cito-bak` backup is written before the first change, and running it again just rotates the key rather than adding a second entry.
50
-
51
- ```bash
52
- npx cito-mcp install --dry-run # show the plan, write nothing
53
- npx cito-mcp install --key … --client cursor # one client only
54
- npx cito-mcp install --help
55
- ```
56
-
57
- Get a key at [citoapi.com/dashboard](https://citoapi.com/dashboard).
58
-
59
- ### Manual — Claude Code
60
-
61
- ```bash
62
- claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" npx -y cito-mcp
63
- ```
64
-
65
- **Quote the `--`.** PowerShell 5.1 strips a bare `--` before the CLI sees it; because `-e` takes a variable number of values it then swallows `npx -y cito-mcp` as env vars and fails with `unknown option '-y'`. The quoted form works in PowerShell, cmd, bash and zsh alike. `npx cito-mcp install` avoids the problem entirely.
66
-
67
- From a local clone (development):
68
-
69
- ```bash
70
- cd mcp
71
- npm install
72
- npm run build
73
- claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" node "%CD%\dist\index.js"
74
- ```
75
-
76
- ### Cursor
77
-
78
- Add to Cursor MCP settings (e.g. `.cursor/mcp.json` or Cursor Settings → MCP):
79
-
80
- ```json
81
- {
82
- "mcpServers": {
83
- "cito": {
84
- "command": "npx",
85
- "args": ["cito-mcp"],
86
- "env": {
87
- "CITO_API_KEY": "cito_your_key_here"
88
- }
89
- }
90
- }
91
- }
92
- ```
93
-
94
- Windows local clone:
95
-
96
- ```json
97
- {
98
- "mcpServers": {
99
- "cito": {
100
- "command": "node",
101
- "args": ["C:/Users/Owner/Projects/cito-api-scraper-windows/mcp/dist/index.js"],
102
- "env": {
103
- "CITO_API_KEY": "cito_your_key_here"
104
- }
105
- }
106
- }
107
- }
108
- ```
109
-
110
- ### Windsurf / other MCP hosts
111
-
112
- Same shape as Cursor: `command` + `args` + `env.CITO_API_KEY`. Prefer `npx cito-mcp` so clients pick up published patches without a local install.
113
-
114
- The server **exits immediately** if `CITO_API_KEY` is missing. The key is sent only as the `x-api-key` header and is never logged.
115
-
116
- ---
117
-
118
- ## Environment
119
-
120
- | Variable | Required | Default | Description |
121
- | --- | --- | --- | --- |
122
- | `CITO_API_KEY` | **yes** | — | Cito API key → `x-api-key` on every upstream call |
123
- | `CITO_API_BASE` | no | `https://api.citoapi.com/api/v1` | Override base URL (staging / self-hosted) |
124
-
125
- ---
126
-
127
- ## Preferred tool order
128
-
129
- 1. Unsure → `list_capabilities` (optional `api_health` for tier / included games)
130
- 2. Name without ID → `resolve_entity` (chain) or `search_entities` (browse)
131
- 3. Live / upcoming → `live_matches` / `upcoming_schedule`
132
- 4. Match card → `match_summary` (then `match_details` if needed)
133
- 5. Team / player pages → `team_profile` / `player_profile`
134
- 6. Tables / rivalry / preview / event card → `standings` / `head_to_head` / `match_preview` / `event_card`
135
- 7. Escape hatch → `list_routes` to find a path, then `call_api` (allowlisted paths only)
136
-
137
- **Never invent IDs** — resolve them or take them from live / schedule / search results.
138
-
139
- Mnemonic: **resolve → live/schedule → summary → deep**.
140
-
141
- ---
142
-
143
- ## Tool catalog (16)
144
-
145
- All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
146
-
147
- | Tool | Outcome | When to use | When not to use | Key inputs |
148
- | --- | --- | --- | --- | --- |
149
- | `list_capabilities` | Catalog of tools, games, jobs, recipes (no network) | Session start; map UI screens to tools; filter by `game` / `job` | You already know the tool and have IDs | `game?`, `job?`, `q?`, `includeExamples?`, `includeRecipes?` |
150
- | `api_health` | Reachability, key validity, tier, rate limits, optional game probes | Once per session; after 401/403/RATE_LIMIT; entitlement checks | Fetching live scores or entity data | `includeGameProbes?` |
151
- | `resolve_entity` | Name → best typed id/slug (+ ranked candidates) | User named “T1”, “s1mple”, “IEM Cologne” without an ID; chaining into profiles | Already have a stable id/slug; large browse lists | `q`, `game?`, `type?`, `limit?` |
152
- | `search_entities` | Paginated entity browse/search for one game | Typeahead / pickers; “list teams matching…” | Single-name resolve for chaining; full profile pages | `game`, `q?`, `type?`, `limit?`, `cursor?`, `activeOnly?` |
153
- | `live_matches` | Live board (one game or all); CS2 uses `/cs2/live`; includes UFC | “What’s live?”; ops/dashboard strip | Upcoming fixtures; historical recaps | `game?` (`all` or omit), `limitPerGame?`, `includeLabelsOnly?` |
154
- | `upcoming_schedule` | Upcoming fixtures/events with filters | “What’s on this week?”; team next matches | Live-only boards; deep match recaps | `game`, `hours?`, `from?`, `to?`, `team?`, `league?`, `tournamentId?`, `limit?`, `cursor?` |
155
- | `match_summary` | Composite match card: score, performances, media stubs | Default match UI / recap after a known `matchId` | No matchId yet; pure pre-match → `match_preview`; deep timelines | `game`, `matchId`, `view?`, `includePlayerStats?`, `includeMedia?` |
156
- | `match_details` | Deep sections: timeline, live state, maps, advanced | Analyst dive; live in-game window; full demo list | First-pass live board; simple chat recaps | `game`, `matchId`, `gameId?`, `sections?`, `includeTimeline?`, `includeLiveState?`, `includeAdvanced?` |
157
- | `player_profile` | Player/fighter + form/trends/radar when available | “How is X playing?”; player page scaffold | Full roster → `team_profile`; unresolved name | `game`, `playerId` **or** `slug`, `recentLimit?`, `includeTrends?`, `view?`, `window?`, `role?` |
158
- | `team_profile` | Team/org + roster + recent form | Team page / “who is on this roster?” | UFC fighters → `player_profile`; unresolved name; pure tables | `game`, `teamId` **or** `slug`, `recentLimit?`, `includeFormer?`, `view?` |
159
- | `head_to_head` | Composed H2H (no first-class REST H2H) | Rivalry / series record; preview context | Single-side form only; live scores; standings | `game`, `sideA`, `sideB`, `entityType?`, `limit?`, `from?`, `to?` |
160
- | `standings` | League/event tables or world/division rankings | Playoff picture; UFC rankings; CDL / CS2 tables | Team form; live scores; match recaps | `game`, `scope?`, `leagueId?`, `tournamentId?`, `eventId?`, `season?`, `stage?`, `division?`, `limit?` |
161
- | `match_preview` | Pre-match briefing: sides, rosters/form, H2H stub | Upcoming deep link; pick’ems; preview cards | Completed recaps; deep live state | `game`, `matchId` **or** (`teamA` + `teamB`), `eventId?`, `includeH2H?`, `includeRosters?`, `recentLimit?` |
162
- | `event_card` | Event / fight-night card: identity + bouts in card order (main event first), each corner with photos, record, nickname, weight class; optional rankings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
163
- | `list_routes` | Index of raw REST routes from the live OpenAPI spec (method, path, summary, tag) | Finding a long-tail path before `call_api`; checking an endpoint exists | A curated tool covers the outcome | `game?`, `q?`, `limit?` |
164
- | `call_api` | Allowlisted raw REST (`data.raw`) | Fortnite / long-tail paths; payload debugging | Any job covered by a curated tool | `path`, `method?`, `queryJson?`, `bodyJson?` |
165
-
166
- ### Images
167
-
168
- Fighter and team sides carry an `images` object wherever upstream supplies one —
169
- on `event_card` bout corners and on `player_profile`. No extra call, no N+1.
170
-
171
- ```jsonc
172
- "team1": {
173
- "name": "Islam Makhachev",
174
- "slug": "islam-makhachev",
175
- "record": { "wins": 28, "losses": 1, "draws": 0, "text": "28-1-0 (W-L-D)" },
176
- "championStatus": "champion",
177
- "images": {
178
- "headshotUrl": "https://ufc.com/…/MAKHACHEV_ISLAM_BELT_01-18.png",
179
- "bodyImageUrl": "https://ufc.com/…/athlete_bio_full_body/…",
180
- "imageUrl": "https://ufc.com/…/event_fight_card_upper_body/…",
181
- "proxiedImageUrl": "https://api.citoapi.com/api/v1/public/images/ufc/aHR0cHM6…"
182
- }
183
- }
184
- ```
185
-
186
- **Use `proxiedImageUrl` in a browser.** `ufc.com` sends no CORS header and can
187
- hotlink-block, so raw URLs render as broken images in a web UI. The proxied URL
188
- is served by the API and is safe to put in an `<img src>`.
189
-
190
- When a key is `null` the image does not exist for that entity; when the whole
191
- `images` object is absent, upstream sent nothing for that side. The object is
192
- never partially shaped — if any image exists, all four keys are present.
193
-
194
- ### Games
195
-
196
- | Game | Depth | Notes |
197
- | --- | --- | --- |
198
- | `lol` | deep | Team slugs; `lol-match-*`; no native global search |
199
- | `cs2` | deep | Prefixed ids; live path **`GET /cs2/live`**; trends / rankings |
200
- | `dota2` | thin | Numeric ids; radar; weak/no standings & roster endpoints |
201
- | `cod` | medium | Org slugs; CDL standings; UUID match ids |
202
- | `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
203
-
204
- ### UFC projection notes (0.2.4)
205
-
206
- Hardened agent-facing UFC shapes (offline-tested):
207
-
208
- - **`normalizeMatch`** reads `fighters[]` (`corner` + `fighterName` / `profile.name`), live `red`/`blue`, and `boutId` / `dataId` / bare `id`. Never keeps label `? vs ?` when fighter names exist (including blue-first arrays).
209
- - **`live_matches`** uses `extractLiveRows`: prefer `liveBouts` (empty array = honest empty board); never promote supervisor `events[]` shells into match rows.
210
- - **UFC empty board honesty:** when `count === 0`, section includes `note`, `emptyReason`, slim `health` (`workerAlive`, lag), optional non-live `supervisor` strip and `nextCard` (armed only). Also `data.note` + `meta.warnings` for single-game UFC. Do not treat empty as HTTP failure; do not invent `? vs ?` from event shells.
211
- - **`upcoming_schedule`** expands event → bout rows with fighter labels; applies client-side **`hours` / `from` / `to`** (API has no `hours`); event shells without bouts use the **event name**, not `? vs ?`.
212
- - **`event_card`** bouts share the same `normalizeMatch` path.
213
- - **`standings`** maps division champions to rank **`C`** (`rankText: "C"`, interim **`IC`**); contender `#1` stays numeric `1` — no dual numeric `#1`.
214
-
215
- Fortnite: **`call_api` only** until promoted into the primary enum.
216
-
217
- ### `call_api` allowlist
218
-
219
- Path must start with `/` and match one of:
220
-
221
- `/health` · `/lol` · `/cs2` · `/dota2` · `/cod` · `/ufc` · `/fortnite`
222
-
223
- Absolute URLs and `..` traversal → `PATH_NOT_ALLOWED`. Prefer curated tools for all standard jobs.
224
-
225
- ---
226
-
227
- ## Response envelope
228
-
229
- Every tool returns one JSON object:
230
-
231
- ```json
232
- {
233
- "ok": true,
234
- "data": {},
235
- "meta": {
236
- "game": "cs2",
237
- "source": "match_summary",
238
- "fetchedAt": "2026-07-27T12:00:00.000Z",
239
- "requestId": "mcp_…",
240
- "tookMs": 120,
241
- "upstreamCalls": 3,
242
- "rateLimit": { "tier": "pro", "remaining": 54 }
243
- },
244
- "pagination": { "limit": 20, "hasMore": false, "nextCursor": null },
245
- "partial": [],
246
- "error": null
247
- }
248
- ```
249
-
250
- | Condition | How to handle |
251
- | --- | --- |
252
- | `ok: false` | Tool-level failure; MCP `isError: true`; read `error.code` + `error.recover[]` |
253
- | `ok: true` with `partial[]` | Use successful sections; **do not** treat as total failure |
254
- | List tools | `data.items` + `pagination` (`limit`, `hasMore`, `nextCursor`, …) |
255
-
256
- **Error codes:** `VALIDATION` · `NOT_FOUND` · `UNSUPPORTED_GAME` · `UNAUTHORIZED` · `RATE_LIMIT` · `UPSTREAM` · `PATH_NOT_ALLOWED` · `NOT_IMPLEMENTED`
257
-
258
- **Ambiguity:** `resolve_entity` returns `ok: true` with `data.needsDisambiguation` + `data.candidates` — pick a candidate; do not wait for a hard error.
259
-
260
- Retry only when `error.retryable` is true (typically `RATE_LIMIT`, `UPSTREAM`).
261
-
262
- **Pagination:** default limit 20, max 50 (some tools clamp differently). Honor `pagination.hasMore` and pass `pagination.nextCursor` only — never invent cursors or reuse them after changing filters.
263
-
264
- ---
265
-
266
- ## Builder recipes
267
-
268
- Use these as agent playbooks when scaffolding apps. Prefer one composite per screen over N+1 thin GETs.
269
-
270
- ### 1. Live scoreboard
271
-
272
- **Goal:** multi-game (or single-game) live strip with optional match drill-down.
273
-
274
- ```
275
- 1. api_health # optional — once per session
276
- 2. live_matches { game: "all" } # or "cs2" / "lol" / …
277
- 3. For a selected row:
278
- match_summary { game, matchId } # default card
279
- match_details { …, includeLiveState: true } # only if needed
280
- ```
281
-
282
- **UI map**
283
-
284
- | Screen region | Source |
285
- | --- | --- |
286
- | Live rows (label, score, status) | `live_matches` → `data.sections[].items` |
287
- | Expanded card | `match_summary` → `data.scoreline`, `playerPerformances`, `media` |
288
- | In-game window | `match_details` sections `liveState` / `timeline` |
289
-
290
- **Do not:** N+1 `match_details` for every live row; invent matchIds; use `upcoming_schedule` for live-only boards.
291
-
292
- ### 2. Player profile page
293
-
294
- **Goal:** identity, team, recent form for a named player or fighter.
295
-
296
- ```
297
- 1. resolve_entity { q: "s1mple", game: "cs2", type: "player" }
298
- # or type: "fighter" for UFC
299
- 2. player_profile {
300
- game,
301
- playerId | slug, # from resolve best/candidates
302
- recentLimit: 10,
303
- includeTrends: true,
304
- view: "summary"
305
- }
306
- 3. Optional: head_to_head for rivalry context (fighters/teams)
307
- ```
308
-
309
- **UI map**
310
-
311
- | Screen region | Source |
312
- | --- | --- |
313
- | Header / identity | `data.player` |
314
- | Current team | `data.currentTeam` |
315
- | Recent form list | `data.recentMatches` + `data.form` |
316
- | Career / radar | `data.career`, `data.radar`, `data.seasonStats` (when present) |
317
-
318
- **Do not:** invent playerIds; use `team_profile` for full rosters; skip resolve when the user only gave a display name.
319
-
320
- ### 3. Event hub
321
-
322
- **Goal:** schedule strip + standings/rankings + match previews for a league, tournament, or event.
323
-
324
- ```
325
- 1. list_capabilities { job: "schedule" } # optional orientation
326
- 2. upcoming_schedule {
327
- game: "cs2", # or lol / cod / ufc / dota2
328
- hours: 168, # or from/to ISO window
329
- league | tournamentId | team # scope filters as available
330
- }
331
- 3. standings {
332
- game,
333
- scope: "event" | "league" | "tournament" | "world" | "division",
334
- eventId | leagueId | tournamentId | division | season
335
- }
336
- 4. For a featured upcoming match:
337
- match_preview { game, matchId } # or teamA + teamB
338
- 5. When a match goes live / completes:
339
- match_summary { game, matchId }
340
- ```
341
-
342
- **UI map**
343
-
344
- | Screen region | Source |
345
- | --- | --- |
346
- | Upcoming list | `upcoming_schedule` → `data.items` |
347
- | Table / ranks | `standings` → `data.rows` |
348
- | Featured match briefing | `match_preview` → `sideA` / `sideB` / `h2h` / `talkingPoints` |
349
- | Live / completed card | `match_summary` |
350
-
351
- **Notes:** Dota standings may return `NOT_IMPLEMENTED` or sparse data — fall back to schedule + profiles. UFC event hubs lean on fighter slugs, `boutId`, and `standings` with `scope: "division"`.
352
-
353
- ### Other quick recipes (from `list_capabilities`)
354
-
355
- | Recipe id | Steps |
356
- | --- | --- |
357
- | `live_ops_board` | `api_health` → `live_matches` → `match_summary` / `match_details` |
358
- | `team_page` | `resolve_entity { type: "team" }` → `team_profile` |
359
- | `match_center_completed` | schedule/live for `matchId` → `match_summary` → optional `match_details` |
360
- | `app_scaffold` | `list_capabilities` ∥ `api_health` → sample composites → **ship REST in production** |
361
-
362
- ---
363
-
364
- ## Resources
365
-
366
- | URI | Purpose |
367
- | --- | --- |
368
- | `cito://capabilities` | Static tool / game / workflow summary |
369
- | `cito://llms.txt` | Live product agent context (may 404 upstream) |
370
- | `cito://openapi.json` | Live public OpenAPI for **typed clients** — not for tool generation |
371
-
372
- ---
373
-
374
- ## Transports
375
-
376
- **stdio** is the default (Claude Code, Cursor, Windsurf).
377
-
378
- Optional **stateless Streamable HTTP**:
379
-
380
- ```bash
381
- CITO_API_KEY=cito_your_key_here node dist/index.js --http 8787
382
- # → http://127.0.0.1:8787/mcp
383
- ```
384
-
385
- Hosted (production): `https://api.citoapi.com/mcp`
386
- Send the user's Cito key as `x-api-key`. Initialize and `list_capabilities` work without a key so Smithery can scan.
387
-
388
- ---
389
-
390
- ## Migration from 0.1 (auto-generated tools)
391
-
392
- **Breaking change.** `0.1.x` loaded OpenAPI at boot and mass-generated ~100+ tools (`generateAllTools`), plus a couple of hard-coded helpers (e.g. `cito_live_overview`, `cito_api_health`). Agents selected among thin REST wrappers and often reimplemented composition client-side.
393
-
394
- | 0.1 pattern | 0.2 replacement |
395
- | --- | --- |
396
- | Generated per-path tools (`/cs2/matches/...`, etc.) | Outcome tools in the table above |
397
- | `cito_live_overview` / ad-hoc live probes | `live_matches` (fixed CS2 path `/cs2/live`; UFC included) |
398
- | `cito_api_health` | `api_health` |
399
- | OpenAPI-named tools with `cito_` noise | **15** `snake_case` names, no `cito_` prefix |
400
- | Raw HTTP-shaped responses | Stable envelope: `ok`, `data`, `meta`, `pagination`, `partial`, `error` |
401
- | Agent stitches roster + matches + H2H | `team_profile`, `player_profile`, `head_to_head`, `match_preview` |
402
- | Fortnite / niche paths as first-class tools | `call_api` allowlist |
403
- | Spec cache / boot network for tool list | Static catalog; `list_capabilities` is offline |
404
-
405
- **Action items for existing clients**
406
-
407
- 1. Drop any hardcoded 0.1 tool names; rebind prompts to the 15-tool catalog.
408
- 2. Always parse the envelope (`ok` / `partial` / `error.recover`) — do not assume bare REST JSON.
409
- 3. Use `resolve_entity` before profile tools when you only have a display name.
410
- 4. Prefer composites over reintroducing N+1 `call_api` loops.
411
- 5. Bump config to `npx cito-mcp` (or rebuild from this package) and re-test live board + one profile + one match flow.
412
-
413
- There is **no compatibility shim** for 0.1 tool names in 0.2.
414
-
415
- ---
416
-
417
- ## Development
418
-
419
- ```bash
420
- npm install
421
- npm run build # tsc → dist/
422
- npm test # node:test via tsx, offline (no network)
423
- npm start # node dist/index.js (requires CITO_API_KEY)
424
- ```
425
-
426
- Source layout (authoritative tool registry: `src/tools/index.ts`):
427
-
428
- ```
429
- src/
430
- index.ts # MCP wiring, resources, stdio / --http
431
- client.ts # fetchJson, auth, present, cursors
432
- envelope.ts # success / error envelopes, MCP isError
433
- instructions.ts # server instructions for agents
434
- tools/
435
- index.ts # allTools (15)
436
- meta.ts # list_capabilities, api_health, call_api
437
- resolve.ts # resolve_entity, search_entities
438
- live.ts # live_matches, upcoming_schedule
439
- match.ts # match_summary, match_details
440
- player.ts # player_profile
441
- team.ts # team_profile, head_to_head
442
- standings.ts # standings
443
- insight.ts # match_preview, event_card
444
- normalize.ts # cross-game normalization
445
- types.ts # ToolDef, schemas
446
- ```
447
-
448
- ---
449
-
450
- ## Publish notes
451
-
452
- Package: **`cito-mcp@0.2.4`**
453
-
454
- | Item | Value |
455
- | --- | --- |
456
- | npm name | `cito-mcp` |
457
- | bin | `cito-mcp` → `dist/index.js` |
458
- | published files | `dist/`, `README.md` (`package.json` `"files"`) |
459
- | engines | `node >= 20` |
460
- | runtime dependency | `@modelcontextprotocol/sdk` only |
461
- | prepublish | `npm run prepublishOnly` → `npm run build` |
462
-
463
- ### Pre-publish checklist
464
-
465
- 1. `npm test` — offline suite green.
466
- 2. `npm run build` — clean `dist/`.
467
- 3. Smoke against a real key (not in CI by default):
468
- - `api_health`
469
- - `live_matches`
470
- - `resolve_entity` (e.g. T1 / s1mple)
471
- - `match_summary` with a real `matchId` from live/schedule
472
- 4. Confirm `package.json` version and README match the shipped tool list.
473
- 5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
474
- `prepublishOnly` runs build + tests + smoke, so a broken build cannot ship.
475
-
476
- ### Install line for docs & marketing
477
-
478
- ```bash
479
- npx cito-mcp install --key cito_…
480
- ```
481
-
482
- Manual fallback (note the quoted `--`, required for PowerShell):
483
-
484
- ```bash
485
- claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
486
- ```
487
-
488
- ```json
489
- { "command": "npx", "args": ["cito-mcp"], "env": { "CITO_API_KEY": "cito_…" } }
490
- ```
491
-
492
- ### Semver expectations
493
-
494
- - **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
495
- - Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
496
- - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
497
-
498
- ---
499
-
500
- ## Changelog (summary)
501
-
502
- ### 0.2.4
503
-
504
- - **UFC projection hardening** (offline-tested):
505
- - `normalizeMatch`: `fighters[]` corners + profile, live red/blue, `boutId`/`dataId`; never keep `? vs ?` when names exist
506
- - `extractRows` / `extractLiveRows`: prefer `liveBouts` (including empty); never fake match rows from supervisor `events[]`
507
- - `upcoming_schedule`: client-side `hours`/`from`/`to`; bout expansion with fighter labels; event shells labeled by event name
508
- - `event_card` bouts share the same normalize path
509
- - `standings`: champion rank `C` / interim `IC`; no dual numeric `#1` for champ + contender
510
-
511
- ### 0.2.4
512
-
513
- - **Breaking:** replaced OpenAPI mass-generated tools with **15 curated outcome tools**
514
- - Stable JSON envelope + MCP server instructions
515
- - Fixed CS2 live path (`/cs2/live`); UFC in live fan-out
516
- - Composites with `partial[]` recovery; `call_api` path allowlist
517
- - Resources: `cito://capabilities`, `cito://llms.txt`, `cito://openapi.json`
518
-
519
- See [`_workflow/CHANGELOG-0.2.md`](_workflow/CHANGELOG-0.2.md) for the full 0.2 write-up.
1
+ # cito-mcp
2
+
3
+ Standalone [MCP](https://modelcontextprotocol.io) server for the [Cito esports API](https://api.citoapi.com) — **curated outcome tools** for agents building esports apps, dashboards, bots, and research flows.
4
+
5
+ **Version:** `0.2.4` · **Node:** `>=20` · **Install:** `npx cito-mcp`
6
+
7
+ Primary games: **lol · cs2 · dota2 · cod · ufc**. Fortnite and long-tail REST stay available via `call_api`.
8
+
9
+ ---
10
+
11
+ ## Philosophy: outcomes, not endpoints
12
+
13
+ v0.1 exposed ~100+ tools auto-generated from OpenAPI. Agents had to pick among thin path wrappers, invent IDs, and stitch multi-call UI screens themselves. That catalog was hard to select against and brittle across games.
14
+
15
+ **v0.2 ships 16 hand-authored tools** that answer *jobs* instead of mirroring REST:
16
+
17
+ | Job | Tool |
18
+ | --- | --- |
19
+ | What’s live right now? | `live_matches` |
20
+ | What’s coming up? | `upcoming_schedule` |
21
+ | Build a match card / recap | `match_summary` |
22
+ | Deep timeline / live state | `match_details` |
23
+ | Team page | `team_profile` |
24
+ | Player / fighter form | `player_profile` |
25
+ | Table / rankings | `standings` |
26
+ | Pre-match briefing | `match_preview` |
27
+ | Event / fight-night card | `event_card` |
28
+ | Rivalry record | `head_to_head` |
29
+ | Fighter / team photos | `event_card` · `player_profile` |
30
+ | Which raw REST route exists? | `list_routes` |
31
+ | Name → ID | `resolve_entity` / `search_entities` |
32
+
33
+ Composites multi-fetch server-side, return a **stable JSON envelope**, and isolate partial failures in `partial[]` so one bad secondary section does not fail the whole page.
34
+
35
+ **MCP is design-time / agent assistance.** Ship production backends with Cito REST + the user’s API key. Do not put multi-tenant traffic through this process.
36
+
37
+ ---
38
+
39
+ ## Install
40
+
41
+ ### One command (recommended)
42
+
43
+ ```bash
44
+ npx cito-mcp install --key cito_your_key_here
45
+ ```
46
+
47
+ Detects the MCP clients installed on your machine — Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI — and writes the config for each. Then restart your editor.
48
+
49
+ It is safe to re-run: existing config is merged, not replaced, your other MCP servers are left alone, a `.cito-bak` backup is written before the first change, and running it again just rotates the key rather than adding a second entry.
50
+
51
+ ```bash
52
+ npx cito-mcp install --dry-run # show the plan, write nothing
53
+ npx cito-mcp install --key … --client cursor # one client only
54
+ npx cito-mcp install --help
55
+ ```
56
+
57
+ Get a key at [citoapi.com/dashboard](https://citoapi.com/dashboard).
58
+
59
+ ### Manual — Claude Code
60
+
61
+ ```bash
62
+ claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" npx -y cito-mcp
63
+ ```
64
+
65
+ **Quote the `--`.** PowerShell 5.1 strips a bare `--` before the CLI sees it; because `-e` takes a variable number of values it then swallows `npx -y cito-mcp` as env vars and fails with `unknown option '-y'`. The quoted form works in PowerShell, cmd, bash and zsh alike. `npx cito-mcp install` avoids the problem entirely.
66
+
67
+ From a local clone (development):
68
+
69
+ ```bash
70
+ cd mcp
71
+ npm install
72
+ npm run build
73
+ claude mcp add cito -e CITO_API_KEY=cito_your_key_here "--" node "%CD%\dist\index.js"
74
+ ```
75
+
76
+ ### Cursor
77
+
78
+ Add to Cursor MCP settings (e.g. `.cursor/mcp.json` or Cursor Settings → MCP):
79
+
80
+ ```json
81
+ {
82
+ "mcpServers": {
83
+ "cito": {
84
+ "command": "npx",
85
+ "args": ["cito-mcp"],
86
+ "env": {
87
+ "CITO_API_KEY": "cito_your_key_here"
88
+ }
89
+ }
90
+ }
91
+ }
92
+ ```
93
+
94
+ Windows local clone:
95
+
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "cito": {
100
+ "command": "node",
101
+ "args": ["C:/Users/Owner/Projects/cito-api-scraper-windows/mcp/dist/index.js"],
102
+ "env": {
103
+ "CITO_API_KEY": "cito_your_key_here"
104
+ }
105
+ }
106
+ }
107
+ }
108
+ ```
109
+
110
+ ### Windsurf / other MCP hosts
111
+
112
+ Same shape as Cursor: `command` + `args` + `env.CITO_API_KEY`. Prefer `npx cito-mcp` so clients pick up published patches without a local install.
113
+
114
+ The server **exits immediately** if `CITO_API_KEY` is missing. The key is sent only as the `x-api-key` header and is never logged.
115
+
116
+ ---
117
+
118
+ ## Environment
119
+
120
+ | Variable | Required | Default | Description |
121
+ | --- | --- | --- | --- |
122
+ | `CITO_API_KEY` | **yes** | — | Cito API key → `x-api-key` on every upstream call |
123
+ | `CITO_API_BASE` | no | `https://api.citoapi.com/api/v1` | Override base URL (staging / self-hosted) |
124
+
125
+ ---
126
+
127
+ ## Preferred tool order
128
+
129
+ 1. Unsure → `list_capabilities` (optional `api_health` for tier / included games)
130
+ 2. Name without ID → `resolve_entity` (chain) or `search_entities` (browse)
131
+ 3. Live / upcoming → `live_matches` / `upcoming_schedule`
132
+ 4. Match card → `match_summary` (then `match_details` if needed)
133
+ 5. Team / player pages → `team_profile` / `player_profile`
134
+ 6. Tables / rivalry / preview / event card → `standings` / `head_to_head` / `match_preview` / `event_card`
135
+ 7. Escape hatch → `list_routes` to find a path, then `call_api` (allowlisted paths only)
136
+
137
+ **Never invent IDs** — resolve them or take them from live / schedule / search results.
138
+
139
+ Mnemonic: **resolve → live/schedule → summary → deep**.
140
+
141
+ ---
142
+
143
+ ## Tool catalog (16)
144
+
145
+ All tools are **read-only**. Names are `snake_case` with **no** `cito_` prefix (the server name already brands the surface).
146
+
147
+ | Tool | Outcome | When to use | When not to use | Key inputs |
148
+ | --- | --- | --- | --- | --- |
149
+ | `list_capabilities` | Catalog of tools, games, jobs, recipes (no network) | Session start; map UI screens to tools; filter by `game` / `job` | You already know the tool and have IDs | `game?`, `job?`, `q?`, `includeExamples?`, `includeRecipes?` |
150
+ | `api_health` | Reachability, key validity, tier, rate limits, optional game probes | Once per session; after 401/403/RATE_LIMIT; entitlement checks | Fetching live scores or entity data | `includeGameProbes?` |
151
+ | `resolve_entity` | Name → best typed id/slug (+ ranked candidates) | User named “T1”, “s1mple”, “IEM Cologne” without an ID; chaining into profiles | Already have a stable id/slug; large browse lists | `q`, `game?`, `type?`, `limit?` |
152
+ | `search_entities` | Paginated entity browse/search for one game | Typeahead / pickers; “list teams matching…” | Single-name resolve for chaining; full profile pages | `game`, `q?`, `type?`, `limit?`, `cursor?`, `activeOnly?` |
153
+ | `live_matches` | Live board (one game or all); CS2 uses `/cs2/live`; includes UFC | “What’s live?”; ops/dashboard strip | Upcoming fixtures; historical recaps | `game?` (`all` or omit), `limitPerGame?`, `includeLabelsOnly?` |
154
+ | `upcoming_schedule` | Upcoming fixtures/events with filters | “What’s on this week?”; team next matches | Live-only boards; deep match recaps | `game`, `hours?`, `from?`, `to?`, `team?`, `league?`, `tournamentId?`, `limit?`, `cursor?` |
155
+ | `match_summary` | Composite match card: score, performances, media stubs | Default match UI / recap after a known `matchId` | No matchId yet; pure pre-match → `match_preview`; deep timelines | `game`, `matchId`, `view?`, `includePlayerStats?`, `includeMedia?` |
156
+ | `match_details` | Deep sections: timeline, live state, maps, advanced | Analyst dive; live in-game window; full demo list | First-pass live board; simple chat recaps | `game`, `matchId`, `gameId?`, `sections?`, `includeTimeline?`, `includeLiveState?`, `includeAdvanced?` |
157
+ | `player_profile` | Player/fighter + form/trends/radar when available | “How is X playing?”; player page scaffold | Full roster → `team_profile`; unresolved name | `game`, `playerId` **or** `slug`, `recentLimit?`, `includeTrends?`, `view?`, `window?`, `role?` |
158
+ | `team_profile` | Team/org + roster + recent form | Team page / “who is on this roster?” | UFC fighters → `player_profile`; unresolved name; pure tables | `game`, `teamId` **or** `slug`, `recentLimit?`, `includeFormer?`, `view?` |
159
+ | `head_to_head` | Composed H2H (no first-class REST H2H) | Rivalry / series record; preview context | Single-side form only; live scores; standings | `game`, `sideA`, `sideB`, `entityType?`, `limit?`, `from?`, `to?` |
160
+ | `standings` | League/event tables or world/division rankings | Playoff picture; UFC rankings; CDL / CS2 tables | Team form; live scores; match recaps | `game`, `scope?`, `leagueId?`, `tournamentId?`, `eventId?`, `season?`, `stage?`, `division?`, `limit?` |
161
+ | `match_preview` | Pre-match briefing: sides, rosters/form, H2H stub | Upcoming deep link; pick’ems; preview cards | Completed recaps; deep live state | `game`, `matchId` **or** (`teamA` + `teamB`), `eventId?`, `includeH2H?`, `includeRosters?`, `recentLimit?` |
162
+ | `event_card` | Event / fight-night card: identity + bouts in card order (main event first), each corner with photos, record, nickname, weight class; optional rankings | UFC card, CS2 event hub, tournament overview | Live-only strip; single match recap | `game`, `eventIdOrSlug` **or** `q`, `includeBouts?`, `includeStandings?`, `limit?` |
163
+ | `list_routes` | Index of raw REST routes from the live OpenAPI spec (method, path, summary, tag) | Finding a long-tail path before `call_api`; checking an endpoint exists | A curated tool covers the outcome | `game?`, `q?`, `limit?` |
164
+ | `call_api` | Allowlisted raw REST (`data.raw`) | Fortnite / long-tail paths; payload debugging | Any job covered by a curated tool | `path`, `method?`, `queryJson?`, `bodyJson?` |
165
+
166
+ ### Images
167
+
168
+ Fighter and team sides carry an `images` object wherever upstream supplies one —
169
+ on `event_card` bout corners and on `player_profile`. No extra call, no N+1.
170
+
171
+ ```jsonc
172
+ "team1": {
173
+ "name": "Islam Makhachev",
174
+ "slug": "islam-makhachev",
175
+ "record": { "wins": 28, "losses": 1, "draws": 0, "text": "28-1-0 (W-L-D)" },
176
+ "championStatus": "champion",
177
+ "images": {
178
+ "headshotUrl": "https://ufc.com/…/MAKHACHEV_ISLAM_BELT_01-18.png",
179
+ "bodyImageUrl": "https://ufc.com/…/athlete_bio_full_body/…",
180
+ "imageUrl": "https://ufc.com/…/event_fight_card_upper_body/…",
181
+ "proxiedImageUrl": "https://api.citoapi.com/api/v1/public/images/ufc/aHR0cHM6…"
182
+ }
183
+ }
184
+ ```
185
+
186
+ **Use `proxiedImageUrl` in a browser.** `ufc.com` sends no CORS header and can
187
+ hotlink-block, so raw URLs render as broken images in a web UI. The proxied URL
188
+ is served by the API and is safe to put in an `<img src>`.
189
+
190
+ When a key is `null` the image does not exist for that entity; when the whole
191
+ `images` object is absent, upstream sent nothing for that side. The object is
192
+ never partially shaped — if any image exists, all four keys are present.
193
+
194
+ ### Games
195
+
196
+ | Game | Depth | Notes |
197
+ | --- | --- | --- |
198
+ | `lol` | deep | Team slugs; `lol-match-*`; no native global search |
199
+ | `cs2` | deep | Prefixed ids; live path **`GET /cs2/live`**; trends / rankings |
200
+ | `dota2` | thin | Numeric ids; radar; weak/no standings & roster endpoints |
201
+ | `cod` | medium | Org slugs; CDL standings; UUID match ids |
202
+ | `ufc` | medium | Fighter slugs; `boutId`; live + rankings |
203
+
204
+ ### UFC projection notes (0.2.4)
205
+
206
+ Hardened agent-facing UFC shapes (offline-tested):
207
+
208
+ - **`normalizeMatch`** reads `fighters[]` (`corner` + `fighterName` / `profile.name`), live `red`/`blue`, and `boutId` / `dataId` / bare `id`. Never keeps label `? vs ?` when fighter names exist (including blue-first arrays).
209
+ - **`live_matches`** uses `extractLiveRows`: prefer `liveBouts` (empty array = honest empty board); never promote supervisor `events[]` shells into match rows.
210
+ - **UFC empty board honesty:** when `count === 0`, section includes `note`, `emptyReason`, slim `health` (`workerAlive`, lag), optional non-live `supervisor` strip and `nextCard` (armed only). Also `data.note` + `meta.warnings` for single-game UFC. Do not treat empty as HTTP failure; do not invent `? vs ?` from event shells.
211
+ - **`upcoming_schedule`** expands event → bout rows with fighter labels; applies client-side **`hours` / `from` / `to`** (API has no `hours`); event shells without bouts use the **event name**, not `? vs ?`.
212
+ - **`event_card`** bouts share the same `normalizeMatch` path.
213
+ - **`standings`** maps division champions to rank **`C`** (`rankText: "C"`, interim **`IC`**); contender `#1` stays numeric `1` — no dual numeric `#1`.
214
+
215
+ Fortnite: **`call_api` only** until promoted into the primary enum.
216
+
217
+ ### `call_api` allowlist
218
+
219
+ Path must start with `/` and match one of:
220
+
221
+ `/health` · `/lol` · `/cs2` · `/dota2` · `/cod` · `/ufc` · `/fortnite`
222
+
223
+ Absolute URLs and `..` traversal → `PATH_NOT_ALLOWED`. Prefer curated tools for all standard jobs.
224
+
225
+ ---
226
+
227
+ ## Response envelope
228
+
229
+ Every tool returns one JSON object:
230
+
231
+ ```json
232
+ {
233
+ "ok": true,
234
+ "data": {},
235
+ "meta": {
236
+ "game": "cs2",
237
+ "source": "match_summary",
238
+ "fetchedAt": "2026-07-27T12:00:00.000Z",
239
+ "requestId": "mcp_…",
240
+ "tookMs": 120,
241
+ "upstreamCalls": 3,
242
+ "rateLimit": { "tier": "pro", "remaining": 54 }
243
+ },
244
+ "pagination": { "limit": 20, "hasMore": false, "nextCursor": null },
245
+ "partial": [],
246
+ "error": null
247
+ }
248
+ ```
249
+
250
+ | Condition | How to handle |
251
+ | --- | --- |
252
+ | `ok: false` | Tool-level failure; MCP `isError: true`; read `error.code` + `error.recover[]` |
253
+ | `ok: true` with `partial[]` | Use successful sections; **do not** treat as total failure |
254
+ | List tools | `data.items` + `pagination` (`limit`, `hasMore`, `nextCursor`, …) |
255
+
256
+ **Error codes:** `VALIDATION` · `NOT_FOUND` · `UNSUPPORTED_GAME` · `UNAUTHORIZED` · `RATE_LIMIT` · `UPSTREAM` · `PATH_NOT_ALLOWED` · `NOT_IMPLEMENTED`
257
+
258
+ **Ambiguity:** `resolve_entity` returns `ok: true` with `data.needsDisambiguation` + `data.candidates` — pick a candidate; do not wait for a hard error.
259
+
260
+ Retry only when `error.retryable` is true (typically `RATE_LIMIT`, `UPSTREAM`).
261
+
262
+ **Pagination:** default limit 20, max 50 (some tools clamp differently). Honor `pagination.hasMore` and pass `pagination.nextCursor` only — never invent cursors or reuse them after changing filters.
263
+
264
+ ---
265
+
266
+ ## Builder recipes
267
+
268
+ Use these as agent playbooks when scaffolding apps. Prefer one composite per screen over N+1 thin GETs.
269
+
270
+ ### 1. Live scoreboard
271
+
272
+ **Goal:** multi-game (or single-game) live strip with optional match drill-down.
273
+
274
+ ```
275
+ 1. api_health # optional — once per session
276
+ 2. live_matches { game: "all" } # or "cs2" / "lol" / …
277
+ 3. For a selected row:
278
+ match_summary { game, matchId } # default card
279
+ match_details { …, includeLiveState: true } # only if needed
280
+ ```
281
+
282
+ **UI map**
283
+
284
+ | Screen region | Source |
285
+ | --- | --- |
286
+ | Live rows (label, score, status) | `live_matches` → `data.sections[].items` |
287
+ | Expanded card | `match_summary` → `data.scoreline`, `playerPerformances`, `media` |
288
+ | In-game window | `match_details` sections `liveState` / `timeline` |
289
+
290
+ **Do not:** N+1 `match_details` for every live row; invent matchIds; use `upcoming_schedule` for live-only boards.
291
+
292
+ ### 2. Player profile page
293
+
294
+ **Goal:** identity, team, recent form for a named player or fighter.
295
+
296
+ ```
297
+ 1. resolve_entity { q: "s1mple", game: "cs2", type: "player" }
298
+ # or type: "fighter" for UFC
299
+ 2. player_profile {
300
+ game,
301
+ playerId | slug, # from resolve best/candidates
302
+ recentLimit: 10,
303
+ includeTrends: true,
304
+ view: "summary"
305
+ }
306
+ 3. Optional: head_to_head for rivalry context (fighters/teams)
307
+ ```
308
+
309
+ **UI map**
310
+
311
+ | Screen region | Source |
312
+ | --- | --- |
313
+ | Header / identity | `data.player` |
314
+ | Current team | `data.currentTeam` |
315
+ | Recent form list | `data.recentMatches` + `data.form` |
316
+ | Career / radar | `data.career`, `data.radar`, `data.seasonStats` (when present) |
317
+
318
+ **Do not:** invent playerIds; use `team_profile` for full rosters; skip resolve when the user only gave a display name.
319
+
320
+ ### 3. Event hub
321
+
322
+ **Goal:** schedule strip + standings/rankings + match previews for a league, tournament, or event.
323
+
324
+ ```
325
+ 1. list_capabilities { job: "schedule" } # optional orientation
326
+ 2. upcoming_schedule {
327
+ game: "cs2", # or lol / cod / ufc / dota2
328
+ hours: 168, # or from/to ISO window
329
+ league | tournamentId | team # scope filters as available
330
+ }
331
+ 3. standings {
332
+ game,
333
+ scope: "event" | "league" | "tournament" | "world" | "division",
334
+ eventId | leagueId | tournamentId | division | season
335
+ }
336
+ 4. For a featured upcoming match:
337
+ match_preview { game, matchId } # or teamA + teamB
338
+ 5. When a match goes live / completes:
339
+ match_summary { game, matchId }
340
+ ```
341
+
342
+ **UI map**
343
+
344
+ | Screen region | Source |
345
+ | --- | --- |
346
+ | Upcoming list | `upcoming_schedule` → `data.items` |
347
+ | Table / ranks | `standings` → `data.rows` |
348
+ | Featured match briefing | `match_preview` → `sideA` / `sideB` / `h2h` / `talkingPoints` |
349
+ | Live / completed card | `match_summary` |
350
+
351
+ **Notes:** Dota standings may return `NOT_IMPLEMENTED` or sparse data — fall back to schedule + profiles. UFC event hubs lean on fighter slugs, `boutId`, and `standings` with `scope: "division"`.
352
+
353
+ ### Other quick recipes (from `list_capabilities`)
354
+
355
+ | Recipe id | Steps |
356
+ | --- | --- |
357
+ | `live_ops_board` | `api_health` → `live_matches` → `match_summary` / `match_details` |
358
+ | `team_page` | `resolve_entity { type: "team" }` → `team_profile` |
359
+ | `match_center_completed` | schedule/live for `matchId` → `match_summary` → optional `match_details` |
360
+ | `app_scaffold` | `list_capabilities` ∥ `api_health` → sample composites → **ship REST in production** |
361
+
362
+ ---
363
+
364
+ ## Resources
365
+
366
+ | URI | Purpose |
367
+ | --- | --- |
368
+ | `cito://capabilities` | Static tool / game / workflow summary |
369
+ | `cito://llms.txt` | Live product agent context (may 404 upstream) |
370
+ | `cito://openapi.json` | Live public OpenAPI for **typed clients** — not for tool generation |
371
+
372
+ ---
373
+
374
+ ## Transports
375
+
376
+ **stdio** is the default (Claude Code, Cursor, Windsurf).
377
+
378
+ Optional **stateless Streamable HTTP**:
379
+
380
+ ```bash
381
+ CITO_API_KEY=cito_your_key_here node dist/index.js --http 8787
382
+ # → http://127.0.0.1:8787/mcp
383
+ ```
384
+
385
+ Hosted (production): `https://api.citoapi.com/mcp`
386
+ Send the user's Cito key as `x-api-key`. Initialize and `list_capabilities` work without a key so Smithery can scan.
387
+
388
+ ---
389
+
390
+ ## Migration from 0.1 (auto-generated tools)
391
+
392
+ **Breaking change.** `0.1.x` loaded OpenAPI at boot and mass-generated ~100+ tools (`generateAllTools`), plus a couple of hard-coded helpers (e.g. `cito_live_overview`, `cito_api_health`). Agents selected among thin REST wrappers and often reimplemented composition client-side.
393
+
394
+ | 0.1 pattern | 0.2 replacement |
395
+ | --- | --- |
396
+ | Generated per-path tools (`/cs2/matches/...`, etc.) | Outcome tools in the table above |
397
+ | `cito_live_overview` / ad-hoc live probes | `live_matches` (fixed CS2 path `/cs2/live`; UFC included) |
398
+ | `cito_api_health` | `api_health` |
399
+ | OpenAPI-named tools with `cito_` noise | **15** `snake_case` names, no `cito_` prefix |
400
+ | Raw HTTP-shaped responses | Stable envelope: `ok`, `data`, `meta`, `pagination`, `partial`, `error` |
401
+ | Agent stitches roster + matches + H2H | `team_profile`, `player_profile`, `head_to_head`, `match_preview` |
402
+ | Fortnite / niche paths as first-class tools | `call_api` allowlist |
403
+ | Spec cache / boot network for tool list | Static catalog; `list_capabilities` is offline |
404
+
405
+ **Action items for existing clients**
406
+
407
+ 1. Drop any hardcoded 0.1 tool names; rebind prompts to the 15-tool catalog.
408
+ 2. Always parse the envelope (`ok` / `partial` / `error.recover`) — do not assume bare REST JSON.
409
+ 3. Use `resolve_entity` before profile tools when you only have a display name.
410
+ 4. Prefer composites over reintroducing N+1 `call_api` loops.
411
+ 5. Bump config to `npx cito-mcp` (or rebuild from this package) and re-test live board + one profile + one match flow.
412
+
413
+ There is **no compatibility shim** for 0.1 tool names in 0.2.
414
+
415
+ ---
416
+
417
+ ## Development
418
+
419
+ ```bash
420
+ npm install
421
+ npm run build # tsc → dist/
422
+ npm test # node:test via tsx, offline (no network)
423
+ npm start # node dist/index.js (requires CITO_API_KEY)
424
+ ```
425
+
426
+ Source layout (authoritative tool registry: `src/tools/index.ts`):
427
+
428
+ ```
429
+ src/
430
+ index.ts # MCP wiring, resources, stdio / --http
431
+ client.ts # fetchJson, auth, present, cursors
432
+ envelope.ts # success / error envelopes, MCP isError
433
+ instructions.ts # server instructions for agents
434
+ tools/
435
+ index.ts # allTools (15)
436
+ meta.ts # list_capabilities, api_health, call_api
437
+ resolve.ts # resolve_entity, search_entities
438
+ live.ts # live_matches, upcoming_schedule
439
+ match.ts # match_summary, match_details
440
+ player.ts # player_profile
441
+ team.ts # team_profile, head_to_head
442
+ standings.ts # standings
443
+ insight.ts # match_preview, event_card
444
+ normalize.ts # cross-game normalization
445
+ types.ts # ToolDef, schemas
446
+ ```
447
+
448
+ ---
449
+
450
+ ## Publish notes
451
+
452
+ Package: **`cito-mcp@0.2.4`**
453
+
454
+ | Item | Value |
455
+ | --- | --- |
456
+ | npm name | `cito-mcp` |
457
+ | bin | `cito-mcp` → `dist/index.js` |
458
+ | published files | `dist/`, `README.md` (`package.json` `"files"`) |
459
+ | engines | `node >= 20` |
460
+ | runtime dependency | `@modelcontextprotocol/sdk` only |
461
+ | prepublish | `npm run prepublishOnly` → `npm run build` |
462
+
463
+ ### Pre-publish checklist
464
+
465
+ 1. `npm test` — offline suite green.
466
+ 2. `npm run build` — clean `dist/`.
467
+ 3. Smoke against a real key (not in CI by default):
468
+ - `api_health`
469
+ - `live_matches`
470
+ - `resolve_entity` (e.g. T1 / s1mple)
471
+ - `match_summary` with a real `matchId` from live/schedule
472
+ 4. Confirm `package.json` version and README match the shipped tool list.
473
+ 5. `npm publish` from `mcp/` (or your release pipeline) with appropriate npm auth / access.
474
+ `prepublishOnly` runs build + tests + smoke, so a broken build cannot ship.
475
+
476
+ ### Install line for docs & marketing
477
+
478
+ ```bash
479
+ npx cito-mcp install --key cito_…
480
+ ```
481
+
482
+ Manual fallback (note the quoted `--`, required for PowerShell):
483
+
484
+ ```bash
485
+ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
486
+ ```
487
+
488
+ ```json
489
+ { "command": "npx", "args": ["cito-mcp"], "env": { "CITO_API_KEY": "cito_…" } }
490
+ ```
491
+
492
+ ### Semver expectations
493
+
494
+ - **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
495
+ - Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
496
+ - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
497
+
498
+ ---
499
+
500
+ ## Changelog (summary)
501
+
502
+ ### 0.2.4
503
+
504
+ - **UFC projection hardening** (offline-tested):
505
+ - `normalizeMatch`: `fighters[]` corners + profile, live red/blue, `boutId`/`dataId`; never keep `? vs ?` when names exist
506
+ - `extractRows` / `extractLiveRows`: prefer `liveBouts` (including empty); never fake match rows from supervisor `events[]`
507
+ - `upcoming_schedule`: client-side `hours`/`from`/`to`; bout expansion with fighter labels; event shells labeled by event name
508
+ - `event_card` bouts share the same normalize path
509
+ - `standings`: champion rank `C` / interim `IC`; no dual numeric `#1` for champ + contender
510
+
511
+ ### 0.2.4
512
+
513
+ - **Breaking:** replaced OpenAPI mass-generated tools with **15 curated outcome tools**
514
+ - Stable JSON envelope + MCP server instructions
515
+ - Fixed CS2 live path (`/cs2/live`); UFC in live fan-out
516
+ - Composites with `partial[]` recovery; `call_api` path allowlist
517
+ - Resources: `cito://capabilities`, `cito://llms.txt`, `cito://openapi.json`
518
+
519
+ See [`_workflow/CHANGELOG-0.2.md`](_workflow/CHANGELOG-0.2.md) for the full 0.2 write-up.