cito-mcp 0.1.0 → 0.2.2

package/dist/client.js

@@ -0,0 +1,208 @@
+/**
+ * Authenticated Cito REST client for curated tools.
+ * Auth: CITO_API_KEY → x-api-key. Logs never include the key.
+ */
+export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
+export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
+/** stderr ONLY — stdout is the MCP stdio channel. */
+export function log(message) {
+    console.error(`[cito-mcp] ${message}`);
+}
+export function authHeaders(apiKey, extra) {
+    return {
+        'x-api-key': apiKey,
+        accept: 'application/json',
+        ...extra,
+    };
+}
+export function parseRateLimitHeaders(headers) {
+    if (!headers)
+        return {};
+    const limitRaw = headers.get('x-ratelimit-limit') ?? headers.get('ratelimit-limit');
+    const remainingRaw = headers.get('x-ratelimit-remaining') ?? headers.get('ratelimit-remaining');
+    const resetRaw = headers.get('x-ratelimit-reset') ?? headers.get('ratelimit-reset');
+    const tier = headers.get('x-cito-tier') ?? headers.get('x-plan-tier');
+    return {
+        tier: tier ?? null,
+        limit: limitRaw != null && limitRaw !== '' ? Number(limitRaw) : null,
+        remaining: remainingRaw != null && remainingRaw !== '' ? Number(remainingRaw) : null,
+        resetAt: resetRaw ?? null,
+    };
+}
+/**
+ * Build absolute URL under api base.
+ * path must start with `/`. Query values skip null/undefined.
+ * Arrays become repeated query keys.
+ */
+export function buildUrl(baseUrl, path, query) {
+    if (!path.startsWith('/')) {
+        throw new Error(`path must start with /: ${path}`);
+    }
+    const base = baseUrl.replace(/\/+$/, '');
+    // LoL-style absolute API paths: if path already includes /api/v1, use origin only
+    let originBase = base;
+    if (path.startsWith('/api/v1/') && base.endsWith('/api/v1')) {
+        originBase = base.slice(0, -'/api/v1'.length) || base;
+    }
+    const qs = new URLSearchParams();
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    qs.append(key, String(item));
+            }
+            else if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+                qs.append(key, String(value));
+            }
+            else {
+                qs.append(key, JSON.stringify(value));
+            }
+        }
+    }
+    const q = qs.toString();
+    return `${originBase}${path}${q ? `?${q}` : ''}`;
+}
+/** Pretty-print JSON; truncate oversized bodies with an agent-actionable note. */
+export function present(text, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+    let out = text;
+    try {
+        out = JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        // Not JSON — return as-is.
+    }
+    if (out.length > maxBytes) {
+        return (`${out.slice(0, maxBytes)}\n\n` +
+            `[cito-mcp] Response truncated at ${maxBytes} bytes (full body was ${out.length}). ` +
+            `Narrow the result with query parameters (e.g. smaller limit, date range, or an id filter) and retry.`);
+    }
+    return out;
+}
+export async function fetchJson(ctx, path, opts) {
+    const fetcher = ctx.fetchImpl ?? fetch;
+    const method = (opts?.method ?? 'GET').toUpperCase();
+    const url = buildUrl(ctx.baseUrl, path, opts?.query);
+    const headers = authHeaders(ctx.apiKey);
+    let body;
+    if (opts?.body !== undefined && method !== 'GET' && method !== 'HEAD') {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(opts.body);
+    }
+    let response;
+    try {
+        response = await fetcher(url, { method, headers, body });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 0,
+            data: { message: error.message },
+            headers: {},
+            text: error.message,
+            url,
+        };
+    }
+    const text = await response.text();
+    let data = null;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        data = text;
+    }
+    return {
+        ok: response.ok,
+        status: response.status,
+        data,
+        headers: parseRateLimitHeaders(response.headers),
+        text,
+        url,
+    };
+}
+export async function parallelGet(ctx, paths) {
+    const results = await Promise.all(paths.map(async ({ key, path, query }) => {
+        const result = await fetchJson(ctx, path, { query });
+        return [key, result];
+    }));
+    return Object.fromEntries(results);
+}
+/** Best-effort row extraction across Cito response shapes. */
+export function extractRows(data) {
+    if (data == null)
+        return [];
+    if (Array.isArray(data))
+        return data;
+    if (typeof data !== 'object')
+        return [];
+    const obj = data;
+    // Order matters: UFC /ufc/live nests real bouts under liveBouts while also
+    // shipping supervisor `events` (no fighter names). Prefer bout-like keys first.
+    for (const key of [
+        'data',
+        'liveBouts',
+        'bouts',
+        'matches',
+        'items',
+        'results',
+        'teams',
+        'players',
+        'fighters',
+        'tournaments',
+        'leagues',
+        'orgs',
+        'events',
+        'rankings',
+        'standings',
+        'rows',
+    ]) {
+        if (Array.isArray(obj[key]))
+            return obj[key];
+    }
+    // Nested data.matches / data.items
+    if (obj.data && typeof obj.data === 'object' && !Array.isArray(obj.data)) {
+        return extractRows(obj.data);
+    }
+    return [];
+}
+export function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function pickString(...values) {
+    for (const v of values) {
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+        if (typeof v === 'number' && Number.isFinite(v))
+            return String(v);
+    }
+    return undefined;
+}
+export function clampInt(value, fallback, min, max) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}
+export function encodeCursor(payload) {
+    return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+}
+export function decodeCursor(cursor) {
+    if (!cursor)
+        return null;
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf8');
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function gameNotIncludedHint(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data ?? '');
+    return /GAME_NOT_INCLUDED|not included|plan does not|upgrade/i.test(text);
+}

package/dist/envelope.js

@@ -0,0 +1,210 @@
+/**
+ * Canonical JSON envelope for every curated cito-mcp tool response.
+ * Agents branch on `ok` / `error.code` / `partial[]` without scraping prose.
+ */
+export function isOk(e) {
+    return e.ok === true;
+}
+export function isError(e) {
+    return e.ok === false;
+}
+export function hasPartial(e) {
+    return e.ok === true && Array.isArray(e.partial) && e.partial.length > 0;
+}
+export const DEFAULT_RECOVER = {
+    NOT_FOUND: [
+        'Call resolve_entity or search_entities with a name/query from the user',
+        'Retry this tool with an id/slug from the results',
+    ],
+    AMBIGUOUS_ENTITY: [
+        'Disambiguate using an exact id or slug from the candidates list',
+        'Retry with that single identifier',
+    ],
+    RATE_LIMIT: [
+        'Wait until the rate limit resets (see meta.rateLimit / message)',
+        'Retry once; reduce parallel tool calls and prefer composites',
+    ],
+    UNAUTHORIZED: [
+        'Verify CITO_API_KEY is set and valid',
+        'Call api_health to confirm tier and included games',
+    ],
+    UPSTREAM: [
+        'Retry this tool once',
+        'If it still fails, narrow params (limit, date range) or use a smaller tool',
+    ],
+    VALIDATION: [
+        'Fix arguments using the error message and tool schema',
+        'Re-check required params, enums, and exclusive id/slug groups',
+    ],
+    UNSUPPORTED_GAME: [
+        'Use a supported game enum value for this tool (lol|cs2|dota2|cod|ufc)',
+        'Call api_health to see which games your plan includes',
+    ],
+    PATH_NOT_ALLOWED: [
+        'Use only allowlisted path prefixes: /health /lol /cs2 /dota2 /cod /ufc /fortnite',
+        'Prefer a curated tool from list_capabilities when one covers the outcome',
+    ],
+    NOT_IMPLEMENTED: [
+        'Call list_capabilities for an alternate tool that covers this job',
+        'Use call_api only if you know a valid REST path for the gap',
+    ],
+};
+export const MAX_ENVELOPE_CHARS = 100_000;
+export const DEFAULT_PAGE_LIMIT = 20;
+export const MAX_PAGE_LIMIT = 50;
+export function mapHttpToCode(status, hints) {
+    if (status === 404)
+        return 'NOT_FOUND';
+    if (status === 429)
+        return 'RATE_LIMIT';
+    if (status === 401)
+        return 'UNAUTHORIZED';
+    if (status === 403) {
+        return hints?.gameNotIncluded ? 'UNSUPPORTED_GAME' : 'UNAUTHORIZED';
+    }
+    if (status === 400 && hints?.ambiguous)
+        return 'AMBIGUOUS_ENTITY';
+    if (status === 400)
+        return 'VALIDATION';
+    if (status >= 500 || status === 0)
+        return 'UPSTREAM';
+    return 'UPSTREAM';
+}
+export function newRequestId() {
+    return `mcp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+export function successEnvelope(args) {
+    const meta = {
+        game: args.game,
+        source: args.source,
+        fetchedAt: args.fetchedAt ?? new Date().toISOString(),
+    };
+    if (args.requestId)
+        meta.requestId = args.requestId;
+    if (args.tookMs !== undefined)
+        meta.tookMs = args.tookMs;
+    if (args.upstreamCalls !== undefined)
+        meta.upstreamCalls = args.upstreamCalls;
+    if (args.rateLimit)
+        meta.rateLimit = args.rateLimit;
+    if (args.warnings?.length)
+        meta.warnings = args.warnings;
+    if (args.entities)
+        meta.entities = args.entities;
+    const out = {
+        ok: true,
+        data: args.data,
+        meta,
+    };
+    if (args.pagination)
+        out.pagination = args.pagination;
+    if (args.partial?.length)
+        out.partial = args.partial;
+    if (args.truncated)
+        out.truncated = args.truncated;
+    return out;
+}
+export function errorEnvelope(args) {
+    const retryable = args.retryable ??
+        (args.code === 'RATE_LIMIT' || args.code === 'UPSTREAM');
+    const meta = {
+        game: args.game,
+        source: args.source,
+        fetchedAt: args.fetchedAt ?? new Date().toISOString(),
+    };
+    if (args.requestId)
+        meta.requestId = args.requestId;
+    if (args.tookMs !== undefined)
+        meta.tookMs = args.tookMs;
+    if (args.upstreamCalls !== undefined)
+        meta.upstreamCalls = args.upstreamCalls;
+    if (args.rateLimit)
+        meta.rateLimit = args.rateLimit;
+    const error = {
+        code: args.code,
+        message: args.message,
+        recover: args.recover ?? DEFAULT_RECOVER[args.code],
+        retryable,
+    };
+    if (args.httpStatus !== undefined)
+        error.httpStatus = args.httpStatus;
+    if (args.retryAfterMs !== undefined)
+        error.retryAfterMs = args.retryAfterMs;
+    if (args.hint)
+        error.hint = args.hint;
+    if (args.details)
+        error.details = args.details;
+    return {
+        ok: false,
+        data: null,
+        meta,
+        error,
+    };
+}
+export function partialFromRejection(section, err) {
+    const code = err.code ?? 'UPSTREAM';
+    return {
+        section,
+        ok: false,
+        code,
+        message: err.message ?? `Section "${section}" failed`,
+        recover: err.recover ?? DEFAULT_RECOVER[code],
+        ...(err.httpStatus !== undefined ? { httpStatus: err.httpStatus } : {}),
+    };
+}
+/**
+ * Enforce MAX_ENVELOPE_CHARS with structural shrink (never mid-slice JSON).
+ * Prefers trimming data.items when present.
+ */
+export function sealEnvelope(envelope) {
+    let text = JSON.stringify(envelope);
+    if (text.length <= MAX_ENVELOPE_CHARS)
+        return envelope;
+    if (!envelope.ok)
+        return envelope;
+    const data = envelope.data;
+    if (data && Array.isArray(data.items)) {
+        let items = data.items;
+        const from = items.length;
+        while (items.length > 1 && JSON.stringify({ ...envelope, data: { ...data, items } }).length > MAX_ENVELOPE_CHARS) {
+            items = items.slice(0, Math.max(1, Math.floor(items.length / 2)));
+        }
+        const sealed = {
+            ...envelope,
+            data: { ...data, items },
+            truncated: {
+                applied: true,
+                reason: 'max_envelope_chars',
+                maxChars: MAX_ENVELOPE_CHARS,
+                dropped: { itemsFrom: from, itemsTo: items.length },
+                recover: [
+                    'Pass a smaller limit or use pagination.cursor for the next page',
+                    'Request view=summary and avoid heavy include* flags',
+                ],
+            },
+            pagination: envelope.pagination
+                ? { ...envelope.pagination, hasMore: true }
+                : { limit: from, hasMore: true },
+        };
+        return sealed;
+    }
+    return {
+        ...envelope,
+        truncated: {
+            applied: true,
+            reason: 'max_envelope_chars',
+            maxChars: MAX_ENVELOPE_CHARS,
+            recover: [
+                'Request view=summary and lower limits',
+                'Drop optional include* flags (timeline, advanced, media)',
+            ],
+        },
+    };
+}
+export function toMcpResult(envelope) {
+    const sealed = sealEnvelope(envelope);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(sealed, null, 2) }],
+        ...(sealed.ok ? {} : { isError: true }),
+    };
+}