cito-mcp 0.6.0 → 0.6.1

package/dist/tools/resolve.js

@@ -376,20 +376,20 @@ async function searchGame(ctx, game, q, type, limit) {
 }
 export const resolveEntity = {
     name: 'resolve_entity',
-    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
-
-When to use:
-- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
-- Need a canonical id/slug before profile or match tools
-
-Prefer over search_entities when you want one best match (or small ranked set) to chain.
-Prefer search_entities when browsing many results with pagination.
-
-Do not use when: you already have a stable id/slug from a prior tool.
-
-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.
-
-Parallel-safe: yes. API calls: 1–5.
+    description: `Natural-language / fuzzy query → best typed entity ID(s) + game (player, team, event, tournament, match, fighter).
+
+When to use:
+- User named an entity without an ID ("T1", "s1mple", "IEM Cologne", "Islam Makhachev")
+- Need a canonical id/slug before profile or match tools
+
+Prefer over search_entities when you want one best match (or small ranked set) to chain.
+Prefer search_entities when browsing many results with pagination.
+
+Do not use when: you already have a stable id/slug from a prior tool.
+
+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.
+
+Parallel-safe: yes. API calls: 1–5.
 Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -441,11 +441,11 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
             ? [gameParse.game]
             : [...PRIMARY_GAMES];
         const partial = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         const all = [];
         const results = await Promise.all(games.map((g) => searchGame(ctx, g, q, type, limit)));
         for (const r of results) {
-            upstreamCalls += r.calls;
+            apiCalls += r.calls;
             all.push(...r.candidates);
             if (r.error)
                 partial.push(r.error);
@@ -469,7 +469,7 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
             game: best?.game ?? gameParse.game ?? null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             partial: partial.length ? partial : undefined,
             entities: best
                 ? {
@@ -492,22 +492,22 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
 };
 export const searchEntities = {
     name: 'search_entities',
-    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
-
-When to use:
-- Typeahead / pickers
-- "List teams matching…"
-- Exploring entities without committing to one ID
-- UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
-
-Prefer over resolve_entity when the user wants a list.
-Prefer resolve_entity when chaining one name into a profile tool.
-
-Do not use when: fetching a known entity profile — use team_profile or player_profile.
-
-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.
-
-Parallel-safe: yes. API calls: 1–3.
+    description: `Browse/search teams, players, tournaments, events, fighters with type filter and pagination.
+
+When to use:
+- Typeahead / pickers
+- "List teams matching…"
+- Exploring entities without committing to one ID
+- UFC fighter lookup by name/nickname (uses /ufc/search + client re-rank)
+
+Prefer over resolve_entity when the user wants a list.
+Prefer resolve_entity when chaining one name into a profile tool.
+
+Do not use when: fetching a known entity profile — use team_profile or player_profile.
+
+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.
+
+Parallel-safe: yes. API calls: 1–3.
 Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -549,10 +549,10 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         const offset = typeof cursor?.offset === 'number' ? cursor.offset : 0;
         const activeOnly = args.activeOnly !== false;
         let items = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let total = null;
-        let upstreamPaged = true;
-        let preserveUpstreamOrder = false;
+        let apiPaged = true;
+        let preserveApiOrder = false;
         const pageQuery = (extra = {}) => ({
             limit,
             offset,
@@ -563,7 +563,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         });
         async function listPath(path, entityType, extra = {}) {
             const res = await fetchJson(ctx, path, { query: pageQuery(extra) });
-            upstreamCalls += 1;
+            apiCalls += 1;
             if (!res.ok) {
                 throw Object.assign(new Error(`HTTP ${res.status}`), {
                     status: res.status,
@@ -592,7 +592,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             else if (game === 'cs2') {
                 if (q && (type === 'any' || !['team', 'player', 'event'].includes(type))) {
                     const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (res.ok) {
                         const envelope = asRecord(res.data) ?? {};
                         const data = asRecord(envelope.data) ?? envelope;
@@ -625,7 +625,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             else if (game === 'dota2') {
                 if (q) {
                     const res = await fetchJson(ctx, '/dota2/search', { query: { q, limit } });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (res.ok) {
                         const data = asRecord(res.data) ?? {};
                         if (type === 'team' || type === 'any')
@@ -648,18 +648,18 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             else if (game === 'tennis') {
                 if (type === 'player' || type === 'any') {
                     const res = await fetchJson(ctx, '/tennis/players/search', { query: { q, limit } });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (res.ok) {
                         const envelope = asRecord(res.data) ?? {};
                         const data = asRecord(envelope.data) ?? envelope;
                         items.push(...extractRows(data.items ?? data).map((r) => entityRef(r, 'player', game)));
                         if (q)
-                            preserveUpstreamOrder = true;
+                            preserveApiOrder = true;
                     }
                 }
                 if (type === 'tournament' || type === 'event' || type === 'any') {
                     const res = await fetchJson(ctx, '/tennis/competitions', { query: { q, page_size: limit } });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (res.ok) {
                         const envelope = asRecord(res.data) ?? {};
                         const data = asRecord(envelope.data) ?? envelope;
@@ -669,11 +669,11 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             }
             else if (game === 'cod') {
                 if (q) {
-                    upstreamPaged = false;
+                    apiPaged = false;
                     const res = await fetchJson(ctx, '/cod/search', {
                         query: { q, limit, ...(type !== 'any' ? { type: type === 'team' ? 'org' : type } : {}) },
                     });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (res.ok)
                         items.push(...extractRows(res.data).map((r) => entityRef(r, type === 'any' ? 'unknown' : type, game)));
                 }
@@ -688,9 +688,9 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             }
             else if (game === 'ufc') {
                 if (q) {
-                    upstreamPaged = false;
+                    apiPaged = false;
                     const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     if (!res.ok) {
                         throw Object.assign(new Error(`HTTP ${res.status}`), {
                             status: res.status,
@@ -761,7 +761,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 source: 'search_entities',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls,
+                apiCalls,
                 httpStatus: e.status,
                 rateLimit: e.headers,
             });
@@ -777,7 +777,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         const scoreOf = (it) => typeof it.meta?.score === 'number'
             ? it.meta.score
             : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
-        const upstreamTotal = total;
+        const unfilteredTotal = total;
         let droppedBelowFloor = [];
         const ENTITY_TYPES = new Set(['player', 'team', 'fighter']);
         const protectedRow = q ? items.find((it) => ENTITY_TYPES.has(it.type)) ?? null : null;
@@ -803,15 +803,15 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             if (droppedBelowFloor.length)
                 items = items.filter(keep);
         }
-        if (q && !preserveUpstreamOrder) {
+        if (q && !preserveApiOrder) {
             items.sort((a, b) => {
                 const am = a.meta?.matchedBy === 'top-hit' ? 1 : 0;
                 const bm = b.meta?.matchedBy === 'top-hit' ? 1 : 0;
                 return bm - am || scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name);
             });
         }
-        const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
-        const hasMore = upstreamPaged
+        const pageItems = apiPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
+        const hasMore = apiPaged
             ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
             : offset + pageItems.length < items.length;
         const floorWarnings = [];
@@ -829,7 +829,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             warnings: floorWarnings.length ? floorWarnings : undefined,
             pagination: {
                 limit,
@@ -849,7 +849,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                             matched: items.length,
                             droppedBelowFloor: droppedBelowFloor.length,
                             dropped: droppedBelowFloor.slice(0, 25),
-                            unfilteredTotal: upstreamTotal ?? null,
+                            unfilteredTotal: unfilteredTotal ?? null,
                         },
                     }
                     : {}),

package/dist/tools/schedule.js

@@ -134,13 +134,13 @@ Parallel-safe: yes. API calls: 1 or 2.`,
         const limit = clampInt(args.limit, 20, 1, 50);
         const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
         const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
-        const upstreamPage = 500;
+        const apiPage = 500;
         const settled = await Promise.allSettled([
             wantScheduled
-                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: upstreamPage } })
+                ? fetchJson(ctx, '/tennis/schedule', { query: { date, limit: apiPage } })
                 : Promise.resolve(null),
             wantCompleted
-                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: upstreamPage } })
+                ? fetchJson(ctx, '/tennis/matches/completed', { query: { date, limit: apiPage } })
                 : Promise.resolve(null),
         ]);
         const rejected = [];
@@ -208,7 +208,7 @@ Parallel-safe: yes. API calls: 1 or 2.`,
                 source: 'tennis_schedule',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: rejected.length,
+                apiCalls: rejected.length,
                 recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
             });
         }
@@ -255,14 +255,14 @@ Parallel-safe: yes. API calls: 1 or 2.`,
                 }
                 : {}),
         };
-        const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
+        const apiCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
         if (rejected.length > 0) {
             return successEnvelope({
                 source: 'tennis_schedule',
                 game,
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls,
+                apiCalls,
                 data,
                 partial: rejected.map((r) => partialFromRejection(r.section, {
                     code: r.code,
@@ -270,7 +270,7 @@ Parallel-safe: yes. API calls: 1 or 2.`,
                     ...(r.httpStatus !== undefined ? { httpStatus: r.httpStatus } : {}),
                 })),
                 warnings: [
-                    `${rejected.length} of ${upstreamCalls} schedule section(s) failed; the rest of the day is still returned.`,
+                    `${rejected.length} of ${apiCalls} schedule section(s) failed; the rest of the day is still returned.`,
                 ],
             });
         }
@@ -279,7 +279,7 @@ Parallel-safe: yes. API calls: 1 or 2.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             data,
         });
     },

package/dist/tools/standings.js

@@ -271,7 +271,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                     source: 'standings',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls: 1,
+                    apiCalls: 1,
                     httpStatus: res.status,
                     rateLimit: res.headers,
                 });
@@ -293,7 +293,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                     source: 'standings',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls: 1,
+                    apiCalls: 1,
                     recover: [
                         'Use team_profile with radar for style/form',
                         'Use call_api if a standings path is added later',
@@ -305,7 +305,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 game,
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 rateLimit: res.headers,
                 warnings: ['Dota standings composed from team worldRanking fields; sparse'],
                 data: {
@@ -327,7 +327,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 source: 'standings',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
             });
@@ -361,13 +361,13 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             });
         }
         const obj = asRecord(res.data);
-        const upstreamMeta = asRecord(obj?.meta) ?? {};
-        const upstreamTotal = typeof obj?.total === 'number' ? obj.total : null;
+        const apiMeta = asRecord(obj?.meta) ?? {};
+        const unfilteredTotal = typeof obj?.total === 'number' ? obj.total : null;
         const rankedPlayers = typeof obj?.ranked_players === 'number' ? obj.ranked_players : null;
         const totalPages = typeof obj?.total_pages === 'number' ? obj.total_pages : null;
-        const upstreamHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
-        const effectiveTotal = upstreamTotal ?? allRows.length;
-        const effectiveHasMore = upstreamHasNext ?? offset + rows.length < effectiveTotal;
+        const apiHasNext = typeof obj?.has_next === 'boolean' ? obj.has_next : null;
+        const effectiveTotal = unfilteredTotal ?? allRows.length;
+        const effectiveHasMore = apiHasNext ?? offset + rows.length < effectiveTotal;
         const standingsPagination = {
             limit,
             offset,
@@ -376,7 +376,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             nextCursor: effectiveHasMore ? String(offset + rows.length) : null,
             prevCursor: offset > 0 ? String(Math.max(0, offset - limit)) : null,
         };
-        const dataQuality = asRecord(upstreamMeta.dataQuality) ?? {};
+        const dataQuality = asRecord(apiMeta.dataQuality) ?? {};
         const warnings = [];
         const pushWarning = (value) => {
             if (typeof value !== 'string')
@@ -385,23 +385,23 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             if (trimmed && !warnings.includes(trimmed))
                 warnings.push(trimmed);
         };
-        pushWarning(upstreamMeta.warning);
+        pushWarning(apiMeta.warning);
         pushWarning(dataQuality.warning);
         const tennisCoverage = game === 'tennis' ? asRecord(obj?.list_coverage) : null;
         if (tennisCoverage && tennisCoverage.status === 'partial')
             pushWarning(tennisCoverage.note);
-        if (Array.isArray(upstreamMeta.warnings)) {
-            for (const w of upstreamMeta.warnings)
+        if (Array.isArray(apiMeta.warnings)) {
+            for (const w of apiMeta.warnings)
                 pushWarning(w);
         }
-        const dataFreshness = pickString(upstreamMeta.dataFreshness, upstreamMeta.freshnessStatus, dataQuality.dataFreshness);
-        const status = pickString(upstreamMeta.status, dataQuality.status);
+        const dataFreshness = pickString(apiMeta.dataFreshness, apiMeta.freshnessStatus, dataQuality.dataFreshness);
+        const status = pickString(apiMeta.status, dataQuality.status);
         if (status === 'fallback') {
             pushWarning('Standings served from last-known-good rankings (fallback).');
         }
-        if (dataFreshness === 'cached' || upstreamMeta.stale === true) {
-            pushWarning(typeof upstreamMeta.dataAgeHours === 'number'
-                ? `Rankings dataFreshness=cached (ageHours=${upstreamMeta.dataAgeHours}).`
+        if (dataFreshness === 'cached' || apiMeta.stale === true) {
+            pushWarning(typeof apiMeta.dataAgeHours === 'number'
+                ? `Rankings dataFreshness=cached (ageHours=${apiMeta.dataAgeHours}).`
                 : 'Rankings dataFreshness=cached or stale.');
         }
         return successEnvelope({
@@ -410,7 +410,7 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             warnings: warnings.length ? warnings : undefined,
             data: {
@@ -432,16 +432,16 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                     ? {
                         rankingDate: pickString(obj?.ranking_date) ?? null,
                         listCoverage: tennisCoverage ? normalizeCoverage(tennisCoverage) : null,
-                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, apiMeta.syncedAt, apiMeta.fetchedAt, obj?.ranking_date) ?? null,
                     }
                     : {
-                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt) ??
+                        updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, apiMeta.syncedAt, apiMeta.fetchedAt) ??
                             null,
                     }),
                 ...(dataFreshness ? { dataFreshness } : {}),
                 ...(status ? { status } : {}),
-                ...(upstreamMeta.warning || dataQuality.warning
-                    ? { warning: pickString(upstreamMeta.warning, dataQuality.warning) }
+                ...(apiMeta.warning || dataQuality.warning
+                    ? { warning: pickString(apiMeta.warning, dataQuality.warning) }
                     : {}),
             },
         });