search-rotation 0.4.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Bially (LocalFoundry)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/wordmark-dark.svg">
+  <img src="docs/assets/brand/wordmark-light.svg" width="376" alt="search-rotation">
+</picture>
+
+**One MCP server for web search and page extraction across multiple providers.**
+
+Built by [Robin Bially](https://github.com/localfoundry) under the LocalFoundry label.
+
+Rotate across available quotas, automatically fail over when a provider is unavailable, and return consistent results to your AI assistant. A local dashboard lets you manage API keys, reorder engines, check quotas, and inspect request history.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dashboard-dark.png">
+  <img src="docs/assets/dashboard-light.png" alt="search-rotation dashboard showing per-engine call counts, remaining budgets, recent activity, and expanded MCP setup">
+</picture>
+
+*Actual dashboard UI, shown in English with illustrative demo data. Calls and provider budgets are displayed separately; activity bars offer time-window and per-engine details.*
+
+## Quick start
+
+### Homebrew
+
+```sh
+brew install localfoundry/tap/search-rotation
+search-rotation --http --open
+```
+
+Homebrew installs the required Node.js runtime. For MCP over stdio, configure your
+client to run `search-rotation` with no arguments. See the
+[LocalFoundry tap](https://github.com/localfoundry/homebrew-tap) for upgrades and details.
+
+### GitHub / npx
+
+Requires **Node.js 20.3+** and **Git**. Install directly from GitHub — **no npm account needed**.
+
+```sh
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.9
+```
+
+To preview the dashboard:
+
+```sh
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.9 --http --open
+```
+
+Add your provider keys in the dashboard, then connect your assistant using the **[MCP client setup guide](docs/clients.md)** for Codex, Claude, Cursor, or OpenCode.
+
+## What you get
+
+- **Search and fetch:** independent rotation for web search and Markdown page extraction.
+- **Automatic failover:** quota-aware ordering, rate-limit cooldowns, and request timeouts.
+- **Local dashboard:** API keys, drag-and-drop engine order, per-engine calls and errors, separate quota balances, and interactive request history.
+- **Local or remote:** MCP over stdio or authenticated Streamable HTTP.
+
+**Providers:** Tavily · Firecrawl · Parallel · Exa · Google PSE · Jina Reader · DuckDuckGo HTML. [Keyless access and quota accounting](docs/provider-access.md) vary by provider.
+
+## MCP tools
+
+`web_search` · `fetch_url` · `engine_status` · `open_dashboard`
+
+The dashboard's **MCP Tools** tab explains each tool, its parameters, and copyable example calls.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/mcp-tools-dark.png">
+  <img src="docs/assets/mcp-tools-light.png" alt="MCP Tools overview with parameters and example calls for all four tools">
+</picture>
+
+*Actual dashboard UI, shown in English.*
+
+## Search time filters
+
+`web_search` accepts the following arguments:
+
+| Parameter | Meaning |
+| --- | --- |
+| `query` | Required search text. |
+| `numResults` | Optional result count, 1–20; otherwise the dashboard setting applies. |
+| `engine` | Preferred provider, subject to time-filter support and availability; failover stays enabled. |
+| `timeRange` | `day`, `week`, `month`, or `year`: UTC date window starting 1, 7, 30, or 365 days ago, through today. |
+| `startDate` | Optional lower date bound in `YYYY-MM-DD` format. |
+| `endDate` | Optional upper date bound in `YYYY-MM-DD` format. |
+
+Use either `timeRange` or explicit dates. One-sided bounds and equal start/end dates are allowed; invalid calendar dates, reversed bounds, and mixing relative and explicit filters are rejected before any provider request.
+
+```json
+{"name":"web_search","arguments":{"query":"AI inference research","timeRange":"week","numResults":5}}
+```
+
+```json
+{"name":"web_search","arguments":{"query":"AI inference research","startDate":"2026-08-01","endDate":"2026-08-31"}}
+```
+
+Relative windows are resolved **once per request** into UTC dates, including across failover. These are date filters, not exact rolling 24-hour windows; `month` and `year` mean 30 and 365 days, not calendar arithmetic. Exa receives the start of the first UTC day and the end of the last UTC day.
+
+### Provider support and rotation
+
+| Provider / access | Relative window | Two date bounds | One date bound |
+| --- | --- | --- | --- |
+| Tavily, with or without key | Yes | Yes | Yes |
+| Firecrawl, with or without key | Yes | Yes | Skipped |
+| Exa, direct API with key | Yes | Yes | Yes |
+| Exa, hosted MCP without key | Skipped | Skipped | Skipped |
+| Parallel, either access mode | Skipped | Skipped | Skipped |
+| Google PSE / DuckDuckGo HTML | Skipped | Skipped | Skipped |
+
+This table describes **implemented support in search-rotation**, not every upstream feature. Tavily receives `start_date` / `end_date`, Firecrawl receives a custom `tbs` range, and Exa receives `startPublishedDate` / `endPublishedDate`. Firecrawl is conservatively excluded for one-sided dates; the other skipped paths have no implemented date mapping.
+
+The router excludes incompatible providers **before quota checks and rotation**, including when an incompatible `engine` is preferred. Each eligible provider pool has its own rotation cursor, so mixing filtered and unfiltered searches does not starve providers. Existing quota priorities, cooldowns, strict-free rules, and failover apply within that pool. If no compatible provider is available, the search fails explicitly; it never retries without the filter. Searches without time arguments retain access to all otherwise eligible providers.
+
+Results show a publication date when supplied by the adapter, and request history includes the requested period. Provider date metadata can be estimated or missing: Tavily filters publication **or update** dates, Exa filters estimated publication dates, and Firecrawl uses its search index's date interpretation. Exact boundary inclusion follows the provider; this is not an independent verification of each page's publication date. See the [Tavily](https://docs.tavily.com/documentation/api-reference/endpoint/search), [Firecrawl](https://docs.firecrawl.dev/api-reference/endpoint/search), and [Exa](https://exa.ai/docs/reference/search) references.
+
+After updating, reconnect your MCP client to load the new tool schema.
+
+## Releasing
+
+```sh
+VERSION=0.4.9 ./scripts/release.sh --publish
+```
+
+The script checks the package (`npm ci`, build, tests, `npm run smoke:package`), bumps the version, points the document pins at it, commits and tags, packs the tarball with its checksum, creates the GitHub release and updates the formula in `localfoundry/homebrew-tap`. Without `--publish` it only prepares the artifacts in `.build/releases`; `--dry-run` checks the prerequisites, `--draft` creates a draft release and `--force` tolerates a dirty tree. The tap is cloned temporarily when `TAP_DIR` is not set, so a fresh checkout is enough.
+
+## Learn more
+
+[Client setup](docs/clients.md) · [Operations & configuration (DE)](docs/operations.md) · [Releases](https://github.com/localfoundry/search-rotation-mcp/releases) · [CI](https://github.com/localfoundry/search-rotation-mcp/actions/workflows/ci.yml) · [MIT license](LICENSE)

package/dist/abort.js

@@ -0,0 +1,14 @@
+/** Stop waiting even if a provider fails to honour cancellation. */
+export function abortable(work, signal) {
+    if (!signal)
+        return work;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason ?? new Error('Anfrage abgebrochen'));
+        signal.addEventListener('abort', abort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+        if (signal.aborted) {
+            signal.removeEventListener('abort', abort);
+            abort();
+        }
+    });
+}

package/dist/config.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function configDir() {
+    return process.env.SEARCH_ROTATION_HOME || path.join(os.homedir(), ".config", "search-rotation");
+}
+export function normalizeConfig(raw, d) {
+    const known = new Set(d.knownIds);
+    const rawEngines = Array.isArray(raw?.engines)
+        ? raw.engines
+            .filter((e) => e && typeof e.id === "string" && known.has(e.id))
+            .map((e) => ({
+            id: e.id,
+            enabled: typeof e.enabled === "boolean" ? e.enabled : d.defaultEnabled[e.id] ?? true,
+            apiKey: typeof e.apiKey === "string" && e.apiKey.trim() ? e.apiKey.trim() : undefined,
+            extra: e.extra && typeof e.extra === "object" && !Array.isArray(e.extra)
+                ? Object.fromEntries(Object.entries(e.extra).filter(([, v]) => typeof v === "string"))
+                : undefined,
+        }))
+        : [];
+    const have = new Set(rawEngines.map((e) => e.id));
+    // Such-Engines in Such-Reihenfolge, danach evtl. fetch-only Engines (z. B. Jina)
+    for (const id of d.knownIds) {
+        if (!have.has(id))
+            rawEngines.push({ id, enabled: d.defaultEnabled[id] ?? true });
+    }
+    const fetchSet = new Set(d.fetchOrder);
+    const fo = Array.isArray(raw?.fetchOrder)
+        ? raw.fetchOrder.filter((id) => typeof id === "string" && fetchSet.has(id))
+        : [];
+    for (const id of d.fetchOrder) {
+        if (!fo.includes(id))
+            fo.push(id);
+    }
+    const seen = new Set();
+    const engines = rawEngines.filter((e) => {
+        // Hand-editierte Configs können Dubletten enthalten — der Router würde
+        // sonst dieselbe Engine mehrfach pro Suche aufrufen (doppelte Quota!).
+        if (seen.has(e.id))
+            return false;
+        seen.add(e.id);
+        return true;
+    });
+    for (const engine of engines) {
+        if (d.requiredKeyIds?.includes(engine.id) && !engine.apiKey)
+            engine.enabled = false;
+    }
+    const s = raw?.settings ?? {};
+    const rawLimits = s.monthlyLimits && typeof s.monthlyLimits === "object" && !Array.isArray(s.monthlyLimits)
+        ? s.monthlyLimits
+        : {};
+    // Nur endliche Zahlen >= 0 — ein Tippfehler ("abc") würde die Engine sonst
+    // unbegrenzt schalten, statt sie zu drosseln.
+    const monthlyLimits = {};
+    for (const [k, v] of Object.entries(rawLimits)) {
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            monthlyLimits[k] = v;
+    }
+    return {
+        version: 1,
+        engines,
+        fetchOrder: fo,
+        settings: {
+            port: Number.isInteger(s.port) && s.port >= 1024 && s.port <= 65535 ? s.port : 6277,
+            token: typeof s.token === "string" ? s.token : "",
+            monthlyLimits,
+            dailyLimits: Object.fromEntries(Object.entries(s.dailyLimits ?? {}).filter(([, v]) => typeof v === "number" && Number.isFinite(v) && v >= 0)),
+            strictFreeMode: s.strictFreeMode === true,
+            defaultNumResults: s.defaultNumResults === null ? null : Number.isInteger(s.defaultNumResults) && s.defaultNumResults >= 1 && s.defaultNumResults <= 20 ? s.defaultNumResults : 8,
+            requestTimeoutMs: Number.isInteger(s.requestTimeoutMs) && s.requestTimeoutMs >= 1000 && s.requestTimeoutMs <= 300_000 ? s.requestTimeoutMs : 60_000,
+        },
+    };
+}
+export class ConfigStore {
+    dir;
+    file;
+    constructor(dir = configDir()) {
+        this.dir = dir;
+        this.file = path.join(dir, "config.json");
+    }
+    load(d) {
+        fs.mkdirSync(this.dir, { recursive: true });
+        if (!fs.existsSync(this.file)) {
+            const cfg = normalizeConfig(null, d);
+            this.save(cfg);
+            return cfg;
+        }
+        let raw;
+        try {
+            raw = JSON.parse(fs.readFileSync(this.file, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Konfigdatei ${this.file} ist kein gültiges JSON: ${err.message}`);
+        }
+        return normalizeConfig(raw, d);
+    }
+    save(cfg) {
+        fs.mkdirSync(this.dir, { recursive: true });
+        const tmp = `${this.file}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+        fs.renameSync(tmp, this.file);
+        try {
+            fs.chmodSync(this.file, 0o600);
+        }
+        catch {
+            /* chmod optional */
+        }
+    }
+}

package/dist/engines/base.js

@@ -0,0 +1,72 @@
+import { VERSION } from "../version.js";
+export const USER_AGENT = `search-rotation/${VERSION}`;
+export class NeedsKeyError extends Error {
+    constructor(engineId, signupUrl) {
+        super(`${engineId}: kein API-Key konfiguriert — gratis Key: ${signupUrl}`);
+        this.name = "NeedsKeyError";
+    }
+}
+export class HttpError extends Error {
+    status;
+    body;
+    url;
+    retryAfter;
+    constructor(status, body, url, retryAfter) {
+        let host = url;
+        try {
+            host = new URL(url).host;
+        }
+        catch {
+            /* URL schon im Fehlertext behalten */
+        }
+        super(`HTTP ${status} von ${host}: ${body.slice(0, 200)}`);
+        this.status = status;
+        this.body = body;
+        this.url = url;
+        this.retryAfter = retryAfter;
+        this.name = "HttpError";
+    }
+}
+export async function httpText(url, init = {}, opts = {}) {
+    const timeout = AbortSignal.timeout(opts.timeoutMs ?? 20_000);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+    const headers = {
+        "user-agent": USER_AGENT,
+        // new Headers(...) normalisiert auch Headers-Instanzen und string[][] mit
+        // — ein simpler Spread würde sie als leeres Objekt droppen.
+        ...Object.fromEntries(new Headers(init.headers ?? undefined)),
+    };
+    const res = await fetch(url, { ...init, signal, headers });
+    const body = await res.text();
+    if (!res.ok)
+        throw new HttpError(res.status, body, url, res.headers.get("retry-after"));
+    return body;
+}
+export async function httpJson(url, init = {}, opts = {}) {
+    const text = await httpText(url, { ...init, headers: { accept: "application/json", ...Object.fromEntries(new Headers(init.headers ?? undefined)) } }, opts);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Ungültige Antwort von ${safeHost(url)} (kein JSON): ${text.slice(0, 120)}`);
+    }
+}
+export function bearer(key) {
+    return key ? { authorization: `Bearer ${key}` } : {};
+}
+export function cap(n, fallback = 8, max = 20) {
+    const v = typeof n === "number" && Number.isFinite(n) ? Math.round(n) : fallback;
+    return Math.min(Math.max(v, 1), Math.max(Math.round(max), 1));
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+/** Undefined means the provider chooses, including no local result slicing. */
+export function optionalCap(n) {
+    return n === undefined ? undefined : cap(n);
+}

package/dist/engines/duckduckgo.js

@@ -0,0 +1,98 @@
+import { optionalCap as cap, HttpError } from "./base.js";
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+    uuml: "ü",
+    ouml: "ö",
+    auml: "ä",
+    Uuml: "Ü",
+    Ouml: "Ö",
+    Auml: "Ä",
+    szlig: "ß",
+};
+function decodeEntities(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, code) => {
+        if (ENTITIES[code])
+            return ENTITIES[code];
+        const lower = code.toLowerCase();
+        if (lower.startsWith("#x"))
+            return String.fromCodePoint(parseInt(code.slice(2), 16));
+        if (code.startsWith("#"))
+            return String.fromCodePoint(parseInt(code.slice(1), 10));
+        return m;
+    });
+}
+function stripTags(s) {
+    return decodeEntities(s.replace(/<[^>]*>/g, ""))
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Best-effort-Parser für https://html.duckduckgo.com/html/ (inoffiziell). */
+export function parseDdgHtml(html) {
+    const items = [];
+    const linkRe = /<a[^>]+class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+    const snippetRe = /<a[^>]+class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/g;
+    const links = [...html.matchAll(linkRe)];
+    for (const [i, m] of links.slice(0, 20).entries()) {
+        // Ein Snippet gehört nur zum Bereich nach diesem Treffer und vor dem nächsten.
+        const block = html.slice(m.index + m[0].length, links[i + 1]?.index ?? html.length);
+        snippetRe.lastIndex = 0;
+        const snippet = snippetRe.exec(block)?.[1];
+        let raw = decodeEntities(m[1]);
+        const uddg = raw.match(/[?&]uddg=([^&]+)/);
+        if (uddg) {
+            try {
+                raw = decodeURIComponent(uddg[1]);
+            }
+            catch {
+                raw = uddg[1];
+            }
+        }
+        items.push({ title: stripTags(m[2]) || "(ohne Titel)", url: raw, snippet: snippet === undefined ? undefined : stripTags(snippet) });
+    }
+    return items;
+}
+async function search(input, ctx) {
+    const timeout = AbortSignal.timeout(20_000);
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeout]) : timeout;
+    const res = await fetch("https://html.duckduckgo.com/html/", {
+        method: "POST",
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            accept: "text/html",
+            "accept-language": "en",
+        },
+        body: new URLSearchParams({ q: input.query }),
+        redirect: "follow",
+        signal,
+    });
+    if (!res.ok) {
+        throw new HttpError(res.status, await res.text().catch(() => ""), "https://html.duckduckgo.com/html/");
+    }
+    const html = await res.text();
+    const items = parseDdgHtml(html).slice(0, cap(input.numResults));
+    if (items.length === 0) {
+        throw new Error("duckduckgo: keine Ergebnisse (möglicherweise blockiert — Bot-Detection)");
+    }
+    return { items };
+}
+export const DUCKDUCKGO = {
+    meta: {
+        id: "duckduckgo",
+        label: "DuckDuckGo (HTML)",
+        homepage: "https://duckduckgo.com",
+        signupUrl: "https://duckduckgo.com",
+        keyless: "ip",
+        defaultEnabled: false,
+        capabilities: ["search"],
+        monthlyFree: 0,
+        quota: { period: "ip", unit: "requests", estimated: true },
+        quotaEndpoint: false,
+        notes: "Inoffizieller HTML-Scrape: kein Kontingent, aber Bot-Detection möglich. Als letzte Instanz gedacht.",
+    },
+    search,
+};

package/dist/engines/exa.js

@@ -0,0 +1,113 @@
+import { optionalCap as cap, httpJson } from "./base.js";
+import { withHostedMcp } from "./hosted-mcp.js";
+const SIGNUP = "https://dashboard.exa.ai";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+/**
+ * Keyless-Fallback: Exas gehosteter MCP-Server ist ohne Key IP-basiert
+ * nutzbar und bietet Suche (web_search_exa) und Fetch (web_fetch_exa).
+ * Pro Aufruf eine eigene Client-Session — einfach und robust.
+ */
+function mcpText(result) {
+    return (result?.content ?? [])
+        .filter((c) => c?.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n\n");
+}
+function parseExaMcpSearch(text) {
+    const items = [];
+    for (const block of text.split(/\n-{3,}\n/)) {
+        const url = block.match(/^URL:\s*(\S+)$/m)?.[1]?.trim();
+        if (!url)
+            continue;
+        const title = block.match(/^Title:\s*(.+)$/m)?.[1]?.trim() || url;
+        const hl = block.indexOf("Highlights:");
+        const snippet = hl >= 0
+            ? block
+                .slice(hl + "Highlights:".length)
+                .replace(/\s+/g, " ")
+                .trim()
+                .slice(0, 500)
+            : undefined;
+        items.push({ title, url, snippet });
+    }
+    return items;
+}
+async function directSearch(input, ctx) {
+    const j = await httpJson("https://api.exa.ai/search", {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": ctx.apiKey },
+        body: JSON.stringify({
+            query: input.query,
+            startPublishedDate: input.startDate ? `${input.startDate}T00:00:00.000Z` : undefined,
+            endPublishedDate: input.endDate ? `${input.endDate}T23:59:59.999Z` : undefined,
+            numResults: cap(input.numResults),
+            type: "auto",
+            contents: { text: { maxCharacters: 400 } },
+        }),
+    }, { 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?.text === "string" ? r.text.slice(0, 500) : undefined,
+        published: typeof r?.publishedDate === "string" ? r.publishedDate : undefined,
+    }));
+    return { items };
+}
+async function directFetch(input, ctx) {
+    const j = await httpJson("https://api.exa.ai/contents", {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-api-key": ctx.apiKey },
+        body: JSON.stringify({ ids: [input.url], text: { maxCharacters: 50_000 } }),
+    }, { signal: ctx.signal, timeoutMs: 45_000 });
+    const text = j?.results?.[0]?.text;
+    if (typeof text !== "string" || !text.trim())
+        throw new Error("exa: kein Inhalt extrahiert");
+    return text;
+}
+async function search(input, ctx) {
+    // Mit Key: direkte API. Ohne Key: gehosteter Exa-MCP (IP-basiert, gratis).
+    if (!ctx.apiKey) {
+        const text = await withHostedMcp(EXA_MCP_URL, ctx, 30_000, async (client, signal) => {
+            const res = await client.callTool({ name: "web_search_exa", arguments: { query: input.query, numResults: cap(input.numResults) } }, undefined, { timeout: 30_000, signal });
+            if (res?.isError)
+                throw new Error(`exa-mcp: ${mcpText(res).slice(0, 200)}`);
+            return mcpText(res);
+        });
+        const items = parseExaMcpSearch(text);
+        if (items.length === 0)
+            throw new Error("exa-mcp: keine Ergebnisse");
+        return { items };
+    }
+    return directSearch(input, ctx);
+}
+async function fetchUrl(input, ctx) {
+    if (!ctx.apiKey) {
+        const text = await withHostedMcp(EXA_MCP_URL, ctx, 45_000, async (client, signal) => {
+            const res = await client.callTool({ name: "web_fetch_exa", arguments: { urls: [input.url], maxCharacters: 50_000 } }, undefined, { timeout: 45_000, signal });
+            if (res?.isError)
+                throw new Error(`exa-mcp: ${mcpText(res).slice(0, 200)}`);
+            return mcpText(res);
+        });
+        if (!text.trim())
+            throw new Error("exa-mcp: kein Inhalt extrahiert");
+        return text;
+    }
+    return directFetch(input, ctx);
+}
+export const EXA = {
+    meta: {
+        id: "exa",
+        label: "Exa",
+        homepage: "https://exa.ai",
+        signupUrl: SIGNUP,
+        keyless: "ip",
+        capabilities: ["search", "fetch"],
+        monthlyFree: 0,
+        quota: { period: "month", unit: "requests", estimated: true },
+        quotaEndpoint: false,
+        notes: "Ohne Key: automatisch über gehosteten Exa-MCP (mcp.exa.ai, IP-basiert limitiert) — Suche und Fetch. Mit Key: direkte API. Nutzung lokal gezählt; tatsächliches Guthaben und Anbieter-Gesamtverbrauch unbekannt.",
+    },
+    supportsSearchTime: (_input, ctx) => Boolean(ctx.apiKey),
+    search,
+    fetchUrl,
+};

package/dist/engines/firecrawl.js

@@ -0,0 +1,78 @@
+import { bearer, optionalCap as cap, httpJson } from "./base.js";
+const BASE = "https://api.firecrawl.dev/v2";
+async function search(input, ctx) {
+    const usDate = (date) => `${date.slice(5, 7)}/${date.slice(8, 10)}/${date.slice(0, 4)}`;
+    const tbs = input.startDate && input.endDate
+        ? `cdr:1,cd_min:${usDate(input.startDate)},cd_max:${usDate(input.endDate)}` : undefined;
+    const j = await httpJson(`${BASE}/search`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...bearer(ctx.apiKey) },
+        body: JSON.stringify({ query: input.query, limit: cap(input.numResults), tbs }),
+    }, { signal: ctx.signal, timeoutMs: 45_000 });
+    if (j && j.success === false)
+        throw new Error(`firecrawl: ${j.error ?? "unbekannter Fehler"}`);
+    const arr = j?.data?.web ?? (Array.isArray(j?.data) ? j.data : []);
+    const items = arr.map((d) => ({
+        title: d?.title || d?.url || "(ohne Titel)",
+        url: String(d?.url ?? ""),
+        snippet: typeof d?.description === "string"
+            ? d.description.slice(0, 500)
+            : typeof d?.markdown === "string"
+                ? d.markdown.slice(0, 300)
+                : undefined,
+    }));
+    return { items };
+}
+async function fetchUrl(input, ctx) {
+    const j = await httpJson(`${BASE}/scrape`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...bearer(ctx.apiKey) },
+        body: JSON.stringify({ url: input.url, formats: ["markdown"], onlyMainContent: true }),
+    }, { signal: ctx.signal, timeoutMs: 45_000 });
+    if (j && j.success === false)
+        throw new Error(`firecrawl: ${j.error ?? "unbekannter Fehler"}`);
+    const md = j?.data?.markdown;
+    if (typeof md !== "string" || !md.trim())
+        throw new Error("firecrawl: kein Inhalt gescraped");
+    return md;
+}
+async function remoteQuota(ctx) {
+    const j = await httpJson(`${BASE}/team/credit-usage`, { headers: bearer(ctx.apiKey) }, { signal: ctx.signal });
+    // Response: { success, data: { remainingCredits, planCredits, billingPeriodStart, billingPeriodEnd } }
+    const d = j?.data ?? {};
+    const limit = pickNum(d.planCredits);
+    const remaining = pickNum(d.remainingCredits);
+    return {
+        limit,
+        remaining,
+        used: limit !== undefined && remaining !== undefined ? limit - remaining : undefined,
+    };
+}
+function pickNum(...vals) {
+    for (const v of vals) {
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+export const FIRECRAWL = {
+    meta: {
+        id: "firecrawl",
+        label: "Firecrawl",
+        homepage: "https://www.firecrawl.dev",
+        signupUrl: "https://www.firecrawl.dev/signin",
+        keyless: "ip",
+        capabilities: ["search", "fetch"],
+        monthlyFree: 1000,
+        quota: { period: "month", unit: "credits", limit: 1000, estimated: true, costs: { search: 2, fetch: 1 } },
+        quotaEndpoint: true,
+        notes: "Gratis-Guthaben mit Konto; kein garantierter monatlicher Reset. Quota per API abrufbar; Reset nach Billing-Periode (Kontostand zählt Remote), nicht am Kalendermonat. Ohne Key nur wenige IP-basierte Requests.",
+    },
+    // Documented Firecrawl v2 default: 10 results (docs.firecrawl.dev/api-reference/endpoint/search).
+    // Cost remains an estimate; do not substitute our dashboard default here.
+    estimateCost: (kind, input) => kind === "search" ? 2 * Math.ceil((cap(input.numResults) ?? 10) / 10) : 1,
+    supportsSearchTime: input => Boolean(input.startDate && input.endDate),
+    search,
+    fetchUrl,
+    remoteQuota,
+};

package/dist/engines/googlecse.js

@@ -0,0 +1,41 @@
+import { optionalCap as cap, httpJson, NeedsKeyError } from "./base.js";
+const SIGNUP = "https://developers.google.com/custom-search/v1/overview";
+async function search(input, ctx) {
+    if (!ctx.apiKey)
+        throw new NeedsKeyError("google-cse", SIGNUP);
+    const cx = ctx.extra?.cx;
+    if (!cx)
+        throw new Error("google-cse: CX (Search Engine ID) fehlt — im Dashboard unter Extras hinterlegen.");
+    const url = new URL("https://www.googleapis.com/customsearch/v1");
+    url.searchParams.set("key", ctx.apiKey);
+    url.searchParams.set("cx", cx);
+    url.searchParams.set("q", input.query);
+    if (input.numResults !== undefined)
+        url.searchParams.set("num", String(Math.min(cap(input.numResults), 10)));
+    const j = await httpJson(url.toString(), {}, { signal: ctx.signal });
+    if (j?.error?.message)
+        throw new Error(`google-cse: ${j.error.message}`);
+    const items = (Array.isArray(j?.items) ? j.items : []).map((r) => ({
+        title: r?.title || "(ohne Titel)",
+        url: String(r?.link ?? ""),
+        snippet: typeof r?.snippet === "string" ? r.snippet : undefined,
+    }));
+    return { items };
+}
+export const GOOGLE_CSE = {
+    meta: {
+        id: "google-cse",
+        label: "Google PSE",
+        homepage: "https://www.google.com",
+        signupUrl: SIGNUP,
+        keyless: "no",
+        capabilities: ["search"],
+        monthlyFree: 3000,
+        quota: { period: "day", unit: "requests", limit: 100, timeZone: "America/Los_Angeles", estimated: false },
+        quotaEndpoint: false,
+        notes: "Für bestehende Kunden: 100 Queries pro Pacific-Tag. API-Key und Search Engine ID (CX) erforderlich. Für Neukunden geschlossen; Abschaltung am 1. Januar 2027.",
+        extraFields: [{ key: "cx", label: "Search Engine ID (CX)" }],
+        defaultEnabled: false,
+    },
+    search,
+};