search-mcp-rotator 1.0.0 → 1.0.2

package/README.md

@@ -1,18 +1,66 @@
 # Search MCP Rotator
 
-![Search MCP Rotator](./poster.png)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sahilchouksey/search-mcp-rotator/main/poster.png" alt="Search MCP Rotator" width="100%" />
+</p>
 
-A local MCP (Model Context Protocol) proxy server that provides transparent API key rotation for search providers. When one key is exhausted, rate-limited, or returns any server-side error, the proxy automatically rotates to the next available key and retries the request — transparently, without the MCP client knowing a rotation occurred.
+A local MCP proxy that transparently rotates API keys across search providers. When a key is rate-limited, exhausted, or errors, it automatically switches to the next key and retries — invisible to the MCP client.
 
-## Features
+---
+
+## Quick Start
+
+### Step 1 — Add your API keys
+
+Run the interactive setup CLI to select providers and enter your keys:
+
+```bash
+npx search-mcp-rotator --setup
+```
+
+The wizard walks through each provider, lets you paste multiple keys at once (comma-separated), and writes config to `~/.config/search-mcp-rotator/config.json` automatically.
+
+> Press `Ctrl+O` on any provider screen to open its API key dashboard in your browser.
+
+### Step 2 — Add to your MCP client
+
+#### OpenCode — `~/.config/opencode/opencode.json`
+
+```json
+{
+  "mcp": {
+    "exa":        { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=exa"],        "enabled": true },
+    "firecrawl":  { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=firecrawl"],  "enabled": true },
+    "tavily":     { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=tavily"],     "enabled": true },
+    "linkup":     { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=linkup"],     "enabled": true },
+    "brightdata": { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=brightdata"], "enabled": true },
+    "olostep":    { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=olostep"],    "enabled": true },
+    "dappier":    { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=dappier"],    "enabled": true },
+    "parallel":   { "type": "local", "command": ["npx", "-y", "search-mcp-rotator", "--provider=parallel"],   "enabled": true }
+  }
+}
+```
+
+#### Pi agent — `~/.pi/agent/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "exa":        { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=exa"],        "lifecycle": "lazy" },
+    "firecrawl":  { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=firecrawl"],  "lifecycle": "lazy" },
+    "tavily":     { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=tavily"],     "lifecycle": "lazy" },
+    "linkup":     { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=linkup"],     "lifecycle": "lazy" },
+    "brightdata": { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=brightdata"], "lifecycle": "lazy" },
+    "olostep":    { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=olostep"],    "lifecycle": "lazy" },
+    "dappier":    { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=dappier"],    "lifecycle": "lazy" },
+    "parallel":   { "command": "npx", "args": ["-y", "search-mcp-rotator", "--provider=parallel"],   "lifecycle": "lazy" }
+  }
+}
+```
+
+> Only include providers you configured in Step 1. No `--config` flag needed — reads from `~/.config/search-mcp-rotator/config.json` automatically. Restart your client after editing.
 
-- **Transparent Key Rotation**: Automatic failover between API keys
-- **Multi-Provider Support**: Supports 9 search providers with different auth patterns
-- **Flexible Rotation Strategies**: Round-robin, priority, and random selection
-- **Circuit Breaker Pattern**: Prevents cascading failures
-- **Configurable Cooldowns**: Smart recovery timing per provider
-- **Strategy-as-Tool-Argument**: LLMs can choose rotation strategy per request
-- **Comprehensive Error Detection**: Provider-specific exhaustion patterns
+---
 
 ## Supported Providers
 
@@ -21,22 +69,32 @@ A local MCP (Model Context Protocol) proxy server that provides transparent API
 | **Exa** | Bearer header | Neural/semantic web search, code search |
 | **Firecrawl** | Bearer header | Web scraping, deep crawl, structured extraction |
 | **Linkup** | Bearer header | Real-time web search, source-cited answers |
-| **Bright Data** | Bearer header | 40+ scraping tools, Google SERP, Amazon |
+| **Bright Data** | Bearer header | 40+ scraping tools, Google SERP |
 | **Olostep** | Bearer header | Search + extract + AI answers with citations |
 | **Tavily** | Query param | Real-time web search, extract, map, crawl |
 | **Dappier** | Query param | Real-time news, finance, sports, weather |
 | **Parallel** | Custom header | Highest-accuracy general web search |
 
-## Installation
+---
 
-```bash
-npm install
-npm run build
-```
+## Features
+
+- **Transparent Key Rotation** — automatic failover between API keys
+- **Multi-Provider Support** — 8 providers, different auth patterns handled automatically
+- **Flexible Rotation Strategies** — round-robin, priority, random per tool call
+- **Circuit Breaker** — prevents cascading failures
+- **Configurable Cooldowns** — smart recovery timing per provider
+- **Bulk Key Entry** — paste comma-separated keys during setup
 
-## Configuration
+---
 
-Copy `config.example.json` to `config.json` and add your API keys:
+## Manual Configuration
+
+Prefer editing config directly instead of `--setup`? Copy the example and add your keys:
+
+```bash
+cp config.example.json ~/.config/search-mcp-rotator/config.json
+```
 
 ```json
 {
@@ -54,124 +112,66 @@ Copy `config.example.json` to `config.json` and add your API keys:
 }
 ```
 
-### Environment Variable Overrides
-
-Keys can be overridden via environment variables:
+Keys can also be set via environment variables:
 
 ```bash
 export EXA_KEYS="key1,key2,key3"
 export FIRECRAWL_KEYS="key1,key2"
 ```
 
-## Usage
-
-Start a rotator for a specific provider:
-
-```bash
-# Using built binary
-node dist/index.js --provider=exa --config=config.json
-
-# Or using npm script
-npm run dev -- --provider=exa --config=config.json
-```
-
-## OpenCode Integration
-
-Register each rotator as a local MCP server in `~/.config/opencode/opencode.json`:
-
-```json
-{
-  "mcpServers": {
-    "exa-rotator": {
-      "type": "local",
-      "command": "node",
-      "args": [
-        "/path/to/search-mcp-rotator/dist/index.js",
-        "--provider=exa"
-      ],
-      "env": {
-        "MCP_ROTATOR_CONFIG": "/path/to/config.json"
-      },
-      "enabled": true
-    }
-  }
-}
-```
+---
 
 ## Rotation Strategies
 
 Every tool call accepts an optional `strategy` parameter:
 
-- **`round-robin`** (default): Distribute requests evenly across keys
-- **`priority`**: Always use first healthy key, fallback to others
-- **`random`**: Random key selection to avoid patterns
+| Strategy | Behavior |
+|----------|----------|
+| `round-robin` (default) | Distribute requests evenly across keys |
+| `priority` | Always use first healthy key, fallback to others |
+| `random` | Random key selection |
 
-```typescript
-// Example tool call with strategy override
-{
-  "query": "AI news",
-  "strategy": "priority"  // Optional: overrides provider default
-}
-```
+---
 
 ## Architecture
 
 ```
-OpenCode (MCP client)
+MCP Client (OpenCode / Pi / etc.)
         │  stdio transport
         ▼
 ┌─────────────────────────┐
-│   Search MCP Rotator Proxy     │
-│  (local stdio server)   │
+│   Search MCP Rotator    │
+│   (local stdio proxy)   │
 │                         │
-│  ┌─────────────────┐    │
-│  │   KeyPool       │    │
-│  │  [key1, key2,   │    │
-│  │   key3, key4]   │    │
-│  │  activeIdx = 0  │    │
-│  │  degraded: Map  │    │
-│  └─────────────────┘    │
+│  KeyPool [k1, k2, k3]  │
+│  activeIdx = 0          │
+│  degraded: Map          │
 │                         │
-│  On tool call:          │
 │  1. pick active key     │
 │  2. inject into request │
 │  3. forward upstream    │
 │  4. on rate-limit:      │
 │     mark degraded       │
-│     rotate key          │
-│     retry same call     │
+│     rotate key, retry   │
 └─────────────────────────┘
-        │  HTTP (Streamable HTTP transport)
+        │  HTTP (Streamable HTTP)
         ▼
   Remote MCP Provider
-  (Exa / Firecrawl / etc.)
 ```
 
-## Error Detection
-
-The rotator detects exhaustion signals specific to each provider:
-
-- **HTTP Status Codes**: 401, 402, 429, etc.
-- **JSON-RPC Error Codes**: Provider-specific codes
-- **Message Patterns**: "rate limit", "quota", "credits exhausted"
-- **Special Cases**: Provider-specific error formats
+---
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Development with auto-reload
-npm run dev -- --provider=exa
-
-# Type checking
-npm run typecheck
-
-# Build for production
 npm run build
+npm run dev -- --provider=exa   # watch mode
+npm run typecheck
 ```
 
+---
+
 ## License
 
-MIT
+MIT

package/dist/setup.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_CONFIG_DIR: string;
+export declare const DEFAULT_CONFIG_PATH: string;
+export declare function runSetup(outputPath?: string): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,360 @@
+import React, { useState, useCallback } from 'react';
+import { render, Box, Text, useInput, useApp } from 'ink';
+import TextInput from 'ink-text-input';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { exec } from 'child_process';
+// ─── Universal config path ────────────────────────────────────────────────────
+export const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.config', 'search-mcp-rotator');
+export const DEFAULT_CONFIG_PATH = path.join(DEFAULT_CONFIG_DIR, 'config.json');
+// ─── Providers ────────────────────────────────────────────────────────────────
+const PROVIDERS = [
+    { id: 'exa', name: 'Exa', description: 'Neural/semantic web search, code search', url: 'https://mcp.exa.ai/mcp', authPattern: 'bearer', cooldownMs: 60000, keyHint: 'exa.ai → Dashboard → API Keys', keyUrl: 'https://exa.ai' },
+    { id: 'firecrawl', name: 'Firecrawl', description: 'Web scraping, deep crawl, structured extraction', url: 'https://mcp.firecrawl.dev/mcp', authPattern: 'bearer', cooldownMs: 60000, keyHint: 'firecrawl.dev → Dashboard (prefix: fc-)', keyUrl: 'https://firecrawl.dev' },
+    { id: 'tavily', name: 'Tavily', description: 'Real-time web search, extract, map, crawl', url: 'https://mcp.tavily.com/mcp/', authPattern: 'queryparam', cooldownMs: 60000, keyHint: 'app.tavily.com → API Keys (prefix: tvly-)', keyUrl: 'https://tavily.com', queryParamName: 'tavilyApiKey' },
+    { id: 'linkup', name: 'Linkup', description: 'Real-time web search, source-cited answers', url: 'https://mcp.linkup.so/mcp', authPattern: 'bearer', cooldownMs: 60000, keyHint: 'app.linkup.so → API Keys', keyUrl: 'https://linkup.so' },
+    { id: 'brightdata', name: 'Bright Data', description: 'Google SERP + 40 scraping tools (5k free/mo)', url: 'https://mcp.brightdata.com/mcp', authPattern: 'bearer', cooldownMs: 60000, keyHint: 'brightdata.com → Settings → API Token', keyUrl: 'https://brightdata.com' },
+    { id: 'olostep', name: 'Olostep', description: 'Search + extract + AI answers with citations', url: 'https://mcp.olostep.com/mcp', authPattern: 'bearer', cooldownMs: 300000, keyHint: 'olostep.com → Dashboard → API Keys', keyUrl: 'https://olostep.com' },
+    { id: 'dappier', name: 'Dappier', description: 'Real-time news, finance, sports, weather', url: 'https://mcp.dappier.com/mcp', authPattern: 'queryparam', cooldownMs: 300000, keyHint: 'dappier.com → Dashboard → API Keys', keyUrl: 'https://dappier.com', queryParamName: 'apiKey' },
+    { id: 'parallel', name: 'Parallel', description: 'Highest-accuracy general web search', url: 'https://search.parallel.ai/mcp', authPattern: 'customheader', cooldownMs: 60000, keyHint: 'platform.parallel.ai → API Keys', keyUrl: 'https://parallel.ai', headerName: 'x-api-key' },
+];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function openUrl(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${cmd} "${url}"`, () => { });
+}
+function buildEntry(p, keys) {
+    const e = { enabled: true, url: p.url, authPattern: p.authPattern, keys: [...keys], strategy: 'round-robin', cooldownMs: p.cooldownMs };
+    if (p.authPattern === 'queryparam')
+        e.queryParamName = p.queryParamName;
+    if (p.authPattern === 'customheader')
+        e.headerName = p.headerName;
+    return e;
+}
+function syncConfig(configPath, configs) {
+    if (!Object.keys(configs).length)
+        return;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify({ logLevel: 'info', providers: configs }, null, 2));
+}
+// ─── Divider ─────────────────────────────────────────────────────────────────
+const Divider = () => (React.createElement(Box, { marginY: 0 },
+    React.createElement(Text, { dimColor: true }, '─'.repeat(60))));
+// ─── Screen: Provider Checklist ───────────────────────────────────────────────
+const ProviderSelect = ({ onConfirm }) => {
+    const [cursor, setCursor] = useState(0);
+    const [selected, setSelected] = useState(new Set());
+    useInput((input, key) => {
+        if (key.upArrow)
+            setCursor(c => Math.max(0, c - 1));
+        if (key.downArrow)
+            setCursor(c => Math.min(PROVIDERS.length - 1, c + 1));
+        if (input === ' ') {
+            setSelected(s => {
+                const next = new Set(s);
+                const id = PROVIDERS[cursor].id;
+                next.has(id) ? next.delete(id) : next.add(id);
+                return next;
+            });
+        }
+        if (input === 'a')
+            setSelected(new Set(PROVIDERS.map(p => p.id)));
+        if (input === 'i')
+            setSelected(s => new Set(PROVIDERS.map(p => p.id).filter(id => !s.has(id))));
+        if (key.return) {
+            if (selected.size > 0)
+                onConfirm(PROVIDERS.map(p => p.id).filter(id => selected.has(id)));
+        }
+    });
+    return (React.createElement(Box, { flexDirection: "column", gap: 0 },
+        React.createElement(Divider, null),
+        React.createElement(Box, { marginBottom: 1 }),
+        PROVIDERS.map((p, i) => (React.createElement(Box, { key: p.id },
+            React.createElement(Text, { color: "cyan" },
+                i === cursor ? '›' : ' ',
+                " "),
+            React.createElement(Text, { color: selected.has(p.id) ? 'green' : 'white', bold: selected.has(p.id) }, selected.has(p.id) ? '[x] ' : '[ ] '),
+            React.createElement(Text, { bold: i === cursor }, p.name.padEnd(14)),
+            React.createElement(Text, { dimColor: true }, p.description)))),
+        React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { dimColor: true }, "\u2191\u2193 navigate  Space select  a all  i invert  Enter confirm"))));
+};
+// ─── Screen: Selected summary ─────────────────────────────────────────────────
+const SelectedSummary = ({ ids }) => (React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Divider, null),
+    React.createElement(Box, { marginBottom: 1 }),
+    React.createElement(Text, { bold: true }, "  Selected providers:"),
+    React.createElement(Box, { marginBottom: 1 }),
+    ids.map(id => {
+        const p = PROVIDERS.find(x => x.id === id);
+        return (React.createElement(Box, { key: id },
+            React.createElement(Text, { color: "green" }, "  [x] "),
+            React.createElement(Text, { bold: true }, p.name.padEnd(14)),
+            React.createElement(Text, { dimColor: true }, p.description)));
+    }),
+    React.createElement(Box, { marginBottom: 1 })));
+// ─── Screen: Key Entry (one provider at a time) ───────────────────────────────
+const KeyEntryView = ({ provider, providerIndex, totalProviders, existingKeys, prevProvider, inputMode, modeLocked, onKeyAdded, onUndo, onBack, onSkip, onModeToggle }) => {
+    const [value, setValue] = useState('');
+    const [urlOpened, setUrlOpened] = useState(false);
+    const [message, setMessage] = useState('');
+    const keyNum = existingKeys.length + 1;
+    const isFirstKey = keyNum === 1;
+    // Allow mode toggle on Key 1 with no keys for THIS provider —
+    // even if mode is globally locked by another provider's entry
+    const canToggle = isFirstKey && existingKeys.length === 0;
+    useInput((input, key) => {
+        // Ctrl+O — open provider site
+        if (key.ctrl && input === 'o') {
+            openUrl(provider.keyUrl);
+            setUrlOpened(true);
+        }
+        // Tab — toggle mode only on Key 1 before lock, clear any \t ink-text-input added
+        if (key.tab && canToggle) {
+            setValue('');
+            onModeToggle();
+        }
+    });
+    const handleSubmit = useCallback((val) => {
+        const trimmed = val.trim();
+        setValue('');
+        setMessage('');
+        // Back navigation
+        if (trimmed === 'b' || trimmed === 'back') {
+            if (isFirstKey && prevProvider) {
+                onBack();
+                return;
+            }
+            if (keyNum > 1) {
+                onUndo();
+                return;
+            }
+        }
+        // Empty — skip or finish
+        if (!trimmed) {
+            if (isFirstKey && existingKeys.length === 0) {
+                onSkip();
+                return;
+            }
+            onSkip();
+            return;
+        }
+        // Always split by comma — if multiple keys pasted at any point, parse them all
+        const newKeys = trimmed.includes(',')
+            ? trimmed.split(',').map(k => k.trim()).filter(Boolean)
+            : [trimmed];
+        if (newKeys.length > 0) {
+            setMessage(`✓ ${newKeys.length > 1 ? newKeys.length + ' keys' : 'Key ' + keyNum} saved`);
+            onKeyAdded(newKeys);
+            // Multiple keys pasted at once — all provided, advance to next provider
+            if (newKeys.length > 1) {
+                onSkip();
+            }
+        }
+    }, [value, isFirstKey, keyNum, existingKeys, inputMode, modeLocked, prevProvider]);
+    // Build hint
+    let hint = '';
+    if (isFirstKey) {
+        const backHint = prevProvider ? `  b = ← ${prevProvider.name}` : '';
+        hint = inputMode === 'bulk' ? `comma-separated${backHint}` : `blank to skip${backHint}`;
+    }
+    else {
+        hint = `blank to finish  •  b = undo key ${keyNum - 1}  •  comma-sep for multiple`;
+    }
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Divider, null),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Box, null,
+            React.createElement(Text, { bold: true, color: "cyan" },
+                "  [ ",
+                provider.name,
+                " ] "),
+            React.createElement(Text, { dimColor: true },
+                "(",
+                providerIndex + 1,
+                "/",
+                totalProviders,
+                ")")),
+        React.createElement(Text, { dimColor: true },
+            "  ",
+            provider.description),
+        React.createElement(Text, { dimColor: true },
+            "  Key: ",
+            provider.keyHint),
+        React.createElement(Text, { dimColor: true },
+            "  ",
+            urlOpened ? `↗  Opened ${provider.keyUrl}` : `Ctrl+O — open ${provider.keyUrl}`),
+        React.createElement(Box, null,
+            React.createElement(Text, { dimColor: true }, "  Mode: "),
+            React.createElement(Text, { bold: true, color: inputMode === 'bulk' ? 'yellow' : 'white' }, inputMode === 'single' ? 'Single' : 'Bulk'),
+            canToggle
+                ? React.createElement(Text, { dimColor: true },
+                    "  Tab \u2192 ",
+                    inputMode === 'single' ? 'Bulk' : 'Single')
+                : modeLocked
+                    ? React.createElement(Text, { dimColor: true }, "  (locked)")
+                    : null),
+        React.createElement(Box, { marginBottom: 1 }),
+        existingKeys.map((k, i) => (React.createElement(Box, { key: i },
+            React.createElement(Text, { color: "green" },
+                "  \u2713 Key ",
+                i + 1,
+                " "),
+            React.createElement(Text, { dimColor: true },
+                k.slice(0, 8),
+                '*'.repeat(8))))),
+        React.createElement(Box, null,
+            React.createElement(Text, null,
+                "  ",
+                isFirstKey && inputMode === 'bulk' ? 'Keys' : `API Key ${keyNum}`,
+                " "),
+            React.createElement(Text, { dimColor: true },
+                "(",
+                hint,
+                "): "),
+            React.createElement(TextInput, { value: value, onChange: setValue, onSubmit: handleSubmit })),
+        message && React.createElement(Box, { marginTop: 0 },
+            React.createElement(Text, { color: "green" },
+                "  ",
+                message))));
+};
+// ─── Screen: Done ─────────────────────────────────────────────────────────────
+const DoneScreen = ({ configs, configPath }) => {
+    const { exit } = useApp();
+    useInput((_, key) => { if (key.return || key.escape)
+        exit(); });
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Divider, null),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Text, { color: "green", bold: true },
+            "  \u2713 Config saved to ",
+            configPath),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Divider, null),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Text, { bold: true }, "  Add to ~/.config/opencode/opencode.json:"),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Text, { dimColor: true },
+            "  ",
+            '  "mcp": {'),
+        Object.keys(configs).map(id => (React.createElement(Box, { key: id, flexDirection: "column" },
+            React.createElement(Text, { dimColor: true },
+                '    ',
+                React.createElement(Text, { color: "white" },
+                    "\"",
+                    id,
+                    "\""),
+                React.createElement(Text, { dimColor: true },
+                    ": ",
+                    '{')),
+            React.createElement(Text, { dimColor: true }, '      "type": "local",'),
+            React.createElement(Text, { dimColor: true },
+                '      "command": ["npx", "-y", "search-mcp-rotator", "--provider=',
+                id,
+                '"]},'),
+            React.createElement(Text, { dimColor: true }, '      "enabled": true'),
+            React.createElement(Text, { dimColor: true }, '    },')))),
+        React.createElement(Text, { dimColor: true }, '  }'),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Divider, null),
+        React.createElement(Box, { marginBottom: 1 }),
+        React.createElement(Text, { color: "green", bold: true }, "  Setup complete! Restart OpenCode to activate."),
+        React.createElement(Text, { dimColor: true }, "  Press Enter to exit.")));
+};
+const App = ({ configPath }) => {
+    const { exit } = useApp();
+    const [screen, setScreen] = useState('select');
+    const [selectedIds, setSelectedIds] = useState([]);
+    const [providerIndex, setProviderIndex] = useState(0);
+    const [providerConfigs, setProviderConfigs] = useState({});
+    const [inputMode, setInputMode] = useState('single');
+    const [modeLocked, setModeLocked] = useState(false);
+    // Ctrl+C global handler
+    useInput((_, key) => {
+        if (key.ctrl && _.toLowerCase() === 'c')
+            exit();
+    });
+    // ── Provider checklist confirmed ────────────────────────────────────────────
+    const handleSelectConfirm = useCallback((ids) => {
+        setSelectedIds(ids);
+        setProviderIndex(0);
+        setScreen('keys');
+    }, []);
+    // ── Key added for current provider ──────────────────────────────────────────
+    const handleKeyAdded = useCallback((newKeys) => {
+        setProviderConfigs(prev => {
+            const id = selectedIds[providerIndex];
+            const provider = PROVIDERS.find(p => p.id === id);
+            const existingKeys = prev[id]?.keys ?? [];
+            const merged = [...existingKeys, ...newKeys];
+            const updated = { ...prev, [id]: buildEntry(provider, merged) };
+            syncConfig(configPath, updated);
+            return updated;
+        });
+        if (!modeLocked)
+            setModeLocked(true);
+    }, [selectedIds, providerIndex, modeLocked, configPath]);
+    // ── Undo last key ──────────────────────────────────────────────────────────
+    const handleUndo = useCallback(() => {
+        setProviderConfigs(prev => {
+            const id = selectedIds[providerIndex];
+            const provider = PROVIDERS.find(p => p.id === id);
+            const keys = [...(prev[id]?.keys ?? [])];
+            keys.pop();
+            const updated = { ...prev };
+            if (keys.length > 0)
+                updated[id] = buildEntry(provider, keys);
+            else
+                delete updated[id];
+            syncConfig(configPath, updated);
+            return updated;
+        });
+    }, [selectedIds, providerIndex, configPath]);
+    // ── Go back to previous provider ────────────────────────────────────────────
+    const handleBack = useCallback(() => {
+        setProviderIndex(i => Math.max(0, i - 1));
+    }, []);
+    // ── Skip / finish current provider → advance ─────────────────────────────
+    const handleSkip = useCallback(() => {
+        if (providerIndex + 1 >= selectedIds.length) {
+            setScreen('done');
+        }
+        else {
+            setProviderIndex(i => i + 1);
+        }
+    }, [providerIndex, selectedIds]);
+    // ── Mode toggle ────────────────────────────────────────────────────────────
+    // canToggle in KeyEntryView is the gatekeeper — no double-check needed here
+    const handleModeToggle = useCallback(() => {
+        setInputMode(m => m === 'single' ? 'bulk' : 'single');
+    }, []);
+    // ─── Render ─────────────────────────────────────────────────────────────────
+    if (screen === 'select') {
+        return (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(Box, { marginBottom: 1 }),
+            React.createElement(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 2 },
+                React.createElement(Text, { bold: true, color: "cyan" }, "Search MCP Rotator \u2014 Setup")),
+            React.createElement(Text, { dimColor: true },
+                "  Config: ",
+                configPath),
+            React.createElement(ProviderSelect, { onConfirm: handleSelectConfirm })));
+    }
+    if (screen === 'keys') {
+        const id = selectedIds[providerIndex];
+        const provider = PROVIDERS.find(p => p.id === id);
+        const prevId = providerIndex > 0 ? selectedIds[providerIndex - 1] : null;
+        const prev = prevId ? PROVIDERS.find(p => p.id === prevId) : null;
+        const existingKeys = providerConfigs[id]?.keys ?? [];
+        return (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(SelectedSummary, { ids: selectedIds }),
+            React.createElement(KeyEntryView, { provider: provider, providerIndex: providerIndex, totalProviders: selectedIds.length, existingKeys: existingKeys, prevProvider: prev, inputMode: inputMode, modeLocked: modeLocked, onKeyAdded: handleKeyAdded, onUndo: handleUndo, onBack: handleBack, onSkip: handleSkip, onModeToggle: handleModeToggle })));
+    }
+    return React.createElement(DoneScreen, { configs: providerConfigs, configPath: configPath });
+};
+// ─── Entry ────────────────────────────────────────────────────────────────────
+export async function runSetup(outputPath) {
+    const configPath = outputPath ?? DEFAULT_CONFIG_PATH;
+    const { waitUntilExit } = render(React.createElement(App, { configPath: configPath }));
+    await waitUntilExit();
+}