cito-mcp 0.4.5 → 0.4.6

package/README.md

@@ -535,7 +535,7 @@ claude mcp add cito -e CITO_API_KEY=cito_… "--" npx -y cito-mcp
 ### Semver expectations
 
 - **0.2.4** is a **major surface break** vs 0.1 (tool rename + removal of OpenAPI mass-generation).
-- Further 0.2.x patches may refine envelopes and composite quality without renaming the 15 tools.
+- Further 0.2.x patches may refine envelopes and composite quality without renaming the shipped tools. (This line previously said "15 tools" while the catalog shipped 42 — the count here is intentionally not restated, because a number duplicated in prose drifts the moment the catalog changes.)
 - Promoting Fortnite (or other titles) into the primary `game` enum would be a minor feature bump with catalog/docs updates.
 
 ---

package/dist/client.js

@@ -102,6 +102,8 @@ export async function fetchJson(ctx, path, opts) {
     catch {
         data = text;
     }
+    if (!opts?.raw && response.ok && isTennisPath(path))
+        data = flattenTennisEnvelope(data);
     return {
         ok: response.ok,
         status: response.status,
@@ -158,6 +160,43 @@ export function asRecord(value) {
     }
     return null;
 }
+const TENNIS_LIST_META_KEYS = new Set(['count', 'limit', 'total', 'page', 'totalPages', 'hasNext', 'hasPrev']);
+function isTennisPath(path) {
+    return /^(\/api\/v1)?\/tennis(\/|\?|$)/.test(path);
+}
+function snakeKey(key) {
+    return key.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export function flattenTennisEnvelope(body) {
+    const env = asRecord(body);
+    if (!env || !('data' in env) || 'items' in env)
+        return body;
+    const meta = asRecord(env.meta);
+    if (!meta)
+        return body;
+    const success = env.success ?? true;
+    if (Array.isArray(env.data)) {
+        const out = { success, items: env.data };
+        for (const [key, value] of Object.entries(meta)) {
+            if (!TENNIS_LIST_META_KEYS.has(key))
+                out[snakeKey(key)] = value;
+        }
+        out.total = typeof meta.total === 'number' ? meta.total : env.data.length;
+        out.page = typeof meta.page === 'number' ? meta.page : 1;
+        out.page_size = typeof meta.limit === 'number' ? meta.limit : env.data.length;
+        if (typeof meta.totalPages === 'number')
+            out.total_pages = meta.totalPages;
+        if (typeof meta.hasNext === 'boolean')
+            out.has_next = meta.hasNext;
+        if (typeof meta.hasPrev === 'boolean')
+            out.has_prev = meta.hasPrev;
+        return out;
+    }
+    const resource = asRecord(env.data);
+    if (resource)
+        return { success, ...resource };
+    return body;
+}
 export function unwrapPayload(value) {
     let cur = value;
     for (let depth = 0; depth < 3; depth += 1) {

package/dist/instructions.js

@@ -1,77 +1,77 @@
-export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
-
-You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
-
-## Hard rules
-
-1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
-2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
-3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
-4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
-5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
-
-## Game parameter
-
-game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
-
-- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
-- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
-- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
-
-## Preferred tool order
-
-1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
-2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
-3. Live / upcoming → live_matches; upcoming_schedule.
-4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
-5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
-6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
-7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
-
-Mnemonic: resolve → live/schedule → summary → deep.
-
-## Parallel vs sequence
-
-Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
-
-Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
-
-Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
-
-## Pagination
-
-Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
-
-## Errors
-
-ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable.
-
-ok:true with partial[] → use successful sections; do not treat partial as total fail.
-ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
-resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
-
-## Recipes
-
-Live board: api_health (optional) → live_matches → match_summary for selected matchId.
-UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
-Team page: resolve_entity {type:team} → team_profile.
-Player card: resolve_entity {type:player|fighter} → player_profile.
-Fight night / event card: resolve_entity {type:event} → event_card {includeMatches:true} → match_preview for a featured bout.
-Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
-App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
-
-## Resources
-
-- cito://llms.txt — product context when available
-- cito://capabilities — catalog summary
-- cito://openapi.json — optional public OpenAPI fetch for typed clients
-
-## What not to do
-
-- Invent match/player/team IDs from memory.
-- Parallel-paginate the same list with different cursors.
-- N+1 match_details for every live row.
-- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
-- Ship production traffic through MCP.
-- Flood odds/timelines when a summary answers the question.
+export const SERVER_INSTRUCTIONS = `# Cito MCP — agent operating manual
+
+You are connected to Cito esports data (read-only). Prefer curated outcome tools over raw REST. Production apps must call Cito REST with the user's API key; use this MCP to design, prototype, and resolve IDs — not as a multi-tenant runtime bus.
+
+## Hard rules
+
+1. **Never invent IDs.** Do not guess matchId, gameId, playerId, team slug, eventId, or boutId. Always obtain IDs from a prior tool result (resolve, live, schedule, search, or list). If the user gives a name ("T1", "s1mple", "UFC 300"), call resolve_entity/search_entities first.
+2. **Resolve before deep.** Name → ID/slug → summary/page → deep stats. Skip resolve only when the user already provided a Cito ID/slug.
+3. **One screen, one composite.** Prefer a page/summary tool over stitching 4–6 thin GETs.
+4. **Honor the envelope.** Parse ok, data, pagination, partial, error, meta.rateLimit, meta.entities. Partial section failures are not total failures — use successful sections.
+5. **Read-only.** All curated tools are safe to retry except where error.retryable is false for bad args / entitlement.
+
+## Game parameter
+
+game enum (unless a tool documents otherwise): lol | cs2 | dota2 | ufc | cod | tennis | all
+
+- Default when the user named one title: that game. Default for "what's live?" / multi-title: omit game or all on tools that accept it.
+- On UNSUPPORTED_GAME / 403 for a title: stop retrying that game; call api_health; report plan gaps.
+- Fortnite and other titles may appear via call_api/resources; do not assume they are in the curated enum until list_capabilities says so.
+
+## Preferred tool order
+
+1. Unsure → list_capabilities (filter by game or job). Optional: api_health for key/tier/included games.
+2. Name without ID → resolve_entity (best match) or search_entities (browse). Reuse returned id/slug.
+3. Live / upcoming → live_matches; upcoming_schedule.
+4. Match UI / recap → match_summary first. match_details only for timelines, full maps, demos, live state.
+5. Team page → team_profile. Player form → player_profile. Tables/ranks → standings.
+6. Pre-match → match_preview. Rivalry → head_to_head. Event / fight-night card → event_card.
+7. Escape hatch → call_api (allowlisted path prefixes; prefer GET). Prefer curated tools.
+
+Mnemonic: resolve → live/schedule → summary → deep.
+
+## Parallel vs sequence
+
+Parallel-safe: independent reads (team_profile A ∥ team_profile B; live_matches ∥ api_health). Cap ~3–5 concurrent agent tools; check meta.rateLimit.remaining.
+
+Serial required: resolve → detail; pagination (cursor from page N only); live board → selected match deep-dive.
+
+Prefer server-side fan-out inside composites (partial[] recovery) over agent N+1.
+
+## Pagination
+
+Lists use pagination: { limit, offset?, total?, hasMore, nextCursor, prevCursor }. Default limit 20, max 50. Loop with cursor: pagination.nextCursor and the same filters. Never invent cursors. Empty list is ok:true with items:[].
+
+## Errors
+
+ok:false → read error.code (VALIDATION, NOT_FOUND, UNSUPPORTED_GAME, RATE_LIMIT, UNAUTHORIZED, UPSTREAM, PATH_NOT_ALLOWED, NOT_IMPLEMENTED). Follow error.recover[]. Retry only when retryable.
+
+ok:true with partial[] → use successful sections; do not treat partial as total fail.
+ok:true with meta.warnings[] → filters or depth degraded; do not assume ignored filters applied.
+resolve_entity ambiguity is soft: ok:true with data.needsDisambiguation and data.candidates — pick a candidate; do not wait for AMBIGUOUS_ENTITY.
+
+## Recipes
+
+Live board: api_health (optional) → live_matches → match_summary for selected matchId.
+UFC empty live (count=0): read section.note / emptyReason / health (workerAlive, lag) / supervisor / nextCard — do not claim "API offline" without workerAlive/lag; never invent matchups from supervisor shells.
+Team page: resolve_entity {type:team} → team_profile.
+Player card: resolve_entity {type:player|fighter} → player_profile.
+Fight night / event card: resolve_entity {type:event} → event_card {includeMatches:true} → match_preview for a featured bout.
+Match preview (named sides): resolve_entity each side (optional) → match_preview {teamA, teamB}.
+App scaffold: list_capabilities ∥ api_health ∥ live_matches, then one composite per screen.
+
+## Resources
+
+- cito://llms.txt — product context when available
+- cito://capabilities — catalog summary
+- cito://openapi.json — optional public OpenAPI fetch for typed clients
+
+## What not to do
+
+- Invent match/player/team IDs from memory.
+- Parallel-paginate the same list with different cursors.
+- N+1 match_details for every live row.
+- Retry UNSUPPORTED_GAME or VALIDATION unchanged.
+- Ship production traffic through MCP.
+- Flood odds/timelines when a summary answers the question.
 `;

package/dist/scrub.js

@@ -15,6 +15,50 @@ const INTERNAL_KEYS = new Set([
     'wikiUrl',
     'wiki_url',
     'jsonLd',
+    '_mergeSource',
+    '_provenance',
+    'duplicateOf',
+    'duplicate_of',
+    'identityConfidence',
+    'identity_confidence',
+    'roleSource',
+    'role_source',
+    'verifiedCompetitive',
+    'verified_competitive',
+    'profileAttemptedAt',
+    'profileFailureMessage',
+    'profileFailureReason',
+    'profileFetchStatus',
+    'profileImageAttemptedAt',
+    'profileImageAttempts',
+    'profileImageError',
+    'profileImageSteamAttemptedAt',
+    'profileImageWorker',
+    'ratingSource',
+    'requiredSourceData',
+    'rawText',
+    'raw_text',
+    'scrapedAt',
+    'scraped_at',
+    'sourceSummary',
+    'sourceNote',
+    'durableStatsTables',
+    'lineupSource',
+    'mapMediaSource',
+    'rosterSource',
+    'upstream',
+    'liveCandidateWindowMinutes',
+    'rowHash',
+    'row_hash',
+    'snapshotHash',
+    'snapshot_hash',
+    'syncRunId',
+    'sync_run_id',
+    'discoveredSources',
+    'sidecarAvailable',
+    'imageCandidates',
+    'image_candidates',
+    'source_url',
 ]);
 const SCRAPE_PARENTS = new Set(['dataAvailability', 'health']);
 const SCRAPE_KEYS = new Set(['strategy', 'samples']);

package/dist/tools/insight.js

@@ -260,20 +260,20 @@ export function composeH2H(game, sideA, sideB, rows, limit) {
 }
 export const matchPreview = {
     name: 'match_preview',
-    description: `COMPOSITE pre-match briefing: sides, roster/form snippets, H2H stub, event context — for pick'ems, articles, and match-page before state.
-
-When to use:
-- Upcoming match deep link
-- "Who should I watch before this game?"
-- App scaffold for preview cards
-
-Prefer over: manually chaining team_profile ×2 + head_to_head + schedule.
-Prefer match_summary when match is completed; match_details for live in-game.
-
-Do not use when: user wants final score/recap of a finished match.
-
-Parallel-safe: yes. Upstream cost: 4–8.
-Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
+    description: `COMPOSITE pre-match briefing: sides, roster/form snippets, H2H stub, event context — for pick'ems, articles, and match-page before state.
+
+When to use:
+- Upcoming match deep link
+- "Who should I watch before this game?"
+- App scaffold for preview cards
+
+Prefer over: manually chaining team_profile ×2 + head_to_head + schedule.
+Prefer match_summary when match is completed; match_details for live in-game.
+
+Do not use when: user wants final score/recap of a finished match.
+
+Parallel-safe: yes. Upstream cost: 4–8.
+Tennis H2H accepts an optional surface filter (Hard, Clay, Grass).
 Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "recentLimit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -707,31 +707,31 @@ async function resolveEventKey(ctx, game, q) {
 }
 export const eventCard = {
     name: 'event_card',
-    description: `COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet.
-
-When to use:
-- UFC fight night / numbered event page ("UFC 300 card", "Fight Night")
-- CS2 event hub with match list
-- Tournament/event overview before match_preview drill-down
-
-Bouts come back in card order — main event first, then prelims, then early prelims.
-Each bout carries weightClass, titleBout, card placement, and (once fought) result
-{ method, round, time, referee, winnerSlug }. Each corner carries images
-{ headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
-championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
-browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
-
-Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
-
-Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
-
-Do not use when: you only need live scores (live_matches); single finished match recap (match_summary); no event name/id yet and game unknown.
-
-Tennis: pass a tournament id/slug to get the draw bracket — rounds carry a round
-code (Q1..R128, QF, SF, F) with each match's players and score. Set is the
-primary tennis path here; there is no separate draw tool.
-
-Parallel-safe: yes. Upstream cost: 1–4.
+    description: `COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet.
+
+When to use:
+- UFC fight night / numbered event page ("UFC 300 card", "Fight Night")
+- CS2 event hub with match list
+- Tournament/event overview before match_preview drill-down
+
+Bouts come back in card order — main event first, then prelims, then early prelims.
+Each bout carries weightClass, titleBout, card placement, and (once fought) result
+{ method, round, time, referee, winnerSlug }. Each corner carries images
+{ headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
+championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
+browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
+
+Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
+
+Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
+
+Do not use when: you only need live scores (live_matches); single finished match recap (match_summary); no event name/id yet and game unknown.
+
+Tennis: pass a tournament id/slug to get the draw bracket — rounds carry a round
+code (Q1..R128, QF, SF, F) with each match's players and score. Set is the
+primary tennis path here; there is no separate draw tool.
+
+Parallel-safe: yes. Upstream cost: 1–4.
 Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "includeStandings": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/live.js

@@ -154,20 +154,20 @@ function slimUfcNextCard(payload) {
 }
 export const liveMatches = {
     name: 'live_matches',
-    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
-
-When to use:
-- "What's live right now?"
-- Ops/dashboard live strip
-
-Prefer over: sequential per-game call_api live probes.
-
-Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
-
-CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
-UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
-
-Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
+    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
+
+When to use:
+- "What's live right now?"
+- Ops/dashboard live strip
+
+Prefer over: sequential per-game call_api live probes.
+
+Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
+
+CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
+
+Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
     inputSchema: {
         type: 'object',
@@ -347,24 +347,24 @@ Example: { "game": "all", "limitPerGame": 10 }`,
 };
 export const upcomingSchedule = {
     name: 'upcoming_schedule',
-    description: `Upcoming matches/events for one game, with game-specific filters.
-
-When to use:
-- "What's on this week?"
-- Calendar UI; team next matches
-
-Prefer over: live_matches for not-yet-started fixtures.
-
-Do not use when: only in-progress matches needed → live_matches.
-
-Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
-- lol: hours, team (slug), league (slug)
-- cs2: team, from, to (ISO); hours not applied upstream
-- cod: team, tournamentId
-- dota2: limit/cursor primarily; team may be client-filtered where data allows
-- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `Upcoming matches/events for one game, with game-specific filters.
+
+When to use:
+- "What's on this week?"
+- Calendar UI; team next matches
+
+Prefer over: live_matches for not-yet-started fixtures.
+
+Do not use when: only in-progress matches needed → live_matches.
+
+Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
+- lol: hours, team (slug), league (slug)
+- cs2: team, from, to (ISO); hours not applied upstream
+- cod: team, tournamentId
+- dota2: limit/cursor primarily; team may be client-filtered where data allows
+- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
+
+Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
     inputSchema: {
         type: 'object',

package/dist/tools/match.js

@@ -163,18 +163,18 @@ function primaryPath(game, matchId) {
 }
 export const matchSummary = {
     name: 'match_summary',
-    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
-
-When to use:
-- Match recap / default match UI
-- After user selects a live or completed matchId
-
-Prefer over match_details for chat answers and default UIs.
-Prefer match_details for timelines, full map trees, live state, advanced packages.
-
-Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `COMPOSITE match card: scoreline, key context, player performances, and VOD/demo links when available.
+
+When to use:
+- Match recap / default match UI
+- After user selects a live or completed matchId
+
+Prefer over match_details for chat answers and default UIs.
+Prefer match_details for timelines, full map trees, live state, advanced packages.
+
+Do not use when: no matchId yet (resolve from live/schedule); pure pre-match → match_preview.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "matchId": "cs2-match-123", "view": "summary", "includePlayerStats": true }`,
     inputSchema: {
         type: 'object',
@@ -586,23 +586,23 @@ export function summarizeTennisMatchStats(data) {
 }
 export const matchDetails = {
     name: 'match_details',
-    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
-
-When to use:
-- Analyst deep dive
-- Live in-game window (LoL/CS2/UFC)
-- Full demo list
-
-Prefer over match_summary only when summary is insufficient.
-Prefer match_summary for short answers and default cards.
-
-Do not use when: first-pass live board (use live_matches + match_summary).
-
-Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
-UFC betting lines: sections:["odds"] (opt-in, never in the default set).
-If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
-
-Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
+    description: `Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory.
+
+When to use:
+- Analyst deep dive
+- Live in-game window (LoL/CS2/UFC)
+- Full demo list
+
+Prefer over match_summary only when summary is insufficient.
+Prefer match_summary for short answers and default cards.
+
+Do not use when: first-pass live board (use live_matches + match_summary).
+
+Section selection: pass includeTimeline / includeLiveState / includeAdvanced booleans, OR an explicit sections[] list.
+UFC betting lines: sections:["odds"] (opt-in, never in the default set).
+If sections[] is non-empty it wins (booleans are ignored). LoL liveState/advanced require gameId.
+
+Parallel-safe: yes. Upstream cost: 1–8 (section-gated).
 Example: { "game": "lol", "matchId": "lol-match-1", "includeTimeline": true, "includeLiveState": false }`,
     inputSchema: {
         type: 'object',

package/dist/tools/meta.js

@@ -834,7 +834,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 });
             }
         }
-        const res = await fetchJson(ctx, path, { method, query });
+        const res = await fetchJson(ctx, path, { method, query, raw: true });
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),

package/dist/tools/player.js

@@ -44,17 +44,17 @@ function identityFrom(game, raw, idHint, slugHint) {
 }
 export const playerProfile = {
     name: 'player_profile',
-    description: `Player or UFC fighter profile: identity, current team, recent matches, and form/trends/radar when available.
-
-When to use:
-- "How is X playing lately?"
-- Player page scaffold; form inputs for previews
-
-Prefer over: manual multi-call career/trends/matches via call_api.
-
-Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
-
-Parallel-safe: yes. Upstream cost: 2–5.
+    description: `Player or UFC fighter profile: identity, current team, recent matches, and form/trends/radar when available.
+
+When to use:
+- "How is X playing lately?"
+- Player page scaffold; form inputs for previews
+
+Prefer over: manual multi-call career/trends/matches via call_api.
+
+Do not use when: full team roster needed → team_profile; unresolved name → resolve_entity first.
+
+Parallel-safe: yes. Upstream cost: 2–5.
 Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includeTrends": true }`,
     inputSchema: {
         type: 'object',
@@ -541,17 +541,17 @@ function normalizeFormMatch(row) {
 }
 export const playerForm = {
     name: 'player_form',
-    description: `Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows (opponent, score, surface). Optional surface filter (Hard/Clay/Grass).
-
-When to use:
-- "How is X playing lately?"; current streak; surface-specific record (e.g. clay last 5).
-
-Prefer over: player_profile (identity + career aggregates, no streak); raw form via call_api for agent-normalized rows.
-
-Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
-
-Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
-
+    description: `Tennis player form: W/L record over the last N completed matches, current win/loss streak, and per-match rows (opponent, score, surface). Optional surface filter (Hard/Clay/Grass).
+
+When to use:
+- "How is X playing lately?"; current streak; surface-specific record (e.g. clay last 5).
+
+Prefer over: player_profile (identity + career aggregates, no streak); raw form via call_api for agent-normalized rows.
+
+Do not use when: career totals/titles → player_profile with game tennis (wires /stats); ranking deltas → rankings_movers.
+
+Tennis-only. Limit defaults to 10 (max 50, matching the API). Upstream rows arrive newest-first; the streak is the leading run of that order.
+
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -700,18 +700,18 @@ Parallel-safe: yes. Upstream cost: 1.`,
 };
 export const playerMatches = {
     name: 'player_matches',
-    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
-
-When to use:
-- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
-
-Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
-
-Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
-
-Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
-surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
-
+    description: `Tennis player match log: every archived match for one player, newest first, with opponent, tournament, round, surface and score.
+
+When to use:
+- "Show me Shelton's last 20 matches"; full match history; every match at a given tournament; filtering a player's record by surface.
+
+Prefer over: player_form (a W/L summary with a small window and a streak, not the log); call_api for /tennis/players/{id}/matches.
+
+Do not use when: aggregate totals, titles, or win% → player_stats; identity → player_profile; one match's box score → match_details.
+
+Tennis-only. Limit defaults to 20 (max 50). Rows arrive newest-first. Use
+surface to narrow to Hard/Clay/Grass; tournamentId pins one event.
+
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
         type: 'object',
@@ -869,16 +869,16 @@ Parallel-safe: yes. Upstream cost: 1.`,
 };
 export const playerStats = {
     name: 'player_stats',
-    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
-
-When to use:
-- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
-
-Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
-
-Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
-
-Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
+    description: `Tennis player career statistics: W/L totals, win percentage, titles, Grand Slam and Masters titles, plus per-surface and per-level breakdowns. Optional surface/year filters.
+
+When to use:
+- "How many titles does Alcaraz have?"; career win%; Grand Slam title count; record on clay; a season-scoped record.
+
+Prefer over: player_profile (identity + a summary block, no breakdowns); player_matches (individual rows, no aggregates).
+
+Do not use when: the match log → player_matches; ranking over time → player_rankings_history.
+
+Tennis-only. Filters are surface (Hard/Clay/Grass/Carpet) and yearFrom/yearTo.
 Upstream cost: 1.`,
     inputSchema: {
         type: 'object',

package/dist/tools/standings.js

@@ -77,26 +77,26 @@ export function normalizeStandingRow(row, index) {
 }
 export const standings = {
     name: 'standings',
-    description: `League/event standings or world/division rankings normalized to ranked rows.
-
-When to use:
-- Table / playoff picture
-- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
-
-Prefer over: raw standings via call_api for agent-normalized rows.
-
-Do not use when: single team form → team_profile; live scores → live_matches.
-Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
-
-Required scope keys by game:
-- lol: leagueId OR tournamentId
-- cs2: omit for world rankings; eventId for event standings
-- cod: optional season/stage
-- ufc: optional division (scope=division)
-- tennis: optional division (ATP or WTA tour; default ATP)
-- dota2: best-effort worldRanking only
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `League/event standings or world/division rankings normalized to ranked rows.
+
+When to use:
+- Table / playoff picture
+- UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
+
+Prefer over: raw standings via call_api for agent-normalized rows.
+
+Do not use when: single team form → team_profile; live scores → live_matches.
+Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
+
+Required scope keys by game:
+- lol: leagueId OR tournamentId
+- cs2: omit for world rankings; eventId for event standings
+- cod: optional season/stage
+- ufc: optional division (scope=division)
+- tennis: optional division (ATP or WTA tour; default ATP)
+- dota2: best-effort worldRanking only
+
+Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "cod", "season": "2026", "limit": 50 }`,
     inputSchema: {
         type: 'object',

package/dist/tools/team.js

@@ -31,18 +31,18 @@ function numberOrNull(value) {
 }
 export const teamProfile = {
     name: 'team_profile',
-    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
-
-When to use:
-- Team page / "who is on this roster?"
-- Builder team screen sample
-
-Prefer over: separate roster + matches + detail via call_api.
-
-Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
-Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+Prefer over: separate roster + matches + detail via call_api.
+
+Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
+Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -532,19 +532,19 @@ function winnerSide(match, a) {
 }
 export const headToHead = {
     name: 'head_to_head',
-    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
-
-When to use:
-- Rivalry / series record questions
-- Supporting context for previews
-
-Prefer over: agent-side double match-list filtering.
-
-Do not use when: single-side form only → team_profile or player_profile.
-
-Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
-
-Parallel-safe: yes. Upstream cost: 2–4.
+    description: `Composed head-to-head record between two teams, two UFC fighters, or two tennis players. No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+Do not use when: single-side form only → team_profile or player_profile.
+
+Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
+
+Parallel-safe: yes. Upstream cost: 2–4.
 Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -960,18 +960,18 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
 };
 export const h2hMatrix = {
     name: 'h2h_matrix',
-    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
-
-When to use:
-- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
-- Group-stage or semifinal-field comparisons
-
-Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
-
-Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
-
-Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
-
+    description: `Multi-player tennis head-to-head grid: every pair's series record in one comparison matrix.
+
+When to use:
+- Draw/field analysis: how each contender fares against every other (e.g. Alcaraz vs Zverev vs Sinner round-robin records)
+- Group-stage or semifinal-field comparisons
+
+Prefer over: N head_to_head calls for an N-player field; raw matrix via call_api.
+
+Do not use when: a two-player rivalry deep-dive with tiebreak/decider splits → head_to_head; season stat leaders → leaderboard_*; rankings → standings.
+
+Tennis-only. players takes 2-16 ids or names (names resolve via player search). Each matrix cell is "W-L" from the row player's perspective, "-" on the diagonal.
+
 Parallel-safe: yes. Upstream cost: 1 + one search per unresolved name.`,
     inputSchema: {
         type: 'object',

package/package.json

@@ -1,8 +1,28 @@
 {
   "name": "cito-mcp",
-  "version": "0.4.5",
-  "description": "Standalone MCP server for the Cito esports and sports API — 42 curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
+  "version": "0.4.6",
+  "description": "Standalone MCP server for the Cito esports and sports API — curated outcome tools for agents (live scoreboards, round economy, opening duels, clutches, vetoes, rosters, tennis, mma).",
   "type": "module",
+  "homepage": "https://cito.gg",
+  "//REPOSITORY": "Intentionally NOT set. cito-api-scraper and cito.gg are PRIVATE repos and must stay that way, so a repository URL pointing at them would render as a broken 404 link on the public npm page and would not satisfy MCP Registry npm ownership validation. Set this only if a PUBLIC repo for this package is ever created (e.g. achillesscriptsvip/cito-mcp with this directory as root) — then use `git+https://github.com/OWNER/REPO.git` and mirror it in the `mcpName`/server.json `name` pair. Do not point it at the private monorepo.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "esports",
+    "cs2",
+    "counter-strike",
+    "counter-strike-2",
+    "lol",
+    "league-of-legends",
+    "dota2",
+    "cod",
+    "ufc",
+    "mma",
+    "tennis",
+    "live-scores",
+    "sports-data",
+    "esports-api"
+  ],
   "bin": {
     "cito-mcp": "dist/index.js"
   },