cito-mcp 0.5.8 → 0.6.1

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.
@@ -31,7 +31,7 @@ function pushCandidates(out, game, type, rows, q, limit) {
31
31
  let matchedBy;
32
32
  if (q && score <= 0 && index === 0) {
33
33
  score = 95;
34
- matchedBy = 'upstream-first';
34
+ matchedBy = 'top-hit';
35
35
  }
36
36
  const secondary = {};
37
37
  for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
@@ -366,7 +366,7 @@ async function searchGame(ctx, game, q, type, limit) {
366
366
  candidates,
367
367
  calls,
368
368
  error: partialFromRejection(`game:${game}`, {
369
- code: 'UPSTREAM',
369
+ code: 'SERVICE_ERROR',
370
370
  message: e.message,
371
371
  }),
372
372
  };
@@ -376,20 +376,20 @@ async function searchGame(ctx, game, q, type, limit) {
376
376
  }
377
377
  export const resolveEntity = {
378
378
  name: 'resolve_entity',
379
- description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
380
-
381
- When to use:
382
- - User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
383
- - Need a canonical id/slug before profile or match tools
384
-
385
- Prefer over search_entities when you want one best match (or small ranked set) to chain.
386
- Prefer search_entities when browsing many results with pagination.
387
-
388
- Do not use when: you already have a stable id/slug from a prior tool.
389
-
390
- Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
391
-
392
- Parallel-safe: yes. Upstream cost: 1–5.
379
+ description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
380
+
381
+ When to use:
382
+ - User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
383
+ - Need a canonical id/slug before profile or match tools
384
+
385
+ Prefer over search_entities when you want one best match (or small ranked set) to chain.
386
+ Prefer search_entities when browsing many results with pagination.
387
+
388
+ Do not use when: you already have a stable id/slug from a prior tool.
389
+
390
+ Empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true — pick from candidates or refine q/game/type. Does not emit AMBIGUOUS_ENTITY as a hard error.
391
+
392
+ Parallel-safe: yes. API calls: 1–5.
393
393
  Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
394
394
  inputSchema: {
395
395
  type: 'object',
@@ -441,11 +441,11 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
441
441
  ? [gameParse.game]
442
442
  : [...PRIMARY_GAMES];
443
443
  const partial = [];
444
- let upstreamCalls = 0;
444
+ let apiCalls = 0;
445
445
  const all = [];
446
446
  const results = await Promise.all(games.map((g) => searchGame(ctx, g, q, type, limit)));
447
447
  for (const r of results) {
448
- upstreamCalls += r.calls;
448
+ apiCalls += r.calls;
449
449
  all.push(...r.candidates);
450
450
  if (r.error)
451
451
  partial.push(r.error);
@@ -469,7 +469,7 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
469
469
  game: best?.game ?? gameParse.game ?? null,
470
470
  requestId,
471
471
  tookMs: Date.now() - started,
472
- upstreamCalls,
472
+ apiCalls,
473
473
  partial: partial.length ? partial : undefined,
474
474
  entities: best
475
475
  ? {
@@ -492,22 +492,22 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
492
492
  };
493
493
  export const searchEntities = {
494
494
  name: 'search_entities',
495
- description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
496
-
497
- When to use:
498
- - Typeahead / pickers
499
- - "List teams matching…"
500
- - Exploring entities without committing to one ID
501
- - UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
502
-
503
- Prefer over resolve_entity when the user wants a list.
504
- Prefer resolve_entity when chaining one name into a profile tool.
505
-
506
- Do not use when: fetching a known entity profile — use team_profile or player_profile.
507
-
508
- UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
509
-
510
- Parallel-safe: yes. Upstream cost: 1–3.
495
+ description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
496
+
497
+ When to use:
498
+ - Typeahead / pickers
499
+ - "List teams matching…"
500
+ - Exploring entities without committing to one ID
501
+ - UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
502
+
503
+ Prefer over resolve_entity when the user wants a list.
504
+ Prefer resolve_entity when chaining one name into a profile tool.
505
+
506
+ Do not use when: fetching a known entity profile — use team_profile or player_profile.
507
+
508
+ UFC: with q set, results are ranked (exact name > multi-token match > nickname). "Jon Jones" should return jon-jones first — never the generic P4P list.
509
+
510
+ Parallel-safe: yes. API calls: 1–3.
511
511
  Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
512
512
  inputSchema: {
513
513
  type: 'object',
@@ -549,10 +549,10 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
549
549
  const offset = typeof cursor?.offset === 'number' ? cursor.offset : 0;
550
550
  const activeOnly = args.activeOnly !== false;
551
551
  let items = [];
552
- let upstreamCalls = 0;
552
+ let apiCalls = 0;
553
553
  let total = null;
554
- let upstreamPaged = true;
555
- let preserveUpstreamOrder = false;
554
+ let apiPaged = true;
555
+ let preserveApiOrder = false;
556
556
  const pageQuery = (extra = {}) => ({
557
557
  limit,
558
558
  offset,
@@ -563,7 +563,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
563
563
  });
564
564
  async function listPath(path, entityType, extra = {}) {
565
565
  const res = await fetchJson(ctx, path, { query: pageQuery(extra) });
566
- upstreamCalls += 1;
566
+ apiCalls += 1;
567
567
  if (!res.ok) {
568
568
  throw Object.assign(new Error(`HTTP ${res.status}`), {
569
569
  status: res.status,
@@ -592,7 +592,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
592
592
  else if (game === 'cs2') {
593
593
  if (q && (type === 'any' || !['team', 'player', 'event'].includes(type))) {
594
594
  const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
595
- upstreamCalls += 1;
595
+ apiCalls += 1;
596
596
  if (res.ok) {
597
597
  const envelope = asRecord(res.data) ?? {};
598
598
  const data = asRecord(envelope.data) ?? envelope;
@@ -625,7 +625,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
625
625
  else if (game === 'dota2') {
626
626
  if (q) {
627
627
  const res = await fetchJson(ctx, '/dota2/search', { query: { q, limit } });
628
- upstreamCalls += 1;
628
+ apiCalls += 1;
629
629
  if (res.ok) {
630
630
  const data = asRecord(res.data) ?? {};
631
631
  if (type === 'team' || type === 'any')
@@ -648,18 +648,18 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
648
648
  else if (game === 'tennis') {
649
649
  if (type === 'player' || type === 'any') {
650
650
  const res = await fetchJson(ctx, '/tennis/players/search', { query: { q, limit } });
651
- upstreamCalls += 1;
651
+ apiCalls += 1;
652
652
  if (res.ok) {
653
653
  const envelope = asRecord(res.data) ?? {};
654
654
  const data = asRecord(envelope.data) ?? envelope;
655
655
  items.push(...extractRows(data.items ?? data).map((r) => entityRef(r, 'player', game)));
656
656
  if (q)
657
- preserveUpstreamOrder = true;
657
+ preserveApiOrder = true;
658
658
  }
659
659
  }
660
660
  if (type === 'tournament' || type === 'event' || type === 'any') {
661
661
  const res = await fetchJson(ctx, '/tennis/competitions', { query: { q, page_size: limit } });
662
- upstreamCalls += 1;
662
+ apiCalls += 1;
663
663
  if (res.ok) {
664
664
  const envelope = asRecord(res.data) ?? {};
665
665
  const data = asRecord(envelope.data) ?? envelope;
@@ -669,11 +669,11 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
669
669
  }
670
670
  else if (game === 'cod') {
671
671
  if (q) {
672
- upstreamPaged = false;
672
+ apiPaged = false;
673
673
  const res = await fetchJson(ctx, '/cod/search', {
674
674
  query: { q, limit, ...(type !== 'any' ? { type: type === 'team' ? 'org' : type } : {}) },
675
675
  });
676
- upstreamCalls += 1;
676
+ apiCalls += 1;
677
677
  if (res.ok)
678
678
  items.push(...extractRows(res.data).map((r) => entityRef(r, type === 'any' ? 'unknown' : type, game)));
679
679
  }
@@ -688,9 +688,9 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
688
688
  }
689
689
  else if (game === 'ufc') {
690
690
  if (q) {
691
- upstreamPaged = false;
691
+ apiPaged = false;
692
692
  const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
693
- upstreamCalls += 1;
693
+ apiCalls += 1;
694
694
  if (!res.ok) {
695
695
  throw Object.assign(new Error(`HTTP ${res.status}`), {
696
696
  status: res.status,
@@ -761,7 +761,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
761
761
  source: 'search_entities',
762
762
  requestId,
763
763
  tookMs: Date.now() - started,
764
- upstreamCalls,
764
+ apiCalls,
765
765
  httpStatus: e.status,
766
766
  rateLimit: e.headers,
767
767
  });
@@ -777,7 +777,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
777
777
  const scoreOf = (it) => typeof it.meta?.score === 'number'
778
778
  ? it.meta.score
779
779
  : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
780
- const upstreamTotal = total;
780
+ const unfilteredTotal = total;
781
781
  let droppedBelowFloor = [];
782
782
  const ENTITY_TYPES = new Set(['player', 'team', 'fighter']);
783
783
  const protectedRow = q ? items.find((it) => ENTITY_TYPES.has(it.type)) ?? null : null;
@@ -792,26 +792,26 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
792
792
  meta: {
793
793
  ...(it.meta ?? {}),
794
794
  score: raw,
795
- ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'upstream-first' } : {}),
795
+ ...(isProtected && raw < RELEVANCE_FLOOR ? { matchedBy: 'top-hit' } : {}),
796
796
  },
797
797
  };
798
798
  });
799
- const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'upstream-first';
799
+ const keep = (it) => it.meta?.score >= RELEVANCE_FLOOR || it.meta?.matchedBy === 'top-hit';
800
800
  droppedBelowFloor = items
801
801
  .filter((it) => !keep(it))
802
802
  .map((it) => ({ id: it.id, name: it.name, score: it.meta?.score }));
803
803
  if (droppedBelowFloor.length)
804
804
  items = items.filter(keep);
805
805
  }
806
- if (q && !preserveUpstreamOrder) {
806
+ if (q && !preserveApiOrder) {
807
807
  items.sort((a, b) => {
808
- const am = a.meta?.matchedBy === 'upstream-first' ? 1 : 0;
809
- const bm = b.meta?.matchedBy === 'upstream-first' ? 1 : 0;
808
+ const am = a.meta?.matchedBy === 'top-hit' ? 1 : 0;
809
+ const bm = b.meta?.matchedBy === 'top-hit' ? 1 : 0;
810
810
  return bm - am || scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name);
811
811
  });
812
812
  }
813
- const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
814
- const hasMore = upstreamPaged
813
+ const pageItems = apiPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
814
+ const hasMore = apiPaged
815
815
  ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
816
816
  : offset + pageItems.length < items.length;
817
817
  const floorWarnings = [];
@@ -820,8 +820,8 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
820
820
  .slice(0, 5)
821
821
  .map((d) => `${d.name} (${d.id})`)
822
822
  .join(', ');
823
- floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all — the upstream search is a ` +
824
- `substring match with no relevance floor, so it pads every page: ${sample}. ` +
823
+ floorWarnings.push(`Dropped ${droppedBelowFloor.length} result(s) that do not match "${q}" at all (the name search is a ` +
824
+ `substring match with no relevance floor, so it pads every page): ${sample}. ` +
825
825
  `If one of these is what you wanted, query it by name or id directly.`);
826
826
  }
827
827
  return successEnvelope({
@@ -829,7 +829,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
829
829
  game,
830
830
  requestId,
831
831
  tookMs: Date.now() - started,
832
- upstreamCalls,
832
+ apiCalls,
833
833
  warnings: floorWarnings.length ? floorWarnings : undefined,
834
834
  pagination: {
835
835
  limit,
@@ -849,7 +849,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
849
849
  matched: items.length,
850
850
  droppedBelowFloor: droppedBelowFloor.length,
851
851
  dropped: droppedBelowFloor.slice(0, 25),
852
- upstreamTotal: upstreamTotal ?? null,
852
+ unfilteredTotal: unfilteredTotal ?? null,
853
853
  },
854
854
  }
855
855
  : {}),
@@ -54,7 +54,7 @@ export const tennisSchedule = {
54
54
  When to use:
55
55
  - "What tennis is on today?"; a specific day's fixtures; results completed on a given date; building a daily digest.
56
56
 
57
- Prefer over: call_api for /tennis/schedule and /tennis/matches/completed (both require ?date=, which this tool supplies and validates); live_matches (in-progress only, right now); upcoming_schedule (a forward window, not a specific day).
57
+ Prefer over: call_api for /tennis/schedule and /tennis/matches/completed (this tool supplies and validates the date, and bounds the rows); live_matches (in-progress only, right now); upcoming_schedule (a forward window, not a specific day).
58
58
 
59
59
  Do not use when: matches currently in play → live_matches; a named player's history → player_matches.
60
60
 
@@ -62,13 +62,14 @@ Tennis-only. 'date' defaults to today (UTC) and MUST be YYYY-MM-DD. Choose with
62
62
  'include': both (default), scheduled, or completed. Both halves are fetched in
63
63
  parallel, so either can fail on its own without losing the other.
64
64
 
65
- 'limit' bounds EACH half (the completed route ignores ?limit= upstream, so the
66
- bound is applied here); scheduledCount/completedCount report how many rows the
65
+ 'limit' bounds EACH half (the bound is applied by this tool); scheduledCount/completedCount report how many rows the
67
66
  day held and *Returned how many came back. The two halves overlap: the day's
68
67
  list includes matches already played, so the same matchId can appear in both —
69
68
  see the overlap block before de-duplicating or counting.
70
69
 
71
- Parallel-safe: yes. Upstream cost: 1 or 2.`,
70
+ Rows: start_time_known false means no start time is held (scheduled_at is then midnight). start_time_kind says whether scheduled_at is when the match actually started (actual) or the published order-of-play time (scheduled). Read status for where a match is now and outcome for how it ended.
71
+
72
+ Parallel-safe: yes. API calls: 1 or 2.`,
72
73
  inputSchema: {
73
74
  type: 'object',
74
75
  additionalProperties: false,
@@ -133,13 +134,13 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
133
134
  const limit = clampInt(args.limit, 20, 1, 50);
134
135
  const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
135
136
  const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
136
- const upstreamPage = 500;
137
+ const apiPage = 500;
137
138
  const settled = await Promise.allSettled([
138
139
  wantScheduled
139
- ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: upstreamPage } })
140
+ ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: apiPage } })
140
141
  : Promise.resolve(null),
141
142
  wantCompleted
142
- ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: upstreamPage } })
143
+ ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: apiPage } })
143
144
  : Promise.resolve(null),
144
145
  ]);
145
146
  const rejected = [];
@@ -172,7 +173,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
172
173
  else if (schedRes.status === 'rejected') {
173
174
  rejected.push({
174
175
  section: 'schedule',
175
- code: 'UPSTREAM',
176
+ code: 'SERVICE_ERROR',
176
177
  message: String(schedRes.reason).slice(0, 200),
177
178
  });
178
179
  }
@@ -194,7 +195,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
194
195
  else if (compRes.status === 'rejected') {
195
196
  rejected.push({
196
197
  section: 'completed',
197
- code: 'UPSTREAM',
198
+ code: 'SERVICE_ERROR',
198
199
  message: String(compRes.reason).slice(0, 200),
199
200
  });
200
201
  }
@@ -207,7 +208,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
207
208
  source: 'tennis_schedule',
208
209
  requestId,
209
210
  tookMs: Date.now() - started,
210
- upstreamCalls: rejected.length,
211
+ apiCalls: rejected.length,
211
212
  recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
212
213
  });
213
214
  }
@@ -254,14 +255,14 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
254
255
  }
255
256
  : {}),
256
257
  };
257
- const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
258
+ const apiCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
258
259
  if (rejected.length > 0) {
259
260
  return successEnvelope({
260
261
  source: 'tennis_schedule',
261
262
  game,
262
263
  requestId,
263
264
  tookMs: Date.now() - started,
264
- upstreamCalls,
265
+ apiCalls,
265
266
  data,
266
267
  partial: rejected.map((r) => partialFromRejection(r.section, {
267
268
  code: r.code,
@@ -269,7 +270,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
269
270
  ...(r.httpStatus !== undefined ? { httpStatus: r.httpStatus } : {}),
270
271
  })),
271
272
  warnings: [
272
- `${rejected.length} of ${upstreamCalls} schedule section(s) failed; the rest of the day is still returned.`,
273
+ `${rejected.length} of ${apiCalls} schedule section(s) failed; the rest of the day is still returned.`,
273
274
  ],
274
275
  });
275
276
  }
@@ -278,7 +279,7 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
278
279
  game,
279
280
  requestId,
280
281
  tookMs: Date.now() - started,
281
- upstreamCalls,
282
+ apiCalls,
282
283
  data,
283
284
  });
284
285
  },
@@ -1,3 +1,4 @@
1
+ import { normalizeCoverage } from './rankings.js';
1
2
  import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
2
3
  import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
3
4
  import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -77,26 +78,26 @@ export function normalizeStandingRow(row, index) {
77
78
  }
78
79
  export const standings = {
79
80
  name: 'standings',
80
- description: `League/event standings or world/division rankings normalized to ranked rows.
81
-
82
- When to use:
83
- - Table / playoff picture
84
- - UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
85
-
86
- Prefer over: raw standings via call_api for agent-normalized rows.
87
-
88
- Do not use when: single team form → team_profile; live scores → live_matches.
89
- Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
90
-
91
- Required scope keys by game:
92
- - lol: leagueId OR tournamentId
93
- - cs2: omit for world rankings; eventId for event standings
94
- - cod: optional season/stage
95
- - ufc: optional division (scope=division)
96
- - tennis: optional division (ATP or WTA tour; default ATP)
97
- - dota2: best-effort worldRanking only
98
-
99
- Parallel-safe: yes. Upstream cost: 1–2.
81
+ description: `League/event standings or world/division rankings normalized to ranked rows.
82
+
83
+ When to use:
84
+ - Table / playoff picture
85
+ - UFC rankings; CS2 world or event standings; CDL standings; LoL league/tournament tables
86
+
87
+ Prefer over: raw standings via call_api for agent-normalized rows.
88
+
89
+ Do not use when: single team form → team_profile; live scores → live_matches.
90
+ Dota has no first-class standings (may NOT_IMPLEMENTED or weak worldRanking).
91
+
92
+ Required scope keys by game:
93
+ - lol: leagueId OR tournamentId
94
+ - cs2: omit for world rankings; eventId for event standings
95
+ - cod: optional season/stage
96
+ - ufc: optional division (scope=division)
97
+ - tennis: optional division (ATP or WTA tour; default ATP); optional season YYYY = that season's last published list (default: latest). listCoverage says when an archived list is held only in part
98
+ - dota2: best-effort worldRanking only
99
+
100
+ Parallel-safe: yes. API calls: 1–2.
100
101
  Example: { "game": "cod", "season": "2026", "limit": 50 }`,
101
102
  inputSchema: {
102
103
  type: 'object',
@@ -112,7 +113,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
112
113
  leagueId: stringSchema('LoL league id for league standings.'),
113
114
  tournamentId: stringSchema('LoL/COD tournament id.'),
114
115
  eventId: stringSchema('CS2 event id for event standings.'),
115
- season: stringSchema('Season key (COD).'),
116
+ season: stringSchema('Season key (COD). Tennis: a year (YYYY) gives that season\'s last published ranking list.'),
116
117
  stage: stringSchema('Stage key (COD / LoL).'),
117
118
  division: stringSchema('UFC division key.'),
118
119
  limit: limitSchema({ default: 50, max: 100 }),
@@ -145,7 +146,11 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
145
146
  const leagueId = typeof args.leagueId === 'string' ? args.leagueId : undefined;
146
147
  const tournamentId = typeof args.tournamentId === 'string' ? args.tournamentId : undefined;
147
148
  const eventId = typeof args.eventId === 'string' ? args.eventId : undefined;
148
- const season = typeof args.season === 'string' ? args.season : undefined;
149
+ const season = typeof args.season === 'string'
150
+ ? args.season
151
+ : typeof args.season === 'number' && Number.isFinite(args.season)
152
+ ? String(Math.trunc(args.season))
153
+ : undefined;
149
154
  const stage = typeof args.stage === 'string' ? args.stage : undefined;
150
155
  const division = typeof args.division === 'string' ? args.division : undefined;
151
156
  const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
@@ -241,7 +246,18 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
241
246
  else if (game === 'tennis') {
242
247
  const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
243
248
  path = '/tennis/standings';
244
- query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
249
+ const tennisSeason = season && /^\d{4}$/.test(season.trim()) ? season.trim() : undefined;
250
+ if (season && !tennisSeason) {
251
+ return errorEnvelope({
252
+ code: 'VALIDATION',
253
+ message: `season must be a year (YYYY) for tennis (got '${season}')`,
254
+ game,
255
+ source: 'standings',
256
+ requestId,
257
+ tookMs: Date.now() - started,
258
+ });
259
+ }
260
+ query = { tour, top_n: Math.min(limit, 100), page: tennisPage, ...(tennisSeason ? { season: tennisSeason } : {}) };
245
261
  effectiveScope = 'world';
246
262
  title = `${tour} singles rankings`;
247
263
  }
@@ -255,7 +271,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
255
271
  source: 'standings',
256
272
  requestId,
257
273
  tookMs: Date.now() - started,
258
- upstreamCalls: 1,
274
+ apiCalls: 1,
259
275
  httpStatus: res.status,
260
276
  rateLimit: res.headers,
261
277
  });
@@ -277,7 +293,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
277
293
  source: 'standings',
278
294
  requestId,
279
295
  tookMs: Date.now() - started,
280
- upstreamCalls: 1,
296
+ apiCalls: 1,
281
297
  recover: [
282
298
  'Use team_profile with radar for style/form',
283
299
  'Use call_api if a standings path is added later',
@@ -289,7 +305,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
289
305
  game,
290
306
  requestId,
291
307
  tookMs: Date.now() - started,
292
- upstreamCalls: 1,
308
+ apiCalls: 1,
293
309
  rateLimit: res.headers,
294
310
  warnings: ['Dota standings composed from team worldRanking fields; sparse'],
295
311
  data: {
@@ -311,7 +327,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
311
327
  source: 'standings',
312
328
  requestId,
313
329
  tookMs: Date.now() - started,
314
- upstreamCalls: 1,
330
+ apiCalls: 1,
315
331
  httpStatus: res.status,
316
332
  rateLimit: res.headers,
317
333
  });
@@ -345,13 +361,13 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
345
361
  });
346
362
  }
347
363
  const obj = asRecord(res.data);
348
- const upstreamMeta = asRecord(obj?.meta) ?? {};
349
- const upstreamTotal = typeof obj?.total === 'number' ? obj.total : null;
364
+ const apiMeta = asRecord(obj?.meta) ?? {};
365
+ const unfilteredTotal = typeof obj?.total === 'number' ? obj.total : null;
350
366
  const rankedPlayers = typeof obj?.ranked_players === 'number' ? obj.ranked_players : null;
351
367
  const totalPages = typeof obj?.total_pages === 'number' ? obj.total_pages : null;
352
- const upstreamHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
353
- const effectiveTotal = upstreamTotal ?? allRows.length;
354
- const effectiveHasMore = upstreamHasNext ?? offset + rows.length < effectiveTotal;
368
+ const apiHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
369
+ const effectiveTotal = unfilteredTotal ?? allRows.length;
370
+ const effectiveHasMore = apiHasNext ?? offset + rows.length < effectiveTotal;
355
371
  const standingsPagination = {
356
372
  limit,
357
373
  offset,
@@ -360,7 +376,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
360
376
  nextCursor: effectiveHasMore ? String(offset + rows.length) : null,
361
377
  prevCursor: offset > 0 ? String(Math.max(0, offset - limit)) : null,
362
378
  };
363
- const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
379
+ const dataQuality = asRecord(apiMeta.dataQuality) ?? {};
364
380
  const warnings = [];
365
381
  const pushWarning = (value) => {
366
382
  if (typeof value !== 'string')
@@ -369,20 +385,23 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
369
385
  if (trimmed && !warnings.includes(trimmed))
370
386
  warnings.push(trimmed);
371
387
  };
372
- pushWarning(upstreamMeta.warning);
388
+ pushWarning(apiMeta.warning);
373
389
  pushWarning(dataQuality.warning);
374
- if (Array.isArray(upstreamMeta.warnings)) {
375
- for (const w of upstreamMeta.warnings)
390
+ const tennisCoverage = game === 'tennis' ? asRecord(obj?.list_coverage) : null;
391
+ if (tennisCoverage && tennisCoverage.status === 'partial')
392
+ pushWarning(tennisCoverage.note);
393
+ if (Array.isArray(apiMeta.warnings)) {
394
+ for (const w of apiMeta.warnings)
376
395
  pushWarning(w);
377
396
  }
378
- const dataFreshness = pickString(upstreamMeta.dataFreshness, upstreamMeta.freshnessStatus, dataQuality.dataFreshness);
379
- const status = pickString(upstreamMeta.status, dataQuality.status);
397
+ const dataFreshness = pickString(apiMeta.dataFreshness, apiMeta.freshnessStatus, dataQuality.dataFreshness);
398
+ const status = pickString(apiMeta.status, dataQuality.status);
380
399
  if (status === 'fallback') {
381
400
  pushWarning('Standings served from last-known-good rankings (fallback).');
382
401
  }
383
- if (dataFreshness === 'cached' || upstreamMeta.stale === true) {
384
- pushWarning(typeof upstreamMeta.dataAgeHours === 'number'
385
- ? `Rankings dataFreshness=cached (ageHours=${upstreamMeta.dataAgeHours}).`
402
+ if (dataFreshness === 'cached' || apiMeta.stale === true) {
403
+ pushWarning(typeof apiMeta.dataAgeHours === 'number'
404
+ ? `Rankings dataFreshness=cached (ageHours=${apiMeta.dataAgeHours}).`
386
405
  : 'Rankings dataFreshness=cached or stale.');
387
406
  }
388
407
  return successEnvelope({
@@ -391,7 +410,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
391
410
  game,
392
411
  requestId,
393
412
  tookMs: Date.now() - started,
394
- upstreamCalls: 1,
413
+ apiCalls: 1,
395
414
  rateLimit: res.headers,
396
415
  warnings: warnings.length ? warnings : undefined,
397
416
  data: {
@@ -412,16 +431,17 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
412
431
  ...(game === 'tennis'
413
432
  ? {
414
433
  rankingDate: pickString(obj?.ranking_date) ?? null,
415
- updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
434
+ listCoverage: tennisCoverage ? normalizeCoverage(tennisCoverage) : null,
435
+ updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, apiMeta.syncedAt, apiMeta.fetchedAt, obj?.ranking_date) ?? null,
416
436
  }
417
437
  : {
418
- updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
438
+ updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, apiMeta.syncedAt, apiMeta.fetchedAt) ??
419
439
  null,
420
440
  }),
421
441
  ...(dataFreshness ? { dataFreshness } : {}),
422
442
  ...(status ? { status } : {}),
423
- ...(upstreamMeta.warning || dataQuality.warning
424
- ? { warning: pickString(upstreamMeta.warning, dataQuality.warning) }
443
+ ...(apiMeta.warning || dataQuality.warning
444
+ ? { warning: pickString(apiMeta.warning, dataQuality.warning) }
425
445
  : {}),
426
446
  },
427
447
  });