cito-mcp 0.1.0 → 0.2.2

package/dist/tools/resolve.js

@@ -0,0 +1,518 @@
+/**
+ * resolve_entity + search_entities
+ */
+import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIncludedHint, pickString, asRecord, } from '../client.js';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { entityRef, rankScore } from './normalize.js';
+import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+function pushCandidates(out, game, type, rows, q, limit) {
+    for (const row of rows) {
+        const ref = entityRef(row, type, game);
+        const score = rankScore(q, ref.name, ref.id, ref.slug);
+        if (q && score <= 0 && type !== 'any') {
+            // still include search API hits even if local rank is weak
+        }
+        const r = asRecord(row) ?? {};
+        const secondary = {};
+        for (const key of ['lolPlayerId', 'codPlayerId', 'matchId', 'boutId', 'tournamentId', 'eventId']) {
+            const v = pickString(r[key]);
+            if (v)
+                secondary[key] = v;
+        }
+        out.push({
+            game,
+            type: pickString(r.entity_type, r.type, type) ?? type,
+            id: ref.id,
+            slug: ref.slug,
+            name: ref.name,
+            score: q ? (score || 10) : 10,
+            ...(Object.keys(secondary).length ? { secondaryIds: secondary } : {}),
+        });
+    }
+    out.sort((a, b) => b.score - a.score);
+    if (out.length > limit * 3)
+        out.length = limit * 3;
+}
+async function searchGame(ctx, game, q, type, limit) {
+    const candidates = [];
+    let calls = 0;
+    try {
+        if (game === 'cs2') {
+            const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
+            calls += 1;
+            if (!res.ok) {
+                return {
+                    candidates,
+                    calls,
+                    error: partialFromRejection(`game:${game}`, {
+                        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                        message: `cs2 search HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }),
+                };
+            }
+            const data = asRecord(res.data) ?? {};
+            const buckets = [
+                ['team', data.teams],
+                ['player', data.players],
+                ['event', data.events],
+                ['match', data.matches],
+                ['tournament', data.tournaments],
+            ];
+            for (const [t, bucket] of buckets) {
+                if (type !== 'any' && type !== t)
+                    continue;
+                const rows = Array.isArray(bucket) ? bucket : extractRows(bucket);
+                pushCandidates(candidates, game, t, rows, q, limit);
+            }
+            if (candidates.length === 0) {
+                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+            }
+        }
+        else if (game === 'dota2') {
+            const res = await fetchJson(ctx, '/dota2/search', { query: { q, limit } });
+            calls += 1;
+            if (!res.ok) {
+                return {
+                    candidates,
+                    calls,
+                    error: partialFromRejection(`game:${game}`, {
+                        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                        message: `dota2 search HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }),
+                };
+            }
+            const data = asRecord(res.data) ?? {};
+            for (const [t, key] of [
+                ['team', 'teams'],
+                ['player', 'players'],
+                ['tournament', 'tournaments'],
+                ['match', 'matches'],
+            ]) {
+                if (type !== 'any' && type !== t)
+                    continue;
+                pushCandidates(candidates, game, t, extractRows(data[key] ?? data), q, limit);
+            }
+            if (candidates.length === 0) {
+                pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+            }
+        }
+        else if (game === 'cod') {
+            const query = { q, limit };
+            if (type !== 'any')
+                query.type = type === 'team' ? 'org' : type;
+            const res = await fetchJson(ctx, '/cod/search', { query });
+            calls += 1;
+            if (!res.ok) {
+                return {
+                    candidates,
+                    calls,
+                    error: partialFromRejection(`game:${game}`, {
+                        code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                        message: `cod search HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }),
+                };
+            }
+            pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
+        }
+        else if (game === 'lol') {
+            const tasks = [];
+            if (type === 'any' || type === 'team') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/lol/teams', { query: { search: q, limit: String(limit) } });
+                    calls += 1;
+                    if (res.ok)
+                        pushCandidates(candidates, game, 'team', extractRows(res.data), q, limit);
+                })());
+            }
+            if (type === 'any' || type === 'player') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/lol/players', { query: { search: q, limit: String(limit) } });
+                    calls += 1;
+                    if (res.ok)
+                        pushCandidates(candidates, game, 'player', extractRows(res.data), q, limit);
+                })());
+            }
+            if (type === 'any' || type === 'tournament') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/lol/tournaments', { query: { limit: String(limit) } });
+                    calls += 1;
+                    if (res.ok) {
+                        const rows = extractRows(res.data).filter((row) => {
+                            const name = pickString(asRecord(row)?.name, asRecord(row)?.slug) ?? '';
+                            return !q || rankScore(q, name) > 0;
+                        });
+                        pushCandidates(candidates, game, 'tournament', rows, q, limit);
+                    }
+                })());
+            }
+            if (type === 'any' || type === 'event' || type === 'league') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/lol/leagues', {});
+                    calls += 1;
+                    if (res.ok) {
+                        const rows = extractRows(res.data).filter((row) => {
+                            const name = pickString(asRecord(row)?.name, asRecord(row)?.slug) ?? '';
+                            return !q || rankScore(q, name) > 0;
+                        });
+                        pushCandidates(candidates, game, 'league', rows, q, limit);
+                    }
+                })());
+            }
+            await Promise.all(tasks);
+        }
+        else if (game === 'ufc') {
+            const tasks = [];
+            if (type === 'any' || type === 'fighter' || type === 'player') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/ufc/fighters', { query: { q, limit, page: 1 } });
+                    calls += 1;
+                    if (res.ok)
+                        pushCandidates(candidates, game, 'fighter', extractRows(res.data), q, limit);
+                })());
+            }
+            if (type === 'any' || type === 'event' || type === 'tournament') {
+                tasks.push((async () => {
+                    const res = await fetchJson(ctx, '/ufc/events', { query: { q, limit, page: 1 } });
+                    calls += 1;
+                    if (res.ok)
+                        pushCandidates(candidates, game, 'event', extractRows(res.data), q, limit);
+                })());
+            }
+            await Promise.all(tasks);
+        }
+    }
+    catch (e) {
+        return {
+            candidates,
+            calls,
+            error: partialFromRejection(`game:${game}`, {
+                code: 'UPSTREAM',
+                message: e.message,
+            }),
+        };
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    return { candidates: candidates.slice(0, limit), calls };
+}
+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.
+Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['q'],
+        properties: {
+            q: stringSchema('Search text (name or tag). Keep short.', 'T1'),
+            game: gameSchema({
+                allowAll: false,
+                description: 'Strongly recommended. If omitted, fans out across primary games and ranks candidates.',
+            }),
+            type: {
+                type: 'string',
+                enum: ['player', 'team', 'event', 'tournament', 'match', 'fighter', 'any'],
+                default: 'any',
+                description: 'Entity type bias. Example: "team".',
+            },
+            limit: limitSchema({ default: 5, max: 10, description: 'Max ranked candidates (default 5, max 10).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const q = typeof args.q === 'string' ? args.q.trim() : '';
+        if (!q) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'q is required and must be a non-empty string',
+                game: null,
+                source: 'resolve_entity',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const gameParse = parseGame(args.game, { allowAll: false });
+        if (gameParse.error && args.game != null && args.game !== '') {
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: gameParse.error,
+                game: null,
+                source: 'resolve_entity',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const type = typeof args.type === 'string' ? args.type : 'any';
+        const limit = clampInt(args.limit, 5, 1, 10);
+        const games = gameParse.game && isPrimaryGame(gameParse.game)
+            ? [gameParse.game]
+            : [...PRIMARY_GAMES];
+        const partial = [];
+        let upstreamCalls = 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;
+            all.push(...r.candidates);
+            if (r.error)
+                partial.push(r.error);
+        }
+        all.sort((a, b) => b.score - a.score);
+        const candidates = all.slice(0, limit);
+        const best = candidates[0] ?? null;
+        const needsDisambiguation = !best ||
+            (candidates.length > 1 && (candidates[1].score >= best.score - 5 || best.score < 50));
+        return successEnvelope({
+            source: 'resolve_entity',
+            game: best?.game ?? gameParse.game ?? null,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            partial: partial.length ? partial : undefined,
+            entities: best
+                ? {
+                    games: [best.game],
+                    ids: {
+                        ...(best.id ? { id: best.id } : {}),
+                        ...(best.slug ? { slug: best.slug } : {}),
+                    },
+                }
+                : undefined,
+            data: {
+                query: q,
+                resolvedGame: best?.game ?? null,
+                best,
+                candidates,
+                needsDisambiguation,
+            },
+        });
+    },
+};
+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
+
+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.
+
+Parallel-safe: yes. Upstream cost: 1–3.
+Example: { "game": "cs2", "q": "vitality", "type": "team", "limit": 20 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            q: stringSchema('Optional search text.', 'vitality'),
+            type: {
+                type: 'string',
+                enum: ['team', 'player', 'tournament', 'event', 'fighter', 'league', 'any'],
+                default: 'any',
+                description: 'Entity type filter. Example: "team".',
+            },
+            limit: limitSchema({ default: DEFAULT_PAGE_LIMIT, max: MAX_PAGE_LIMIT }),
+            cursor: stringSchema('Opaque cursor from pagination.nextCursor only.'),
+            activeOnly: boolSchema('Prefer active entities when the API supports it.', true),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'search_entities',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        const q = typeof args.q === 'string' ? args.q.trim() : '';
+        const type = typeof args.type === 'string' ? args.type : 'any';
+        const limit = clampInt(args.limit, DEFAULT_PAGE_LIMIT, 1, MAX_PAGE_LIMIT);
+        const cursor = decodeCursor(typeof args.cursor === 'string' ? args.cursor : null);
+        const offset = typeof cursor?.offset === 'number' ? cursor.offset : 0;
+        const activeOnly = args.activeOnly !== false;
+        let items = [];
+        let upstreamCalls = 0;
+        let total = null;
+        const pageQuery = (extra = {}) => ({
+            limit,
+            offset,
+            page: Math.floor(offset / limit) + 1,
+            ...(q ? { q, search: q } : {}),
+            ...(activeOnly ? { active: true } : {}),
+            ...extra,
+        });
+        async function listPath(path, entityType, extra = {}) {
+            const res = await fetchJson(ctx, path, { query: pageQuery(extra) });
+            upstreamCalls += 1;
+            if (!res.ok) {
+                throw Object.assign(new Error(`HTTP ${res.status}`), {
+                    status: res.status,
+                    data: res.data,
+                    headers: res.headers,
+                });
+            }
+            const rows = extractRows(res.data);
+            const obj = asRecord(res.data);
+            if (typeof obj?.total === 'number')
+                total = obj.total;
+            items.push(...rows.map((row) => entityRef(row, entityType, game)));
+            return res;
+        }
+        try {
+            if (game === 'lol') {
+                if (type === 'team' || type === 'any')
+                    await listPath('/lol/teams', 'team');
+                if (type === 'player' || type === 'any')
+                    await listPath('/lol/players', 'player');
+                if (type === 'tournament' || type === 'any')
+                    await listPath('/lol/tournaments', 'tournament');
+                if (type === 'league' || type === 'any')
+                    await listPath('/lol/leagues', 'league');
+            }
+            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;
+                    if (res.ok) {
+                        const data = asRecord(res.data) ?? {};
+                        if (type === 'any' || type === 'team') {
+                            items.push(...extractRows(data.teams).map((r) => entityRef(r, 'team', game)));
+                        }
+                        if (type === 'any' || type === 'player') {
+                            items.push(...extractRows(data.players).map((r) => entityRef(r, 'player', game)));
+                        }
+                        if (type === 'any' || type === 'event') {
+                            items.push(...extractRows(data.events).map((r) => entityRef(r, 'event', game)));
+                        }
+                    }
+                }
+                else {
+                    if (type === 'team' || type === 'any')
+                        await listPath('/cs2/teams', 'team');
+                    if (type === 'player' || type === 'any')
+                        await listPath('/cs2/players', 'player');
+                    if (type === 'event' || type === 'tournament' || type === 'any')
+                        await listPath('/cs2/events', 'event');
+                }
+            }
+            else if (game === 'dota2') {
+                if (q) {
+                    const res = await fetchJson(ctx, '/dota2/search', { query: { q, limit } });
+                    upstreamCalls += 1;
+                    if (res.ok) {
+                        const data = asRecord(res.data) ?? {};
+                        if (type === 'team' || type === 'any')
+                            items.push(...extractRows(data.teams ?? res.data).map((r) => entityRef(r, 'team', game)));
+                        if (type === 'player' || type === 'any')
+                            items.push(...extractRows(data.players).map((r) => entityRef(r, 'player', game)));
+                        if (type === 'tournament' || type === 'any')
+                            items.push(...extractRows(data.tournaments).map((r) => entityRef(r, 'tournament', game)));
+                    }
+                }
+                else {
+                    if (type === 'team' || type === 'any')
+                        await listPath('/dota2/teams', 'team');
+                    if (type === 'player' || type === 'any')
+                        await listPath('/dota2/players', 'player');
+                    if (type === 'tournament' || type === 'any')
+                        await listPath('/dota2/tournaments', 'tournament');
+                }
+            }
+            else if (game === 'cod') {
+                if (q) {
+                    const res = await fetchJson(ctx, '/cod/search', {
+                        query: { q, limit, ...(type !== 'any' ? { type: type === 'team' ? 'org' : type } : {}) },
+                    });
+                    upstreamCalls += 1;
+                    if (res.ok)
+                        items.push(...extractRows(res.data).map((r) => entityRef(r, type === 'any' ? 'unknown' : type, game)));
+                }
+                else {
+                    if (type === 'player' || type === 'any')
+                        await listPath('/cod/players', 'player');
+                    if (type === 'team' || type === 'any')
+                        await listPath('/cod/orgs', 'team');
+                    if (type === 'tournament' || type === 'any')
+                        await listPath('/cod/tournaments', 'tournament');
+                }
+            }
+            else if (game === 'ufc') {
+                if (type === 'fighter' || type === 'player' || type === 'any') {
+                    await listPath('/ufc/fighters', 'fighter', q ? { q } : {});
+                }
+                if (type === 'event' || type === 'tournament' || type === 'any') {
+                    await listPath('/ufc/events', 'event', q ? { q } : {});
+                }
+            }
+        }
+        catch (e) {
+            return errorEnvelope({
+                code: mapHttpToCode(e.status ?? 0, { gameNotIncluded: gameNotIncludedHint(e.data) }),
+                message: e.message ?? 'search failed',
+                game,
+                source: 'search_entities',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+                httpStatus: e.status,
+                rateLimit: e.headers,
+            });
+        }
+        // de-dupe by game+type+id
+        const seen = new Set();
+        items = items.filter((it) => {
+            const key = `${it.game}:${it.type}:${it.id}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        }).slice(0, limit);
+        const hasMore = items.length >= limit;
+        return successEnvelope({
+            source: 'search_entities',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            pagination: {
+                limit,
+                offset,
+                total,
+                hasMore,
+                nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
+                prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
+            },
+            data: { items },
+        });
+    },
+};
+export const resolveTools = [resolveEntity, searchEntities];