search-rotation 0.4.11 → 0.5.0

package/README.md

@@ -43,7 +43,7 @@ client to run `search-rotation` with no arguments. See the
 ### Pinned release from GitHub
 
 ```sh
-npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.4.11
+npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.5.0
 ```
 
 Use this when you want a fixed version instead of the current npm release.
@@ -61,20 +61,22 @@ Add your provider keys in the dashboard, then connect your assistant using the *
 
 ## MCP tools
 
-`web_search` · `fetch_url` · `engine_status` · `open_dashboard`
+`search_web` · `fetch_url` · `get_engine_status` · `update_engine_config` · `open_dashboard`
+
+Every name pairs an action with its target. `update_engine_config` covers what the dashboard's engine list does: enable and disable engines, set the search and fetch rotation order, and set monthly or daily limits per engine. API keys stay in the dashboard. If your client keeps an allowlist of tool names, replace the earlier `web_search` and `engine_status` entries there.
 
 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">
+  <img src="docs/assets/mcp-tools-light.png" alt="MCP Tools overview with parameters and example calls for all five tools">
 </picture>
 
 *Actual dashboard UI, shown in English.*
 
 ## Search time filters
 
-`web_search` accepts the following arguments:
+`search_web` accepts the following arguments:
 
 | Parameter | Meaning |
 | --- | --- |
@@ -88,11 +90,11 @@ The dashboard's **MCP Tools** tab explains each tool, its parameters, and copyab
 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}}
+{"name":"search_web","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"}}
+{"name":"search_web","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.

package/dist/index.js

@@ -74,6 +74,12 @@ async function main() {
     const router = new SearchRouter({ getConfig, usage, adapters: ADAPTERS, history });
     const month = () => usage.monthKey();
     const status = () => buildStatus(getConfig(), usage, ADAPTERS);
+    const saveConfig = (next) => {
+        store.save(next);
+        cfg = next;
+        // Neuer Key? Dann Remote-Quota sofort frisch ziehen statt 5 Min Cache.
+        clearRemoteQuotaCache();
+    };
     const testEngine = async (id, kind, arg, signal) => {
         const adapter = ADAPTERS.find(a => a.meta.id === id);
         if (!adapter)
@@ -124,6 +130,7 @@ async function main() {
     const security = mountSecurity(app, { token, origin, additionalOrigins: [localOrigin], dashboardEnabled });
     const mcpDeps = {
         router, status, month, dashboardUrl,
+        getConfig, saveConfig,
         openDashboard: () => {
             if (dashboardEnabled)
                 openBrowser(security.browserUrl());
@@ -132,12 +139,7 @@ async function main() {
     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();
-        },
+        saveConfig,
         adapters: ADAPTERS,
         status,
         month,

package/dist/mcp/engine-config.js

@@ -0,0 +1,179 @@
+import { capabilityAccess, capabilityRotation, missingExtraConfiguration, } from "./engine-status.js";
+const CAPABILITIES = ["search", "fetch"];
+function capableIds(rows, capability) {
+    return rows.filter(row => capabilityAccess(row, capability) !== "unsupported").map(row => row.id);
+}
+function checkOrder(field, value, capable) {
+    if (!Array.isArray(value) || value.some(id => typeof id !== "string")) {
+        return { error: `${field} must be an array of engine ids` };
+    }
+    const order = value;
+    const unknown = order.filter(id => !capable.includes(id));
+    if (unknown.length) {
+        return { error: `${field}: unknown or unsupported engine ids: ${[...new Set(unknown)].join(", ")}. Supported ids: ${capable.join(", ")}` };
+    }
+    if (new Set(order).size !== order.length) {
+        return { error: `${field} contains duplicate engine ids` };
+    }
+    const missing = capable.filter(id => !order.includes(id));
+    if (missing.length) {
+        return { error: `${field} must list every capable engine exactly once; missing: ${missing.join(", ")}` };
+    }
+    return { order };
+}
+function checkLimits(field, value, known) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { error: `${field} must be an object mapping engine ids to integers or null` };
+    }
+    const limits = {};
+    for (const [id, raw] of Object.entries(value)) {
+        if (!known.includes(id)) {
+            return { error: `${field}: unknown engine id "${id}". Known ids: ${known.join(", ")}` };
+        }
+        if (raw === null) {
+            limits[id] = null;
+            continue;
+        }
+        if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+            return { error: `${field}.${id} must be a non-negative integer or null (null removes the override), got ${JSON.stringify(raw)}` };
+        }
+        limits[id] = raw;
+    }
+    return { limits };
+}
+/**
+ * Wendet eine Teiländerung auf eine Kopie der Konfiguration an. Bei Fehlern wird
+ * nichts zurückgegeben, was geschrieben werden dürfte: die Prüfungen laufen
+ * vollständig, bevor der Aufrufer speichert.
+ */
+export function applyEngineConfigPatch(cfg, rows, patch) {
+    const known = rows.map(row => row.id);
+    const byId = new Map(rows.map(row => [row.id, row]));
+    const searchCapable = capableIds(rows, "search");
+    const fetchCapable = capableIds(rows, "fetch");
+    const enabledEntries = Object.entries(patch.enabled ?? {});
+    const empty = enabledEntries.length === 0 &&
+        patch.searchOrder === undefined &&
+        patch.fetchOrder === undefined &&
+        Object.keys(patch.monthlyLimits ?? {}).length === 0 &&
+        Object.keys(patch.dailyLimits ?? {}).length === 0;
+    if (empty) {
+        return {
+            ok: false,
+            error: "Nothing to change: pass at least one of enabled, searchOrder, fetchOrder, monthlyLimits or dailyLimits.",
+        };
+    }
+    let engines = cfg.engines.map(engine => ({
+        ...engine,
+        extra: engine.extra ? { ...engine.extra } : undefined,
+    }));
+    const limits = {
+        monthlyLimits: { ...cfg.settings.monthlyLimits },
+        dailyLimits: { ...(cfg.settings.dailyLimits ?? {}) },
+    };
+    const changed = [];
+    for (const [id, enabled] of enabledEntries) {
+        const row = byId.get(id);
+        if (!row) {
+            return { ok: false, error: `enabled: unknown engine id "${id}". Known ids: ${known.join(", ")}` };
+        }
+        const engine = engines.find(candidate => candidate.id === id);
+        if (!engine) {
+            return { ok: false, error: `enabled: unknown engine id "${id}". Known ids: ${known.join(", ")}` };
+        }
+        // Nur ein tatsächlicher Wechsel auf "enabled" braucht Credentials; ein
+        // wiederholtes enabled=true auf einer laufenden Engine bleibt idempotent.
+        if (enabled && !engine.enabled) {
+            const modes = CAPABILITIES.map(capability => capabilityAccess(row, capability));
+            if (modes.every(mode => mode === "unsupported" || mode === "api_key_required" || mode === "extra_configuration_required")) {
+                const fields = missingExtraConfiguration(row);
+                const reason = modes.includes("extra_configuration_required")
+                    ? `required extra configuration is missing (${fields.join(", ")})`
+                    : "no API key is configured and this engine does not work keyless";
+                return {
+                    ok: false,
+                    error: `cannot enable "${id}": ${reason}. Set it in the dashboard (open_dashboard) first; nothing was changed.`,
+                };
+            }
+        }
+        if (engine.enabled !== enabled) {
+            changed.push(`${id}: enabled ${engine.enabled} -> ${enabled}`);
+            engine.enabled = enabled;
+        }
+    }
+    if (patch.searchOrder !== undefined) {
+        const checked = checkOrder("searchOrder", patch.searchOrder, searchCapable);
+        if ("error" in checked)
+            return { ok: false, error: checked.error };
+        const searchSet = new Set(searchCapable);
+        const byConfigId = new Map(engines.map(engine => [engine.id, engine]));
+        // Such-Engines in der gewünschten Reihenfolge, alles andere (z. B. reine
+        // Fetch-Engines wie Jina) unverändert dahinter — wie in normalizeConfig.
+        const others = engines.filter(engine => !searchSet.has(engine.id)).map(engine => engine.id);
+        const ordered = [...checked.order, ...others]
+            .map(id => byConfigId.get(id))
+            .filter((engine) => Boolean(engine));
+        const before = engines.map(engine => engine.id).join(", ");
+        const after = ordered.map(engine => engine.id).join(", ");
+        if (before !== after)
+            changed.push(`search order: ${before} -> ${after}`);
+        engines = ordered;
+    }
+    let fetchOrder = cfg.fetchOrder;
+    if (patch.fetchOrder !== undefined) {
+        const checked = checkOrder("fetchOrder", patch.fetchOrder, fetchCapable);
+        if ("error" in checked)
+            return { ok: false, error: checked.error };
+        if (fetchOrder.join(", ") !== checked.order.join(", ")) {
+            changed.push(`fetch order: ${fetchOrder.join(", ")} -> ${checked.order.join(", ")}`);
+        }
+        fetchOrder = checked.order;
+    }
+    for (const field of ["monthlyLimits", "dailyLimits"]) {
+        const raw = patch[field];
+        if (raw === undefined)
+            continue;
+        const checked = checkLimits(field, raw, known);
+        if ("error" in checked)
+            return { ok: false, error: checked.error };
+        const label = field === "monthlyLimits" ? "monthly" : "daily";
+        for (const [id, limit] of Object.entries(checked.limits)) {
+            const current = limits[field][id] ?? null;
+            if (limit === null)
+                delete limits[field][id];
+            else
+                limits[field][id] = limit;
+            if (current !== limit) {
+                changed.push(`${id}: ${label} limit ${current ?? "provider default"} -> ${limit ?? "provider default"}`);
+            }
+        }
+    }
+    return {
+        ok: true,
+        changed,
+        config: {
+            version: 1,
+            engines,
+            fetchOrder,
+            settings: { ...cfg.settings, monthlyLimits: limits.monthlyLimits, dailyLimits: limits.dailyLimits },
+        },
+    };
+}
+/** Kompakte, rosterweite Sicht auf die effektive Konfiguration für Tool-Antworten. */
+export function engineRotationSummary(rows, cfg) {
+    const searchPos = new Map(cfg.engines.map((engine, index) => [engine.id, index]));
+    const fetchPos = new Map(cfg.fetchOrder.map((id, index) => [id, index]));
+    return rows.map(row => {
+        const engine = cfg.engines.find(candidate => candidate.id === row.id);
+        const enabled = engine?.enabled ?? false;
+        return {
+            id: row.id,
+            name: row.label,
+            enabled,
+            search: capabilityRotation(capabilityAccess(row, "search"), enabled, searchPos.get(row.id) ?? -1),
+            fetch: capabilityRotation(capabilityAccess(row, "fetch"), enabled, fetchPos.get(row.id) ?? -1),
+            monthlyLimitOverride: cfg.settings.monthlyLimits[row.id] ?? null,
+            dailyLimitOverride: cfg.settings.dailyLimits?.[row.id] ?? null,
+        };
+    });
+}

package/dist/mcp/engine-status.js

@@ -1,3 +1,30 @@
+/** Zusatzfelder (z. B. Google `cx`), die konfiguriert sein müssen, aber leer sind. */
+export function missingExtraConfiguration(row) {
+    return (row.extraFields ?? []).filter(field => !row.extrasSet?.[field.key]).map(field => field.key);
+}
+/**
+ * Zugriffsmodus einer Engine für eine Fähigkeit — gemeinsame Wahrheit für
+ * `engine_status` und die Engine-Konfiguration, damit beide nie auseinanderlaufen.
+ */
+export function capabilityAccess(row, capability) {
+    const supported = row.supportedCapabilities ?? row.capabilities ?? [];
+    if (!supported.includes(capability))
+        return "unsupported";
+    const keyless = row.keylessCapabilities ?? (row.keyless === "ip" ? row.capabilities ?? [] : []);
+    if (!row.hasKey && !keyless.includes(capability))
+        return "api_key_required";
+    if (missingExtraConfiguration(row).length)
+        return "extra_configuration_required";
+    return row.hasKey ? "configured_key" : "keyless";
+}
+/** Rotationsplatz einer Fähigkeit; -1 bedeutet: nicht in der konfigurierten Reihenfolge. */
+export function capabilityRotation(mode, enabled, position) {
+    return {
+        mode,
+        includedInRotation: enabled && (mode === "keyless" || mode === "configured_key") && position >= 0,
+        configuredOrder: position >= 0 ? position + 1 : null,
+    };
+}
 /** Model-facing facts. Configuration and stored diagnostics are not live health checks. */
 export function engineStatus(rows, month, version) {
     return {
@@ -11,17 +38,10 @@ export function engineStatus(rows, month, version) {
             "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 missing = missingExtraConfiguration(row);
             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 }];
+                return [capability, capabilityRotation(capabilityAccess(row, capability), row.enabled, position)];
             }));
             const q = row.quota;
             const anonymous = !row.hasKey;
@@ -32,7 +52,7 @@ export function engineStatus(rows, month, version) {
                 enabled: row.enabled,
                 disabledReason: row.enabled ? null : "disabled_in_configuration; original reason not recorded",
                 apiKeyConfigured: row.hasKey,
-                missingExtraConfiguration,
+                missingExtraConfiguration: missing,
                 access,
                 localUsage: { successfulSearches: row.used.search, successfulFetches: row.used.fetch, failedAttempts: row.used.errors ?? 0 },
                 quota: {

package/dist/mcp/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { RouterError } from "../router.js";
 import { engineStatus } from "./engine-status.js";
+import { applyEngineConfigPatch, engineRotationSummary } from "./engine-config.js";
 import { dateSchema, timeRangeSchema, describeSearchTime } from "../search-time.js";
 import { VERSION } from "../version.js";
 import { readFileSync } from "node:fs";
@@ -25,16 +26,17 @@ async function withRouterDiagnostics(operation) {
 }
 export function buildMcpServer(deps) {
     const server = new McpServer({ name: "search-rotation", version: VERSION, icons });
-    server.registerTool("web_search", {
+    server.registerTool("search_web", {
         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.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: "Search the web through a rotating pool of search providers (Tavily, Firecrawl, Parallel, Exa, Google PSE, DuckDuckGo) with automatic failover when one errors, is rate-limited or has no local quota left. Use it when the answer depends on current web pages and no URL is known yet; use fetch_url to read a page whose URL is already known. Returns numbered results (title, URL, snippet, publication date when the provider supplies one) and names the provider that answered plus every failed attempt, so failover stays visible. Time filters keep rotation inside the providers that implement them and fail explicitly instead of searching without the filter; if every eligible provider fails, the tool returns an error listing each provider's reason. The engine parameter only prefers a provider and leaves failover active.",
         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"),
+            engine: z.string().optional().describe("Preferred engine id from get_engine_status; only moves that engine to the front, failover to the others stays active. Engines without implemented support for the time filter are skipped even when preferred."),
         },
     }, 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 }));
@@ -55,9 +57,10 @@ export function buildMcpServer(deps) {
     });
     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.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: "Fetch one web page and return its main content as Markdown, rotating across extraction providers (Jina Reader, Firecrawl, Parallel, Tavily, Exa) with failover. Use it to read a URL the user or a previous search_web result already names; it does not discover links or crawl a site. Only http and https URLs are accepted. The result names the provider that succeeded, lists failed attempts and truncates content beyond 50,000 characters with a marker; if every provider fails, the tool returns an error listing each provider's reason.",
         inputSchema: {
-            url: z.string().url().describe("URL to fetch"),
+            url: z.string().url().describe("Absolute http(s) URL of the page to fetch, including scheme and host"),
         },
     }, async ({ url }, extra) => {
         const r = await withRouterDiagnostics(deps.router.fetchUrl({ url }, { signal: deps.requestSignal ? AbortSignal.any([extra.signal, deps.requestSignal]) : extra.signal }));
@@ -69,10 +72,10 @@ export function buildMcpServer(deps) {
         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", {
+    server.registerTool("get_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.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: "Read this server's local engine configuration: enabled state, configured rotation order, per-capability access (keyless, configured key, or key/extra credentials still required), local usage counters and the quota source per engine. Use it before update_engine_config for valid engine ids, and as the machine-readable answer when you need to know which providers are active, how much quota is left or why a provider is skipped — the dashboard is the human-facing view of the same installation. The tool performs no search and no fetch: it is not a live health check, stored errors are historical observations, and a disabled engine is a configuration state, not proof that a key is missing. Provider balances can come from a cached lookup that the dashboard refreshes; unknown provider limits are reported as null rather than zero or unlimited.",
         inputSchema: {},
     }, async () => {
         const status = engineStatus(await deps.status(), deps.month(), VERSION);
@@ -83,7 +86,8 @@ export function buildMcpServer(deps) {
     });
     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.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: "Open the local dashboard of this server in a browser on the machine running the server, for a human: it is the only place to enter API keys and provider credentials, strict-free mode, port and access token, and it shows the interactive usage, quota and request-history views. Use it for those credential and network settings and when a person should look at the data; read configuration with get_engine_status and change engines with update_engine_config instead, because their results are machine-readable and this call only launches a browser. The browser opens on the server host, not on the client's machine, and a server started with --no-dashboard returns an error.",
         inputSchema: {},
     }, async () => {
         const url = deps.dashboardUrl();
@@ -101,5 +105,60 @@ export function buildMcpServer(deps) {
         deps.openDashboard();
         return { content: [{ type: "text", text: `Dashboard: ${url}` }] };
     });
+    server.registerTool("update_engine_config", {
+        title: "Update Engine Config",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: "Change the local engine configuration: enable or disable engines, set the search and fetch rotation order, and set monthly or daily call limits per engine. Use it when the user wants a provider switched on or off, reordered or capped; call get_engine_status first for valid ids, current order and access modes. The tool writes the shared configuration file of this installation, so the change applies to later searches of every client without a restart. API keys are not accepted here: an engine that still needs a key or extra credentials cannot be enabled until they are set in the dashboard (open_dashboard). Returns the effective per-engine configuration, or an error naming the offending ids — on error nothing is written.",
+        inputSchema: {
+            enabled: z.record(z.string(), z.boolean()).optional().describe("Per engine id (see get_engine_status): true enables, false disables. Enabling an engine whose access mode is api_key_required or extra_configuration_required fails until the credential exists in the dashboard."),
+            searchOrder: z.array(z.string()).optional().describe("Complete search rotation: every search-capable engine id exactly once, the first entry is queried first. Fetch-only engines are not part of this order and keep their place behind it."),
+            fetchOrder: z.array(z.string()).optional().describe("Complete fetch rotation: every fetch-capable engine id exactly once, the first entry is tried first."),
+            monthlyLimits: z.record(z.string(), z.number().int().min(0).nullable()).optional().describe("Per engine id: cap for locally counted calls per month, or null to remove the override and fall back to the provider default. The cap drives rotation and strict-free ordering; it does not change the provider account."),
+            dailyLimits: z.record(z.string(), z.number().int().min(0).nullable()).optional().describe("Per engine id: cap for locally counted calls per day, or null to remove the override. Applies to providers whose quota period is counted per day."),
+        },
+    }, async ({ enabled, searchOrder, fetchOrder, monthlyLimits, dailyLimits }) => {
+        const rows = await deps.status();
+        const applied = applyEngineConfigPatch(deps.getConfig(), rows, {
+            enabled,
+            searchOrder,
+            fetchOrder,
+            monthlyLimits,
+            dailyLimits,
+        });
+        if (!applied.ok) {
+            return { isError: true, content: [{ type: "text", text: applied.error }] };
+        }
+        if (applied.changed.length)
+            deps.saveConfig(applied.config);
+        const engines = engineRotationSummary(rows, deps.getConfig());
+        const head = applied.changed.length
+            ? "Local engine configuration updated (applies to later searches, no restart needed):"
+            : "No change: the requested values already match the local configuration.";
+        const lines = engines.map(engine => {
+            const parts = [engine.enabled ? "enabled" : "disabled"];
+            for (const capability of ["search", "fetch"]) {
+                const state = engine[capability];
+                if (state.mode === "unsupported")
+                    continue;
+                parts.push(`${capability} ${state.configuredOrder === null ? "not in rotation" : `#${state.configuredOrder}`} (${state.mode})`);
+            }
+            if (engine.monthlyLimitOverride !== null)
+                parts.push(`monthly limit ${engine.monthlyLimitOverride}`);
+            if (engine.dailyLimitOverride !== null)
+                parts.push(`daily limit ${engine.dailyLimitOverride}`);
+            return `- ${engine.id}: ${parts.join(", ")}`;
+        });
+        const text = [
+            head,
+            ...applied.changed.map(change => `- ${change}`),
+            "",
+            "Effective configuration:",
+            ...lines,
+        ].join("\n");
+        return {
+            structuredContent: { ok: true, changed: applied.changed, engines },
+            content: [{ type: "text", text }],
+        };
+    });
     return server;
 }

package/docs/assets/search-rotation.svg

@@ -22,7 +22,7 @@
     <text x="76" y="286" fill="#8d9bb5" font-size="12" font-weight="700" letter-spacing="1.5">DEIN MCP-CLIENT</text>
     <text x="76" y="327" fill="#f1f4fb" font-size="23" font-weight="650">Eine Anfrage</text>
     <rect x="75" y="347" width="202" height="39" rx="8" fill="#0c1220"/>
-    <text x="89" y="372" fill="#c5baff" font-family="'SFMono-Regular', Consolas, monospace" font-size="15">web_search(query)</text>
+    <text x="89" y="372" fill="#c5baff" font-family="'SFMono-Regular', Consolas, monospace" font-size="15">search_web(query)</text>
     <text x="76" y="417" fill="#93a0b8" font-size="14">Codex · Claude · Cursor · …</text>
     <path d="M307 346 H368" fill="none" stroke="#78879e" stroke-width="2" marker-end="url(#arrow)"/>
     <rect x="384" y="235" width="328" height="228" rx="18" fill="url(#router)" stroke="#726ca7"/>

package/docs/clients.md

@@ -77,7 +77,7 @@ Add this entry under `mcp.servers`:
 If installed locally, use `search-rotation` as the command. A prebuilt archive is also available under [GitHub Releases](https://github.com/robin-bially/search-rotation-mcp/releases/latest):
 
 ```sh
-npm install -g ./search-rotation-0.4.11.tgz
+npm install -g ./search-rotation-0.5.0.tgz
 ```
 
 npx installs the package from the npm registry, so no Git access is required. The pinned
@@ -88,7 +88,7 @@ For remote HTTP access, authentication and advanced settings, see the [operation
 
 ## Multiple harnesses and updates
 
-Each stdio client starts its own server process. Its dashboard binds to the configured port (6277 by default), or the next free port up to 20 ports higher. `open_dashboard` opens the dashboard belonging to that process; it does not attach to another harness's process.
+Each stdio client starts its own server process. Its dashboard binds to the configured port (6277 by default), or the next free port up to 20 ports higher. `open_dashboard` opens the dashboard belonging to that process; it does not attach to another harness's process. Configuration is shared, though: every process reads `~/.config/search-rotation/config.json`, so an `update_engine_config` call in one harness applies to the others as soon as they read the file for their next search.
 
 Processes using the same `SEARCH_ROTATION_HOME` share configuration and counters. Engine settings reload before requests; port and authentication changes require a restart. Rotation cursors, cooldowns and in-flight reservations are per process, so strict-free mode is not a global spending lock across harnesses.
 

package/docs/distribution.md

@@ -7,11 +7,11 @@ what still needs attention. Snapshot: 2026-09-26, after the account rename from
 
 | Channel | Entry | Kept current by | State |
 | --- | --- | --- | --- |
-| npm | `search-rotation` | release workflow, trusted publishing | 0.4.10; 0.4.11 blocked by the stale trusted publisher, see below |
+| npm | `search-rotation` | release workflow, trusted publishing | 0.4.11 |
 | Homebrew | `brew install robin-bially/tap/search-rotation` | release script writes the formula | 0.4.11 |
-| Official MCP Registry | `io.github.robin-bially/search-rotation` | release workflow, GitHub OIDC | blocked: the registry verifies the npm package, so it needs 0.4.11 on npm first; `io.github.localfoundry/search-rotation` stays live at 0.4.10 because the registry has no unpublish |
+| Official MCP Registry | `io.github.robin-bially/search-rotation` | release workflow, GitHub OIDC | 0.4.11; the old `io.github.localfoundry/search-rotation` stays frozen at 0.4.10 because the registry has no unpublish |
 | GitHub releases | tag, tarball and checksum | release script | v0.4.11 |
-| Glama | [directory entry](https://glama.ai/mcp/servers/robin-bially/search-rotation-mcp), rated A | Glama indexes the repository on its own | listed; the account rename is pending a re-crawl |
+| Glama | [directory entry](https://glama.ai/mcp/servers/robin-bially/search-rotation-mcp), rated A | Glama indexes the repository on its own | listed under the current account name; Glama picked up the rename by itself, the previous `RobinBially` path still resolves |
 | mcpservers.org | [submission](https://mcpservers.org/de/submit) from 2026-09-26 | reviewed by the site | in review, up to two weeks |
 | PulseMCP | — | ingests the official registry | submissions paused, not listed yet |
 | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers/pull/15171) | Search & Data Extraction | maintainers | pull request open, listing checks done |
@@ -37,14 +37,14 @@ Four details are easy to forget:
 - `server.json` and `mcpName` must name the same server; `test/registry-manifest.test.ts` fails when they drift apart.
 - The registry limits `description` to 100 characters.
 - The registry verifies ownership through the published npm package, so a manifest can only be registered once that version exists on npm. The workflow skips an already published version, which makes a re-run safe.
-- npm trusted publishing is bound to one repository. The entry for `search-rotation` still named `localfoundry/search-rotation-mcp`, so the 0.4.11 publish failed with `404 Not Found - PUT https://registry.npmjs.org/search-rotation`. Repair with `npm trust github search-rotation --file publish.yml --repo robin-bially/search-rotation-mcp --allow-publish`, then revoke the stale entry (`npm trust list search-rotation`, `npm trust revoke search-rotation --id=<id>`) and re-run the publish workflow. Both commands ask for a one-time password in the browser. The old owner name is free again, so the stale entry also lets a stranger publish to this package.
+- npm trusted publishing is bound to one repository, so an account rename has to be re-pointed by hand: `npm trust github search-rotation --file publish.yml --repo robin-bially/search-rotation-mcp --allow-publish` (one-time password in the browser). That was missed for 0.4.11, whose publish failed with `404 Not Found - PUT https://registry.npmjs.org/search-rotation`; the stale entry for `localfoundry/search-rotation-mcp` was revoked on 2026-09-26, because the freed owner name would otherwise let a stranger publish to this package.
 
 ## Recurring checks
 
-- After a release: `npm view search-rotation version` and the [registry entry](https://registry.modelcontextprotocol.io/?q=io.github.robin-bially%2Fsearch-rotation) should both show the new version. The release script already waits for npm, but a failed publish workflow leaves the release and the tap ahead of npm, as with 0.4.11.
+- After a release: `npm view search-rotation version` and the [registry entry](https://registry.modelcontextprotocol.io/?q=io.github.robin-bially%2Fsearch-rotation) should both show the new version. The release script already waits for npm. A failed publish workflow leaves the release and the tap ahead of npm, which happened with 0.4.11; `gh workflow run publish.yml` then repairs npm and the registry in one run.
 - Dependency and tap maintenance runs outside this repository on a biweekly schedule.
 - The GitHub account moved from `localfoundry` to `robin-bially` on 2026-09-26. The registry has no unpublish, so the entry `io.github.localfoundry/search-rotation` stays frozen at 0.4.10 while the next release adds `io.github.robin-bially/search-rotation`. The old handle is free again, so anything still pointing there can end up at a different account.
-- Open externally: mcpservers.org reviews the submission, PulseMCP is paused, the three list pull requests wait for their maintainers, and Glama re-crawls repositories at its own pace.
+- Open externally: mcpservers.org reviews the submission, PulseMCP is paused, and the three list pull requests wait for their maintainers. Glama has re-crawled the repository after the rename.
 
 ## Deliberately not used
 

package/docs/operations.md

@@ -15,7 +15,7 @@ Die Cooldowns und Rotationspositionen gelten pro Serverprozess und werden beim N
 
 ### 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.
+Dashboard und `get_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.
 
@@ -46,7 +46,7 @@ Für dieses Beispiel leitet ein HTTPS-Reverse-Proxy `search.example.com` an Port
 
 `/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.
+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; `get_engine_status` und `update_engine_config` arbeiten weiterhin auf der lokalen Konfigurationsdatei.
 
 Ohne Keys verwenden Firecrawl/Exa die Server-Egress-IP; verfügbare IP-Kontingente hängen deshalb vom Hosting ab.
 

package/docs/release-notes.md

@@ -1,3 +1,30 @@
+## v0.5.0 — Consistent tool names and programmable engine configuration
+
+The tool definitions were rewritten against the TDQS rubric, and two tools changed
+name: `web_search` is now `search_web`, `engine_status` is now `get_engine_status`.
+All five tools follow the same verb_noun pattern. Arguments, results and error texts
+are unchanged, so only clients that keep an allowlist of tool names need an edit.
+
+`update_engine_config` is new: it enables or disables engines, sets the search and
+fetch rotation order, and sets monthly or daily limits per engine. It writes the same
+local configuration file as the dashboard and applies to later searches without a
+restart; API keys stay in the dashboard.
+
+Every description now states when to use the tool and how failures surface, and all
+five tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
+`openWorldHint`).
+
+```sh
+brew update && brew upgrade robin-bially/tap/search-rotation
+```
+
+Or run the pinned GitHub version:
+
+```sh
+npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.5.0
+```
+
+
 ## v0.4.11 — Distribution under the robin-bially account
 
 The GitHub account moved from `localfoundry` to `robin-bially`, so every distribution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "search-rotation",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "mcpName": "io.github.robin-bially/search-rotation",
   "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",

package/static/app.js

@@ -478,9 +478,10 @@ function renderSnippets() {
 
 function renderTools() {
   const tools = [
-    { name: "web_search", icon: "search", params: [["query", "query"], ["numResults", "count"], ["engine", "engine"], ["timeRange", "timeRange"], ["startDate", "startDate"], ["endDate", "endDate"]], args: { query: "latest AI research", numResults: 5, timeRange: "week" } },
+    { name: "search_web", icon: "search", params: [["query", "query"], ["numResults", "count"], ["engine", "engine"], ["timeRange", "timeRange"], ["startDate", "startDate"], ["endDate", "endDate"]], args: { query: "latest AI research", numResults: 5, timeRange: "week" } },
     { name: "fetch_url", icon: "link", params: [["url", "url"]], args: { url: "https://example.com" } },
-    { name: "engine_status", icon: "gauge", params: [], args: {} },
+    { name: "get_engine_status", icon: "gauge", params: [], args: {} },
+    { name: "update_engine_config", icon: "grip", params: [["enabled", "enabled"], ["searchOrder", "searchOrder"], ["fetchOrder", "fetchOrder"], ["monthlyLimits", "monthlyLimits"], ["dailyLimits", "dailyLimits"]], args: { enabled: { duckduckgo: false }, searchOrder: ["tavily", "firecrawl", "parallel", "exa", "google-cse", "duckduckgo"] } },
     { name: "open_dashboard", icon: "stack", params: [], args: {} },
   ];
   $("#view").innerHTML = '<div class="page">' + pageHead(t("tools.title"), t("tools.sub")) +

package/static/i18n.js

@@ -30,12 +30,13 @@ window.I18N = {
     "settings.results": "Standard-Ergebnisanzahl",
     "nav.tools": "MCP Tools",
     "tools.title": "MCP Tools",
-    "tools.sub": "Vier Werkzeuge, die dein KI-Assistent aufrufen kann",
+    "tools.sub": "Fünf Werkzeuge, die dein KI-Assistent aufrufen kann",
     "tools.intro": "Beschreibe deinem Assistenten einfach, was du brauchst. Er ruft das passende Tool auf. Die Beispiele zeigen Toolname und Argumente; Kopieren führt keinen Aufruf aus.",
-    "tools.web_search": "Sucht im Web und gibt Titel, URLs und Textauszüge zurück. Rotiert automatisch zwischen Engines und wechselt bei Fehlern zum nächsten Anbieter.",
-    "tools.fetch_url": "Ruft eine bestimmte Webseite ab und gibt ihren Inhalt als Markdown zurück. Nutzt eine eigene Anbieter-Rotation für die Textextraktion.",
-    "tools.engine_status": "Zeigt Aktivierung, Zugang pro Funktion, lokale Nutzung und Kontingente. Fehlende Keys sind nicht automatisch ein Problem: Einige Funktionen gehen keyless. Gespeicherte Fehler sind historisch; dies ist kein Live-Funktionstest.",
-    "tools.open_dashboard": "Öffnet dieses Dashboard im Browser des Rechners, auf dem der Server läuft. Bei einem entfernten Server öffnet es nicht automatisch deinen lokalen Browser.",
+    "tools.search_web": "Sucht im Web und gibt Titel, URLs und Textauszüge zurück. Rotiert automatisch zwischen Engines und wechselt bei Fehlern zum nächsten Anbieter. Richtig, solange keine URL bekannt ist; für eine bekannte Adresse ist fetch_url zuständig.",
+    "tools.fetch_url": "Ruft eine bestimmte Webseite ab und gibt ihren Inhalt als Markdown zurück. Nutzt eine eigene Anbieter-Rotation für die Textextraktion. Richtig für eine bekannte URL; Seiten finden kann nur search_web.",
+    "tools.get_engine_status": "Zeigt Aktivierung, Reihenfolge, Zugang pro Funktion, lokale Nutzung und Kontingente. Fehlende Keys sind nicht automatisch ein Problem: Einige Funktionen gehen keyless. Gespeicherte Fehler sind historisch; dies ist kein Live-Funktionstest.",
+    "tools.update_engine_config": "Schaltet Engines ein oder aus, setzt die Reihenfolge von Such- und Fetch-Rotation und begrenzt Aufrufe pro Engine (Monats- und Tageslimit). Schreibt die lokale Konfigurationsdatei und gilt für spätere Suchen ohne Neustart; API-Keys und Zugangsdaten bleiben im Dashboard.",
+    "tools.open_dashboard": "Öffnet dieses Dashboard im Browser des Rechners, auf dem der Server läuft: API-Keys, Zugangsdaten, Netzwerkeinstellungen sowie Nutzung, Kontingente und Verlauf. Bei einem entfernten Server öffnet es nicht automatisch deinen lokalen Browser.",
     "tools.parameters": "Parameter",
     "tools.none": "Keine Parameter.",
     "tools.example": "Beispielaufruf",
@@ -47,6 +48,11 @@ window.I18N = {
     "tools.param.startDate": "Optional · Startdatum YYYY-MM-DD. Allein oder mit endDate; muss vor oder auf endDate liegen.",
     "tools.param.endDate": "Optional · Enddatum YYYY-MM-DD. Datumsinterpretation hängt vom Anbieter ab; ungeeignete Anbieter werden übersprungen.",
     "tools.param.url": "Erforderlich · Vollständige URL der Webseite.",
+    "tools.param.enabled": "Optional · Pro Engine-ID: true aktiviert, false deaktiviert. Aktivieren scheitert, solange ein nötiger Key oder Zusatzfelder fehlen.",
+    "tools.param.searchOrder": "Optional · Vollständige Such-Rotation: jede suchfähige Engine-ID genau einmal, erste zuerst. Reine Fetch-Engines bleiben außen vor.",
+    "tools.param.fetchOrder": "Optional · Vollständige Fetch-Rotation: jede fetchfähige Engine-ID genau einmal, erste zuerst.",
+    "tools.param.monthlyLimits": "Optional · Pro Engine-ID: Obergrenze für lokal gezählte Aufrufe pro Monat. null entfernt den Override und stellt den Anbieterstandard her.",
+    "tools.param.dailyLimits": "Optional · Pro Engine-ID: Obergrenze für lokal gezählte Aufrufe pro Tag. null entfernt den Override.",
 
     "settings.title": "Rotation einstellen",
     "settings.strict": "Strikter Gratis-Modus",
@@ -190,12 +196,13 @@ window.I18N = {
     "settings.results": "Default result count",
     "nav.tools": "MCP Tools",
     "tools.title": "MCP Tools",
-    "tools.sub": "Four tools your AI assistant can call",
+    "tools.sub": "Five tools your AI assistant can call",
     "tools.intro": "Tell your assistant what you need and it will call the appropriate tool. Examples show tool names and arguments; copying an example does not run it.",
-    "tools.web_search": "Searches the web and returns titles, URLs and snippets. Automatically rotates between engines and falls back to another provider when a request fails.",
-    "tools.fetch_url": "Fetches a specific webpage and returns its content as Markdown. Uses a separate provider rotation for text extraction.",
-    "tools.engine_status": "Reports configuration, access per capability, local usage and quotas. A missing key is not always a problem: some capabilities work keyless. Stored errors are historical; this is not a live health check.",
-    "tools.open_dashboard": "Opens this dashboard in a browser on the machine running the server. A remote server does not automatically open your local browser.",
+    "tools.search_web": "Searches the web and returns titles, URLs and snippets. Automatically rotates between engines and falls back to another provider when a request fails. Use it while no URL is known; fetch_url reads a known address.",
+    "tools.fetch_url": "Fetches a specific webpage and returns its content as Markdown. Uses a separate provider rotation for text extraction. Use it for a known URL; finding pages is search_web's job.",
+    "tools.get_engine_status": "Reports configuration, rotation order, access per capability, local usage and quotas. A missing key is not always a problem: some capabilities work keyless. Stored errors are historical; this is not a live health check.",
+    "tools.update_engine_config": "Enables or disables engines, sets the search and fetch rotation order and caps calls per engine (monthly and daily limits). Writes the local configuration file and applies to later searches without a restart; API keys and credentials stay in the dashboard.",
+    "tools.open_dashboard": "Opens this dashboard in a browser on the machine running the server: API keys, credentials, network settings, plus usage, quotas and history. A remote server does not automatically open your local browser.",
     "tools.parameters": "Parameters",
     "tools.none": "No parameters.",
     "tools.example": "Example call",
@@ -207,6 +214,11 @@ window.I18N = {
     "tools.param.startDate": "Optional · Start date YYYY-MM-DD. Alone or with endDate; must be on or before endDate.",
     "tools.param.endDate": "Optional · End date YYYY-MM-DD. Date semantics depend on the provider; incompatible providers are skipped.",
     "tools.param.url": "Required · Full webpage URL.",
+    "tools.param.enabled": "Optional · Per engine ID: true enables, false disables. Enabling fails while a required key or extra configuration is missing.",
+    "tools.param.searchOrder": "Optional · Complete search rotation: every search-capable engine ID exactly once, first entry first. Fetch-only engines are not part of this order.",
+    "tools.param.fetchOrder": "Optional · Complete fetch rotation: every fetch-capable engine ID exactly once, first entry first.",
+    "tools.param.monthlyLimits": "Optional · Per engine ID: cap for locally counted calls per month. null removes the override and restores the provider default.",
+    "tools.param.dailyLimits": "Optional · Per engine ID: cap for locally counted calls per day. null removes the override.",
 
     "settings.title": "Rotation settings",
     "settings.strict": "Strict free mode",