Benutzerdefinierter PostgreSQL MCP-Server für RAGmonsters

Überblick

Dieses Repository demonstriert einen fortgeschritteneren Ansatz zur Integration von Large Language Models (LLMs) in Datenbanken mithilfe des Model Context Protocol (MCP). Während generische MCP-PostgreSQL-Server es LLMs ermöglichen, Datenbanken über reine SQL-Abfragen zu erkunden, verfolgt dieses Projekt einen anderen Ansatz und erstellt einen benutzerdefinierten MCP-Server mit einer domänenspezifischen API, die auf die Anforderungen der Anwendung zugeschnitten ist.

Diese Implementierung verwendet FastMCP , eine Hochleistungsimplementierung des Model Context Protocol, die eine verbesserte Effizienz und Zuverlässigkeit für toolbasierte Interaktionen mit LLMs bietet.

Dieses Projekt basiert auf dem RAGmonsters -Datensatz. RAGmonsters ist ein Open-Source-Projekt, das einen umfangreichen, fiktiven Datensatz von Monstern mit verschiedenen Attributen, Fähigkeiten und Beziehungen bereitstellt – speziell entwickelt für die Demonstration und das Testen von Retrieval-Augmented Generation (RAG)-Systemen.

Das Problem mit dem generischen MCP-Datenbankzugriff

Generische MCP-PostgreSQL-Server stellen LLMs ein query zur Verfügung, das ihnen Folgendes ermöglicht:

• Datenbankschemata erkunden

• Formulieren Sie SQL-Abfragen basierend auf Fragen in natürlicher Sprache

• Führen Sie diese Abfragen für die Datenbank aus

Obwohl dieser Ansatz funktioniert, weist er für reale Anwendungen mehrere Einschränkungen auf:

• Kognitive Belastung : Der LLM muss das gesamte Datenbankschema verstehen

• Ineffizienz : Oft sind mehrere SQL-Abfragen erforderlich, um eine einzelne Frage zu beantworten

• Sicherheitsbedenken : Der Zugriff auf reine SQL-Daten erfordert eine sorgfältige und zeitnahe Entwicklung, um Injektionsangriffe zu verhindern.

• Leistung : Komplexe Abfragen können ineffizient sein, wenn der LLM die Indizierungsstrategie der Datenbank nicht versteht

• Wissenslücke im Fachgebiet : Dem LLM fehlt das Verständnis für Geschäftsregeln und domänenspezifische Einschränkungen

Über den RAGmonsters-Datensatz

RAGmonsters ist ein offener Datensatz, der speziell zum Testen und Demonstrieren von Retrieval-Augmented Generation (RAG)-Systemen entwickelt wurde. Er enthält Informationen über fiktive Monster mit vielfältigen Attributen, Fähigkeiten und Beziehungen und eignet sich somit perfekt für Demonstrationen von Abfragen in natürlicher Sprache.

Die PostgreSQL-Version von RAGmonsters bietet eine gut strukturierte relationale Datenbank mit mehreren Tabellen und Beziehungen, darunter:

• Monster mit verschiedenen Attributen (Angriffskraft, Verteidigung, Gesundheit usw.)

• Fähigkeiten, die Monster besitzen können

• Elemente (Feuer, Wasser, Erde usw.) mit komplexen Beziehungen

• Lebensräume, in denen Monster zu finden sind

• Evolutionsketten und Beziehungen zwischen Monstern

Dieser umfangreiche, vernetzte Datensatz eignet sich ideal, um die Leistungsfähigkeit domänenspezifischer APIs im Vergleich zum allgemeinen SQL-Zugriff zu demonstrieren.

Unsere Lösung: Domänenspezifische MCP-API

Dieses Projekt zeigt, wie ein benutzerdefinierter MCP-Server erstellt wird, der eine übergeordnete, domänenspezifische API für den RAGmonsters-Datensatz bereitstellt. Anstatt reine SQL-Funktionen bereitzustellen, bietet unser MCP-Server spezielle Funktionen, die:

1. Abstrakte Datenbankkomplexität : Verstecken Sie das zugrunde liegende Schema und die SQL-Details

2. Bereitstellung domänenspezifischer Vorgänge : Bieten Sie Funktionen an, die mit Geschäftskonzepten übereinstimmen

3. Für allgemeine Abfragen optimieren : Implementieren Sie effiziente Abfragemuster für häufig gestellte Fragen

4. Geschäftsregeln durchsetzen : Einbetten domänenspezifischer Logik und Einschränkungen

5. Verbessern Sie die Sicherheit : Reduzieren Sie die Angriffsfläche, indem Sie den direkten SQL-Zugriff entfernen

Webschnittstelle

Das Projekt umfasst zwei Hauptschnittstellen für die Interaktion mit dem RAGmonsters-Datensatz:

Explorer-Schnittstelle

Eine datenorientierte Schnittstelle zum Erkunden und Filtern des RAGmonsters-Datensatzes über die MCP-API:

• Durchsuchen Sie alle Monster mit Filtern nach Kategorie, Lebensraum und Seltenheit

• Detaillierte Informationen zu jedem Monster anzeigen

• Interaktive Benutzeroberfläche, erstellt mit Bootstrap

Chat-Schnittstelle

Eine natürliche Sprachschnittstelle zur Interaktion mit dem RAGmonsters-Datensatz:

• Stellen Sie Fragen zu Monstern in natürlicher Sprache

• Erhalten Sie Markdown-formatierte Antworten mit umfangreicher Formatierung

• Unterstützt durch das ReAct-Agentenmuster von LangGraph

• Nahtlose Integration mit den MCP-Tools

Über diese Schnittstelle können Benutzer:

• Durchsuchen Sie alle Monster im Datensatz

• Filtern Sie Monster nach Lebensraum, Kategorie und Seltenheit

• Sehen Sie sich detaillierte Informationen zu jedem Monster an, einschließlich Kräften, Fähigkeiten, Stärken und Schwächen

Beispiel: Domänenspezifische API vs. generisches SQL

Generischer MCP-PostgreSQL-Ansatz:

Unser benutzerdefinierter MCP-Server-Ansatz:

Projektstruktur

Merkmale

• Benutzerdefinierter MCP-Server mit FastMCP : Hochleistungsfähige domänenspezifische API für RAGmonsters-Daten

• Optimierte Abfragen : Vorgefertigte, effiziente Datenbankoperationen

• Business-Logik-Schicht : In die API eingebettete Domänenregeln und -einschränkungen

• Strukturiertes Antwortformat : Konsistente JSON-Antworten für den LLM-Verbrauch

• Umfassende Protokollierung : Detaillierte Protokollierung für Debugging und Überwachung

• Test Suite : Skripte zur Überprüfung der Serverfunktionalität und LLM-Integration

• LLM-Integration :

  • LangChain.js-Integration mit OpenAI und anderen kompatiblen LLM-Anbietern

  • LangGraph ReAct-Agentenmuster für effiziente Toolnutzung

  • Automatische Handhabung von Tool-Aufrufen und -Antworten

• Webschnittstellen :

  • Explorer-Oberfläche zum Durchsuchen und Filtern von Monstern

  • Chat-Schnittstelle mit Markdown-Rendering für natürliche Sprachinteraktion

Merkmale

• LangChain.js-Integration : Vollständig integrierte LLM-Interaktionen mit MCP-Tools

• Webschnittstelle : Explorer- und Chat-Schnittstellen für die Interaktion mit dem RAGmonsters-Datensatz

• Bereit zur Bereitstellung : Konfiguriert für die einfache Bereitstellung auf Plattformen wie Clever Cloud

Vorteile dieses Ansatzes

1. Verbesserte Leistung : Optimierte Abfragen und Caching-Strategien

2. Bessere Benutzererfahrung : Genauere und schnellere Antworten

3. Reduzierte Token-Nutzung : LLM muss keine komplexen SQL- oder Schemainformationen verarbeiten

4. Verbesserte Sicherheit : Kein direkter SQL-Zugriff bedeutet geringeres Risiko von Injektionsangriffen

5. Wartbarkeit : Änderungen am Datenbankschema erfordern kein erneutes Training des LLM

6. Skalierbarkeit : Kann größere und komplexere Datenbanken verarbeiten

Erste Schritte

Installation

1. Dieses Repository klonen

2. Abhängigkeiten installieren: npm install

3. Kopieren Sie .env.example nach .env und konfigurieren Sie Ihre PostgreSQL-Verbindungszeichenfolge und LLM-API-Schlüssel

4. Führen Sie das MCP-Server-Testskript aus: npm run test

5. Führen Sie das LLM-Integrationstestskript aus: npm run test:llm

6. Starten Sie den Server: npm start

Verfügbare Tools

Der MCP-Server bietet die folgenden Tools:

1. getMonsters - Holen Sie sich eine Liste von Monstern mit optionaler Filterung, Sortierung und Paginierung

   • Parameter: Filter (Kategorie, Lebensraum, Seltenheit), Sortierung (Feld, Richtung), Grenze, Offset

   • Rückgabe: Array von Monsterobjekten mit grundlegenden Informationen

2. getMonsterById - Erhalten Sie detaillierte Informationen zu einem bestimmten Monster anhand der ID

   • Parameter: monsterId

   • Rückgabe: Detailliertes Monsterobjekt mit allen Attributen, Kräften, Fähigkeiten, Stärken und Schwächen

3. add - Einfaches Dienstprogramm zum Addieren zweier Zahlen (zum Testen)

   • Parameter: a, b

   • Gibt zurück: Summe der beiden Zahlen

LLM Integrationsarchitektur

Dieses Projekt verwendet einen modernen Ansatz zur LLM-Integration mit domänenspezifischen Tools:

LangGraph ReAct Agent-Muster

Die Anwendung verwendet das ReAct-Agentenmuster (Reasoning and Acting) von LangGraph, das:

1. Verarbeitet Benutzeranfragen, um die Absicht zu verstehen

2. Bestimmt, welche Tools basierend auf der Abfrage verwendet werden sollen

3. Führt automatisch die entsprechenden Tools aus

4. Fasst die Ergebnisse zu einer kohärenten Antwort zusammen

5. Bewältigt bei Bedarf mehrstufiges Denken

Testen der LLM-Integration

Das Projekt enthält ein Testskript, das zeigt, wie LangChain.js verwendet wird, um ein LLM in den MCP-Server zu integrieren:

Dieses Skript:

1. Stellt eine Verbindung zum MCP-Server über StdioClientTransport her

2. Lädt alle verfügbaren MCP-Tools mit den MCP-Adaptern von LangChain

3. Erstellt einen LangChain-Agenten mit der OpenAI-API

4. Verarbeitet eine natürlichsprachliche Abfrage über Monster

5. Zeigt, wie das LLM Tool-Aufrufe durchführt, um Informationen abzurufen

6. Protokolliert detaillierte Informationen zur Interaktion

Sie können die Testabfragen im Skript ändern, um verschiedene Funktionen des Systems zu untersuchen. Das Skript befindet sich unter scripts/testLlmWithMcpServer.js .

Voraussetzungen

• Node.js 23 oder höher

• PostgreSQL-Datenbank mit RAGmonsters-Daten

• Zugriff auf eine LLM-API (z. B. OpenAI)

• FastMCP-Paket (in Abhängigkeiten enthalten)

Umgebungsvariablen

Erstellen Sie eine .env Datei mit den folgenden Variablen:

LLM-Konfiguration

• LLM_API_KEY : Ihr OpenAI-API-Schlüssel oder ein kompatibler Anbieterschlüssel

• LLM_API_MODEL : Das zu verwendende Modell (Standard: gpt-4o-mini)

• LLM_API_URL : Der API-Endpunkt (Standard: OpenAI-Endpunkt)

Die Anwendung unterstützt jede OpenAI-kompatible API, einschließlich selbst gehosteter Modelle und alternativer Anbieter.

Bereitstellung in Clever Cloud

Verwenden der Clever Cloud CLI

1. Installieren Sie die Clever Cloud CLI:

   npm install -g clever-tools

2. Melden Sie sich bei Ihrem Clever Cloud-Konto an:

   clever login

3. Erstellen Sie eine neue Anwendung:

   clever create --type node <APP_NAME>

4. Fügen Sie Ihre Domäne hinzu (optional, aber empfohlen):

   clever domain add <YOUR_DOMAIN_NAME>

5. Erstellen Sie ein PostgreSQL-Add-on und verknüpfen Sie es mit Ihrer Anwendung:

   clever addon create <APP_NAME>-pg --plan dev clever service link-addon <APP_NAME>-pg

   Dadurch wird die Umgebungsvariable POSTGRESQL_ADDON_URI automatisch in Ihrer Anwendung festgelegt.

6. Legen Sie die erforderlichen Umgebungsvariablen fest:

   clever env set LLM_API_KEY "your-openai-api-key" clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers

7. Stellen Sie Ihre Anwendung bereit:

   clever deploy

8. Öffnen Sie Ihre Anwendung:

   clever open

Verwenden der Clever Cloud-Konsole

Sie können die Bereitstellung auch direkt über die Clever Cloud Console durchführen:

1. Erstellen Sie eine neue Anwendung in der Konsole

2. Wählen Sie Node.js als Laufzeitumgebung

3. Erstellen Sie ein PostgreSQL-Add-on und verknüpfen Sie es mit Ihrer Anwendung

4. Legen Sie die erforderlichen Umgebungsvariablen in der Konsole fest:

   • LLM_API_KEY : Ihr OpenAI-API-Schlüssel

   • LLM_API_MODEL : (Optional) Das zu verwendende Modell, standardmäßig gpt-4o-mini

5. Stellen Sie Ihre Anwendung mithilfe der Git- oder GitHub-Integration bereit

Wichtige Hinweise

• Die Umgebungsvariable POSTGRESQL_ADDON_URI wird von Clever Cloud automatisch gesetzt, wenn Sie ein PostgreSQL-Add-on mit Ihrer Anwendung verknüpfen

• Die Anwendung erfordert Node.js 20 oder höher, das auf Clever Cloud verfügbar ist

• Die Anwendung wird automatisch auf Port 8080 ausgeführt, dem Standardport für Node.js-Anwendungen auf Clever Cloud

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE.

Danksagung

• RAGmonster für den Beispieldatensatz

• Model Context Protocol für die MCP-Spezifikation

• FastMCP für die performante MCP-Implementierung

• Clever Cloud für Hosting-Funktionen