mase-ppi/mcp-test-server

MCP Server

Ein schlanker Spring Boot MCP-Server, der Daten (Timescale/PostgreSQL) per Model Context Protocol (MCP, Spring AI) als Ressourcen + Tools bereitstellt. Fokus: Abfragen & Kontextbereitstellung – keine Daten-Ingestion im aktuellen Code.

Übersicht

Bereitgestellt werden:

• SQL-Query Tool (eingeschränkt sinnvoll nutzen)
• Ressourcendokumentation (Schema, Beispielabfragen, Gerätedaten-Metainfo)
• Resource-Lade-Tool zum Auslesen von MCP-Ressourcen

Features (aktuell)

• MCP SSE-Endpunkt (/mcp/device or /sse)
• Tools: load (Ressourcen lesen), query (SQL gegen device_states & andere Tabellen)
• Ressourcen: Schema, Beispielabfragen, Beispieldaten, Geräte-Attribut-Dokumentation
• Direkte SQL-Ausführung via JdbcTemplate (KEINE Entities definiert – JPA nur vorbereitet)

Architektur-Komponenten

• Einstieg: McpServerDbApplication
• Tools: TimescaleToolResource.query, MakeResourcesAccessible.load
• Ressourcen:
  • home-devices-Information
  • DatabaseSchema-TimescaleToolResource
  • device-insights-readMe
  • device-insights_devices_example_queries
  • Sample-Data-Sampling-of-device-insights
• Schema: DeviceHistoryDbSchema (device_states)
• SQL-Service: HistoryService (JdbcTemplate)

Voraussetzungen

• Java 17+ (gebaut wird mit JDK 21 Image, Quellcode kompatibel zu 17)
• Maven 3.9+
• PostgreSQL / TimescaleDB

Konfiguration

application.properties (vereinfacht – Variablen via Umgebungsvariablen):

server.port=9090
spring.ai.mcp.server.name=Home-Device-Server
spring.ai.mcp.server.version=0.0.1
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.sse-message-endpoint=/mcp/device
spring.datasource.url=jdbc:postgresql://${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
spring.datasource.username=postgres
spring.datasource.password=${POSTGRES_PASSWORD}

Erforderliche Umgebungsvariablen:

• POSTGRES_HOST
• POSTGRES_PORT
• POSTGRES_DB
• POSTGRES_PASSWORD

Optionale (derzeit funktionslos im Code):

• MQTT_SERVER_URI, mqtt.publisherId (MQTT nicht implementiert)

Build & Run

mvn clean package
java -jar target/mcp-test-server-0.0.1-SNAPSHOT.jar

Docker (multi-stage, JDK 21 Runtime):

docker build -t mcp-server .
docker run -e POSTGRES_HOST=postgres \
           -e POSTGRES_PORT=5432 \
           -e POSTGRES_DB=jarvis \
           -e POSTGRES_PASSWORD=secret \
           -p 9090:9090 mcp-server

Compose (Beispiel selbst erstellen): .env mit DB Variablen anlegen.

Datenbankschema (Kernausschnitt)

CREATE TABLE public.device_states (
    "time" timestamptz NOT NULL,
    floor text NULL,
    room text NULL,
    device_short text NULL,
    device_full text NULL,
    value_type text NULL,
    value_value numeric(10,2) NULL
);
-- passende Indizes laut DeviceHistoryDbSchema

(Hinweis: Kommentarzeichen // in Schema-Dokumentation sind beschreibend, kein gültiges SQL.)

MCP Endpunkt

• SSE: /mcp/device

Tools

1. load(uri: string)
   • Lädt Inhalt einer verfügbaren MCP-Ressource (erst Ressourcen auflisten, dann gezielt laden)
2. query(query: string)
   • Führt SQL aus. Verantwortung für LIMIT + Zeitfilter liegt beim Aufrufer. Beispielabfragen vorher lesen (device-insights_devices_example_queries).

Wichtige Ressourcen

• home-devices-Information → Gerätemetadaten & Attributbedeutung
• DatabaseSchema-TimescaleToolResource → Tabellen-/Schemaüberblick
• device-insights-readMe → Nutzungshinweise
• device-insights_devices_example_queries → Beispiel-SQL
• Sample-Data-Sampling-of-device-insights → aktuelle Stichprobe

Beispiel SQL (aus Ressourcen)

Durchschnittstemperatur je Raum:

SELECT room, AVG(value_value) AS avg_temp
FROM public.device_states
WHERE value_type = 'temperature'
GROUP BY room;

Entwicklungshinweise

• Keine Entities: reine JDBC-Abfragen (HistoryService)
• Erweiterung: Entities + Repositories ergänzen oder Ingestion-Mechanismen hinzufügen
• Tests fehlen – empfehlenswert für SQL-Validierung

Lizenz

Noch keine Lizenzdatei hinterlegt – bitte ergänzen (z.B. MIT oder Apache 2.0).

Status: README konsistent mit aktuellem Code (Stand: letzter Review).