BlazeSQL MCP-Server

Dieses Projekt implementiert einen Model Context Protocol (MCP)-Server mit dem @modelcontextprotocol/sdk der als Proxy für die BlazeSQL Natural Language Query API fungiert. Es ermöglicht MCP-kompatiblen Clients (wie Cursor, Claude 3 mit Tool-Nutzung, dem MCP Inspector usw.) die Interaktion mit BlazeSQL in natürlicher Sprache.

Merkmale

• Erstellt mit der modernen McpServer Hilfsklasse aus dem MCP SDK.

• Stellt die BlazeSQL Natural Language Query API als MCP-Tool namens blazesql_query bereit.

• Verwendet zod zur robusten Validierung der Tool-Eingabeparameter.

• Behandelt die API-Schlüsselauthentifizierung sicher über Umgebungsvariablen.

• Kommuniziert mit Clients über den standardmäßigen MCP-Stdio-Transport.

Related MCP server: MySQL MCP Server

Workflow-Diagramm

Dieses Diagramm zeigt die Abfolge der Interaktionen, wenn ein Client das Tool blazesql_query verwendet (Hinweis: Die interne Serverlogik verwendet jetzt McpServer , was die Toolregistrierung im Vergleich zu den im Diagramm gezeigten Low-Level-Handlern vereinfacht):

sequenceDiagram
    participant Client as MCP Client (e.g., Cursor)
    participant Server as BlazeSQL MCP Server (index.ts)
    participant Env as Environment (.env)
    participant BlazeAPI as BlazeSQL API

    Client->>Server: ListTools Request (via stdio)
    Server-->>Client: ListTools Response (tools: [blazesql_query]) (via stdio)

    Client->>Server: CallTool Request (blazesql_query, db_id, nl_request) (via stdio)
    Server->>Env: Read BLAZE_API_KEY
    Env-->>Server: BLAZE_API_KEY
    Server->>BlazeAPI: POST /natural_language_query_api (apiKey, db_id, nl_request)
    BlazeAPI->>BlazeAPI: Process Query (NL->SQL, Execute)
    BlazeAPI-->>Server: HTTPS Response (JSON: agent_response, query, data_result OR error)
    Server->>Server: Format Response (Agent response, SQL, and data into single text block)
    Server-->>Client: CallTool Response (content: [{type: text, text: formattedMarkdown}]) (via stdio)

Voraussetzungen

• Node.js (LTS-Version empfohlen)

• Garn (Klassisch oder Beere)

• Ein BlazeSQL-Konto mit einem API-Schlüssel (für die API ist ein Team Advanced-Abonnement erforderlich).

• Mindestens eine Datenbankverbindung ist in Ihrem BlazeSQL-Konto konfiguriert.

• BlazeSQL Natural Language Query API-Dokumentation: https://help.blazesql.com/en/article/natural-language-query-api-1fgx4au/

Aufstellen

1. Klonen Sie das Repository:

   git clone <repository-url>
   cd blaze-sql-mcp-server

2. Abhängigkeiten installieren:

   yarn install

   Dadurch werden alle erforderlichen Abhängigkeiten installiert, einschließlich @modelcontextprotocol/sdk , dotenv und zod .

3. Umgebungsvariablen konfigurieren:

   • Kopieren Sie die Beispielumgebungsdatei:

     cp .env.sample .env

   • Bearbeiten Sie die .env Datei:

     # .env
     BLAZE_API_KEY=YOUR_BLAZESQL_API_KEY_HERE

     Ersetzen Sie YOUR_BLAZESQL_API_KEY_HERE durch Ihren tatsächlichen API-Schlüssel, den Sie aus Ihren BlazeSQL-Kontoeinstellungen erhalten haben.

Ausführen des Servers

1. Erstellen Sie den Server: Kompilieren Sie den TypeScript-Code in JavaScript:

   yarn build

2. Führen Sie den Server aus: Führen Sie den kompilierten Code aus:

   node build/index.js

   Der Server startet und protokolliert Meldungen in stderr (möglicherweise wird „API-Schlüssel erfolgreich geladen …“ usw. angezeigt). Er wartet nun über die Standard-Ein-/Ausgabe (stdio) auf eine MCP-Clientverbindung.

Verbinden eines MCP-Clients

Dieser Server verwendet den stdio- Transportmechanismus.

Verwenden des MCP Inspector (zum Testen empfohlen)

1. Stellen Sie sicher, dass der Server nicht bereits separat ausgeführt wird.

2. Führen Sie den Inspector aus und weisen Sie ihn an, Ihren Server zu starten:

   npx @modelcontextprotocol/inspector node build/index.js

3. Die Inspector-Benutzeroberfläche wird gestartet und stellt automatisch eine Verbindung zu Ihrem Server her.

4. Navigieren Sie zur Registerkarte „Tools“, um mit dem Tool blazesql_query zu interagieren.

Verwendung integrierter Clients (Cursor, Claude 3 usw.)

1. Starten Sie den Server in einem Terminal:

   node build/index.js

2. Konfigurieren Sie den Client: In den Einstellungen Ihres MCP-Clients müssen Sie eine benutzerdefinierte Serverkonfiguration hinzufügen.

   • Transport: Wählen Sie stdio aus.

   • Befehl: Geben Sie den genauen Befehl zum Ausführen des Servers an. Sie müssen den absoluten Pfad zum Knoten und den absoluten Pfad zur Datei build/index.js angeben.

     • Beispiel (macOS/Linux – Pfade nach Bedarf anpassen): /usr/local/bin/node /Users/your_username/path/to/blaze-sql-mcp-server/build/index.js

     • Sie können den Pfad zum Knoten mithilfe der Angabe which node in Ihrem Terminal finden.

     • Den Pfad zum Projekt finden Sie mit pwd im Projektverzeichnis.

   • Speichern Sie die Konfiguration.

3. Der Client sollte jetzt in der Lage sein, eine Verbindung zu Ihrem lokal laufenden Server herzustellen und dessen Tools aufzulisten/verwenden.

Verwenden des blazesql_query -Tools

Sobald die Verbindung hergestellt ist, kann der Client das Tool blazesql_query aufrufen.

• Toolname: blazesql_query

• Argumente:

  • db_id (Zeichenfolge, erforderlich): Die ID der Zieldatenbankverbindung in Ihrem BlazeSQL-Konto. Sie finden diese ID in der BlazeSQL-Webanwendung beim Verwalten Ihrer Datenbankverbindungen.

  • natural_language_request (Zeichenfolge, erforderlich): Die Abfrage, die Sie ausführen möchten, in einfachem Englisch (z. B. „Zeige mir die Gesamtzahl der Benutzer“). (Die Eingabe wird mit zod validiert.)

• Beispielaufruf (zur Veranschaulichung wird mcp test verwendet):

  call-tool blazesql_query --db_id "db_your_actual_db_id" --natural_language_request "What were the total sales last month?"

• Ausgabe: Bei Erfolg gibt das Tool einen einzelnen text zurück, der Folgendes enthält:

  • Die Antwort des BlazeSQL-Agenten in natürlicher Sprache.

  • Die generierte SQL-Abfrage innerhalb eines Markdown-Code-Zauns ( sql ... ).

  • Die Datenergebnisse werden als JSON innerhalb eines Markdown-Code-Zauns ( json ... ) formatiert.

  Beispielhafte Struktur innerhalb des text :

  **Agent Response:**
  The total sales last month were $12345.67.
  
  **Generated SQL:**
  ```sql
  SELECT sum(sales_amount) FROM sales WHERE sale_date >= date('now', '-1 month');

  Datenergebnis (JSON):

  [
    {
      "sum(sales_amount)": 12345.67
    }
  ]

  
  If unsuccessful, it returns a `text` content block containing the error message from the BlazeSQL API and marks the response as an error (`isError: true`).