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:
- Abstrakte Datenbankkomplexität : Verstecken Sie das zugrunde liegende Schema und die SQL-Details
- Bereitstellung domänenspezifischer Vorgänge : Bieten Sie Funktionen an, die mit Geschäftskonzepten übereinstimmen
- Für allgemeine Abfragen optimieren : Implementieren Sie effiziente Abfragemuster für häufig gestellte Fragen
- Geschäftsregeln durchsetzen : Einbetten domänenspezifischer Logik und Einschränkungen
- 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:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Must understand schema, joins, and SQL syntax)
1. First query to understand the schema
2. Second query to find monsters with attack power
3. Third query to find vulnerabilities
4. Final query to join and filter results
Unser benutzerdefinierter MCP-Server-Ansatz:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })
Projektstruktur
├── .env.example # Example environment variables
├── package.json # Node.js project configuration
├── README.md # This documentation
├── img/ # Images for documentation
├── scripts/
│ ├── testMcpServer.js # Test script for the MCP server
│ └── testLogger.js # Logger for test script
├── src/
│ ├── index.js # Main application server
│ ├── mcp-server/ # Custom MCP server implementation with FastMCP
│ │ ├── index.js # Server entry point
│ │ ├── tools/ # Domain-specific tools
│ │ │ ├── index.js # Tool registration
│ │ │ └── monsters.js # Monster-related operations
│ │ └── utils/ # Helper utilities
│ │ └── logger.js # Logging functionality
│ ├── llm.js # LangChain integration for LLM
│ └── public/ # Web interface files
│ ├── index.html # Monster explorer interface
│ └── chat.html # Chat interface for LLM interactions
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
- Verbesserte Leistung : Optimierte Abfragen und Caching-Strategien
- Bessere Benutzererfahrung : Genauere und schnellere Antworten
- Reduzierte Token-Nutzung : LLM muss keine komplexen SQL- oder Schemainformationen verarbeiten
- Verbesserte Sicherheit : Kein direkter SQL-Zugriff bedeutet geringeres Risiko von Injektionsangriffen
- Wartbarkeit : Änderungen am Datenbankschema erfordern kein erneutes Training des LLM
- Skalierbarkeit : Kann größere und komplexere Datenbanken verarbeiten
Erste Schritte
Installation
- Dieses Repository klonen
- Abhängigkeiten installieren:
npm install - Kopieren Sie
.env.example nach .env und konfigurieren Sie Ihre PostgreSQL-Verbindungszeichenfolge und LLM-API-Schlüssel - Führen Sie das MCP-Server-Testskript aus:
npm run test - Führen Sie das LLM-Integrationstestskript aus:
npm run test:llm - Starten Sie den Server:
npm start
Der MCP-Server bietet die folgenden Tools:
- 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
- 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
- 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:
- Verarbeitet Benutzeranfragen, um die Absicht zu verstehen
- Bestimmt, welche Tools basierend auf der Abfrage verwendet werden sollen
- Führt automatisch die entsprechenden Tools aus
- Fasst die Ergebnisse zu einer kohärenten Antwort zusammen
- 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:
- Stellt eine Verbindung zum MCP-Server über StdioClientTransport her
- Lädt alle verfügbaren MCP-Tools mit den MCP-Adaptern von LangChain
- Erstellt einen LangChain-Agenten mit der OpenAI-API
- Verarbeitet eine natürlichsprachliche Abfrage über Monster
- Zeigt, wie das LLM Tool-Aufrufe durchführt, um Informationen abzurufen
- 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:
# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database
# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1
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
- Installieren Sie die Clever Cloud CLI:
npm install -g clever-tools
- Melden Sie sich bei Ihrem Clever Cloud-Konto an:
- Erstellen Sie eine neue Anwendung:
clever create --type node <APP_NAME>
- Fügen Sie Ihre Domäne hinzu (optional, aber empfohlen):
clever domain add <YOUR_DOMAIN_NAME>
- 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
POSTGRESQL_ADDON_URI automatisch in Ihrer Anwendung festgelegt. - 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
- Stellen Sie Ihre Anwendung bereit:
- Öffnen Sie Ihre Anwendung:
Verwenden der Clever Cloud-Konsole
Sie können die Bereitstellung auch direkt über die Clever Cloud Console durchführen:
- Erstellen Sie eine neue Anwendung in der Konsole
- Wählen Sie Node.js als Laufzeitumgebung
- Erstellen Sie ein PostgreSQL-Add-on und verknüpfen Sie es mit Ihrer Anwendung
- Legen Sie die erforderlichen Umgebungsvariablen in der Konsole fest:
LLM_API_KEY : Ihr OpenAI-API-SchlüsselLLM_API_MODEL : (Optional) Das zu verwendende Modell, standardmäßig gpt-4o-mini
- 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