askDB MCP

Ein MCP-Server, der natürlichsprachliche Datenfragen in den Schema-Kontext verwandelt, den ein LLM zum Schreiben von SQL benötigt. Er verbindet sich nicht mit deiner Datenbank und generiert selbst kein SQL – er ruft die passenden Tabellendefinitionen aus deinem Pinecone-Index ab und übergibt sie an das jeweilige Modell, das gerade fragt (Claude Code, Claude Desktop, ChatGPT, Cursor).

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

Werkzeuge

Jede Antwort enthält Anweisungen, die das Modell anweisen, nur die zurückgegebenen Tabellen und Spalten zu verwenden, damit es keine Namen erfindet.

Einrichtung

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

Du gibst das an jemand anderen weiter? Schick der Person SETUP.md – es deckt sowohl den lokalen Betrieb als auch die Verbindung zu einer gehosteten Instanz ab.

npm run doctor ist der wichtige Schritt. Er gibt die Index-Konfiguration, die Metadatenfelder, die deine Datensätze tatsächlich verwenden, und eine Beispielsuche aus – so kannst du bestätigen, dass der Server die richtigen Felder liest, bevor du ihn in einen Client einbindest.

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

Client verbinden

Claude Code

Die CLI, die Desktop-App und die IDE-Erweiterungen teilen sich eine Konfiguration, daher registriert dies den Server für alle drei:

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

Überprüfe es mit claude mcp list (askdb: ... ✓ Connected) und starte dann die Desktop-App oder das IDE-Fenster neu – MCP-Server werden beim Start geladen.

Der User-Scope ist bewusst gewählt: Es geht darum, Datenbankfragen zu stellen, während du in deinen anderen Repos arbeitest. Eine projektbezogene .mcp.json würde nur aufgelöst, wenn Claude Code im Root dieses Repos gestartet wird, und die Definition von askdb in beiden Scopes führt dazu, dass Claude Code vor dem Duplikat warnt.

Claude Desktop / Cursor

Füge zu claude_desktop_config.json (oder den MCP-Einstellungen von Cursor) hinzu:

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

Die Anmeldedaten stammen aus der .env neben dem Server, daher landen keine Schlüssel in der Client-Konfiguration.

ChatGPT

ChatGPT-Connectors können keinen lokalen Prozess starten – sie sprechen nur Remote-MCP über HTTP. Führe den HTTP-Transport aus und mache ihn zugänglich:

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

Richte den Connector dann auf https://<your-host>/mcp mit einem Authorization: Bearer <token>-Header aus. Für einen schnellen Test tunnelst du ihn (cloudflared tunnel --url http://localhost:3000); für etwas Dauerhaftes hostest du ihn ordentlich – DEPLOY.md behandelt Netlify vollständig. GET /health ist für Load-Balancer-Checks nicht authentifiziert; /mcp erfordert das Bearer-Token, sobald MCP_AUTH_TOKEN gesetzt ist.

Der HTTP-Transport ist zustandslos – eine Server-Instanz pro Anfrage – er skaliert also hinter einem Load-Balancer ohne Sticky Sessions.

Hosting

Bereitgestellt als zwei Netlify Functions – netlify.toml enthält die Build-Einstellungen, sodass das Importieren des Repos und das Setzen von PINECONE_API_KEY + MCP_AUTH_TOKEN die ganze Arbeit ist. Schritt für Schritt: DEPLOY.md.

Das funktioniert ohne ein Umschreiben des Transports, weil WebStandardStreamableHTTPServerTransport aus dem MCP SDK eine Request entgegennimmt und eine Response zurückgibt – die Signatur der Netlify Functions v2 – sodass netlify/functions/mcp.mjs src/mcp.js unverändert importiert. Dieselbe Datei lässt sich auf Cloudflare Workers, Deno oder Bun ablegen; src/http.js deckt Container und VMs ab.

GET /health benötigt kein Token und meldet, ob die erforderlichen Umgebungsvariablen angekommen sind (nur Vorhandensein, niemals Werte) – der serverlose Ersatz für das Lesen eines Startprotokolls. /mcp fällt sicher zu: Ohne gesetztes MCP_AUTH_TOKEN gibt es 503 zurück, anstatt dein Schema ins Internet zu liefern.

Sobald es läuft, müssen Teamkollegen nichts installieren – nur die URL und ein Token (SETUP.md, Route A).

Konfiguration

Alles optional außer dem API-Schlüssel. Siehe .env.example.

Der Server erkennt automatisch, welche Metadatenfelder deine Datensätze verwenden und ob der Index integriertes Embedding hat, sodass die Standardwerte in der Regel unverändert funktionieren.

Zwei Dinge, die man wissen sollte

Das Embedding-Modell muss übereinstimmen. Wenn EMBED_MODEL nicht das Modell ist, mit dem das Schema eingespielt wurde, fallen alle Scores auf nahe Null und die Ergebnisse sind Rauschen – die Vektoren sind zueinander praktisch zufällig. npm run doctor zeigt dies als unzusammenhängende Tabellen mit Scores um 0.01 statt 0.8. Dieser Index wurde mit multilingual-e5-large erstellt.

Setze DEFAULT_DATABASE, wenn dein Index mehrere Umgebungen enthält. Wenn dasselbe Schema sowohl als *_live als auch als *_test existiert, liefert eine nicht eingegrenzte Suche beide Kopien jeder Tabelle, was die Hälfte der top_k-Slots für Duplikate verbraucht und das Modell Umgebungen in einer Abfrage mischen lässt.

Aufbau