cito-mcp 0.1.0 → 0.2.2

package/dist/tools/types.js

@@ -0,0 +1,85 @@
+import { toMcpResult } from '../envelope.js';
+export const PRIMARY_GAMES = ['lol', 'cs2', 'dota2', 'cod', 'ufc'];
+export const GAME_ENUM = [...PRIMARY_GAMES, 'all'];
+export function isPrimaryGame(value) {
+    return typeof value === 'string' && PRIMARY_GAMES.includes(value);
+}
+export function parseGame(value, opts) {
+    if (value === undefined || value === null || value === '') {
+        if (opts?.required)
+            return { error: 'game is required' };
+        return {};
+    }
+    if (typeof value !== 'string')
+        return { error: 'game must be a string' };
+    const g = value.toLowerCase();
+    if (g === 'all') {
+        if (opts?.allowAll === false) {
+            return { error: 'game=all is not valid for this tool; pick lol|cs2|dota2|cod|ufc' };
+        }
+        return { game: 'all' };
+    }
+    if (PRIMARY_GAMES.includes(g)) {
+        return { game: g };
+    }
+    return {
+        error: `unsupported game "${value}"; use lol|cs2|dota2|cod|ufc${opts?.allowAll !== false ? '|all' : ''}`,
+    };
+}
+export function gameSchema(opts) {
+    const values = opts?.allowAll === false ? [...PRIMARY_GAMES] : [...GAME_ENUM];
+    return {
+        type: 'string',
+        enum: values,
+        description: opts?.description ??
+            (opts?.allowAll === false
+                ? 'Game title: lol | cs2 | dota2 | cod | ufc. Example: "cs2".'
+                : 'Game title: lol | cs2 | dota2 | cod | ufc | all. Omit or all for multi-game tools. Example: "lol".'),
+    };
+}
+export function limitSchema(opts) {
+    const def = opts?.default ?? 20;
+    const max = opts?.max ?? 50;
+    return {
+        type: 'integer',
+        minimum: 1,
+        maximum: max,
+        default: def,
+        description: opts?.description ??
+            `Max items to return (default ${def}, max ${max}). Example: ${def}.`,
+    };
+}
+export function boolSchema(description, defaultValue) {
+    const schema = {
+        type: 'boolean',
+        description,
+    };
+    if (defaultValue !== undefined)
+        schema.default = defaultValue;
+    return schema;
+}
+export function stringSchema(description, example) {
+    const schema = { type: 'string', description };
+    if (example)
+        schema.examples = [example];
+    return schema;
+}
+/** Normalize MCP handler return to MCP content result. */
+export async function runTool(def, args, ctx) {
+    try {
+        const result = await def.handler(args ?? {}, ctx);
+        if (result && typeof result === 'object' && 'content' in result) {
+            return result;
+        }
+        return toMcpResult(result);
+    }
+    catch (error) {
+        const { errorEnvelope, toMcpResult: toResult } = await import('../envelope.js');
+        return toResult(errorEnvelope({
+            code: 'UPSTREAM',
+            message: error.message || 'Unhandled tool error',
+            game: null,
+            source: def.name,
+        }));
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cito-mcp",
-  "version": "0.1.0",
-  "description": "Standalone MCP server for the Cito esports API — tools generated from the live OpenAPI spec, zero per-endpoint code.",
+  "version": "0.2.2",
+  "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": {
     "cito-mcp": "dist/index.js"
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "tsx --test src/*.test.ts",
+    "test": "tsx --test src/**/*.test.ts src/*.test.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"
   },

package/dist/executor.js

@@ -1,75 +0,0 @@
-export const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024;
-export function buildRequestUrl(baseUrl, tool, args) {
-    let path = tool.path;
-    for (const param of tool.pathParams) {
-        const value = args[param];
-        if (value === undefined || value === null) {
-            throw new Error(`missing required path parameter: ${param}`);
-        }
-        path = path.split(`{${param}}`).join(encodeURIComponent(String(value)));
-    }
-    const query = new URLSearchParams();
-    for (const param of tool.queryParams) {
-        const value = args[param];
-        if (value === undefined || value === null)
-            continue;
-        if (Array.isArray(value)) {
-            for (const item of value)
-                query.append(param, String(item));
-        }
-        else {
-            query.append(param, String(value));
-        }
-    }
-    const qs = query.toString();
-    const base = baseUrl.replace(/\/+$/, '');
-    return `${base}${path}${qs ? `?${qs}` : ''}`;
-}
-export async function executeApiCall(opts) {
-    const fetcher = opts.fetchImpl ?? fetch;
-    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
-    let url;
-    try {
-        // Per-tool base: each source spec declares its own servers[0].url (LoL
-        // paths already include /api/v1/lol; global paths are relative to /api/v1).
-        const baseUrl = opts.tool.baseUrl || opts.baseUrl;
-        url = buildRequestUrl(baseUrl, opts.tool, opts.args);
-    }
-    catch (error) {
-        return { content: [{ type: 'text', text: error.message }], isError: true };
-    }
-    const headers = {
-        'x-api-key': opts.apiKey,
-        accept: 'application/json',
-    };
-    let body;
-    if (opts.tool.hasBody && opts.args.body !== undefined) {
-        headers['content-type'] = 'application/json';
-        body = JSON.stringify(opts.args.body);
-    }
-    const response = await fetcher(url, { method: opts.tool.method, headers, body });
-    const text = await response.text();
-    if (!response.ok) {
-        return {
-            content: [{ type: 'text', text: `HTTP ${response.status}\n\n${text}` }],
-            isError: true,
-        };
-    }
-    return { content: [{ type: 'text', text: present(text, maxBytes) }] };
-}
-/** Pretty-print JSON; truncate oversized bodies with an agent-actionable note. */
-export function present(text, maxBytes) {
-    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;
-}

package/dist/spec.js

@@ -1,193 +0,0 @@
-/**
- * Multi-spec loading for cito-mcp.
- *
- * The global spec (…/api/v1/openapi.json) does NOT cover every game — LoL has
- * its own spec (…/api/v1/lol/openapi.json) and other games may ship keyed
- * specs later. Boot fetches a list of spec sources, opportunistically probes
- * per-game spec URLs WITH the x-api-key header (skips 401/404 quietly), and
- * merges everything that answered.
- *
- * Per-source base URL rule (data-driven, documented in README):
- *   baseUrl = spec.servers[0].url when absolute, else CITO_API_BASE.
- * The global spec's paths are relative to /api/v1 (its servers entry); the
- * LoL spec's paths already include /api/v1/lol and its servers entry is the
- * bare origin — so using servers[0].url + verbatim paths is correct for both.
- * Escape hatch: CITO_SPEC_BASE_<KEY> (uppercased key, dashes → underscores).
- *
- * Cache: one merged .spec-cache.json storing per-source entries; any source
- * that fails to fetch falls back to its cached entry.
- */
-import { readFile, writeFile } from 'node:fs/promises';
-export const DEFAULT_API_BASE = 'https://api.citoapi.com/api/v1';
-/** Games probed opportunistically for keyed specs at boot (with the API key). */
-export const OPPORTUNISTIC_SPEC_KEYS = ['cod', 'fortnite', 'dota2', 'cs2', 'ufc'];
-/** stderr ONLY — stdout is the MCP stdio channel. */
-export function log(message) {
-    console.error(`[cito-mcp] ${message}`);
-}
-export function specRefreshMinutes() {
-    const parsed = Number(process.env.CITO_SPEC_REFRESH_MINUTES);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : 60;
-}
-/** Key from a spec URL: the path segment before openapi.json ('global' when none). */
-export function specKeyFromUrl(url, apiBase) {
-    const base = apiBase.replace(/\/+$/, '');
-    if (url === `${base}/openapi.json`)
-        return 'global';
-    const match = url.replace(/\/+$/, '').match(/\/([^/]+)\/openapi\.json$/);
-    return match?.[1] ?? 'global';
-}
-/**
- * Source list resolution:
- *  - CITO_OPENAPI_URLS (comma-separated) overrides entirely.
- *  - CITO_OPENAPI_URL (singular) overrides to a single source.
- *  - Default: global + lol specs on CITO_API_BASE.
- */
-export function defaultSourceDefs(apiBase, env = process.env) {
-    const base = apiBase.replace(/\/+$/, '');
-    if (env.CITO_OPENAPI_URLS) {
-        return env.CITO_OPENAPI_URLS
-            .split(',')
-            .map((url) => url.trim())
-            .filter(Boolean)
-            .map((url) => ({ key: specKeyFromUrl(url, base), url }));
-    }
-    if (env.CITO_OPENAPI_URL) {
-        const url = env.CITO_OPENAPI_URL.trim();
-        return [{ key: specKeyFromUrl(url, base), url }];
-    }
-    return [
-        { key: 'global', url: `${base}/openapi.json` },
-        { key: 'lol', url: `${base}/lol/openapi.json` },
-    ];
-}
-/** Per-source base URL: env escape hatch → servers[0].url when absolute → apiBase. */
-export function baseUrlForSpec(key, spec, apiBase, env = process.env) {
-    const envKey = `CITO_SPEC_BASE_${key.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
-    const override = env[envKey];
-    if (override)
-        return override.replace(/\/+$/, '');
-    const server = spec.servers?.[0]?.url;
-    if (server && /^https?:\/\//.test(server))
-        return server.replace(/\/+$/, '');
-    return apiBase.replace(/\/+$/, '');
-}
-export async function fetchSpec(url, opts = {}) {
-    const fetcher = opts.fetchImpl ?? fetch;
-    const headers = { accept: 'application/json' };
-    if (opts.apiKey)
-        headers['x-api-key'] = opts.apiKey;
-    const response = await fetcher(url, { headers });
-    if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
-    }
-    const spec = (await response.json());
-    if (!spec || typeof spec !== 'object' || !spec.paths) {
-        throw new Error('response is not an OpenAPI document');
-    }
-    return spec;
-}
-export async function readSpecCache(cachePath) {
-    try {
-        const raw = await readFile(cachePath, 'utf8');
-        const parsed = JSON.parse(raw);
-        return parsed && Array.isArray(parsed.sources) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeSpecCache(cachePath, sources) {
-    try {
-        const file = {
-            fetchedAt: new Date().toISOString(),
-            sources: sources.map((source) => ({
-                key: source.key,
-                url: source.url,
-                baseUrl: source.baseUrl,
-                spec: source.spec,
-            })),
-        };
-        await writeFile(cachePath, JSON.stringify(file), 'utf8');
-    }
-    catch (error) {
-        log(`spec cache write failed: ${error.message}`);
-    }
-}
-/**
- * Load all sources: declared defs (network → cache fallback per source), then
- * opportunistic per-game probes with the API key (skip non-200 quietly).
- */
-export async function loadSpecSources(opts) {
-    const cache = await readSpecCache(opts.cachePath);
-    const sources = [];
-    const skipped = [];
-    let cacheDirty = false;
-    for (const def of opts.defs) {
-        try {
-            const spec = await fetchSpec(def.url, { apiKey: opts.apiKey, fetchImpl: opts.fetchImpl });
-            sources.push({
-                ...def,
-                spec,
-                baseUrl: baseUrlForSpec(def.key, spec, opts.apiBase),
-                origin: 'network',
-            });
-            cacheDirty = true;
-        }
-        catch (error) {
-            const cached = cache?.sources.find((entry) => entry.key === def.key);
-            if (cached) {
-                log(`spec '${def.key}' fetch failed (${error.message}) — using cached copy`);
-                sources.push({ ...def, spec: cached.spec, baseUrl: cached.baseUrl, origin: 'cache' });
-            }
-            else {
-                skipped.push({ ...def, reason: error.message });
-                log(`spec '${def.key}' skipped: ${error.message} (no cache)`);
-            }
-        }
-    }
-    const declaredKeys = new Set(opts.defs.map((def) => def.key));
-    const base = opts.apiBase.replace(/\/+$/, '');
-    for (const key of opts.opportunisticKeys ?? []) {
-        if (declaredKeys.has(key))
-            continue;
-        const url = `${base}/${key}/openapi.json`;
-        try {
-            const spec = await fetchSpec(url, { apiKey: opts.apiKey, fetchImpl: opts.fetchImpl });
-            log(`spec '${key}' discovered at ${url}`);
-            sources.push({ key, url, spec, baseUrl: baseUrlForSpec(key, spec, opts.apiBase), origin: 'network' });
-            cacheDirty = true;
-        }
-        catch (error) {
-            skipped.push({ key, url, reason: error.message });
-            log(`spec '${key}' skipped: ${error.message}`);
-        }
-    }
-    const networkSources = sources.filter((source) => source.origin === 'network');
-    if (cacheDirty && networkSources.length > 0) {
-        // Merge fresh sources over the previous cache so skipped keys keep theirs.
-        const merged = [...networkSources];
-        for (const cachedEntry of cache?.sources ?? []) {
-            if (!merged.some((source) => source.key === cachedEntry.key)) {
-                merged.push({ key: cachedEntry.key, url: cachedEntry.url, spec: cachedEntry.spec, baseUrl: cachedEntry.baseUrl, origin: 'cache' });
-            }
-        }
-        await writeSpecCache(opts.cachePath, merged);
-    }
-    return { sources, skipped, fetchedAt: Date.now() };
-}
-/** Re-fetch all sources when the refresh interval elapsed; null = not due. */
-export async function refreshSpecSourcesIfDue(state, opts) {
-    if (Date.now() - state.fetchedAt < opts.refreshMinutes * 60_000)
-        return null;
-    const next = await loadSpecSources(opts);
-    const changed = next.sources.length !== state.sources.length
-        || next.sources.some((source) => {
-            const previous = state.sources.find((entry) => entry.key === source.key);
-            return !previous || previous.spec !== source.spec;
-        });
-    if (!changed)
-        return { ...next, sources: state.sources, fetchedAt: Date.now() };
-    log(`specs refreshed (${next.sources.length} sources)`);
-    return next;
-}

package/dist/tools.js

@@ -1,203 +0,0 @@
-import { log } from './spec.js';
-const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
-const MAX_REF_DEPTH = 4;
-/** Resolve local #/components/... $refs (bounded depth; cycles returned as-is). */
-export function resolveRefs(node, spec, depth = 0) {
-    if (depth > MAX_REF_DEPTH || node === null || typeof node !== 'object')
-        return node;
-    if (Array.isArray(node))
-        return node.map((item) => resolveRefs(item, spec, depth + 1));
-    const record = node;
-    if (typeof record.$ref === 'string' && record.$ref.startsWith('#/')) {
-        const target = record.$ref
-            .slice(2)
-            .split('/')
-            .reduce((acc, key) => {
-            if (acc && typeof acc === 'object')
-                return acc[key];
-            return undefined;
-        }, spec);
-        if (target === undefined)
-            return record;
-        return resolveRefs(target, spec, depth + 1);
-    }
-    const out = {};
-    for (const [key, value] of Object.entries(record)) {
-        out[key] = resolveRefs(value, spec, depth + 1);
-    }
-    return out;
-}
-/** Body schema passthrough: refs resolved, readOnly stripped (agents can't send those). */
-export function simplifyBodySchema(schema, spec) {
-    const resolved = resolveRefs(schema, spec);
-    if (resolved === null || typeof resolved !== 'object')
-        return resolved;
-    if (Array.isArray(resolved))
-        return resolved.map((item) => simplifyBodySchema(item, spec));
-    const out = {};
-    for (const [key, value] of Object.entries(resolved)) {
-        if (key === 'readOnly')
-            continue;
-        out[key] = simplifyBodySchema(value, spec);
-    }
-    return out;
-}
-function capitalize(segment) {
-    return segment ? segment[0].toUpperCase() + segment.slice(1) : segment;
-}
-/**
- * Fallback operation name when the spec has no operationId (the LoL spec
- * ships none): method + capitalized path segments, {param} → By<Param>,
- * leading api/version segments dropped.
- * get /api/v1/lol/live/{gameId}/stats → getLolLiveStatsByGameId
- */
-export function operationNameFromPath(method, path) {
-    const segments = path.split('/').filter(Boolean);
-    const parts = [method.toLowerCase()];
-    for (const segment of segments) {
-        if (segment === 'api' || /^v\d+$/.test(segment))
-            continue; // api + version segments
-        const param = segment.match(/^\{(.+)\}$/);
-        if (param) {
-            parts.push(`By${capitalize(param[1])}`);
-        }
-        else {
-            parts.push(capitalize(segment));
-        }
-    }
-    return parts.join('');
-}
-function sanitizeBase(operationName) {
-    return operationName.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
-}
-/**
- * Tool name: cito_ + sanitized operation name. Exact sanitized collisions
- * append the HTTP method, then a counter. (Cross-spec operationId collisions
- * are handled earlier with the spec-key prefix — see generateAllTools.)
- */
-export function sanitizeToolName(operationName, method, used) {
-    const base = `cito_${sanitizeBase(operationName)}`;
-    if (!used.has(base)) {
-        used.add(base);
-        return base;
-    }
-    const withMethod = `${base}_${method.toLowerCase()}`;
-    if (!used.has(withMethod)) {
-        used.add(withMethod);
-        return withMethod;
-    }
-    let counter = 2;
-    while (used.has(`${withMethod}_${counter}`))
-        counter += 1;
-    const name = `${withMethod}_${counter}`;
-    used.add(name);
-    return name;
-}
-function parameterDescription(param) {
-    const required = param.in === 'path' ? true : param.required === true;
-    const flags = [param.in, required ? 'required' : 'optional'].join(', ');
-    return `- ${param.name} (${flags})${param.description ? `: ${param.description}` : ''}`;
-}
-export function buildToolDescription(op) {
-    const parts = [];
-    if (op.summary)
-        parts.push(op.summary);
-    if (op.description && op.description !== op.summary)
-        parts.push(op.description);
-    const params = op.parameters ?? [];
-    if (params.length > 0) {
-        parts.push(`Parameters:\n${params.map(parameterDescription).join('\n')}`);
-    }
-    if (op.requestBody)
-        parts.push('Accepts a JSON request body (see the `body` argument).');
-    return parts.join('\n\n') || 'Cito API operation';
-}
-function jsonBodySchema(op, spec) {
-    const content = op.requestBody?.content ?? {};
-    const json = content['application/json'] ?? Object.values(content)[0];
-    return json?.schema ? simplifyBodySchema(json.schema, spec) : { type: 'object' };
-}
-export function buildOperationTool(method, path, op, source, used, namePrefix = '') {
-    const operationName = op.operationId || operationNameFromPath(method, path);
-    const pathParams = [];
-    const queryParams = [];
-    const properties = {};
-    const required = [];
-    for (const param of op.parameters ?? []) {
-        const schema = resolveRefs(param.schema ?? { type: 'string' }, source.spec);
-        properties[param.name] = {
-            ...schema,
-            ...(param.description ? { description: param.description } : {}),
-        };
-        if (param.in === 'path') {
-            pathParams.push(param.name);
-            required.push(param.name);
-        }
-        else if (param.in === 'query') {
-            queryParams.push(param.name);
-            if (param.required === true)
-                required.push(param.name);
-        }
-        // header/cookie params are not exposed as tool args (auth is server-side).
-    }
-    const hasBody = Boolean(op.requestBody);
-    if (hasBody) {
-        properties.body = {
-            ...jsonBodySchema(op, source.spec),
-            description: 'JSON request body.',
-        };
-        if (op.requestBody?.required === true)
-            required.push('body');
-    }
-    return {
-        name: sanitizeToolName(`${namePrefix}${operationName}`, method, used),
-        description: buildToolDescription(op),
-        inputSchema: {
-            type: 'object',
-            properties,
-            ...(required.length > 0 ? { required } : {}),
-            additionalProperties: false,
-        },
-        method: method.toUpperCase(),
-        path,
-        baseUrl: source.baseUrl,
-        sourceKey: source.key,
-        pathParams,
-        queryParams,
-        hasBody,
-    };
-}
-/**
- * Generate tools for all loaded spec sources. On an operationId collision
- * across sources, the LATER source's tool is prefixed with its spec key
- * (cito_<key>_...) and the collision is logged to stderr.
- */
-export function generateAllTools(sources) {
-    const tools = [];
-    const used = new Set();
-    const claimedOperationIds = new Set();
-    for (const source of sources) {
-        for (const [path, item] of Object.entries(source.spec.paths ?? {})) {
-            for (const [method, op] of Object.entries(item ?? {})) {
-                if (!HTTP_METHODS.has(method.toLowerCase()) || !op || typeof op !== 'object')
-                    continue;
-                let namePrefix = '';
-                if (op.operationId && claimedOperationIds.has(op.operationId)) {
-                    namePrefix = `${source.key}_`;
-                    log(`operationId collision: '${op.operationId}' also in spec '${source.key}' — tool prefixed cito_${source.key}_…`);
-                }
-                const tool = buildOperationTool(method, path, op, source, used, namePrefix);
-                if (tool) {
-                    tools.push(tool);
-                    if (op.operationId)
-                        claimedOperationIds.add(op.operationId);
-                }
-            }
-        }
-    }
-    return tools;
-}
-/** Single-spec convenience wrapper (tests / single-source setups). */
-export function generateTools(spec, baseUrl = '') {
-    return generateAllTools([{ key: 'global', baseUrl, spec }]);
-}