search-rotation 0.4.9

package/docs/operations.md

@@ -0,0 +1,66 @@
+# Betrieb und Konfiguration
+
+[Zurück zur README](../README.md)
+
+## Wie die Rotation arbeitet
+
+1. Suche und Fetch haben unabhängige Round-Robin-Zähler. Die Reihenfolge kommt aus dem Dashboard.
+2. Die Priorität bleibt über alle Aufrufe erhalten: **gesund → höchstens 10 % übrig → erschöpft**. Rotiert wird jeweils innerhalb einer Klasse.
+3. Fehler führen zur nächsten Engine und erscheinen als `Failover after: …`. HTTP 429 pausiert eine Engine gemäß `Retry-After` (Sekunden oder HTTP-Datum; ohne Header 30 s). 401/403 pausieren 60 s; ab zwei sonstigen Fehlern steigt die Pause von 30 s bis maximal 5 min. Ein Keywechsel hebt die bisherige Pause auf.
+4. Ein Gesamtzeitlimit von standardmäßig **60 s** umfasst Quota-Abfragen und alle Failover-Versuche. MCP-Abbruch bzw. HTTP-Verbindungsabbruch wird an die Anbieter weitergereicht. Nach Abbruch startet kein weiterer Versuch.
+5. `engine` bevorzugt eine Engine, umgeht aber weder Cooldown noch den strikten Gratis-Modus.
+6. **Strikter Gratis-Modus** (optional, Dashboard → Engines): Bereits ausgeschöpfte bekannte Kontingente werden vollständig ausgeschlossen; auch ein einzelner oder bevorzugter Anbieter wird dann nicht mehr aufgerufen. Unbekannte IP-Kontingente bleiben verwendbar. Laufende Aufrufe reservieren ihre Einheiten innerhalb eines Routers. Die Diagnose-Buttons testen nur die gewählte Engine (auch wenn deaktiviert), unterliegen aber denselben Zeit-, Cooldown- und Kontingentregeln.
+
+Die Cooldowns und Rotationspositionen gelten pro Serverprozess und werden beim Neustart zurückgesetzt. Im stateless HTTP-Modus beendet ein geschlossener Request die zugehörige Operation; eine separate `notifications/cancelled`-Nachricht besitzt keine langlebige Session-Zuordnung. Bei stdio wird die MCP-Cancellation direkt verarbeitet.
+
+### Kontingente und Speicherung
+
+Dashboard und `engine_status` zeigen **Zeitraum, Einheit, Quelle und Schätzstatus**. Google zählt pro Tag in `America/Los_Angeles` einschließlich Sommerzeit; Monatszähler verwenden UTC. Keyless Firecrawl/Exa sowie Jina und DuckDuckGo werden als unbekanntes IP-Kontingent angezeigt, nicht als kostenloses Monatsguthaben.
+
+Tavily/Firecrawl verwenden, soweit vorhanden, den Remote-Kontostand mit fünf Minuten Cache. Eigene erfolgreiche Aufrufe reduzieren den gecachten Rest sofort. Die lokalen Credit-Schätzungen sind derzeit Tavily Search 1 / Fetch 0,2 sowie Firecrawl Search 2 je angefangene 10 angefragte Treffer / Fetch 1. Die Aufrufzahl wird davon unabhängig gespeichert. Andere Engines zählen lokal Requests; ein aus Geldguthaben abgeleitetes Exa-Limit bleibt eine Schätzung.
+
+Der Gratis-Modus ist **keine Ausgabengarantie**: andere Anwendungen können dasselbe Konto belasten, Anbieter können Kosten ändern oder bereits gestartete/abgebrochene Requests abrechnen. Externe Nutzung und parallele Serverprozesse können einen Remote-Cache überholen. Für eine verbindliche Kostenobergrenze zusätzlich das Ausgabenlimit beim Anbieter setzen.
+
+`usage.json` und `history.json` bleiben im bisherigen Verzeichnis. Prozessübergreifende Sperren serialisieren vollständige Schreibtransaktionen; atomarer Rename mit individuellen temporären Dateien verhindert halbe Snapshots. Leser sehen Änderungen anderer Prozesse. Monatsdaten bleiben kompatibel, Tagesdaten werden für 62 Tage gehalten. Nachweislich tote Lock-Owner werden automatisch bereinigt; langsame lebende Prozesse werden nicht verdrängt. Bei einer blockierten Sperre schlägt das Schreiben nach 10 s mit einer Diagnose fehl. Ein seltener PID-Reuse-Fall nach einem Crash kann die automatische Bereinigung verzögern. Bereits laufende ältere Versionen vor dem Update beenden, da diese die neuen Sperren nicht verwenden.
+
+## Remote-Betrieb (Streamable HTTP)
+
+```bash
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.9 --http --host 0.0.0.0 --port 6277 --public-origin https://search.example.com --token <geheim>
+```
+
+Client-Config (Claude):
+
+```json
+{
+  "mcpServers": {
+    "search-rotation": {
+      "url": "https://search.example.com/mcp",
+      "headers": { "Authorization": "Bearer <geheim>" }
+    }
+  }
+}
+```
+
+Für dieses Beispiel leitet ein HTTPS-Reverse-Proxy `search.example.com` an Port 6277 weiter. Ein Bind außerhalb von Loopback benötigt einen Token. `--public-origin` legt die erlaubte externe Origin und den Host für Browser und MCP fest; fremde Hosts/Origins werden abgewiesen. Ohne Proxy kann eine passende `http://HOST:6277`-Origin verwendet werden.
+
+`/mcp` bleibt Bearer-authentifiziert. Im Browser führt die Dashboard-URL zu **`/login`**: Token einmal im Passwortformular eingeben, anschließend gilt ein acht Stunden gültiges `HttpOnly`-/`SameSite=Strict`-Session-Cookie (bei HTTPS zusätzlich `Secure`). Geheimnisfreie Skripte und Styles sind öffentlich, die Dashboard-API ist geschützt. API-Schreibzugriffe benötigen JSON und eine erlaubte Origin, sofern der Client eine sendet.
+
+Langlebige Tokens erscheinen weder in Logs noch in Tool-Ergebnissen oder URLs. `open_dashboard` öffnet intern einen 60 s gültigen Einmallink; der zurückgegebene Text enthält nur die Basis-URL. Die frühere `?token=…`-Anmeldung entfällt. `--no-dashboard` schaltet Dashboard, Login und Admin-API vollständig ab.
+
+Ohne Keys verwenden Firecrawl/Exa die Server-Egress-IP; verfügbare IP-Kontingente hängen deshalb vom Hosting ab.
+
+## Konfiguration
+
+Datei: `~/.config/search-rotation/config.json` (0600, wird vom Dashboard gepflegt). Override: `SEARCH_ROTATION_HOME`. Reihenfolge = Array-Reihenfolge (`engines` = Suche, `fetchOrder` = Fetch). Token zusätzlich via `--token` oder `SEARCH_ROTATION_TOKEN`.
+
+Zusätzliche `settings`-Felder (alte Configs erhalten Defaults):
+
+| Feld | Default | Verhalten |
+|---|---|---|
+| `strictFreeMode` | `false` | Bekannte ausgeschöpfte Kontingente vollständig überspringen |
+| `requestTimeoutMs` | `60000` | Gesamtbudget je Suche/Fetch, konfigurierbar von 1000 bis 300000 ms |
+| `monthlyLimits` | `{}` | Lokales Monatslimit pro Engine, in deren angezeigter Einheit |
+| `dailyLimits` | `{}` | Lokales Tageslimit pro Engine mit Tagesfenster, z. B. `{"google-cse": 100}` |
+
+Ein Limit `0` bedeutet weiterhin „kein festes lokales Limit“; zum Abschalten den Engine-Toggle verwenden. Ein gültiger Remote-Kontostand hat Vorrang vor lokalen Limits. Änderungen an Token oder Port benötigen einen **Neustart**; die Config-API kennzeichnet sie mit `requiresRestart: true`. Gratis-Modus und Zeitlimit wirken sofort.

package/docs/provider-access.md

@@ -0,0 +1,38 @@
+# Provider access and quota accounting
+
+Verified against provider documentation on 2026-09-05.
+
+| Provider | Without an API key? | Default without credentials | Evidence / limitation |
+| --- | --- | --- | --- |
+| Exa | Yes, through its hosted MCP server | Enabled | [Official MCP guide](https://docs.exa.ai/reference/exa-mcp): free casual use; search and fetch. Direct REST API requires a key. No known account balance or fixed request allowance for anonymous access. |
+| Firecrawl | Yes, search and scrape | Enabled | [Keyless rate limits](https://docs.firecrawl.dev/rate-limits#keyless-no-api-key) explicitly cover REST and hosted MCP. Shared IP/day request and credit limits; general API introduction still says authentication is required. |
+| Jina Reader | Yes, page extraction | Enabled | [Reader documentation](https://jina.ai/reader/): anonymous rate limits; fetch only in this server. |
+| DuckDuckGo HTML | Yes | Disabled (opt-in) | [Non-JavaScript search](https://duckduckgo.com/duckduckgo-help-pages/features/non-javascript): public HTML interface, not an officially supported search API. Can block automated traffic. |
+| Tavily | Yes for search, using a keyless-access header | Enabled (search only) | [OpenCode 2 implementation](https://github.com/anomalyco/opencode/blob/b09a74591cbd4d2ea1488e56177898a13f21278d/packages/core/src/plugin/websearch/tavily.ts); independently verified without credentials. Standard quickstart only describes authenticated access. |
+| Parallel | Yes for search via hosted MCP | Enabled (search only) | [OpenCode 2 implementation](https://github.com/anomalyco/opencode/blob/b09a74591cbd4d2ea1488e56177898a13f21278d/packages/core/src/plugin/websearch/parallel.ts); independently verified without credentials. Authenticated requests use the direct REST API. |
+| Google CSE | No; API key and search-engine ID required | Disabled | [API overview](https://developers.google.com/custom-search/v1/overview): existing customers only; scheduled discontinuation January 1, 2027. |
+
+“Without a key” never means unlimited. Rate limits and balances may be shared with other users behind the same public IP.
+
+The dashboard distinguishes:
+
+- **Provider account balance:** fetched with a configured key where supported. Firecrawl's billing period is not assumed to be a calendar month. Cached snapshots may include estimated consumption since the last refresh.
+- **Local successful calls:** this installation's successful search/fetch calls in the current UTC calendar month. Failed calls are counted separately. This is not the provider's total consumption; other clients, shared IP traffic and potentially billed failed requests are not observable.
+- **Unknown allowance:** no progress percentage or invented cap. Exa's former approximation of 1,400 requests has been removed, including for authenticated access. Explicit configured limits are local budgets, not verified provider balances.
+
+Existing engines that require credentials are disabled when their key is absent. Configured keys and explicit disabled settings are preserved.
+
+## OpenCode 2 implementation check
+
+The installed `opencode2 v0.0.0-beta-18684` binary contains the same keyless branches as the linked beta source. These are built-in web-search plugins, not an installation of search-rotation.
+
+- Tavily: POST `https://api.tavily.com/search`, `X-Tavily-Access-Mode: keyless`, basic search, 3 chunks per source. OpenCode identifies itself through `X-Client-Name: opencode2`; our independent test used `search-rotation` instead, without Authorization or an API key, and returned HTTP 200 with 3 results.
+- Parallel: MCP `https://search.parallel.ai/mcp`, tool `web_search`, arguments `objective` and `search_queries`. No Authorization header without configured credentials. Independent SDK test using client name search-rotation returned 10 results. Tool discovery also exposed `web_fetch`, which was not tested.
+
+This proves anonymous search access at verification time, not unlimited usage or support for every extraction endpoint. No account balance or cap is inferred. search-rotation now implements both anonymous search paths. Without credentials, these engines are omitted from fetch rotation and expose search only in the dashboard. With credentials, search and fetch use their direct APIs.
+
+## Result count
+
+In **Engines → Rotation settings**, choose **Custom count** (1–20) or **Provider default**. Existing and fresh configurations retain 8 until changed. An explicit `numResults` tool argument overrides this setting. Provider default omits the count from upstream requests; result counts may differ after rotation or failover. DuckDuckGo returns all results parsed from its HTML page; Parallel's hosted MCP returns its own result set (explicit counts are applied locally). Google CSE still caps explicit requests at 10.
+
+Firecrawl documents a default of 10 results, so our cost estimate for an omitted count is 2 credits, not an assumed dashboard count. Explicit counts above 10 are estimated at 4 credits. Source: https://docs.firecrawl.dev/api-reference/endpoint/search . Anonymous provider balances remain unknown; local successful-call counters do not measure their true credit consumption.

package/docs/release-notes.md

@@ -0,0 +1,52 @@
+## v0.4.9 — Updated Node type definitions
+
+Routine maintenance release: the Node type definitions move to 26.6.3. No behaviour change and no configuration migration. The GitHub release page now shows only the notes for the current version instead of the whole changelog.
+
+```sh
+brew update && brew upgrade localfoundry/tap/search-rotation
+```
+
+Or run the pinned GitHub version:
+
+```sh
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.9
+```
+
+
+## v0.4.8 — Updated dependencies
+
+Routine maintenance release: the MCP SDK moves to 1.30.1, Hono to 4.13.9, Zod to 4.6.5, tsx to 4.23.15 and the Node type definitions to 26.6.2, together with the matching transitive updates (jose, proxy-addr, ip-address, fast-uri, undici-types). No behaviour change and no configuration migration.
+
+```sh
+brew update && brew upgrade localfoundry/tap/search-rotation
+```
+
+Or run the pinned GitHub version:
+
+```sh
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.8
+```
+
+
+## v0.4.7 — Clearer dashboard usage, budgets, and activity
+
+Engine call counts are now visible with or without an API key. Search, fetch, and error counts are displayed separately from provider credits, so services such as Firecrawl remain easy to inspect even when a quota API is available.
+
+- Show monthly local engine attempts and their search/fetch/error breakdown consistently across the overview and engine cards.
+- Rename Engine Health to Engine Usage & Budget, with explicit remaining percentages, budget units, and quota-source explanations.
+- Add accessible activity-bar details for each two-hour window, including tool calls and per-engine attempts with fallbacks. Correct the 48-hour boundary and disclose the retained-history limit.
+- Include failed fallback attempts in engine history filters; distinguish empty history from filter misses and add full timestamps to history tooltips.
+- Refresh local call counts even when the quota percentage does not change. Empty history no longer implies a 0% error rate, and exhausted budgets have truly empty bars.
+- Expand MCP setup by default, improve tablet/mobile navigation, and refresh the English light/dark README screenshots using demo data.
+
+No configuration migration is required. Reconnect MCP clients after updating.
+
+```sh
+brew update && brew upgrade localfoundry/tap/search-rotation
+```
+
+Or run the pinned GitHub version:
+
+```sh
+npx -y --allow-git=all github:localfoundry/search-rotation-mcp#v0.4.7
+```

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "search-rotation",
+  "version": "0.4.9",
+  "description": "Round-robin web search over the free tiers of multiple search APIs (Tavily, Firecrawl, Parallel, Exa, Google PSE, Jina, DuckDuckGo) as an MCP server — with a local dashboard for API keys, engine order/toggles and live quota status.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Robin Bially",
+    "url": "https://github.com/localfoundry"
+  },
+  "bin": {
+    "search-rotation": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "static",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.3.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "web-search",
+    "round-robin",
+    "free-tier",
+    "tavily",
+    "firecrawl",
+    "exa",
+    "parallel",
+    "search"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "dev": "tsx src/index.ts --http --port 6277",
+    "start": "node dist/index.js --http --port 6277",
+    "test": "node --import tsx --test test/*.test.ts",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "sync:version-refs": "node scripts/sync-version-refs.mjs"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "hono": "^4.9.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/localfoundry/search-rotation-mcp.git"
+  },
+  "homepage": "https://github.com/localfoundry/search-rotation-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/localfoundry/search-rotation-mcp/issues"
+  }
+}