Tavily MCP-Schlüsselpool

Chinesisch (vereinfacht) README: README.zh.md

Warum? Wenn Sie mehrere Tavily-API-Schlüssel haben (mehrere Konten, ein Team-Budget, gekaufte Credits in großen Mengen, …) und sie über einen KI-Coding-Agenten verwenden, werden Sie schnell auf drei Probleme stoßen:

1. Einzelschlüssel-Engpässe — das Ratenlimit eines Schlüssels bremst alles aus.

2. Stille Fehler — ein Schlüssel läuft ab, erreicht ein Kontingent oder wird widerrufen, und Ihre Suchen funktionieren einfach nicht mehr.

3. Keine Transparenz — Sie wissen nicht, welche Schlüssel verwendet werden oder wie viel.

Dieses Projekt löst alle drei Probleme: ein winziger MCP-Server, der Round-Robin über Ihren Schlüsselpool durchführt, tote Schlüssel automatisch deaktiviert und Nutzungsstatistiken preisgibt — so dass Sie ihn in Claude Desktop, Cursor, DeepSeek Harness oder jeden MCP-Client einbinden können, ohne Ihren Workflow zu ändern.

Ein Tavily-MCP-Server mit einem SQLite-basierten Round-Robin-API-Schlüsselpool, integrierter Nutzungsverfolgung, automatischem Health-basiertem Failover und einem eigenständigen FastAPI-Dashboard. Standard-MCP-Protokoll — funktioniert mit jedem MCP-kompatiblen Client (Claude Desktop, Cursor, DeepSeek Harness, usw.).

Highlights

• 🔄 Round-Robin-Schlüsselrotation über N Tavily-API-Schlüssel (SQLite, null Startkosten).

• 📊 Nutzungsverfolgung: Anzahl der Anfragen pro Schlüssel, Fehleranzahl, verbrauchte Credits.

• 🩺 Automatischer Health-Check: Alle Schlüssel mit einer leichten Suche testen, tote automatisch deaktivieren; Ergebnisse über tavily_pool_status anzeigen.

• 🛠️ Sechs Kern-MCP-Tools (Tavily-Parität: search, extract, crawl, map, research) plus tavily_pool_status und tavily_research_status (asynchroner Abruf).

• 🌐 Eigenständiges FastAPI-Dashboard (CORS-aktiviert, nur Loopback) mit Statistiken, schlüsselspezifischer Ansicht, Hinzufügen/Entfernen/Deaktivieren/Aktivieren und Health-Check mit einem Klick.

• 🔌 Einsetzbar in jeden MCP-Client über stdio; die DSH-Integration ist ein einseitiger Patch + ein Beispiel-Client-Plugin (siehe examples/dsh-integration/).

Unterschiede zum offiziellen tavily-mcp

Architektur

+--------------------------------------------------+
|  MCP clients (Claude Desktop / Cursor / DSH …)   |
+--------+---------------------+-------------------+
         | stdio (JSON-RPC)     | HTTPS / CORS
+--------▼--------------+     +▼-----------------------+
|  mcp_server.py (FastMCP)|     |  dashboard.py (FastAPI) |
|  + key_pool.py (SQLite) |     |  uvicorn 127.0.0.1:8000 |
+----------------------+--+     +-----+----------------+
                       |              |
                       v              v
                tavily_keys.db  <— SQLite-backed pool
                       |
                       v
              Tavily REST API (round-robin over N keys)

Schnellstart

1. Abhängigkeiten installieren

python -m venv .venv
. .venv/bin/activate        # Linux/macOS
# or:  .venv\Scripts\Activate.ps1   (Windows PowerShell)
pip install -r requirements.txt

Die festgelegte mcp-Einschränkung in requirements.txt ist <2.0: siehe DSH-Integration / Fallstrick #1 — der FastMCP-Importpfad wurde in mcp 2.x verschoben.

2. API-Schlüssel hinzufügen

Erstellen Sie eine keys.txt mit einem Schlüssel pro Zeile:

tvly-xxxxxxxxxxxxxxxx
tvly-yyyyyyyyyyyyyyyy

Dann importieren:

python cli.py add --from-file keys.txt

Oder starten Sie das Dashboard (nächster Schritt) und fügen Sie sie in das Formular API-Schlüssel hinzufügen ein. Schlüssel werden im Klartext in tavily_keys.db (SQLite) gespeichert, damit der Pool mit null Startkosten Round-Robin durchführen kann — siehe Sicherheit.

3. MCP-Server starten

Für einen direkten stdio-MCP-Server (jeder MCP-Client):

./run_mcp.sh                                # Linux/macOS
# or:  .venv\Scripts\python.exe mcp_server.py   (Windows)

Der Server kündigt sieben Tools an; die öffentlichen Namen in MCP-bewussten Clients sehen aus wie tavily_search, tavily_extract, usw.

4. Dashboard starten (optional, unabhängiger Prozess)

./run_dashboard.sh                          # default port 8000
# or:  .venv\Scripts\python.exe -m uvicorn dashboard:app --host 127.0.0.1 --port 8000

Öffnen Sie http://127.0.0.1:8000 in Ihrem Browser. Das Dashboard ist CORS-aktiviert für Loopback-Ursprünge, so dass ein eingebettetes Einstellungsfeld in einer anderen Benutzeroberfläche es aufrufen kann.

MCP-Tools

CLI

python cli.py list                 # all keys
python cli.py list --active        # only active
python cli.py stats                # JSON dump of pool state
python cli.py health               # probe every active key; deactivate dead ones
python cli.py recent -n 20         # recent request log
python cli.py add tvly-... [...]   # add one or more keys
python cli.py add --from-file keys.txt
python cli.py activate tvly-xx****yy     # masked id, see `list`
python cli.py deactivate tvly-xx****yy --reason "manually disabled"
python cli.py remove tvly-xx****yy

Verwenden mit Claude Desktop / Cursor / anderen generischen MCP-Clients

Für jeden Client, der einen MCP-stdio-Befehl akzeptiert:

{
  "mcpServers": {
    "tavily": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/this/repo"
    }
  }
}

Oder streamable HTTP, wenn Ihr Client dies unterstützt und Sie den Server selbst in einen HTTP-Transport eingebunden haben — außerhalb des Rahmens dieses Repos.

DeepSeek Harness (DSH)-Integration

Getestet mit @deepseek-ai/dsh 0.1.0-rc.6 (Web-Profil).

Das DeepSeek Harness (dsh) verwendet das Cordis-Plugin-Framework und wird mit einer offiziellen MCP-Client-Bridge (@deepseek-ai/dsh-mcp-client) ausgeliefert. Die Integration ist daher sehr dünn: eine Benutzer-Patch-Schicht + ein Beispiel-Browser-Plugin (dieses Repos examples/dsh-integration/client-tavily-panel/).

A. Tavily-MCP-Server in DSH registrieren

Bearbeiten Sie ~/.dsh/profiles/web/cordis.patch.yml (die Benutzer-Patch-Schicht, die nach jedem Bundle angewendet wird). Fügen Sie einen neuen insert-Block hinzu — die folgenden Werte gehen davon aus, dass das Repo unter C:\Users\ASUS\.dsh\tavily-pool\ liegt:

- insert:
    - id: mcp-tavily
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: tavily
        command: 'C:\Users\ASUS\.dsh\tavily-pool\.venv\Scripts\python.exe'
        args: ['mcp_server.py']
        cwd: 'C:\Users\ASUS\.dsh\tavily-pool'
        # research can take >2 minutes on big topics; the default 30s is too tight
        toolCallTimeoutMs: 600000
        failOnStartupError: false

Überprüfen Sie die Zusammenführung mit dsh --profile web --dump-config, bevor Sie neu starten. Der MCP-Server erscheint dann als mcp__tavily__tavily_search (usw.) in der Tool-Liste des Agenten.

B. (Optional) Dashboard in DSH-Einstellungen einbetten

Kopieren Sie examples/dsh-integration/client-tavily-panel/ an einen beliebigen Ort auf der Festplatte. Das Beispiel verwendet den settings.section-Slot von @deepseek-ai/dsh-client-ui-slots — das Plugin registriert ein Tavily 号池-Panel, das das Dashboard über fetch aufruft. Zur Installation:

1. Platzieren Sie das Paket (z. B. ~/.dsh/plugins/client-tavily-panel/).

2. Verknüpfen Sie es mit dem node_modules des Profils, damit require.resolve es finden kann (DSH lädt Client-Plugins über seine Paketnamen-Auflösungskette):

   New-Item -ItemType Junction `
     -Path "$env:DSH_HOME\profiles\node_modules\dsh-client-tavily-panel" `
     -Target "C:\Users\ASUS\.dsh\plugins\client-tavily-panel"

   Junction (nicht Symlink) vermeidet die Notwendigkeit von Administratorrechten. Wenn Sie dies überspringen und das Paket lokal mit pnpm add hinzufügen, ist das auch in Ordnung — aber Achtung: pnpm kann bei anderen, nicht verwandten file: / GitHub-Quell-Abhängigkeiten in Ihrem Profil hängen bleiben.

3. Fügen Sie einen Roster-Eintrag in cordis.patch.yml hinzu:

   - insert:
       - id: client-tavily-panel
         name: 'dsh-client-tavily-panel'

4. Starten Sie dsh web neu. (Siehe Fallstrick #6 — HMR ist für das Web-Profil absichtlich deaktiviert; Patch-Änderungen werden nur bei einem vollständigen Neustart geladen.)

Nach dem Neustart öffnen Sie ⚙️ Einstellungen — der Eintrag Tavily 号池 erscheint in der linken Navigation.

Fallstricke bei der DeepSeek-Integration

Dies sind echte Fehler, auf die ich (der ursprüngliche Integrator) gestoßen bin. Lesen Sie diese bevor Sie beginnen, in der untenstehenden Reihenfolge — jeder hat Zeit gekostet.

Fallstrick #1: mcp-SDK-Versionierung

mcp_server.py macht from mcp.server.fastmcp import FastMCP. Dieses Modul wurde in mcp 2.0 entfernt (die FastMCP-Implementierung wurde in ein separates fastmcp-Paket mit einer anderen API verschoben). Wenn Sie pip install mcp ausführen und die neueste Version erhalten, startet der MCP-Server nicht:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Festlegen:

# requirements.txt
mcp>=1.0.0,<2.0.0

Getestet mit mcp 1.29.0.

Fallstrick #2: tavily_research ist asynchron und an den erstellenden Schlüssel gebunden

Drei Unterfehler in einem:

• Das tavily-python-SDK hat das erste Positionsargument von research() von query in input umbenannt. Der Aufruf client.research(query=…) schlägt fehl mit missing 1 required positional argument: 'input'.

• Das SDK erzwingt zur Laufzeit model ∈ {"mini", "pro", "auto"}, aber die Tavily-REST-API selbst akzeptiert model=standard|pro. Die Übergabe von standard führt zu model must be one of: mini, pro or auto.

• research() gibt sofort einen Umschlag mit status: pending zurück — das eigentliche Ergebnis kommt 30–120+ Sekunden später. Sie müssen get_research(request_id) abfragen, bis status == "completed". Andernfalls gibt das Tool immer "pending" zurück und Ihr Modell denkt, der Aufruf sei fehlgeschlagen.

• Die Forschungsaufgabe ist an den API-Schlüssel gebunden, der sie erstellt hat. Andere Schlüssel im Pool können das Ergebnis nicht abrufen (gibt 404 zurück). Fragen Sie immer mit derselben TavilyClient-Instanz ab — rufen Sie nicht bei jeder Abfrageiteration erneut pool.next_key() auf, sonst treffen Sie ständig die falschen Schlüssel.

Das tavily_research dieses Repos kapselt bereits den gesamten Lebenszyklus: Abfragen für bis zu ~570s, dann einen Umschlag mit status: timeout und der request_id zurückgeben, damit der Aufrufer später abrufen kann. Ein zweites Tool, tavily_research_status(request_id), durchläuft die Liste der aktiven Schlüssel, um den richtigen Schlüssel für einen Ad-hoc-Abruf zu finden — notwendig, weil der Tool-Aufruf in einem anderen Prozess abgelaufen sein könnte.

Fallstrick #3: dashboard.py UTF-8-Lesefehler unter Windows

dashboard.py macht:

DASHBOARD_HTML = TPL.read_text()

Path.read_text() verwendet standardmäßig locale.getpreferredencoding(), was unter Windows (zh-CN) GBK ist. Die gebündelte templates/dashboard.html ist UTF-8 und enthält CJK-Zeichen, daher löst das Dashboard aus:

UnicodeDecodeError: 'gbk' codec can't decode byte 0xb6 in position 4308

Behebung:

DASHBOARD_HTML = TPL.read_text(encoding="utf-8")

Fallstrick #4: Plattformübergreifende Pfade in run_*.sh

run_mcp.sh und run_dashboard.sh hardcodieren .venv/bin/python3 (Linux-Konventionen) und wurden nie unter Windows getestet. Die Skriptautoren haben auch eine systemd-Einheit mit /home/user/code/Tavily ausgeliefert — eindeutig nur für Linux.

Sie benötigen diese Skripte unter Windows überhaupt nicht; rufen Sie einfach direkt .venv\Scripts\python.exe auf (siehe das YAML oben). Sie werden im Repo für den ursprünglichen Linux-Anwendungsfall aufbewahrt.

Fallstrick #5: DSH-Patch-Konfiguration wird nur beim Start geladen

cordis.patch.yml wird gelesen, wenn das web-Profil startet. Änderungen werden nicht hot-reloaded — die hmr-Zeile im Web-App-Bundle-Patch ist absichtlich deaktiviert:

- id: hmr
  disabled: true
# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.

Nach jeder Bearbeitung von cordis.patch.yml starten Sie dsh web neu (siehe Fallstrick #6, wie Sie dies sicher tun können).

Verwenden Sie dsh --profile web --dump-config, um zu überprüfen, ob Ihr Patch korrekt zusammengeführt wird, ohne die GUI tatsächlich zu starten. Es ist viel schneller als Starten, GUI prüfen, Töten, Reparieren, Wiederholen.

Fallstrick #6: Wie Sie dsh web neu starten, ohne sich selbst zu töten

dsh web ist der Host-Prozess, der diese Konversation ausführt, einschließlich Ihres Tool-Prozesses. Wenn Sie naiv ausführen:

Stop-Process -Id <dsh-web-pid> -Force
Start-Process dsh.cmd web

von einer pwsh, die von demselben dsh web gestartet wurde, töten Sie sich selbst mitten im Befehl, bevor die neue Instanz jemals startet. Beim ersten Versuch brach die PowerShell-Sitzung mit exit code 4294967295 ab und nichts passierte.

Die Lösung: Übergeben Sie den Neustart an die Windows-Taskplanung, die das Skript unter svchost ausführt (nicht unter dsh web):

$script = "$env:TEMP\dsh_restart.ps1"
@"
Start-Sleep -Seconds 8
Stop-Process -Id <dsh-web-pid> -Force
Get-CimInstance Win32_Process |
  Where-Object { `$_.CommandLine -match 'dsh web' } |
  ForEach-Object { Stop-Process -Id `$_.ProcessId -Force }
Start-Sleep -Seconds 3
Start-Process 'C:\…\dsh.cmd' web -WorkingDirectory 'H:\…' -WindowStyle Hidden
"@ | Out-File $script -Encoding utf8

schtasks /create /tn dsh-restart /tr "powershell -NoProfile -File $script" /sc once /st 23:59 /f
schtasks /run /tn dsh-restart
schtasks /delete /tn dsh-restart /f

Dann haben Sie ~8 Sekunden, um Ihre endgültige Antwort zu geben, bevor die alte Instanz stirbt. Sagen Sie dem Benutzer, er solle http://127.0.0.1:3080 nach 20–30 Sekunden aktualisieren.

Fallstrick #7: Migrieren des Tool-Verzeichnisses, während der MCP-Server läuft

DSH's mcp-client stellt bei Verbindungsverlust die Verbindung mit exponentiellem Backoff wieder her (initialDelayMs 500, maxAttempts 10). Das Beenden des Python-Kindprozesses löst eine erneute Verbindung aus – die sofort ein neues Kind erzeugt. Wenn Sie dann versuchen, das Verzeichnis mit Move-Item zu verschieben, hat die neue .venv\Scripts\python.exe die Datei gesperrt und robocopy schlägt mit [Result: 32] / „wird von einem anderen Prozess verwendet“ fehl.

Zwei praktikable Strategien:

• Zuerst kopieren, dann Quelle löschen. Copy-Item liest gesperrte Dateien über Windows-Dateifreigabe; es benötigt keinen exklusiven Zugriff. Nach erfolgreichem Kopieren beenden Sie den alten MCP-Server und entfernen die Quelle. .venv ist vollständig verschiebbar, solange pyvenv.cfg's home =-Zeile noch auf dieselbe Python-Basisinstallation verweist.

• Schleife: Beenden + robocopy /MOVE bis es innerhalb des Backoff-Fensters gelingt. Hässlich, aber funktioniert.

Die ursprüngliche Migration verwendete:

Copy-Item -Path D:\Downloads\Tavily -Destination C:\Users\ASUS\.dsh\tavily-pool -Recurse -Force
# verify copy
Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'python.exe' -and $_.CommandLine -match 'mcp_server' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
# loop until deletion succeeds
for ($i=0; $i -lt 8; $i++) {
  Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'mcp_server' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
  Start-Sleep -Milliseconds 200
  Remove-Item D:\Downloads\Tavily -Recurse -Force -ErrorAction SilentlyContinue
  if (-not (Test-Path D:\Downloads\Tavily)) { break }
  Start-Sleep -Seconds 2
}

Fallstrick Nr. 8: pnpm add kann aufgrund unabhängiger Abhängigkeiten hängen bleiben

Wenn Sie dsh plugin --profile web add <dir> ausführen, um ein lokales Plugin zu installieren, löst pnpm den gesamten Profil-Workspace auf – einschließlich aller GitHub- oder HTTP-Quell-Bundles, die Ihre package.json auflistet. Wenn Ihr Profil bereits etwas wie dsh-files: https://codeload.github.com/...tar.gz/... enthält und dieser Download hängen bleibt (Firewall, DNS, kalter Cache, Registry-Kontingent), wird Ihr lokales Plugin nie installiert und pnpm hängt für das gesamte Timeout.

Workaround: Überspringen Sie pnpm und erstellen Sie die Auflösung selbst:

New-Item -ItemType Junction `
  -Path "$env:DSH_HOME\profiles\node_modules\dsh-client-tavily-panel" `
  -Target "<absolute path to your plugin package>"

Junctions (keine Symlinks) funktionieren ohne Administratorrechte und verhalten sich für require.resolve identisch. Die Patch-Ebene referenziert dann das Paket über sein name-Feld, genau als ob pnpm es installiert hätte.

Fallstrick Nr. 9: Format des Einstellungsbereichs-Client-Plugins

Wenn Sie Ihr eigenes DSH-Client-Plugin (Browserseite) schreiben, ist das Laufzeitformat nicht ESM, nicht Cordis-aus-Quelle. Das dsh-client-modules-Plugin hostet einen kleinen In-Memory-Modul-Lader und ruft jedes Client-Bundle von /plugins/<id>/client.js ab. Das Bundle muss aufrufen:

window.__ModuleLoader__.load({
  id: "your-package-name",   // matches package.json "name"
  factory: (require) => {
    var module = { exports: {} };
    var exports = module.exports;
    var react = require("react");           // available
    var jsx = require("react/jsx-runtime"); // available
    // ... define components ...
    function apply(ctx) {
      ctx.slots.inject("settings.section", () => ctx.slots.register({
        name: "settings.section",
        id: "your-id",
        order: 100,
        label: "Your Label"
      }, YourComponent));
    }
    exports.apply = apply;
    exports.inject = ["slots"];             // services you depend on
    return module.exports;
  }
});

Und Ihre package.json muss enthalten:

{
  "main": "lib/index.js",
  "exports": { "./client": { "default": "./lib/client.js" } },
  "dsh": { "client": { "inject": ["@deepseek-ai/dsh-client-ui-slots"], "platform": "web" } }
}

lib/index.js ist der Host-Eintrag – er läuft serverseitig; er kann eine No-Op sein (function apply() {}; export { apply };).

Sicherheit

• Klartextschlüssel im Ruhezustand. tavily_keys.db speichert Ihre Tavily-API-Schlüssel im Klartext, da der SQLite-gestützte Pool bei jeder Anfrage abgefragt wird. Schützen Sie die Datei mit Dateisystemberechtigungen (Linux: chmod 600). Übergeben Sie niemals tavily_keys.db an die Versionskontrolle (siehe .gitignore).

• Standardmäßig nur Loopback-Dashboard. dashboard.py bindet an 127.0.0.1:8000. Wenn Sie es in einem LAN freigeben, fügen Sie sofort eine Authentifizierung hinzu.

• CORS ist absichtlich weit geöffnet – das Dashboard soll von eingebetteten UIs auf demselben Host aufgerufen werden. Dies ist aufgrund der Loopback-Bindung sicher, aber wenn Sie die Bindungsadresse ändern, schränken Sie CORSMiddleware.allow_origins entsprechend ein.

• Rotieren eines durchgesickerten Schlüssels: python cli.py remove tvly-xxxxxxxx****yyyy, widerrufen Sie ihn im Tavily-Dashboard, wiederholen Sie für jede Zeile im Pool.

Fehlerbehebung

Danksagungen

Der Pool-Management-Code (key_pool.py, dashboard.py, das FastMCP mcp_server.py-Grundgerüst, cli.py) wurde ursprünglich von einem nicht genannten Autor geschrieben und öffentlich geteilt. Dieses Repository fügt hinzu:

• mcp 1.x-Kompatibilität (query→input, model-Mapping, Research-Polling).

• Ein neues Tool tavily_research_status für asynchrones Abrufen.

• Windows-Plattformübergreifende Korrekturen (UTF-8-Lesen in dashboard.py).

• Ein einsatzbereites Einstellungsbereichs-Client-Plugin für DSH und das obige Integrations-Fallstrick-Protokoll.

Wenn Sie den ursprünglichen Autor kennen, öffnen Sie bitte ein Issue, damit ich eine Danksagung hinzufügen kann.

Lizenz

MIT. Siehe LICENSE.