ProAlpha MCP Server

# ProAlpha MCP Server Ein Model-Context-Protocol (MCP) Server für ProAlpha MSSQL-Datenbanken, der eine Read-Only-Schnittstelle zu Ihrer Datenbank bereitstellt und automatisch Schemas erfasst. ## Funktionen - Verbindung zu ProAlpha MSSQL-Datenbanken - Automatische Erfassung des Datenbankschemas - Bereitstellung von Tabellenstrukturen als MCP-Ressourcen - Tools für Read-Only SQL-Abfragen - Prompts für gängige Datenanalyseaufgaben ## Anforderungen - Python 3.8 oder höher - Zugriff auf eine laufende ProAlpha-API (siehe .env: DB_SERVER_HOST, DB_SERVER_PORT, DB_API_KEY) - Eine ProAlpha MSSQL-Datenbank (über die API erreichbar) > **Hinweis:** Ein ODBC-Treiber für SQL Server wird nur auf dem API-Server benötigt, der die Verbindung zur MSSQL-Datenbank herstellt. Für den MCP-Server selbst ist keine ODBC-Installation erforderlich. ## Installation 1. Repository klonen oder herunterladen 2. Neue Umgebung mit conda anlegen (empfohlen): ```bash conda create -n mcp-proalpha python=3.11 conda activate mcp-proalpha ``` 3. uv installieren (falls nicht vorhanden): ```bash pip install uv ``` 4. Abhängigkeiten installieren: ```bash uv pip install -r requirements.txt ``` > **Hinweis:** uv ist ein schneller, moderner Ersatz für pip und wird für die Installation empfohlen. Alternativ kann weiterhin pip verwendet werden. 5. Konfigurationsdateien erstellen: Erstellen Sie eine `.env` Datei mit den folgenden Einstellungen: ```ini DB_SERVER_PORT=8080 DB_SERVER_HOST=http://localhost DB_API_KEY=your_api_key MCP_PORT=8000 MCP_HOST=0.0.0.0 API_SERVER_PORT=8081 API_SERVER_HOST=http://localhost SCHEMA_CACHE_PATH=./schema_cache # Transport-Protokoll für den MCP-Server: stdio, streamable-http oder sse MCP_TRANSPORT=streamable-http ``` - **MCP_TRANSPORT** bestimmt das Transport-Protokoll für den Server: | Transport-Protokoll | Beschreibung | Endpoint | |-----------------------|------------------------------------------------------|----------------------------------| | streamable-http | Empfohlen für Web-Deployments (Default) | `http://localhost:8000/mcp` | | stdio | Für lokale Tools und CLI-Skripte | | | sse | Für Kompatibilität mit bestehenden SSE-Clients | `http://localhost:8000/sse` | 6. Optional: Erstellen Sie eine Standard-Konfiguration für MCP-Prompts: ```bash ./app/generate_prompts.py ``` Dies erstellt eine `mcp_prompts.json`-Datei mit Standardvorlagen für Prompts und Toolbeispiele. ## Verwendung ### Server starten Der Server verwendet das in der `.env` konfigurierte Transport-Protokoll (`MCP_TRANSPORT`). - Für lokale CLI-Tools: `MCP_TRANSPORT=stdio` - Für Web-Deployments: `MCP_TRANSPORT=streamable-http` - Für SSE-Clients: `MCP_TRANSPORT=sse` ```bash python -m app ``` (optional) mit fastmcp-cli: ```bash fastmcp run mcp-proalpha.py ``` Der Server wird standardmäßig auf Port 8000 gestartet (außer bei stdio). ### Verbindung mit MCP Inspector ```bash npx @modelcontextprotocol/inspector python -m app ``` Öffnen Sie den [MCP Inspector](http://127.0.0.1:6274/) und verbinden Sie sich mit Ihrem Server (z.B. `http://localhost:8000/sse`). #### Alternativ: MCP Inspector mit uvx Falls Sie uvx (Node.js-Toolrunner von uv) installiert haben, können Sie den Inspector auch so starten: ```bash uvx @modelcontextprotocol/inspector python -m app ``` > **Hinweis:** uvx funktioniert analog zu npx, ist aber oft schneller und kann für Node.js-basierte Tools verwendet werden. ### HTTP REST-API verwenden Die REST-API ist parallel zum MCP-Server auf Port 8081 verfügbar. Beispiele für Endpunkte: - `GET /api/schema` – Gibt das gesamte Datenbankschema zurück - `GET /api/schema/tables` – Gibt eine Liste aller Tabellen zurück - `GET /api/schema/tables/{table_name}` – Gibt das Schema einer bestimmten Tabelle zurück - `GET /api/schema/views` – Gibt eine Liste aller Views zurück - `GET /api/schema/views/{view_name}` – Gibt das Schema einer bestimmten View zurück - `GET /api/schema/relationships` – Gibt alle Tabellenbeziehungen zurück - `POST /api/query` – Führt eine Read-Only-SQL-Abfrage aus (JSON: `{ "query": "SELECT ..." }`) - `POST /api/schema/refresh` – Aktualisiert den Schema-Cache - `GET /api/tools` – Gibt eine Liste aller verfügbaren Tools mit Name, Beschreibung und Parametern zurück (Tool-Discovery, analog zu `list_tools` im MCP-Server) - `GET /api/tools/{tool_name}` – Gibt die Details eines bestimmten Tools (Name, Beschreibung, Parameter) zurück - `GET /api/prompts` – Gibt eine Liste aller verfügbaren Prompts mit Name, Titel und Beschreibung zurück - `GET /api/prompts/{prompt_name}` – Gibt das Template eines bestimmten Prompts zurück Beispiel für eine SQL-Abfrage per curl: ```bash curl -X POST http://localhost:8081/api/query -H "Content-Type: application/json" -d '{"query": "SELECT TOP 5 * FROM BeispielTabelle"}' ``` ## MCP-Ressourcen Der Server stellt folgende MCP-Ressourcen bereit: - `resource://database_schema` – Das vollständige Datenbankschema - `table://{table_name}` – Schema jeder Tabelle - `view://{view_name}` – Schema jeder View - `resource://relationships` – Beziehungen zwischen den Tabellen ## MCP-Tools Der Server stellt folgende MCP-Tools bereit: - `execute_sql` – Führt eine Read-Only-SQL-Abfrage aus - `get_table_sample` – Gibt eine Stichprobe der Daten einer Tabelle zurück - `refresh_schema` – Aktualisiert den Schema-Cache - `list_tools` – Gibt eine Liste aller verfügbaren Tools mit Beschreibung und Parametern zurück (nützlich für LLMs und Clients zur Tool-Discovery) ## Testen des Servers Das Repository enthält ein Test-Skript, mit dem die grundlegende Funktionalität des Servers überprüft werden kann: ```bash # Server in einem Terminal starten python -m app # In einem anderen Terminal das Test-Skript ausführen ./test_server.py ``` Das Test-Skript prüft die MCP-Serverfunktionalität und kann auch REST-API-Endpunkte testen. ## Beispiel für MCP-Anfragen ### SQL-Abfrage ausführen ```json { "resources": [], "tools": [ { "id": "execute_sql", "parameters": { "query": "SELECT TOP 10 * FROM BeispielTabelle" } } ] } ``` ### Tabellendaten abrufen ```json { "resources": [], "tools": [ { "id": "get_table_sample", "parameters": { "table_name": "BeispielTabelle", "limit": 5 } } ] } ``` ## Integration mit LLMs Dieser MCP-Server ist kompatibel mit jedem LLM, das das Model-Context-Protocol unterstützt. ### Beispiel-Prompts #### Datenbankanalyse ``` Analysiere die Tabelle [TabellenName] und beschreibe ihre Struktur und Beziehungen. ``` #### Datenabfrage ``` Schreibe eine SQL-Abfrage, um [Geschäftsfrage] zu beantworten. ``` #### Schema-Erkundung ``` Finde alle Tabellen und Spalten, die mit [Suchbegriff] zu tun haben könnten. ``` > **Hinweis:** Mit dem Tool `list_tools` können LLMs und Clients alle verfügbaren Tools und deren Parameter dynamisch abfragen und so die Interaktion automatisieren oder Vorschläge generieren. ## Deployment mit Docker und Docker Compose ### Docker Sie können den MCP-Server auch in einem Docker-Container betreiben. Ein passendes `Dockerfile` ist im Repository enthalten. **Build und Starten des Containers:** ```bash docker build -t mcp-proalpha . docker run -p 8000:8000 --env-file .env mcp-proalpha ``` - Die Umgebungsvariablen werden über die `.env`-Datei gesetzt (siehe Abschnitt Installation). - Der Server ist dann unter `http://localhost:8000` erreichbar. - Falls Sie auch die REST-API zur Verfügung stellen möchten, denken Sie daran, zusätzlich Port 8081 zu mappen: ```bash docker run -p 8000:8000 -p 8081:8081 --env-file .env mcp-proalpha ``` ### Docker Compose Für komplexere Setups (z.B. mit mehreren Services oder persistenter Speicherung) empfiehlt sich Docker Compose. Ein Beispiel für eine `docker-compose.yml` ist im Repository enthalten: ```yaml version: '3.8' services: mcp-proalpha: build: . ports: - "8000:8000" - "8081:8081" # API-Server-Port, falls benötigt env_file: - .env volumes: - ./schema_cache:/app/schema_cache ``` **Starten mit Docker Compose:** ```bash docker-compose up --build ``` - Die Daten im Ordner `schema_cache` werden im Container persistiert. - Die Konfiguration erfolgt weiterhin über die `.env`-Datei. ## Lizenz MIT ([LICENSE](./LICENSE))