search-rotation 0.4.9

package/dist/engines/hosted-mcp.js

@@ -0,0 +1,24 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { VERSION } from "../version.js";
+export async function withHostedMcp(endpoint, ctx, timeoutMs, fn) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+    signal.throwIfAborted();
+    const client = new Client({ name: "search-rotation", version: VERSION });
+    const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
+        // Der SDK-Request-Abbruch allein beendet keinen hängenden HTTP-Handshake.
+        fetch: (input, init) => {
+            const inputSignal = input instanceof Request ? input.signal : undefined;
+            const signals = [signal, init?.signal, inputSignal].filter((s) => Boolean(s));
+            return fetch(input, { ...init, signal: AbortSignal.any(signals) });
+        },
+    });
+    try {
+        await client.connect(transport, { signal, timeout: timeoutMs });
+        return await fn(client, signal);
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}

package/dist/engines/index.js

@@ -0,0 +1,13 @@
+import { TAVILY } from "./tavily.js";
+import { FIRECRAWL } from "./firecrawl.js";
+import { PARALLEL } from "./parallel.js";
+import { EXA } from "./exa.js";
+import { GOOGLE_CSE } from "./googlecse.js";
+import { JINA } from "./jina.js";
+import { DUCKDUCKGO } from "./duckduckgo.js";
+export const ADAPTERS = [TAVILY, FIRECRAWL, PARALLEL, EXA, GOOGLE_CSE, JINA, DUCKDUCKGO];
+/** Alle Engine-Ids — auch fetch-only (Jina), die tauchen nicht in SEARCH_ORDER auf. */
+export const KNOWN_IDS = ADAPTERS.map((a) => a.meta.id);
+export const SEARCH_ORDER = ["tavily", "firecrawl", "parallel", "exa", "google-cse", "duckduckgo"];
+export const FETCH_ORDER = ["jina", "firecrawl", "parallel", "tavily", "exa"];
+export const DEFAULT_ENABLED = Object.fromEntries(ADAPTERS.map(a => [a.meta.id, a.meta.defaultEnabled ?? a.meta.keyless === "ip"]));

package/dist/engines/jina.js

@@ -0,0 +1,28 @@
+import { httpText } from "./base.js";
+async function fetchUrl(input, ctx) {
+    const headers = { accept: "text/markdown" };
+    if (ctx.apiKey)
+        headers.authorization = `Bearer ${ctx.apiKey}`;
+    const text = await httpText(`https://r.jina.ai/${input.url}`, { headers }, {
+        signal: ctx.signal,
+        timeoutMs: 45_000,
+    });
+    if (!text.trim())
+        throw new Error("jina: leere Antwort");
+    return text;
+}
+export const JINA = {
+    meta: {
+        id: "jina",
+        label: "Jina Reader",
+        homepage: "https://jina.ai/reader",
+        signupUrl: "https://jina.ai/reader",
+        keyless: "ip",
+        capabilities: ["fetch"],
+        monthlyFree: 0,
+        quota: { period: "ip", unit: "requests", estimated: true },
+        quotaEndpoint: false,
+        notes: "Ohne Key IP-basiert (~20 Requests/Minute), mit Key höhere Limits. Nur fürs Abrufen von Seiten.",
+    },
+    fetchUrl,
+};

package/dist/engines/parallel.js

@@ -0,0 +1,74 @@
+import { optionalCap as cap, httpJson, NeedsKeyError } from "./base.js";
+import { withHostedMcp } from "./hosted-mcp.js";
+const SIGNUP = "https://platform.parallel.ai";
+const BASE = "https://api.parallel.ai/v1";
+async function search(input, ctx) {
+    const j = !ctx.apiKey ? await withHostedMcp("https://search.parallel.ai/mcp", ctx, 30_000, async (client, signal) => {
+        const result = await client.callTool({ name: "web_search", arguments: { objective: input.query, search_queries: [input.query] } }, undefined, { timeout: 30_000, signal });
+        if (result.isError)
+            throw new Error("parallel-mcp: " + result.content.filter(c => c.type === "text").map(c => c.text).join("\n").slice(0, 300));
+        const data = result.structuredContent;
+        if (!Array.isArray(data?.results))
+            throw new Error("parallel-mcp: invalid search response");
+        return data;
+    }) : await httpJson(`${BASE}/search`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": ctx.apiKey },
+        body: JSON.stringify({
+            objective: input.query,
+            search_queries: [input.query],
+            mode: "fast",
+            max_results: cap(input.numResults),
+            max_chars_per_result: 400,
+        }),
+    }, { signal: ctx.signal });
+    const items = (Array.isArray(j?.results) ? j.results : []).slice(0, cap(input.numResults)).map((r) => ({
+        title: r?.title || r?.url || "(ohne Titel)",
+        url: String(r?.url ?? ""),
+        snippet: Array.isArray(r?.excerpts) ? r.excerpts.join(" … ").slice(0, 600) : undefined,
+        published: typeof r?.publish_date === "string" ? r.publish_date : undefined,
+    }));
+    return { items };
+}
+async function fetchUrl(input, ctx) {
+    if (!ctx.apiKey)
+        throw new NeedsKeyError("parallel", SIGNUP);
+    const j = await httpJson(`${BASE}/extract`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": ctx.apiKey },
+        body: JSON.stringify({ urls: [input.url], advanced_settings: { full_content: true } }),
+    }, { signal: ctx.signal, timeoutMs: 45_000 });
+    const r0 = j?.results?.[0];
+    const md = typeof r0?.full_content === "string" && r0.full_content
+        ? r0.full_content
+        : Array.isArray(r0?.excerpts)
+            ? r0.excerpts.join("\n\n")
+            : "";
+    if (!md.trim()) {
+        // Parallel liefert Fehler pro URL im errors[]-Array — mit ausgeben.
+        const errs = Array.isArray(j?.errors) ? j.errors : [];
+        const detail = errs
+            .map((e) => `${e?.error_type ?? "error"}: ${e?.content ?? ""}`.trim())
+            .filter(Boolean)
+            .join("; ");
+        throw new Error("parallel: kein Inhalt extrahiert" + (detail ? ` (${detail.slice(0, 200)})` : ""));
+    }
+    return md;
+}
+export const PARALLEL = {
+    meta: {
+        id: "parallel",
+        label: "Parallel",
+        homepage: "https://parallel.ai",
+        signupUrl: SIGNUP,
+        keyless: "ip",
+        keylessCapabilities: ["search"],
+        capabilities: ["search", "fetch"],
+        monthlyFree: 5000,
+        quota: { period: "month", unit: "requests", limit: 5000, estimated: true },
+        quotaEndpoint: false,
+        notes: "Suche ohne Key über gehosteten Parallel-MCP. Fetch nutzt die direkte API mit Key. Ohne Key werden nur lokale Aufrufe gezählt; Anbieterlimit und Gesamtverbrauch unbekannt.",
+    },
+    search,
+    fetchUrl,
+};

package/dist/engines/tavily.js

@@ -0,0 +1,74 @@
+import { bearer, optionalCap as cap, httpJson, NeedsKeyError } from "./base.js";
+const SIGNUP = "https://app.tavily.com";
+const BASE = "https://api.tavily.com";
+async function search(input, ctx) {
+    const j = await httpJson(`${BASE}/search`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "X-Client-Name": "search-rotation",
+            ...(ctx.apiKey ? bearer(ctx.apiKey) : { "X-Tavily-Access-Mode": "keyless" }) },
+        body: JSON.stringify({
+            query: input.query,
+            start_date: input.startDate,
+            end_date: input.endDate,
+            max_results: cap(input.numResults),
+            ...(ctx.apiKey ? { include_answer: true } : { chunks_per_source: 3 }),
+            search_depth: "basic",
+        }),
+    }, { signal: ctx.signal });
+    const items = (Array.isArray(j?.results) ? j.results : []).map((r) => ({
+        title: r?.title || r?.url || "(ohne Titel)",
+        url: String(r?.url ?? ""),
+        snippet: typeof r?.content === "string" ? r.content.slice(0, 500) : undefined,
+        published: typeof r?.published_date === "string" ? r.published_date : undefined,
+    }));
+    return { items, answer: typeof j?.answer === "string" && j.answer ? j.answer : undefined };
+}
+async function fetchUrl(input, ctx) {
+    if (!ctx.apiKey)
+        throw new NeedsKeyError("tavily", SIGNUP);
+    const j = await httpJson(`${BASE}/extract`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...bearer(ctx.apiKey) },
+        body: JSON.stringify({ urls: [input.url] }),
+    }, { signal: ctx.signal });
+    const content = j?.results?.[0]?.raw_content;
+    if (typeof content !== "string" || !content.trim())
+        throw new Error("tavily: kein Inhalt extrahiert");
+    return content;
+}
+async function remoteQuota(ctx) {
+    if (!ctx.apiKey)
+        throw new NeedsKeyError("tavily", SIGNUP);
+    const j = await httpJson(`${BASE}/usage`, { headers: bearer(ctx.apiKey) }, { signal: ctx.signal });
+    // Response: { key: { usage, limit, search_usage, ... }, account: { current_plan, plan_usage, plan_limit, ... } }
+    const ku = Array.isArray(j?.key_usage) ? j.key_usage[0] : j?.key_usage;
+    const used = pickNumber(j?.key?.usage, ku?.usage, j?.usage);
+    const limit = pickNumber(j?.key?.limit, ku?.limit, j?.limit);
+    return { used, limit, remaining: used !== undefined && limit !== undefined ? limit - used : undefined };
+}
+function pickNumber(...vals) {
+    for (const v of vals) {
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+export const TAVILY = {
+    meta: {
+        id: "tavily",
+        label: "Tavily",
+        homepage: "https://www.tavily.com",
+        signupUrl: SIGNUP,
+        keyless: "ip",
+        keylessCapabilities: ["search"],
+        capabilities: ["search", "fetch"],
+        monthlyFree: 1000,
+        quota: { period: "month", unit: "credits", limit: 1000, estimated: true, costs: { search: 1, fetch: 0.2 } },
+        quotaEndpoint: true,
+        notes: "Suche ohne Key im Keyless-Modus; Limit und Gesamtverbrauch unbekannt. Fetch benötigt einen Key. Mit Key ist die Quota per API abrufbar.",
+    },
+    supportsSearchTime: () => true,
+    search,
+    fetchUrl,
+    remoteQuota,
+};

package/dist/history.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import { atomicWriteFile, withFileLock } from "./persistence.js";
+const MAX_ITEMS = 20;
+const MAX_MARKDOWN = 3000;
+/**
+ * Verlauf der Such-/Fetch-Aufrufe als Ring-Puffer in einer JSON-Datei.
+ * Serialisiert Lesen, Schreiben und Löschen über eine Prozesssperre.
+ */
+export class HistoryStore {
+    file;
+    maxEntries;
+    constructor(file, maxEntries = 500) {
+        this.file = file;
+        this.maxEntries = maxEntries;
+    }
+    read() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.file, "utf8"));
+            if (Array.isArray(raw))
+                return raw;
+        }
+        catch (error) {
+            // Keep missing/corrupt-file recovery; an I/O failure must not cause a
+            // successful later write to replace an unread existing snapshot.
+            if (!(error instanceof SyntaxError) && error.code !== "ENOENT")
+                throw error;
+        }
+        return [];
+    }
+    write(entries) {
+        atomicWriteFile(this.file, JSON.stringify(entries));
+    }
+    record(entry) {
+        const capped = { ...entry };
+        if (capped.result?.items && capped.result.items.length > MAX_ITEMS) {
+            capped.result = { ...capped.result, items: capped.result.items.slice(0, MAX_ITEMS) };
+        }
+        if (capped.result?.markdown && capped.result.markdown.length > MAX_MARKDOWN) {
+            capped.result = { ...capped.result, markdown: capped.result.markdown.slice(0, MAX_MARKDOWN) };
+        }
+        try {
+            withFileLock(this.file, () => {
+                const entries = this.read().filter((e) => e && typeof e.ts === "string");
+                entries.unshift({ ...capped, ts: new Date().toISOString() });
+                this.write(entries.slice(0, this.maxEntries));
+            });
+        }
+        catch {
+            // Optional history must never turn a successful provider request into failover.
+            process.stderr.write("search-rotation: history persistence failed\n");
+        }
+    }
+    list(limit = 50) {
+        return this.read().slice(0, Math.min(Math.max(limit, 1), 200));
+    }
+    clear() {
+        withFileLock(this.file, () => fs.rmSync(this.file, { force: true }));
+    }
+}

package/dist/index.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createServer } from "node:net";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConfigStore, configDir } from "./config.js";
+import { ADAPTERS, SEARCH_ORDER, FETCH_ORDER, DEFAULT_ENABLED, KNOWN_IDS } from "./engines/index.js";
+import { UsageStore } from "./usage.js";
+import { HistoryStore } from "./history.js";
+import { SearchRouter, RouterError } from "./router.js";
+import { buildStatus, clearRemoteQuotaCache } from "./status.js";
+import { buildMcpServer } from "./mcp/server.js";
+import { mountMcpHttp } from "./mcp/http.js";
+import { buildWebApp } from "./web/app.js";
+import { VERSION } from "./version.js";
+import { mountSecurity } from "./web/security.js";
+function findFreePort(start, host, tries = 20) {
+    return new Promise((resolve, reject) => {
+        const attempt = (port) => {
+            if (port > start + tries) {
+                reject(new Error(`Kein freier Port ab ${start} gefunden`));
+                return;
+            }
+            const srv = createServer();
+            srv.unref();
+            srv.on("error", () => attempt(port + 1));
+            srv.listen(port, host, () => {
+                srv.close(() => resolve(port));
+            });
+        };
+        attempt(start);
+    });
+}
+function openBrowser(url) {
+    try {
+        const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+        const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        // spawn failures arrive asynchronously; never log the one-time login URL.
+        child.on("error", () => console.error("[search-rotation] Browser konnte nicht geöffnet werden; Dashboard-URL manuell öffnen."));
+        child.unref();
+    }
+    catch {
+        console.error("[search-rotation] Browser konnte nicht geöffnet werden; Dashboard-URL manuell öffnen.");
+    }
+}
+async function main() {
+    const args = parseArgs({
+        options: {
+            http: { type: "boolean", default: false },
+            port: { type: "string" },
+            host: { type: "string" },
+            "public-origin": { type: "string" },
+            token: { type: "string" },
+            open: { type: "boolean", default: false },
+            "no-dashboard": { type: "boolean", default: false },
+        },
+    }).values;
+    const store = new ConfigStore();
+    const defaults = {
+        knownIds: KNOWN_IDS,
+        searchOrder: SEARCH_ORDER,
+        fetchOrder: FETCH_ORDER,
+        defaultEnabled: DEFAULT_ENABLED,
+        requiredKeyIds: ADAPTERS.filter(a => a.meta.keyless === "no").map(a => a.meta.id),
+    };
+    let cfg = store.load(defaults);
+    const getConfig = () => (cfg = store.load(defaults));
+    const usage = new UsageStore(configDir());
+    const history = new HistoryStore(path.join(configDir(), "history.json"));
+    const router = new SearchRouter({ getConfig, usage, adapters: ADAPTERS, history });
+    const month = () => usage.monthKey();
+    const status = () => buildStatus(getConfig(), usage, ADAPTERS);
+    const testEngine = async (id, kind, arg, signal) => {
+        const adapter = ADAPTERS.find(a => a.meta.id === id);
+        if (!adapter)
+            return { ok: false, ms: 0, error: "unbekannte Engine" };
+        if (kind === "search" && !adapter.search)
+            return { ok: false, ms: 0, error: "Engine kann nicht suchen" };
+        if (kind === "fetch" && !adapter.fetchUrl)
+            return { ok: false, ms: 0, error: "Engine kann nicht fetchen" };
+        const start = Date.now();
+        try {
+            if (kind === "search") {
+                const out = await router.search({ query: arg || "model context protocol", numResults: 3 }, { onlyEngine: id, signal });
+                return { ok: true, ms: Date.now() - start, count: out.items.length,
+                    preview: out.items.slice(0, 3).map(item => `${item.title} — ${item.url}`).join("\n") };
+            }
+            const out = await router.fetchUrl({ url: arg || "https://example.com" }, { onlyEngine: id, signal });
+            return { ok: true, ms: Date.now() - start, chars: out.markdown.length, preview: out.markdown.slice(0, 400) };
+        }
+        catch (err) {
+            const detail = err instanceof RouterError ? err.attempts.map(a => a.error).filter(Boolean).join("; ") : "";
+            const message = err instanceof Error ? err.message : String(err);
+            return { ok: false, ms: Date.now() - start, error: detail || message };
+        }
+    };
+    const token = args.token ?? process.env.SEARCH_ROTATION_TOKEN ?? cfg.settings.token;
+    const host = args.host ?? "127.0.0.1";
+    const dashboardEnabled = !args["no-dashboard"];
+    const loopback = ["127.0.0.1", "localhost", "::1"].includes(host);
+    if (!loopback && !token)
+        throw new Error("Remote-Bind benötigt --token oder SEARCH_ROTATION_TOKEN");
+    // HTTP-Server nötig für das Dashboard UND für --http — sonst hat der Prozess
+    // kein Keep-Alive-Handle und beendet sich sofort (--http --no-dashboard-Fix).
+    const httpNeeded = dashboardEnabled || args.http;
+    const wantedPort = args.port !== undefined ? Number(args.port) : cfg.settings.port;
+    const basePort = Number.isInteger(wantedPort) && wantedPort >= 1024 && wantedPort <= 65535
+        ? wantedPort
+        : cfg.settings.port;
+    const port = httpNeeded ? await findFreePort(basePort, host) : 0;
+    const browserHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+    const localOrigin = `http://${browserHost.includes(":") ? `[${browserHost}]` : browserHost}:${port}`;
+    const publicOrigin = args["public-origin"] ? new URL(args["public-origin"]) : new URL(localOrigin);
+    if (!["http:", "https:"].includes(publicOrigin.protocol) || publicOrigin.username || publicOrigin.password || publicOrigin.search || publicOrigin.hash || publicOrigin.pathname !== "/") {
+        throw new Error("--public-origin muss eine HTTP(S)-Origin ohne Pfad, Zugangsdaten oder Query sein");
+    }
+    const origin = publicOrigin.origin;
+    const dashboardUrl = () => dashboardEnabled ? `${origin}/` : null;
+    const app = new Hono();
+    const security = mountSecurity(app, { token, origin, additionalOrigins: [localOrigin], dashboardEnabled });
+    const mcpDeps = {
+        router, status, month, dashboardUrl,
+        openDashboard: () => {
+            if (dashboardEnabled)
+                openBrowser(security.browserUrl());
+        },
+    };
+    app.route("/", buildWebApp({
+        configPath: store.file,
+        getConfig,
+        saveConfig: (next) => {
+            store.save(next);
+            cfg = next;
+            // Neuer Key? Dann Remote-Quota sofort frisch ziehen statt 5 Min Cache.
+            clearRemoteQuotaCache();
+        },
+        adapters: ADAPTERS,
+        status,
+        month,
+        testEngine,
+        historyList: (limit) => history.list(limit),
+        historyClear: () => history.clear(),
+    }));
+    mountMcpHttp(app, mcpDeps, security);
+    if (httpNeeded) {
+        const srv = serve({ fetch: app.fetch, port, hostname: host });
+        // TOCTOU-Restrisiko: wird der Port zwischen findFreePort und Binden doch
+        // belegt, laut statt still mit Stacktrace sterben.
+        srv.on("error", (err) => {
+            console.error(`[search-rotation] fatal: HTTP-Server auf ${host}:${port} fehlgeschlagen (${err.code ?? err.message})`);
+            process.exit(1);
+        });
+        if (dashboardEnabled)
+            console.error(`[search-rotation] Dashboard: ${dashboardUrl()}`);
+    }
+    if (args.http) {
+        console.error(`[search-rotation] v${VERSION} — MCP (Streamable HTTP): http://${host}:${port}/mcp` +
+            (token ? " (Bearer-Token nötig)" : ""));
+    }
+    else {
+        // Exit, sobald der MCP-Client stdin schließt — vor connect registrieren,
+        // damit kein Fenster bleibt, in dem der Prozess hängen bleibt.
+        const exit = () => process.exit(0);
+        process.stdin.on("end", exit);
+        process.stdin.on("close", exit);
+        process.stdin.on("error", exit);
+        const mcp = buildMcpServer(mcpDeps);
+        await mcp.connect(new StdioServerTransport());
+        console.error(`[search-rotation] v${VERSION} — MCP stdio aktiv.` +
+            (dashboardEnabled ? ` Dashboard: ${dashboardUrl()}` : ""));
+    }
+    if (args.open && dashboardEnabled)
+        mcpDeps.openDashboard();
+}
+main().catch((err) => {
+    console.error(`[search-rotation] fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    process.exit(1);
+});

package/dist/mcp/engine-status.js

@@ -0,0 +1,58 @@
+/** Model-facing facts. Configuration and stored diagnostics are not live health checks. */
+export function engineStatus(rows, month, version) {
+    return {
+        version,
+        localUsageMonth: month,
+        interpretation: [
+            "enabled is a configuration toggle, not a health check. Disabled does not mean an API key is missing; the original reason for disabling is not recorded.",
+            "Access is capability-specific. keyless search does not imply keyless fetch. Recommend a key only for a capability marked api_key_required, or when the user explicitly wants authenticated access.",
+            "Historical errors are stored observations, not evidence of a current failure or the current authentication requirements. No live search or fetch is performed by this tool.",
+            "includedInRotation describes configuration eligibility only. Runtime cooldowns, quota checks and failover may skip an engine.",
+            "Local usage counts successful calls from this installation, separately from errors. Unknown provider limits and total usage are null, not zero or unlimited. Provider account balances must not be described as monthly consumption.",
+        ],
+        engines: rows.map(row => {
+            const supported = row.supportedCapabilities ?? row.capabilities ?? [];
+            const keyless = row.keylessCapabilities ?? (row.keyless === "ip" ? row.capabilities ?? [] : []);
+            const missingExtraConfiguration = (row.extraFields ?? []).filter(field => !row.extrasSet?.[field.key]).map(field => field.key);
+            const access = Object.fromEntries(["search", "fetch"].map(capability => {
+                const mode = !supported.includes(capability) ? "unsupported"
+                    : !row.hasKey && !keyless.includes(capability) ? "api_key_required"
+                        : missingExtraConfiguration.length ? "extra_configuration_required"
+                            : row.hasKey ? "configured_key" : "keyless";
+                const position = capability === "search" ? row.searchPosition : row.fetchPosition;
+                return [capability, { mode, includedInRotation: row.enabled && (mode === "keyless" || mode === "configured_key") && position >= 0,
+                        configuredOrder: position >= 0 ? position + 1 : null }];
+            }));
+            const q = row.quota;
+            const anonymous = !row.hasKey;
+            const remote = !anonymous && q?.source === "remote";
+            return {
+                id: row.id,
+                name: row.label,
+                enabled: row.enabled,
+                disabledReason: row.enabled ? null : "disabled_in_configuration; original reason not recorded",
+                apiKeyConfigured: row.hasKey,
+                missingExtraConfiguration,
+                access,
+                localUsage: { successfulSearches: row.used.search, successfulFetches: row.used.fetch, failedAttempts: row.used.errors ?? 0 },
+                quota: {
+                    scope: anonymous ? "provider_limit_unknown" : remote ? "provider_account_balance" : "local_allowance",
+                    period: anonymous || remote ? null : q?.period ?? null,
+                    unit: anonymous ? "requests" : q?.unit ?? "requests",
+                    limit: anonymous ? null : q?.limit ?? null,
+                    used: anonymous ? null : q?.used ?? null,
+                    providerTotalUsed: remote ? q.used : null,
+                    source: anonymous ? "unknown" : q?.source ?? "unknown",
+                    estimated: anonymous ? false : q?.estimated ?? true,
+                    timeZone: q?.timeZone ?? null,
+                },
+                diagnostics: {
+                    currentHealth: "not_tested",
+                    lastRecordedError: row.lastError ?? null,
+                    lastSuccessfulCallAt: row.used.lastUsed ?? null,
+                    quotaLookupError: row.remoteError ?? null,
+                },
+            };
+        }),
+    };
+}

package/dist/mcp/http.js

@@ -0,0 +1,35 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { buildMcpServer } from "./server.js";
+/**
+ * Mountet den MCP-Endpoint (Streamable HTTP, stateless) unter /mcp.
+ * Pro Request wird eine frische Transport-/Server-Instanz erzeugt
+ * (dokumentiertes Stateless-Pattern des SDK).
+ */
+export function mountMcpHttp(app, deps, security) {
+    app.all("/mcp", async (c) => {
+        // Stateless-Modus: es gibt keinen langlebigen SSE-Kanal. Ein GET mit
+        // Accept: text/event-stream würde vom Client als reconnectabler Stream
+        // interpretiert → Reconnect-Loop. Deshalb sofort 405.
+        if (c.req.method === "GET") {
+            return c.text("405 — SSE-Streaming im Stateless-Modus nicht unterstützt; JSON-RPC per POST senden.", 405, { allow: "POST" });
+        }
+        const server = buildMcpServer({ ...deps, requestSignal: c.req.raw.signal });
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+            enableDnsRebindingProtection: true,
+            allowedHosts: security?.allowedHosts ?? ["127.0.0.1", "localhost"],
+            allowedOrigins: security?.allowedOrigins ?? ["http://127.0.0.1", "http://localhost"],
+        });
+        await server.connect(transport);
+        try {
+            return await transport.handleRequest(c.req.raw);
+        }
+        finally {
+            setTimeout(() => {
+                void transport.close().catch(() => { });
+                void server.close().catch(() => { });
+            }, 0);
+        }
+    });
+}

package/dist/mcp/server.js

@@ -0,0 +1,105 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { RouterError } from "../router.js";
+import { engineStatus } from "./engine-status.js";
+import { dateSchema, timeRangeSchema, describeSearchTime } from "../search-time.js";
+import { VERSION } from "../version.js";
+import { readFileSync } from "node:fs";
+// Inline packaged icons: clients need no dashboard connection or external image host.
+const icons = ["light", "dark"].map(theme => ({
+    src: `data:image/png;base64,${readFileSync(new URL(`../../docs/assets/brand/icon-${theme}-128.png`, import.meta.url)).toString("base64")}`,
+    mimeType: "image/png",
+    sizes: ["128x128"],
+    theme,
+}));
+async function withRouterDiagnostics(operation) {
+    try {
+        return await operation;
+    }
+    catch (error) {
+        if (error instanceof RouterError && error.attempts.length) {
+            throw new Error(`${error.message}\n${error.attempts.map(a => `${a.engine}: ${a.error ?? (a.ok ? "ok" : "fehlgeschlagen")}`).join("\n")}`);
+        }
+        throw error;
+    }
+}
+export function buildMcpServer(deps) {
+    const server = new McpServer({ name: "search-rotation", version: VERSION, icons });
+    server.registerTool("web_search", {
+        title: "Web Search",
+        description: "Web search with automatic round-robin across multiple free search APIs (Tavily, Firecrawl, Parallel, Exa, Google PSE, DuckDuckGo) including transparent failover. Returns numbered results with title, URL, snippet and publication date when available. Time filters restrict rotation and failover to compatible providers; never silently dropped.",
+        inputSchema: {
+            query: z.string().describe("Search query"),
+            numResults: z.number().int().min(1).max(20).optional().describe("Optional result count (1–20). Omit to use the dashboard setting: a custom count or the provider default."),
+            timeRange: timeRangeSchema.optional().describe("Relative UTC date window: day=1, week=7, month=30, year=365 days through today. Cannot combine with startDate/endDate; day precision, not rolling hours."),
+            startDate: dateSchema.optional().describe("Start date YYYY-MM-DD. May be used alone or with endDate; cannot combine with timeRange."),
+            endDate: dateSchema.optional().describe("End date YYYY-MM-DD (through this date, subject to provider boundary semantics). Cannot combine with timeRange."),
+            engine: z.string().optional().describe("Preferred engine id; failover to the other engines stays active"),
+        },
+    }, async ({ query, numResults, engine, timeRange, startDate, endDate }, extra) => {
+        const r = await withRouterDiagnostics(deps.router.search({ query, numResults, timeRange, startDate, endDate }, { preferEngine: engine, signal: deps.requestSignal ? AbortSignal.any([extra.signal, deps.requestSignal]) : extra.signal }));
+        const lines = r.items.map((it, i) => {
+            const snip = it.snippet ? `\n   ${it.snippet.replace(/\s+/g, " ").slice(0, 400)}` : "";
+            return `${i + 1}. ${it.title}\n   ${it.url}${it.published ? `\n   Published: ${it.published}` : ""}${snip}`;
+        });
+        const failover = r.attempts.filter((a) => !a.ok).map((a) => `${a.engine}: ${a.error}`);
+        const head = [`Search "${query}" via ${r.engine} (${r.items.length} results)`];
+        const period = describeSearchTime({ query, timeRange, startDate, endDate });
+        if (period)
+            head.push(`Time filter: ${period} (provider date semantics apply)`);
+        if (r.answer)
+            head.push(`Answer: ${r.answer}`);
+        if (failover.length)
+            head.push(`Failover after: ${failover.join("; ")}`);
+        return { content: [{ type: "text", text: [...head, lines.join("\n")].join("\n\n") }] };
+    });
+    server.registerTool("fetch_url", {
+        title: "Fetch URL",
+        description: "Fetch a web page and return its content as markdown. Rotates across extraction providers (Jina Reader, Firecrawl, Parallel, Tavily, Exa) with failover.",
+        inputSchema: {
+            url: z.string().url().describe("URL to fetch"),
+        },
+    }, async ({ url }, extra) => {
+        const r = await withRouterDiagnostics(deps.router.fetchUrl({ url }, { signal: deps.requestSignal ? AbortSignal.any([extra.signal, deps.requestSignal]) : extra.signal }));
+        const MAX = 50_000;
+        const text = r.markdown.length > MAX
+            ? `${r.markdown.slice(0, MAX)}\n\n[… truncated, ${r.markdown.length} chars total]`
+            : r.markdown;
+        const failover = r.attempts.filter((a) => !a.ok).map((a) => `${a.engine}: ${a.error}`);
+        const head = `Fetched ${url} via ${r.engine}` + (failover.length ? ` (failover after: ${failover.join("; ")})` : "");
+        return { content: [{ type: "text", text: `${head}\n\n${text}` }] };
+    });
+    server.registerTool("engine_status", {
+        title: "Engine Status",
+        annotations: { readOnlyHint: true, destructiveHint: false },
+        description: "Read engine configuration, per-capability authentication requirements, local usage and quota sources. This is not a live health check. Historical errors do not prove a current failure; disabled engines are not necessarily missing credentials.",
+        inputSchema: {},
+    }, async () => {
+        const status = engineStatus(await deps.status(), deps.month(), VERSION);
+        return {
+            structuredContent: status,
+            content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+        };
+    });
+    server.registerTool("open_dashboard", {
+        title: "Open Dashboard",
+        description: "Open the local dashboard (API keys, engine order and toggles, quota view) in a web browser. Use when the user wants to configure engines or check quota.",
+        inputSchema: {},
+    }, async () => {
+        const url = deps.dashboardUrl();
+        if (!url) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "Dashboard ist deaktiviert (gestartet mit --no-dashboard). Ohne Dashboard-Flag neu starten, um Keys/Reihenfolge/Kontingente zu konfigurieren.",
+                    },
+                ],
+            };
+        }
+        deps.openDashboard();
+        return { content: [{ type: "text", text: `Dashboard: ${url}` }] };
+    });
+    return server;
+}