# 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))