Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript
31.3 KB
Raw Blame
import { Router } from 'express';
import type { NextFunction, Request, Response } from 'express';
import { getDb, getUnifiedApiKey, getSetting } from '../db/index.js';
import { extractApiToken, timingSafeStringEqual } from './proxy.js';
import { runSearch } from '../services/search.js';
import { buildModelListing } from '../services/model-listing.js';
import { supportedParametersForPlatforms } from '../lib/sampling-params.js';
import { getRoutingScores, getRoutingStrategy, setRoutingStrategy } from '../services/router.js';
import type { RoutingStrategy } from '../services/scoring.js';
import { getCacheStats, clearCache } from '../services/cache.js';
import { getCompressionStats } from '../services/compression/stats.js';
import { getQuotaOutlook } from '../services/quota-outlook.js';
import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';
import { z } from 'zod';

// ─────────────────────────────────────────────────────────────────────────
// MCP server for the gateway (POST /mcp) — Model Context Protocol over
// Streamable HTTP, stateless mode.
//
// Lets MCP-speaking agents (Claude Code, Cursor, Cline…) ask the router
// questions mid-session: which free models are usable right now and with
// which parameters, how healthy the provider pool is, what the routing
// strategy is, and how much quota the cache has saved — plus one control
// knob (switching the routing strategy). The ask_freellmapi tool also lets
// ChatGPT and other MCP clients run a non-streaming inference through the same
// /v1/chat/completions path as every OpenAI-compatible client.
//
// Hand-rolled JSON-RPC instead of the MCP SDK for the same reason the
// OpenAPI viewer is dependency-free (#482): the desktop bundle and the
// Node-20 CI matrix punish heavy/new dependencies, and a tools-only
// stateless MCP server is ~five methods of plain JSON-RPC. No sessions, no
// server-initiated streams (GET → 405), single JSON responses.
//
// Auth mirrors /v1: the unified API key as a Bearer token (or x-api-key).
// ─────────────────────────────────────────────────────────────────────────

export const mcpRouter = Router();

// Always negotiated to 2025-06-18: this transport rejects JSON-RPC batches,
// which the 2025-03-26 and 2024-11-05 revisions still allowed — echoing an
// older requested version while enforcing the newer transport rule promised
// clients batching they'd never get. Per the MCP spec the server answers with
// the latest version it supports; clients that can't speak it disconnect.
const PROTOCOL_VERSION = '2025-06-18';

interface JsonRpcRequest {
  jsonrpc?: string;
  id?: number | string | null;
  method?: string;
  params?: Record<string, unknown>;
}

function rpcResult(id: number | string | null, result: unknown) {
  return { jsonrpc: '2.0', id, result };
}

function rpcError(id: number | string | null, code: number, message: string) {
  return { jsonrpc: '2.0', id, error: { code, message } };
}

// One text block carrying pretty-printed JSON — the standard shape for
// machine-readable MCP tool output.
function toolJson(data: unknown) {
  const structuredContent = data && typeof data === 'object' && !Array.isArray(data)
    ? data as Record<string, unknown>
    : { result: data };
  return {
    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
    structuredContent,
  };
}

function toolError(message: string) {
  return { content: [{ type: 'text', text: message }], isError: true };
}

// ── Tool implementations ─────────────────────────────────────────────────

function listModels(args: Record<string, unknown>): unknown {
  const availableOnly = args.available_only !== false; // default true: agents want what they can use
  const { models, autoContextWindow } = buildModelListing();
  const rows = (availableOnly ? models.filter(m => m.available === 1) : models).map(m => ({
    id: m.id,
    name: m.name,
    context_window: m.contextWindow,
    available: m.available === 1,
    platforms: m.platforms,
    supports_tools: m.supportsTools,
    supported_parameters: supportedParametersForPlatforms(m.platforms, { tools: m.supportsTools }),
  }));
  return {
    auto: { id: 'auto', description: 'router picks the best available model', context_window: autoContextWindow },
    count: rows.length,
    models: rows,
  };
}

function providerHealth(): unknown {
  const db = getDb();
  const now = Date.now();
  const keys = db.prepare(`
    SELECT platform, status, COUNT(*) AS n
    FROM api_keys WHERE enabled = 1
    GROUP BY platform, status
  `).all() as Array<{ platform: string; status: string; n: number }>;
  const cooldowns = db.prepare(`
    SELECT platform, COUNT(*) AS n
    FROM rate_limit_cooldowns WHERE expires_at_ms > ?
    GROUP BY platform
  `).all(now) as Array<{ platform: string; n: number }>;
  const availableModels = db.prepare(`
    SELECT m.platform, COUNT(*) AS n
    FROM models m
    WHERE m.enabled = 1 AND EXISTS (
      SELECT 1 FROM api_keys k
      WHERE k.platform = m.platform AND k.enabled = 1
        AND (m.key_id IS NULL OR k.id = m.key_id)
    )
    GROUP BY m.platform
  `).all() as Array<{ platform: string; n: number }>;

  const byPlatform = new Map<string, { keys: Record<string, number>; active_cooldowns: number; available_models: number }>();
  const entry = (p: string) => {
    let e = byPlatform.get(p);
    if (!e) { e = { keys: {}, active_cooldowns: 0, available_models: 0 }; byPlatform.set(p, e); }
    return e;
  };
  for (const k of keys) entry(k.platform).keys[k.status] = k.n;
  for (const c of cooldowns) entry(c.platform).active_cooldowns = c.n;
  for (const m of availableModels) entry(m.platform).available_models = m.n;
  return Object.fromEntries([...byPlatform.entries()].sort(([a], [b]) => a.localeCompare(b)));
}

function providerList(): unknown {
  const db = getDb();
  const keys = db.prepare(`
    SELECT platform, COUNT(*) AS n,
      SUM(CASE WHEN status = 'healthy' THEN 1 ELSE 0 END) AS healthy,
      SUM(CASE WHEN status = 'rate_limited' THEN 1 ELSE 0 END) AS rate_limited,
      SUM(CASE WHEN status = 'invalid' THEN 1 ELSE 0 END) AS invalid,
      SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) AS error
    FROM api_keys WHERE enabled = 1
    GROUP BY platform
    ORDER BY platform
  `).all() as Array<{ platform: string; n: number; healthy: number; rate_limited: number; invalid: number; error: number }>;
  return keys.map(k => ({
    platform: k.platform,
    total_keys: k.n,
    healthy: k.healthy,
    rate_limited: k.rate_limited,
    invalid: k.invalid,
    error: k.error,
  }));
}

function clearCacheTool(): unknown {
  const n = clearCache();
  return { cleared_entries: n };
}

// Forecasting which free pools are about to run dry is the single most useful
// thing an agent can ask before committing to a long task on the free tier.
function quotaOutlook(): unknown {
  return getQuotaOutlook();
}

const USAGE_RANGES: Record<string, number> = { '24h': 24, '7d': 24 * 7, '30d': 24 * 30 };

function usageSummary(args: Record<string, unknown>): unknown {
  // Object.hasOwn: a prototype key ('constructor', 'toString') is truthy via
  // the prototype chain but multiplies to NaN below — fall back to 24h.
  const range = typeof args.range === 'string' && Object.hasOwn(USAGE_RANGES, args.range) ? args.range : '24h';
  const db = getDb();
  // SQLite datetime('now') format (space separator, no ms/Z) — an ISO 'T'
  // string compares GREATER than every same-day stored row (space < 'T'
  // lexicographically), which silently dropped the window's boundary day:
  // "24h" effectively meant "since UTC midnight". Same conversion as
  // routes/analytics.ts.
  const since = new Date(Date.now() - USAGE_RANGES[range] * 3600_000)
    .toISOString().slice(0, 19).replace('T', ' ');
  const totals = db.prepare(`
    SELECT COALESCE(SUM(total_requests), 0) AS requests,
           COALESCE(SUM(success_count), 0) AS successes,
           COALESCE(SUM(error_count), 0) AS errors,
           COALESCE(SUM(input_tokens), 0) AS input_tokens,
           COALESCE(SUM(output_tokens), 0) AS output_tokens
    FROM request_hourly WHERE hour >= ?
  `).get(since.slice(0, 13) + ':00:00') as { requests: number; successes: number; errors: number; input_tokens: number; output_tokens: number };
  const topModels = db.prepare(`
    SELECT platform, model_id, COUNT(*) AS requests,
           SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS successes
    FROM requests WHERE created_at >= ?
    GROUP BY platform, model_id ORDER BY requests DESC LIMIT 5
  `).all(since) as Array<{ platform: string; model_id: string; requests: number; successes: number }>;
  return {
    range,
    requests: totals.requests,
    // Over success+error only: 'canceled' rows (#752) are neither.
    success_rate: totals.successes + totals.errors > 0 ? Math.round((totals.successes / (totals.successes + totals.errors)) * 1000) / 10 : null,
    input_tokens: totals.input_tokens,
    output_tokens: totals.output_tokens,
    top_models: topModels,
  };
}

function routingInfo(): unknown {
  const scores = getRoutingScores();
  return {
    strategy: scores.strategy,
    // Which key of a platform requests are steered to (#919) — a separate knob
    // from the model strategy, so it has to be reported separately too.
    key_selection: scores.keySelectionStrategy,
    top_models: scores.scores
      .filter(s => s.enabled)
      .slice(0, 10)
      .map(s => ({ model: s.modelId, platform: s.platform, score: Math.round(s.score * 1000) / 1000 })),
  };
}

const ROUTING_STRATEGIES = ['priority', 'balanced', 'smartest', 'fastest', 'reliable', 'custom', 'decision'] as const;

function setStrategy(args: Record<string, unknown>): unknown {
  const strategy = args.strategy;
  if (typeof strategy !== 'string' || !(ROUTING_STRATEGIES as readonly string[]).includes(strategy)) {
    throw new Error(`strategy must be one of: ${ROUTING_STRATEGIES.join(', ')}`);
  }
  setRoutingStrategy(strategy as RoutingStrategy);
  return { strategy: getRoutingStrategy() };
}

const DEFAULT_MCP_INFERENCE_TIMEOUT_MS = 120_000;
const MAX_MCP_INFERENCE_TIMEOUT_MS = 300_000;

const askFreeLlmApiSchema = z.object({
  prompt: z.string().min(1).max(400_000),
  system: z.string().min(1).max(50_000).optional(),
  model: z.string().min(1).max(256).optional(),
  temperature: z.number().min(0).max(2).optional(),
  max_tokens: z.number().int().min(1).max(32_768).optional(),
  timeout_ms: z.number().int().min(1_000).max(MAX_MCP_INFERENCE_TIMEOUT_MS).optional(),
}).strict();

function mcpDefaultModel(): string {
  const configured = process.env.MCP_INFERENCE_DEFAULT_MODEL?.trim();
  if (!configured) return 'auto';
  if (configured.length > 256) {
    throw new Error('MCP_INFERENCE_DEFAULT_MODEL must be at most 256 characters');
  }
  return configured;
}

function mcpInferenceTimeoutMs(): number {
  const raw = process.env.MCP_INFERENCE_TIMEOUT_MS?.trim();
  if (!raw) return DEFAULT_MCP_INFERENCE_TIMEOUT_MS;
  const parsed = Number(raw);
  if (!Number.isInteger(parsed) || parsed < 1_000 || parsed > MAX_MCP_INFERENCE_TIMEOUT_MS) {
    return DEFAULT_MCP_INFERENCE_TIMEOUT_MS;
  }
  return parsed;
}

function loopbackChatCompletionsUrl(req: Request): string {
  const port = req.socket.localPort;
  if (!port) throw new Error('Cannot determine the local FreeLLMAPI port for inference');

  let address = (req.socket.localAddress || '127.0.0.1').split('%')[0];
  if (address === '0.0.0.0') address = '127.0.0.1';
  if (address === '::') address = '::1';
  if (address.startsWith('::ffff:')) address = address.slice('::ffff:'.length);
  const host = address.includes(':') ? `[${address}]` : address;
  return `http://${host}:${port}/v1/chat/completions`;
}

function assistantText(payload: any): string {
  const content = payload?.choices?.[0]?.message?.content;
  if (typeof content === 'string') return content;
  if (!Array.isArray(content)) return '';
  return content
    .map((part: any) => typeof part === 'string' ? part : (typeof part?.text === 'string' ? part.text : ''))
    .join('');
}

async function askFreeLlmApi(args: Record<string, unknown>, req: Request, res: Response): Promise<unknown> {
  const parsed = askFreeLlmApiSchema.safeParse(args);
  if (!parsed.success) {
    const detail = parsed.error.errors
      .map(error => `${error.path.join('.') || 'arguments'}: ${error.message}`)
      .slice(0, 5)
      .join(', ');
    throw new Error(`Invalid ask_freellmapi arguments: ${detail}`);
  }

  const input = parsed.data;
  const model = input.model?.trim() || mcpDefaultModel();
  const timeoutMs = input.timeout_ms ?? mcpInferenceTimeoutMs();
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
  const abortOnDisconnect = () => controller.abort();
  req.once('aborted', abortOnDisconnect);
  res.once('close', abortOnDisconnect);

  try {
    const messages = [
      ...(input.system ? [{ role: 'system', content: input.system }] : []),
      { role: 'user', content: input.prompt },
    ];
    const response = await fetch(loopbackChatCompletionsUrl(req), {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: 'application/json',
        Authorization: `Bearer ${getUnifiedApiKey()}`,
      },
      body: JSON.stringify({
        model,
        messages,
        stream: false,
        ...(input.temperature === undefined ? {} : { temperature: input.temperature }),
        ...(input.max_tokens === undefined ? {} : { max_tokens: input.max_tokens }),
      }),
      signal: controller.signal,
    });

    const raw = await response.text();
    let payload: any;
    try {
      payload = raw ? JSON.parse(raw) : null;
    } catch {
      throw new Error(`FreeLLMAPI inference returned non-JSON data (HTTP ${response.status})`);
    }

    if (!response.ok) {
      const upstreamMessage = payload?.error?.message ?? payload?.message ?? `HTTP ${response.status}`;
      throw new Error(`FreeLLMAPI inference failed (${response.status}): ${sanitizeProviderErrorMessage(upstreamMessage)}`);
    }

    const answer = assistantText(payload);
    if (!answer) {
      throw new Error(`FreeLLMAPI inference returned no assistant text (finish_reason: ${payload?.choices?.[0]?.finish_reason ?? 'unknown'})`);
    }

    return {
      answer,
      requested_model: model,
      model: typeof payload?.model === 'string' ? payload.model : null,
      finish_reason: typeof payload?.choices?.[0]?.finish_reason === 'string'
        ? payload.choices[0].finish_reason
        : null,
      usage: payload?.usage && typeof payload.usage === 'object' ? payload.usage : null,
      routed_via: response.headers.get('x-routed-via'),
      fallback_trail: response.headers.get('x-fallback-trail'),
      cache: response.headers.get('x-freellm-cache'),
      compression: response.headers.get('x-freellm-compress'),
      execution_id: typeof payload?.execution_id === 'string'
        ? payload.execution_id
        : response.headers.get('x-request-id'),
    };
  } catch (error: any) {
    if (error?.name === 'AbortError') {
      throw new Error(`FreeLLMAPI inference timed out or was cancelled after ${timeoutMs}ms`);
    }
    throw error;
  } finally {
    clearTimeout(timeout);
    req.off('aborted', abortOnDisconnect);
    res.off('close', abortOnDisconnect);
  }
}

function healthcheck(): unknown {
  const { models } = buildModelListing();
  const availableModels = models.filter(model => model.available === 1).length;
  const providers = providerHealth() as Record<string, {
    keys: Record<string, number>;
    active_cooldowns: number;
    available_models: number;
  }>;
  const providerRows = Object.values(providers);
  const healthyProviders = providerRows.filter(provider =>
    (provider.keys.healthy ?? 0) > 0 && provider.available_models > 0,
  ).length;
  return {
    status: availableModels > 0 ? 'ready' : 'needs_configuration',
    mcp_enabled: isMcpServerEnabled(),
    default_model: mcpDefaultModel(),
    available_models: availableModels,
    configured_providers: providerRows.length,
    healthy_providers: healthyProviders,
    checked_at: new Date().toISOString(),
  };
}

async function webSearch(args: Record<string, unknown>): Promise<unknown> {
  const query = typeof args.query === 'string' ? args.query.trim() : '';
  if (!query) throw new Error('query is required');
  const maxResults = typeof args.max_results === 'number' && Number.isFinite(args.max_results)
    ? Math.min(Math.max(Math.floor(args.max_results), 1), 20)
    : 5;
  const topic = args.topic === 'news' ? 'news' : 'general';
  const result = await runSearch(query, { maxResults, topic });
  return {
    query: result.query,
    provider: result.provider,
    ...((result as { engine?: unknown }).engine ? { engine: (result as { engine?: unknown }).engine } : {}),
    ...(result.answer ? { answer: result.answer } : {}),
    results: result.results.map(r => ({ title: r.title, url: r.url, content: r.content })),
  };
}

// ── Tool registry ────────────────────────────────────────────────────────

interface McpTool {
  title: string;
  description: string;
  inputSchema: Record<string, unknown>;
  outputSchema?: Record<string, unknown>;
  annotations: {
    readOnlyHint: boolean;
    destructiveHint: boolean;
    openWorldHint: boolean;
  };
  run: (args: Record<string, unknown>, req: Request, res: Response) => unknown | Promise<unknown>;
}

const READ_ONLY_LOCAL = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };

const TOOLS: Record<string, McpTool> = {
  ask_freellmapi: {
    title: 'Ask FreeLLMAPI',
    description: 'Use this when the user explicitly wants a FreeLLMAPI model to answer, analyze, rewrite, summarize, or generate text. Routes through the configured free-provider pool. Defaults to the server\'s MCP_INFERENCE_DEFAULT_MODEL (auto when unset). Returns the answer plus model, routing, cache, execution, and token-usage metadata.',
    inputSchema: {
      type: 'object',
      additionalProperties: false,
      properties: {
        prompt: { type: 'string', minLength: 1, maxLength: 400_000, description: 'The complete task or question for the selected FreeLLMAPI model.' },
        system: { type: 'string', minLength: 1, maxLength: 50_000, description: 'Optional system instructions for the FreeLLMAPI model.' },
        model: { type: 'string', minLength: 1, maxLength: 256, description: 'Model id, named chain, or auto. Omit to use MCP_INFERENCE_DEFAULT_MODEL.' },
        temperature: { type: 'number', minimum: 0, maximum: 2 },
        max_tokens: { type: 'integer', minimum: 1, maximum: 32_768 },
        timeout_ms: { type: 'integer', minimum: 1_000, maximum: MAX_MCP_INFERENCE_TIMEOUT_MS, description: 'Optional request timeout. Defaults to MCP_INFERENCE_TIMEOUT_MS or 120000.' },
      },
      required: ['prompt'],
    },
    outputSchema: {
      type: 'object',
      additionalProperties: false,
      properties: {
        answer: { type: 'string' },
        requested_model: { type: 'string' },
        model: { type: ['string', 'null'] },
        finish_reason: { type: ['string', 'null'] },
        usage: { type: ['object', 'null'], additionalProperties: true },
        routed_via: { type: ['string', 'null'] },
        fallback_trail: { type: ['string', 'null'] },
        cache: { type: ['string', 'null'] },
        compression: { type: ['string', 'null'] },
        execution_id: { type: ['string', 'null'] },
      },
      required: ['answer', 'requested_model', 'model', 'finish_reason', 'usage', 'routed_via', 'fallback_trail', 'cache', 'compression', 'execution_id'],
    },
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
    run: (args, req, res) => askFreeLlmApi(args, req, res),
  },
  healthcheck: {
    title: 'Check FreeLLMAPI readiness',
    description: 'Check whether FreeLLMAPI is ready for ChatGPT calls, including MCP state, configured/healthy providers, available models, and the default MCP inference model. This does not spend provider quota.',
    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
    annotations: READ_ONLY_LOCAL,
    run: () => healthcheck(),
  },
  list_models: {
    title: 'List FreeLLMAPI models',
    description: 'List the models this FreeLLMAPI router can serve, with context windows, tool support, and the parameters each model honors (supported_parameters). Defaults to only models that are usable right now.',
    inputSchema: {
      type: 'object',
      properties: {
        available_only: { type: 'boolean', description: 'false to include models that are configured but not currently usable (no key, disabled)', default: true },
      },
    },
    annotations: READ_ONLY_LOCAL,
    run: listModels,
  },
  provider_health: {
    title: 'Inspect provider health',
    description: 'Per-provider key statuses (healthy/rate_limited/invalid/error/unknown), active cooldowns, and how many models each provider can serve right now.',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => providerHealth(),
  },
  usage_summary: {
    title: 'Summarize FreeLLMAPI usage',
    description: 'Request/token totals, success rate, and the top models by traffic for a recent window.',
    inputSchema: {
      type: 'object',
      properties: {
        range: { type: 'string', enum: ['24h', '7d', '30d'], default: '24h' },
      },
    },
    annotations: READ_ONLY_LOCAL,
    run: usageSummary,
  },
  routing_info: {
    title: 'Inspect model routing',
    description: 'The active routing strategy and the current top-scored models in the fallback chain.',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => routingInfo(),
  },
  set_routing_strategy: {
    title: 'Set model routing strategy',
    description: 'Switch the routing strategy (priority = manual chain order; balanced / smartest / fastest / reliable are scored presets; custom uses the saved weight vector).',
    inputSchema: {
      type: 'object',
      properties: {
        strategy: { type: 'string', enum: [...ROUTING_STRATEGIES] },
      },
      required: ['strategy'],
    },
    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
    run: setStrategy,
  },
  cache_stats: {
    title: 'Inspect response-cache savings',
    description: 'Response-cache statistics: entries, total hits, and the prompt/completion tokens the cache has saved.',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => getCacheStats(),
  },
  web_search: {
    title: 'Search the web',
    description: 'Search the web through the search providers configured in FreeLLMAPI (Parallel, Tavily, Exa, Firecrawl, Linkup, Keenable, or a custom search endpoint). Returns titles, URLs and short extracts. Spends the search provider\'s free quota, not model tokens.',
    inputSchema: {
      type: 'object',
      additionalProperties: false,
      properties: {
        query: { type: 'string', minLength: 1, maxLength: 400, description: 'The search query.' },
        max_results: { type: 'integer', minimum: 1, maximum: 20, default: 5 },
        topic: { type: 'string', enum: ['general', 'news'], default: 'general' },
      },
      required: ['query'],
    },
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
    run: webSearch,
  },
  compression_stats: {
    title: 'Inspect prompt-compression savings',
    description: 'Prompt-compression statistics: requests compressed, estimated tokens saved, fidelity-gate discards, and per-engine savings.',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => getCompressionStats(),
  },
  provider_list: {
    title: 'List providers and key status',
    description: 'All platforms with enabled API keys, showing total keys and per-status breakdown (healthy/rate_limited/invalid/error).',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => providerList(),
  },
  clear_cache: {
    title: 'Clear response cache',
    description: 'Flush all cached responses. Returns the number of entries removed.',
    inputSchema: { type: 'object', properties: {} },
    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
    run: () => clearCacheTool(),
  },
  quota_outlook: {
    title: 'Forecast free-tier quota',
    description: 'Per-pool free-tier quota: remaining requests, observed burn rate, estimated exhaustion time, and warnings (exhausting_soon/low_balance). Use before long or token-heavy tasks to see which providers may run dry.',
    inputSchema: { type: 'object', properties: {} },
    annotations: READ_ONLY_LOCAL,
    run: () => quotaOutlook(),
  },
};

// ── JSON-RPC dispatch ────────────────────────────────────────────────────

// Returns the JSON-RPC response for a request, or undefined for a
// notification. JSON-RPC 2.0 defines a notification as a message WITHOUT an
// `id` member (id:null is a — discouraged — request and gets a response);
// detecting notifications by the `notifications/` method prefix answered
// no-id requests and 202'd id-carrying notifications.
async function handleRpc(msg: JsonRpcRequest, req: Request, res: Response): Promise<unknown | undefined> {
  const isNotification = msg.id === undefined;
  const respond = (response: unknown) => (isNotification ? undefined : response);
  const id = msg.id ?? null;
  return respond(await dispatchRpc(msg, id, req, res));
}

async function dispatchRpc(msg: JsonRpcRequest, id: number | string | null, req: Request, res: Response): Promise<unknown> {
  switch (msg.method) {
    case 'initialize': {
      return rpcResult(id, {
        protocolVersion: PROTOCOL_VERSION,
        capabilities: { tools: {} },
        serverInfo: { name: 'freellmapi', version: '1.0.0' },
        instructions: 'Use ask_freellmapi when the user explicitly asks FreeLLMAPI or one of its models to perform a text task. Use healthcheck before troubleshooting availability; list_models for model choice; provider_health, provider_list, usage_summary, cache_stats, compression_stats, quota_outlook, and routing_info for diagnostics. set_routing_strategy changes server state. web_search searches the web through the configured search providers. clear_cache flushes cached responses.',
      });
    }
    case 'ping':
      return rpcResult(id, {});
    case 'tools/list':
      return rpcResult(id, {
        tools: Object.entries(TOOLS).map(([name, t]) => ({
          name,
          title: t.title,
          description: t.description,
          inputSchema: t.inputSchema,
          ...(t.outputSchema ? { outputSchema: t.outputSchema } : {}),
          annotations: t.annotations,
        })),
      });
    case 'tools/call': {
      const name = msg.params?.name as string;
      // Object.hasOwn: a bare index lookup resolves prototype members, so
      // name:"constructor"/"toString" passed the !tool check and died inside
      // the try as a confusing tool-level error instead of -32602.
      const tool = typeof name === 'string' && Object.hasOwn(TOOLS, name) ? TOOLS[name] : undefined;
      if (!tool) return rpcError(id, -32602, `Unknown tool: ${name}`);
      try {
        const args = (msg.params?.arguments as Record<string, unknown>) ?? {};
        return rpcResult(id, toolJson(await tool.run(args, req, res)));
      } catch (err: any) {
        // Tool-level failures are results with isError, not protocol errors.
        return rpcResult(id, toolError(err?.message ?? 'tool failed'));
      }
    }
    default:
      // Known client notifications (notifications/initialized etc.) land here;
      // handleRpc drops the response for anything sent without an id, so they
      // are acked silently without special-casing the method name.
      return rpcError(id, -32601, `Method not found: ${msg.method}`);
  }
}

function authenticate(req: Request, res: Response): boolean {
  const token = extractApiToken(req);
  const unifiedKey = getUnifiedApiKey();
  if (!token || !timingSafeStringEqual(token, unifiedKey)) {
    // Echo the request id when the body carries one, so strict JSON-RPC
    // clients can correlate the auth error with their pending call.
    const body = req.body;
    const id = body && typeof body === 'object' && !Array.isArray(body) && body.id !== undefined ? body.id : null;
    res.status(401).json(rpcError(id, -32001, 'Invalid API key. Authenticate with the unified key as a Bearer token.'));
    return false;
  }
  return true;
}

// ── Lifecycle configuration (#925, MVP-1) ───────────────────────────────────
// The MCP surface exposes provider health, usage stats and routing controls to
// anything holding the unified key, so it is a configured surface rather than
// an always-on one: /api/settings/enable-mcp (and the toggle on the Keys page)
// turns it on and off. The stored default is decided once, by migration:
// installs that already had provider keys when they upgraded keep it on, fresh
// installs start with it off.
export const MCP_ENABLED_SETTING = 'enable_mcp';

export function isMcpServerEnabled(): boolean {
  return getSetting(MCP_ENABLED_SETTING) === '1';
}

// Gate every verb, not just POST: a disabled server must not answer "405, POST
// instead" on GET/DELETE either. Runs before auth so a disabled server says so
// plainly, without hinting whether the presented key would have been valid, and
// reads the setting per request so the toggle applies without a restart.
mcpRouter.use((req: Request, res: Response, next: NextFunction) => {
  if (isMcpServerEnabled()) {
    next();
    return;
  }
  const body = req.body;
  const id = body && typeof body === 'object' && !Array.isArray(body) && body.id !== undefined ? body.id : null;
  res.status(403).json(rpcError(id, -32000, 'MCP server is disabled. Turn it on from the dashboard (Keys -> Agent compatibility) or with PUT /api/settings/enable-mcp {"enabled":true}.'));
});

mcpRouter.post('/', async (req: Request, res: Response) => {
  if (!authenticate(req, res)) return;

  const body = req.body;
  // The 2025-06-18 revision removed JSON-RPC batching; a single message per
  // POST is the interoperable shape.
  if (Array.isArray(body)) {
    res.status(400).json(rpcError(null, -32600, 'Batch requests are not supported'));
    return;
  }
  if (!body || typeof body !== 'object' || typeof body.method !== 'string') {
    res.status(400).json(rpcError(null, -32600, 'Expected a JSON-RPC request object'));
    return;
  }

  const response = await handleRpc(body as JsonRpcRequest, req, res);
  if (response === undefined) {
    res.status(202).end(); // notification — accepted, nothing to say
    return;
  }
  res.json(response);
});

// Stateless server: no server-initiated stream, no sessions to delete.
mcpRouter.get('/', (_req: Request, res: Response) => {
  res.status(405).json(rpcError(null, -32000, 'This MCP server is stateless: POST JSON-RPC messages to /mcp.'));
});
mcpRouter.delete('/', (_req: Request, res: Response) => {
  res.status(405).json(rpcError(null, -32000, 'This MCP server is stateless: there is no session to delete.'));
});