cito-mcp 0.3.4 → 0.3.6

package/dist/install.js

@@ -264,21 +264,21 @@ function parseArgs(argv) {
     }
     return out;
 }
-const HELP = `cito-mcp install — configure the Cito MCP server for your editors
-
-Usage:
-  npx cito-mcp install --key cito_xxx
-  npx cito-mcp install --key cito_xxx --client cursor,claude-code
-  npx cito-mcp install --dry-run
-
-Options:
-  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
-  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex, grok.
-                    Default: every client detected on this machine.
-  --base <url>      Override API base (staging / self-hosted).
-  --dry-run, -n     Show what would change; write nothing.
-  --help, -h        This message.
-
+const HELP = `cito-mcp install — configure the Cito MCP server for your editors
+
+Usage:
+  npx cito-mcp install --key cito_xxx
+  npx cito-mcp install --key cito_xxx --client cursor,claude-code
+  npx cito-mcp install --dry-run
+
+Options:
+  --key <key>       Cito API key. Falls back to $CITO_API_KEY.
+  --client <ids>    Comma-separated: claude-code, claude-desktop, cursor, windsurf, codex, grok.
+                    Default: every client detected on this machine.
+  --base <url>      Override API base (staging / self-hosted).
+  --dry-run, -n     Show what would change; write nothing.
+  --help, -h        This message.
+
 Get a key at https://citoapi.com/dashboard`;
 export async function runInstall(argv) {
     const args = parseArgs(argv);

package/dist/tools/live.js

@@ -422,13 +422,25 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             warnings.push(`Ignored filter "${param}": ${reason}`);
         };
         let path = '';
+        // Set when this tool, not the API, is responsible for the team filter. It
+        // also moves paging client-side, because an upstream offset would be
+        // counted against rows we are about to discard.
+        let clientTeamFilter = false;
         let query = { limit, offset };
         if (game === 'lol') {
             path = '/lol/schedule/upcoming';
+            // The upstream accepts teamSlug but does not apply it: asking for t1
+            // returned Dplus KIA, Team WE and NightBirds. That is a silently wrong
+            // answer, which is worse than an error, so the filter is enforced below.
+            // Filtering client-side means the upstream offset would be counted
+            // against unfiltered rows, so when a team is named we over-fetch and page
+            // here instead.
+            if (team)
+                clientTeamFilter = true;
             query = {
                 hours: String(hours),
-                limit: String(limit),
-                offset: String(offset),
+                limit: String(clientTeamFilter ? Math.min(200, (offset + limit) * 4) : limit),
+                ...(clientTeamFilter ? {} : { offset: String(offset) }),
                 ...(league ? { leagueSlug: league } : {}),
                 ...(team ? { teamSlug: team } : {}),
             };
@@ -514,12 +526,7 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 noteIgnored('tournamentId', 'tennis fixtures have no tournamentId filter');
             if (team)
                 noteIgnored('team', 'tennis fixtures have no team filter; match player names client-side');
-            if (args.hours !== undefined)
-                noteIgnored('hours', 'tennis fixtures cover ~3 days; filter by startTime client-side');
-            if (from)
-                noteIgnored('from', 'tennis fixtures cover ~3 days; filter by startTime client-side');
-            if (to)
-                noteIgnored('to', 'tennis fixtures cover ~3 days; filter by startTime client-side');
+            // hours / from / to applied client-side after fetch (below) — not warned as ignored.
         }
         const res = await fetchJson(ctx, path, { query });
         if (!res.ok) {
@@ -600,8 +607,32 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 }
             }
         }
+        // Tennis: client-side hours / from / to window (fixtures list has no time params)
+        if (game === 'tennis' && (args.hours !== undefined || from || to)) {
+            const now = Date.now();
+            const fromMs = from ? Date.parse(from) : now;
+            const toMs = to ? Date.parse(to) : now + hours * 3600_000;
+            if (Number.isFinite(fromMs) && Number.isFinite(toMs)) {
+                const before = rows.length;
+                rows = rows.filter((row) => {
+                    const r = asRecord(row) ?? {};
+                    const ts = pickString(r.startTime, r.start_time, r.startsAt);
+                    if (!ts)
+                        return true; // keep undated rows rather than drop them
+                    const t = Date.parse(ts);
+                    if (!Number.isFinite(t))
+                        return true;
+                    return t >= fromMs && t <= toMs;
+                });
+                if (before > 0 && rows.length === 0) {
+                    warnings.push(`hours/from/to window matched 0 of ${before} tennis fixtures — widen hours or omit time filters`);
+                }
+            }
+        }
         // Client-side team filter when API ignored it
-        if (team && (game === 'dota2' || game === 'cs2')) {
+        let beforeTeamFilter = rows.length;
+        if (team && (game === 'dota2' || game === 'cs2' || clientTeamFilter)) {
+            beforeTeamFilter = rows.length;
             const t = team.toLowerCase();
             rows = rows.filter((row) => {
                 const m = normalizeMatch(game, row, 'upcoming');
@@ -612,7 +643,11 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 return hay.includes(t);
             });
         }
-        const items = rows.slice(0, limit).map((row) => normalizeMatch(game, row, 'upcoming'));
+        if (team && beforeTeamFilter > 0 && rows.length === 0) {
+            warnings.push(`team "${team}" matched 0 of ${beforeTeamFilter} upcoming fixtures in this window — widen hours or check the slug`);
+        }
+        const items = (clientTeamFilter ? rows.slice(offset, offset + limit) : rows.slice(0, limit))
+            .map((row) => normalizeMatch(game, row, 'upcoming'));
         const obj = asRecord(res.data);
         const total = typeof obj?.total === 'number' ? obj.total : null;
         const hasMore = (typeof obj?.hasMore === 'boolean' ? obj.hasMore : items.length >= limit) ||

package/dist/tools/match.js

@@ -8,6 +8,50 @@ import { boolSchema, gameSchema, isPrimaryGame, parseGame, stringSchema, } from
 async function getSection(ctx, path, query) {
     return fetchJson(ctx, path, { query });
 }
+/**
+ * Series length. The LoL feed states it as `strategy: "Bo5"`, which nothing was
+ * reading, so every match reported bestOf: null. Accept the spelled forms and
+ * the object shape other titles use, and fall back to the declared game count.
+ * Only 1/3/5/7/9 are real series lengths, so anything else is refused rather
+ * than guessed.
+ */
+export function parseBestOf(r) {
+    const fromNumber = (v) => {
+        const n = Number(v);
+        return Number.isFinite(n) && [1, 3, 5, 7, 9].includes(n) ? n : null;
+    };
+    const direct = fromNumber(r.bestOf) ?? fromNumber(r.bo);
+    if (direct)
+        return direct;
+    const strat = r.strategy;
+    if (typeof strat === 'string') {
+        const m = strat.match(/(\d+)/);
+        if (m) {
+            const n = fromNumber(m[1]);
+            if (n)
+                return n;
+        }
+    }
+    // { type: "bestOf", count: 5 }
+    if (strat && typeof strat === 'object') {
+        const o = strat;
+        const n = fromNumber(o.count) ?? fromNumber(o.value) ?? fromNumber(o.bestOf);
+        if (n)
+            return n;
+    }
+    for (const key of ['format', 'seriesType', 'matchFormat']) {
+        const v = r[key];
+        if (typeof v === 'string') {
+            const m = v.match(/(\d+)/);
+            if (m) {
+                const n = fromNumber(m[1]);
+                if (n)
+                    return n;
+            }
+        }
+    }
+    return fromNumber(r.gameCount) ?? null;
+}
 function matchCore(game, matchId, raw) {
     const entity = unwrapPayload(raw);
     const m = normalizeMatch(game, entity);
@@ -23,7 +67,7 @@ function matchCore(game, matchId, raw) {
         status: m.status,
         startTime: m.startTime,
         endTime: pickString(r.endTime, r.endedAt, r.finishedAt) ?? null,
-        bestOf: r.bestOf ?? r.bo ?? null,
+        bestOf: parseBestOf(r),
         label: m.label,
         scoreline,
         score: {

package/dist/tools/normalize.js

@@ -260,8 +260,23 @@ export function normalizeMatch(game, row, forcedStatus) {
             r.resultRound != null ||
             r.isComplete === true ||
             r.completed === true;
-        if (/live|running|in_?progress|ongoing|started|watching/.test(statusRaw))
+        // "started" as a bare substring also matches "not_started", which is how a
+        // fixture that has not begun was being served to customers as live. Require
+        // word boundaries, refuse the explicit not-started spellings, and refuse any
+        // match whose kickoff is still in the future: a scheduled match cannot be
+        // in progress no matter what the upstream status string says.
+        const unstarted = /not[_\s-]?started|unstarted|not[_\s-]?begun|yet[_\s-]?to[_\s-]?start/.test(statusRaw);
+        const looksLive = !unstarted && /\b(live|running|in[_\s-]?progress|ongoing|started|watching)\b/.test(statusRaw);
+        const kickoffPassed = (() => {
+            if (!startTime)
+                return true; // no clock to contradict the feed
+            const t = Date.parse(startTime);
+            return !Number.isFinite(t) || t <= Date.now();
+        })();
+        if (looksLive && kickoffPassed)
             status = 'live';
+        else if (looksLive && !kickoffPassed)
+            status = 'upcoming';
         else if (/complete|finished|ended|final|closed|done|official|result/.test(statusRaw) || hasResult) {
             status = 'completed';
         }

package/dist/tools/resolve.js

@@ -367,20 +367,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. Upstream cost: 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. Upstream cost: 1–5.
 Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
     inputSchema: {
         type: 'object',
@@ -474,22 +474,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. Upstream cost: 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. Upstream cost: 1–3.
 Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
     inputSchema: {
         type: 'object',
@@ -533,6 +533,11 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         let items = [];
         let upstreamCalls = 0;
         let total = null;
+        // pageQuery sends offset/page upstream, so what comes back IS the page and
+        // must not be sliced by offset again. Doing both returned an EMPTY page two
+        // while reporting total=1429 and hasMore=true. The UFC paths below fetch
+        // page 1 deliberately and re-rank in memory, so they page here instead.
+        let upstreamPaged = true;
         const pageQuery = (extra = {}) => ({
             limit,
             offset,
@@ -649,6 +654,8 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             }
             else if (game === 'cod') {
                 if (q) {
+                    // No offset goes upstream on this path, so page it here.
+                    upstreamPaged = false;
                     const res = await fetchJson(ctx, '/cod/search', {
                         query: { q, limit, ...(type !== 'any' ? { type: type === 'team' ? 'org' : type } : {}) },
                     });
@@ -668,6 +675,8 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             else if (game === 'ufc') {
                 if (q) {
                     // Dedicated search ranks name/slug/nickname; /fighters ignores q.
+                    // Returns the whole match set for client re-ranking; page it here.
+                    upstreamPaged = false;
                     const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
                     upstreamCalls += 1;
                     if (!res.ok) {
@@ -762,8 +771,10 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             });
         }
         // pagination over ranked result set
-        const pageItems = items.slice(offset, offset + limit);
-        const hasMore = offset + pageItems.length < items.length || (!q && items.length >= limit);
+        const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
+        const hasMore = upstreamPaged
+            ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)
+            : offset + pageItems.length < items.length;
         return successEnvelope({
             source: 'search_entities',
             game,

package/dist/tools/team.js

@@ -285,20 +285,32 @@ Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
                 }
             })());
             tasks.push((async () => {
-                const res = await fetchJson(ctx, '/lol/schedule', {
-                    query: { teamSlug: team.slug || idOrSlug, completed: 'true', limit: String(recentLimit) },
+                // The matches index, not /lol/schedule. Schedule returned the team's
+                // oldest fixtures: a T1 profile showed MSI 2023 as "recent" while the
+                // index had the 2026 LCK split, newest first. Sort here anyway rather
+                // than trusting upstream order, so the contract holds if either
+                // endpoint changes.
+                const slug = team.slug || idOrSlug;
+                const res = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(slug)}/matches`, {
+                    query: { limit: String(recentLimit) },
                 });
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...res.headers };
                 if (res.ok) {
+                    const startMs = (row) => {
+                        const t = Date.parse(String(row?.startTime ?? ''));
+                        return Number.isFinite(t) ? t : -Infinity;
+                    };
                     recentMatches = extractRows(res.data)
+                        .slice()
+                        .sort((a, b) => startMs(b) - startMs(a))
                         .slice(0, recentLimit)
                         .map((row) => normalizeMatch('lol', row, 'completed'));
                 }
                 else {
                     partial.push(partialFromRejection('recentMatches', {
                         code: mapHttpToCode(res.status),
-                        message: `schedule HTTP ${res.status}`,
+                        message: `team matches HTTP ${res.status}`,
                         httpStatus: res.status,
                     }));
                 }
@@ -664,6 +676,68 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
             rows = extractRows(res.data);
         }
         else if (game === 'lol') {
+            // First-class H2H. The old path pulled sideA's /lol/schedule and filtered
+            // client-side, which missed meetings and returned the oldest first, so a
+            // T1 vs HLE rivalry showed 2023 games and called the earliest one the
+            // "last meeting". This endpoint states the record outright (22 meetings,
+            // 8-13) and lists them newest first.
+            const h2hRes = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(sideA)}/h2h/${encodeURIComponent(sideB)}`, { query: { limit: String(limit) } });
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...h2hRes.headers };
+            if (h2hRes.ok) {
+                const env = asRecord(h2hRes.data) ?? {};
+                const h2h = asRecord(env.data) ?? env;
+                const agg = asRecord(h2h.matches) ?? {};
+                const opponent = asRecord(h2h.opponent) ?? {};
+                const startMs = (v) => {
+                    const t = Date.parse(String(v ?? ''));
+                    return Number.isFinite(t) ? t : -Infinity;
+                };
+                const meetingRows = extractRows(h2h.recentMatches)
+                    .slice()
+                    .sort((a, b) => startMs(asRecord(b)?.date) - startMs(asRecord(a)?.date))
+                    .slice(0, limit)
+                    .map((row) => {
+                    const r = asRecord(row) ?? {};
+                    return {
+                        matchId: pickString(r.matchId) ?? null,
+                        startTime: pickString(r.date) ?? null,
+                        tournamentName: pickString(r.tournamentName) ?? null,
+                        // The feed gives scores in the match's own team order, which it
+                        // does not label, so they are reported as-is rather than being
+                        // assigned to a side we would be guessing at.
+                        team1Score: typeof r.team1Score === 'number' ? r.team1Score : null,
+                        team2Score: typeof r.team2Score === 'number' ? r.team2Score : null,
+                        winnerSlug: pickString(r.winner) ?? null,
+                    };
+                });
+                const wins = typeof agg.wins === 'number' ? agg.wins : null;
+                const losses = typeof agg.losses === 'number' ? agg.losses : null;
+                const total = typeof agg.total === 'number' ? agg.total : meetingRows.length;
+                return successEnvelope({
+                    source: 'head_to_head',
+                    game,
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    data: {
+                        sideA: { idOrSlug: sideA },
+                        sideB: { idOrSlug: sideB, name: pickString(opponent.name) ?? null },
+                        record: {
+                            winsA: wins,
+                            winsB: losses,
+                            draws: 0,
+                            meetings: total,
+                        },
+                        games: asRecord(h2h.games) ?? null,
+                        meetings: meetingRows,
+                        lastMeeting: meetingRows[0] ?? null,
+                        notes: ['Record and meetings come from the first-class /lol/teams/{slug}/h2h/{opponent} endpoint'],
+                    },
+                });
+            }
+            warnings.push(`first-class LoL H2H unavailable (HTTP ${h2hRes.status}); falling back to schedule filtering`);
             const res = await fetchJson(ctx, '/lol/schedule', {
                 query: { teamSlug: sideA, completed: 'true', limit: '50' },
             });
@@ -832,6 +906,17 @@ Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
             if (!Number.isNaN(toMs) && t > toMs)
                 return false;
             return true;
+        })
+            // Newest first. Nothing sorted this before, so `lastMeeting` below was
+            // whichever row the upstream happened to return first, which on an
+            // ascending feed is the OLDEST meeting. It also means a limit cut off the
+            // recent games rather than the ancient ones.
+            .sort((a, b) => {
+            const ta = a.startTime ? Date.parse(a.startTime) : NaN;
+            const tb = b.startTime ? Date.parse(b.startTime) : NaN;
+            const va = Number.isFinite(ta) ? ta : -Infinity;
+            const vb = Number.isFinite(tb) ? tb : -Infinity;
+            return vb - va;
         })
             .slice(0, limit);
         let winsA = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cito-mcp",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Standalone MCP server for the Cito esports API — 15 curated outcome tools for agents (live, schedule, profiles, standings, previews, event cards).",
   "type": "module",
   "bin": {