From 9e877ac4642c2a0c15ba2253783817320fd01e20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mathias=20Gla=CC=88ser?= <mathias.glaeser@beaufort.ch>
Date: Fri, 18 Sep 2026 19:31:08 +0200
Subject: [PATCH] =?UTF-8?q?Dokumentiere=20MCP-Architektur=20f=C3=BCr=20Her?=
 =?UTF-8?q?mes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/modules/market_management/README.md      | 19 ++++
 .../market_management.hermes_mcp.md           | 92 +++++++++++++++++++
 2 files changed, 111 insertions(+)
 create mode 100644 docs/modules/market_management/integrations/market_management.hermes_mcp.md

diff --git a/docs/modules/market_management/README.md b/docs/modules/market_management/README.md
index 12eda72..6fc7ddb 100644
--- a/docs/modules/market_management/README.md
+++ b/docs/modules/market_management/README.md
@@ -23,6 +23,25 @@ sein.
 Die Ownership der Lizenz-/Entitlement-Daten ist noch nicht entschieden und
 bleibt offen.
 
+## MCP-Schnittstelle zu Hermes
+
+Die App stellt die MCP-Server-Schnittstelle bereit. Hermes Agent ist MCP-Client
+und ruft ausschließlich freigegebene Funktionen des Marktmanagement-Moduls
+auf.
+
+Die App behält die Kontrolle über:
+
+- Authentifizierung und Berechtigungsprüfung
+- Validierung und fachliche Interpretation der Eingaben
+- erlaubte Schreiboperationen
+- Persistierung in der eigenen Datenbank
+- Audit- und Quelleninformationen
+
+Hermes erhält keinen direkten Zugriff auf die Datenbank. Das Zielbild und die
+offenen Schnittstellenentscheidungen sind in
+[market_management.hermes_mcp.md](integrations/market_management.hermes_mcp.md)
+dokumentiert.
+
 ## Abgrenzung
 
 - Zunächst keine eigene Benutzerverwaltung.
diff --git a/docs/modules/market_management/integrations/market_management.hermes_mcp.md b/docs/modules/market_management/integrations/market_management.hermes_mcp.md
new file mode 100644
index 0000000..f06f1df
--- /dev/null
+++ b/docs/modules/market_management/integrations/market_management.hermes_mcp.md
@@ -0,0 +1,92 @@
+# market_management.hermes_mcp
+
+Stand: 2026-09-18
+Status: Verbindliches Architektur-Zielbild; technische Schnittstellendetails offen
+
+## 1. Zweck
+
+Das MCP-Interface ermöglicht Hermes Agent, Unterlagen zu analysieren und
+freigegebene erkannte Datenpunkte über das Marktmanagement-Modul in die App zu
+übergeben.
+
+## 2. Rollen und Verantwortungen
+
+### App / Market Management
+
+Die App stellt den MCP-Server bereit und bleibt das führende System für alle
+Marktdaten. Das Marktmanagement-Modul verantwortet insbesondere:
+
+- Benutzer- und Modulberechtigungsprüfung im vorhandenen Zugriffskontext
+- Validierung der Hermes-Eingaben
+- fachliche Feldzuordnung
+- zulässige Schreiboperationen
+- Persistierung in den eigenen Datenstrukturen
+- Quellen-, Lauf- und Auditinformationen
+- Rückgabe des Persistierungsergebnisses an Hermes
+
+### Hermes Agent
+
+Hermes ist MCP-Client. Hermes analysiert übergebene Unterlagen und ruft nur die
+von der App veröffentlichten MCP-Tools auf. Hermes besitzt keinen direkten
+Zugriff auf Datenbank, interne Services oder interne Dateien der App.
+
+## 3. Kontrollfluss
+
+```text
+Hermes Agent
+    → MCP-Aufruf
+MCP-Server der App
+    → Authentifizierung und Berechtigung
+Market-Management-Service
+    → Validierung und fachliche Feldzuordnung
+Eigene Datenbank der App
+    → strukturiertes Ergebnis
+Hermes Agent
+```
+
+## 4. Architekturgrenzen
+
+- Der MCP-Server ist eine externe Schnittstelle der App.
+- Die MCP-Schicht enthält keine eigene Marktfachlogik.
+- Jeder Schreibvorgang läuft über die interne Schnittstelle des
+  Marktmanagement-Moduls.
+- Generische SQL-, Tabellen- oder beliebige Feldschreibwerkzeuge werden nicht
+  veröffentlicht.
+- Hermes darf keine fremden Modul- oder technischen Interna direkt nutzen.
+- Lizenz-/Entitlement-Ownership bleibt offen und wird durch dieses Interface
+  nicht festgelegt.
+
+## 5. Fachliche Schreibregel
+
+Hermes darf grundsätzlich alle vom Marktmanagement-Modul ausdrücklich
+freigegebenen Datenpunkte über MCP übermitteln, zum Beispiel Kontaktperson,
+Anmeldefrist, Zahlungsfrist, Standgebühr oder Infrastrukturangaben.
+
+Die App entscheidet pro Aufruf, ob ein Wert:
+
+- direkt persistiert werden darf,
+- als unsicherer Prüfwert gespeichert wird oder
+- wegen fehlender oder widersprüchlicher Informationen abgewiesen wird.
+
+Die konkrete Freigabelogik ist noch nicht vollständig definiert.
+
+## 6. Offene Schnittstellenentscheidungen
+
+Folgende technische Angaben sind noch offen und müssen vor der Implementierung
+explizit festgelegt werden:
+
+- MCP-Transport und erreichbarer Endpoint
+- Authentifizierung und technische Identität von Hermes
+- Zuordnung von Hermes-Aufrufen zu Benutzeridentität und Modulrecht
+- veröffentlichte MCP-Tools und deren Eingabe-/Ausgabeschemas
+- Dokumentübergabe: Upload, App-interner Dokumentlink oder anderer Weg
+- Synchrones Ergebnis oder asynchrone Rückmeldung
+- Idempotenzschlüssel und Wiederholungsverhalten
+- Umgang mit Konfidenzwerten, Konflikten und manueller Freigabe
+- Umfang der Audit- und Herkunftsdaten
+
+## 7. Architekturstatus
+
+Das Verhältnis „App als MCP-Server, Hermes als MCP-Client“ ist bestätigt. Die
+offenen Punkte betreffen die konkrete technische Ausgestaltung und begründen
+kein weiteres Hauptmodul.