cito-mcp 0.6.0 → 0.6.1

package/dist/tools/meta.js

@@ -609,18 +609,18 @@ const GAMES_META = [
 ];
 export const listCapabilities = {
     name: 'list_capabilities',
-    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
-
-When to use:
-- Session start or "what can you do?"
-- Mapping app screens to tools
-- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
-
-Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
-
-Do not use when: you already know the tool and have IDs — call that tool directly.
-
-Parallel-safe: yes. API calls: 0.
+    description: `Curated catalog of cito-mcp tools, games, jobs, and builder recipes.
+
+When to use:
+- Session start or "what can you do?"
+- Mapping app screens to tools
+- Filtering by game or job (live_board, match_page, team_page, player_form, standings, h2h, schedule, preview, event_card, app_scaffold)
+
+Prefer over: guessing from memory; exploring raw OpenAPI via call_api.
+
+Do not use when: you already know the tool and have IDs — call that tool directly.
+
+Parallel-safe: yes. API calls: 0.
 Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
     inputSchema: {
         type: 'object',
@@ -690,7 +690,7 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
             game: gameParse.game ?? null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 0,
+            apiCalls: 0,
             data: {
                 version: CATALOG_VERSION,
                 tools,
@@ -703,18 +703,18 @@ Example: { "game": "cs2", "job": "live_board", "includeExamples": true }`,
 };
 export const apiHealth = {
     name: 'api_health',
-    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
-
-When to use:
-- Once per session before heavy work
-- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
-- App scaffolding entitlement checks
-
-Prefer over: probing random game endpoints to test the key.
-
-Do not use when: you only need live scores — use live_matches.
-
-Parallel-safe: yes. API calls: 1–6.
+    description: `API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games.
+
+When to use:
+- Once per session before heavy work
+- After 401/403/UNSUPPORTED_GAME/RATE_LIMIT
+- App scaffolding entitlement checks
+
+Prefer over: probing random game endpoints to test the key.
+
+Do not use when: you only need live scores — use live_matches.
+
+Parallel-safe: yes. API calls: 1–6.
 Example: { "includeGameProbes": true }`,
     inputSchema: {
         type: 'object',
@@ -726,10 +726,10 @@ Example: { "includeGameProbes": true }`,
     handler: async (args, ctx) => {
         const started = Date.now();
         const requestId = newRequestId();
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         const health = await fetchJson(ctx, '/health');
-        upstreamCalls += 1;
+        apiCalls += 1;
         rateLimit = health.headers;
         let keyValid = false;
         let reachable = health.ok;
@@ -737,7 +737,7 @@ Example: { "includeGameProbes": true }`,
         let authedStatus = health.status;
         if (!health.ok) {
             const fallback = await fetchJson(ctx, '/lol/leagues');
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = fallback.headers;
             if (fallback.ok) {
                 keyValid = true;
@@ -753,14 +753,14 @@ Example: { "includeGameProbes": true }`,
                     source: 'api_health',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls,
+                    apiCalls,
                     rateLimit: fallback.headers,
                     httpStatus: fallback.status,
                 });
             }
             else {
                 const cs2 = await fetchJson(ctx, '/cs2');
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = cs2.headers;
                 if (cs2.ok) {
                     keyValid = true;
@@ -776,7 +776,7 @@ Example: { "includeGameProbes": true }`,
         }
         else {
             const probe = await fetchJson(ctx, '/lol/leagues');
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = { ...rateLimit, ...probe.headers };
             keyValid = probe.ok || probe.status === 403;
             if (probe.ok)
@@ -801,7 +801,7 @@ Example: { "includeGameProbes": true }`,
                 const res = await fetchJson(ctx, path);
                 return { game, path, res };
             }));
-            upstreamCalls += results.length;
+            apiCalls += results.length;
             for (const { game, res } of results) {
                 probes.push({ game, ok: res.ok, httpStatus: res.status });
                 if (res.ok)
@@ -837,7 +837,7 @@ Example: { "includeGameProbes": true }`,
             game: null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit: mergedRateLimit,
             data: {
                 reachable,
@@ -888,24 +888,24 @@ function pathAllowed(path) {
 }
 export const callApi = {
     name: 'call_api',
-    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
-
-When to use:
-- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
-- Debugging payloads while building an app
-- User explicitly knows an OpenAPI path
-
-Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
-
-Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
-
-Paths are relative to the API base, so "/tennis/players", not "/api/v1/tennis/players". Put query params in query or queryJson, not in the path.
-Tennis: /tennis/h2h takes players=a,b, or player1_id and player2_id (one form is required). /tennis/players has limit up to 100 (over that is a 422; use /tennis/players/batch for a roster). /tennis/tournaments/calendar needs no year (default this year) and returns every row unless given limit. /tennis/rankings defaults to rank_max=100: pass rank_max=5000 for the whole list. /tennis/schedule returns the whole day unless given limit.
-
-Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /apex, /tennis, /raf, /bkfc, /bellator, /pride, /strikeforce, /wec, /dream, /elitexc, /affliction, /pfl, /oktagon, /mma.
-Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
-
-Parallel-safe: yes but discouraged in bulk. API calls: 1.
+    description: `Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.
+
+When to use:
+- Long-tail paths not yet curated (Fortnite, CS2 leaderboards, niche stats)
+- Debugging payloads while building an app
+- User explicitly knows an OpenAPI path
+
+Prefer curated tools for all standard jobs (live, schedule, profiles, standings, H2H, previews).
+
+Do not use when: a curated tool covers the outcome. Avoid parallel storms; same plan rate limits apply.
+
+Paths are relative to the API base, so "/tennis/players", not "/api/v1/tennis/players". Put query params in query or queryJson, not in the path.
+Tennis: /tennis/h2h takes players=a,b, or player1_id and player2_id (one form is required). /tennis/players has limit up to 100 (over that is a 422; use /tennis/players/batch for a roster). /tennis/tournaments/calendar needs no year (default this year) and returns every row unless given limit. /tennis/rankings defaults to rank_max=100: pass rank_max=5000 for the whole list. /tennis/schedule returns the whole day unless given limit.
+
+Path must start with / and match allowlisted prefixes: /health, /lol, /cs2, /dota2, /cod, /ufc, /fortnite, /apex, /tennis, /raf, /bkfc, /bellator, /pride, /strikeforce, /wec, /dream, /elitexc, /affliction, /pfl, /oktagon, /mma.
+Rejects absolute URLs and path traversal → PATH_NOT_ALLOWED.
+
+Parallel-safe: yes but discouraged in bulk. API calls: 1.
 Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"page\\":1,\\"limit\\":20}" }`,
     inputSchema: {
         type: 'object',
@@ -998,7 +998,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
                 source: 'call_api',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 rateLimit: res.headers,
                 httpStatus: res.status,
                 details: { path, method, bodyPreview: present(res.text, 2000) },
@@ -1009,7 +1009,7 @@ Example: { "method": "GET", "path": "/cs2/rankings/teams", "queryJson": "{\\"pag
             game: null,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             warnings: ['Unshaped raw response — prefer curated tools when available'],
             data: {
@@ -1031,20 +1031,20 @@ const SPEC_OMITS = {
 };
 export const listRoutes = {
     name: 'list_routes',
-    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
-
-When to use:
-- You need a long-tail path for call_api and do not want to guess
-- Checking whether an endpoint exists before building around it
-- Mapping what raw data backs a curated tool
-
-Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
-
-Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
-
-Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
-
-Parallel-safe: yes. API calls: 1.
+    description: `Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.
+
+When to use:
+- You need a long-tail path for call_api and do not want to guess
+- Checking whether an endpoint exists before building around it
+- Mapping what raw data backs a curated tool
+
+Prefer curated tools for standard jobs — this indexes the escape hatch, it is not a replacement for list_capabilities.
+
+Do not use when: a curated tool already covers the outcome (call list_capabilities instead).
+
+Note: the spec omits /lol entirely, though LoL routes work. Filtering by game=lol returns that caveat rather than an empty list.
+
+Parallel-safe: yes. API calls: 1.
 Example: { "game": "ufc", "q": "rankings" }`,
     inputSchema: {
         type: 'object',
@@ -1089,7 +1089,7 @@ Example: { "game": "ufc", "q": "rankings" }`,
                 source: 'list_routes',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 rateLimit: res.headers,
                 httpStatus: res.status,
                 recover: [
@@ -1151,7 +1151,7 @@ Example: { "game": "ufc", "q": "rankings" }`,
             source: 'list_routes',
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
         });
     },

package/dist/tools/player.js

@@ -147,7 +147,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         const includeTrends = args.includeTrends !== false;
         const view = args.view === 'full' ? 'full' : args.view === 'compact' ? 'compact' : 'summary';
         const partial = [];
-        let upstreamCalls = 0;
+        let apiCalls = 0;
         let rateLimit = {};
         let primaryPath = '';
         if (game === 'lol')
@@ -165,7 +165,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         let playerRaw = null;
         if (game === 'dota2') {
             const list = await fetchJson(ctx, '/dota2/players', { query: { search: idOrSlug, limit: 5 } });
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = list.headers;
             if (list.ok) {
                 const rows = extractRows(list.data);
@@ -182,7 +182,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         }
         else {
             const res = await fetchJson(ctx, primaryPath);
-            upstreamCalls += 1;
+            apiCalls += 1;
             rateLimit = res.headers;
             if (!res.ok) {
                 return errorEnvelope({
@@ -192,7 +192,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     source: 'player_profile',
                     requestId,
                     tookMs: Date.now() - started,
-                    upstreamCalls,
+                    apiCalls,
                     rateLimit: res.headers,
                     httpStatus: res.status,
                 });
@@ -210,7 +210,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         if (game === 'lol') {
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/lol/players/${encodeURIComponent(idOrSlug)}/teams`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const rows = extractRows(res.data);
@@ -248,7 +248,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/lol/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { limit: String(recentLimit) },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const startMs = (row) => {
@@ -269,7 +269,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     const names = new Map();
                     await Promise.all(slugs.map(async (sl) => {
                         const t = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(sl)}`);
-                        upstreamCalls += 1;
+                        apiCalls += 1;
                         if (!t.ok)
                             return;
                         const body = asRecord(t.data) ?? {};
@@ -301,7 +301,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             if (includeTrends) {
                 tasks.push((async () => {
                     const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/stats`);
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                     if (res.ok)
                         career = unwrapPayload(res.data);
@@ -318,7 +318,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { page_size: recentLimit, ...(view === 'compact' ? { view: 'summary' } : {}) },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const envelope = asRecord(res.data) ?? {};
@@ -342,7 +342,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             ]) {
                 tasks.push((async () => {
                     const res = await fetchJson(ctx, path);
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...res.headers };
                     if (!res.ok) {
                         partial.push(partialFromRejection(section, {
@@ -377,7 +377,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/dota2/players/${encodeURIComponent(idOrSlug)}/radar`, {
                     query,
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     radar = res.data;
@@ -400,7 +400,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
         if (game === 'cod') {
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/cod/players/${encodeURIComponent(idOrSlug)}/stats`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     seasonStats = res.data;
@@ -418,7 +418,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/cod/players/${encodeURIComponent(idOrSlug)}/matches`, {
                     query: { limit: recentLimit },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     recentMatches = extractRows(res.data)
@@ -438,7 +438,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             const fighterKey = slug || idOrSlug;
             tasks.push((async () => {
                 const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/stats`);
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     const metrics = unwrapPayload(res.data);
@@ -456,7 +456,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                 const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/fights`, {
                     query: { limit: recentLimit },
                 });
-                upstreamCalls += 1;
+                apiCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
                     recentMatches = extractRows(res.data)
@@ -477,7 +477,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
                     const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(fighterKey)}/history`, {
                         query: { limit: recentLimit },
                     });
-                    upstreamCalls += 1;
+                    apiCalls += 1;
                     rateLimit = { ...rateLimit, ...hist.headers };
                     if (hist.ok) {
                         recentMatches = extractRows(hist.data)
@@ -507,7 +507,7 @@ Example: { "game": "cs2", "playerId": "cs2-player-1", "recentLimit": 10, "includ
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls,
+            apiCalls,
             rateLimit,
             partial: partial.length ? partial : undefined,
             entities: {
@@ -656,7 +656,7 @@ Parallel-safe: yes. API calls: 1.`,
                 source: 'player_form',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
             });
@@ -695,7 +695,7 @@ Parallel-safe: yes. API calls: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: {
                 games: [game],
@@ -805,7 +805,7 @@ Parallel-safe: yes. API calls: 1.`,
                 source: 'player_matches',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -873,7 +873,7 @@ Parallel-safe: yes. API calls: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: { games: [game], ids: { playerId } },
             data: {
@@ -982,7 +982,7 @@ API calls: 1.`,
                 source: 'player_stats',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -1071,7 +1071,7 @@ API calls: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             entities: { games: [game], ids: { playerId } },
             data: {

package/dist/tools/rankings.js

@@ -193,7 +193,7 @@ Parallel-safe: yes. API calls: 1.`,
                 source: 'rankings_movers',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
             });
@@ -248,7 +248,7 @@ Parallel-safe: yes. API calls: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             warnings: warnings.length ? warnings : undefined,
             data: {
@@ -370,7 +370,7 @@ Parallel-safe: yes. API calls: 1.`,
                 source: 'player_rankings_history',
                 requestId,
                 tookMs: Date.now() - started,
-                upstreamCalls: 1,
+                apiCalls: 1,
                 httpStatus: res.status,
                 rateLimit: res.headers,
                 recover: ['Check the player id with search_entities'],
@@ -390,10 +390,10 @@ Parallel-safe: yes. API calls: 1.`,
         const inWindow = sinceRaw
             ? allHistory.filter((h) => h.date !== null && h.date >= sinceRaw)
             : allHistory;
-        const pagedUpstream = typeof body.total === 'number' && typeof body.order === 'string';
+        const pagedApi = typeof body.total === 'number' && typeof body.order === 'string';
         let total;
         let history;
-        if (pagedUpstream) {
+        if (pagedApi) {
             total = body.total;
             history = body.order === 'desc' ? [...inWindow].reverse() : inWindow;
         }
@@ -404,7 +404,7 @@ Parallel-safe: yes. API calls: 1.`,
         }
         const omittedNewer = Math.min(total, (page - 1) * limit);
         const omittedOlder = Math.max(0, total - omittedNewer - history.length);
-        const hasMore = pagedUpstream && typeof body.has_next === 'boolean' ? body.has_next : omittedOlder > 0;
+        const hasMore = pagedApi && typeof body.has_next === 'boolean' ? body.has_next : omittedOlder > 0;
         const best = history.reduce((acc, h) => {
             if (h.rank === null)
                 return acc;
@@ -425,7 +425,7 @@ Parallel-safe: yes. API calls: 1.`,
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
+            apiCalls: 1,
             rateLimit: res.headers,
             data: {
                 title: `${pickString(body.player_name) ?? playerId} ranking history`,