Erweitere Marktmanagement-MCP fuer Durchfuehrungen

2026-09-19 08:51:17 +02:00
1 parent df5a533983
commit 3267a121de
@@ -0,0 +1,216 @@
+# Hermes: Market-Management-MCP-API
+
+Stand: 2026-09-19
+Status: Aktive technische Schnittstellendokumentation
+
+## Verbindung
+
+Hermes verwendet den MCP-Endpunkt der DEV-App:
+
+```text
+https://erpnaurua.imhochrain.ch/api/market-management-mcp.php
+```
+
+Jeder Request ist ein JSON-RPC-2.0-Request über HTTPS. Der Request benötigt:
+
+```http
+Authorization: Bearer <MARKET_MCP_TOKEN>
+Content-Type: application/json
+```
+
+Der Token wird nicht in dieser Dokumentation oder im Repository gespeichert.
+
+## Verbindungsablauf
+
+### 1. Initialisieren
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2025-03-26"
+  }
+}
+```
+
+### 2. Werkzeuge laden
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+### 3. Werkzeug aufrufen
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "market_management.list_categories",
+    "arguments": {}
+  }
+}
+```
+
+Das Ergebnis steht bei `tools/call` als JSON im Textinhalt des ersten
+`content`-Elements.
+
+## Verfügbare Werkzeuge
+
+### Marktdefinitionen
+
+- `market_management.search_markets`
+  - optional: `search`, `include_archived`, `limit`
+- `market_management.get_market`
+  - erforderlich: `market_id`
+  - optional: `include_archived`
+- `market_management.create_market`
+  - erforderlich: `name`, `category_id`
+- `market_management.update_market`
+  - erforderlich: `market_id`
+  - änderbar: `name`, `category_id`
+- `market_management.archive_market`
+  - erforderlich: `market_id`
+- `market_management.reactivate_market`
+  - erforderlich: `market_id`
+
+### Kategorien
+
+- `market_management.list_categories`
+
+Hermes darf Kategorien lesen und bei einem Markt referenzieren, aber keine
+Kategorien anlegen oder ändern.
+
+### Durchführungen
+
+- `market_management.create_occurrence`
+  - erforderlich: `market_definition_id`
+  - initialer Status: `open`
+  - weitere Durchführungsfelder sind optional und werden typisiert validiert
+- `market_management.get_occurrence`
+  - erforderlich: `occurrence_id`
+- `market_management.update_occurrence`
+  - erforderlich: `occurrence_id`
+- `market_management.archive_occurrence`
+  - erforderlich: `occurrence_id`
+- `market_management.reactivate_occurrence`
+  - erforderlich: `occurrence_id`
+
+Unterstützte Statuswerte:
+
+```text
+open
+waitlist
+registered
+confirmation_pending
+confirmed
+cancelled
+completed
+```
+
+Unterstützte Zahlungsstatuswerte:
+
+```text
+unpaid
+paid
+```
+
+### Durchführungstage
+
+- `market_management.create_day`
+  - erforderlich: `occurrence_id`, `date`
+- `market_management.update_day`
+  - erforderlich: `day_id`
+- `market_management.delete_day`
+  - erforderlich: `day_id`
+
+Weitere mögliche Tagesfelder sind `stand_start_time`, `stand_end_time`,
+`setup_start_time`, `setup_end_time`, `delivery_start_time`,
+`delivery_end_time` und `observations`.
+
+### Veranstalter und Kosten
+
+- `market_management.set_organizer`
+  - erforderlich: `occurrence_id`, `organization_contact_id`,
+    `contact_person_id`
+- `market_management.create_cost_item`
+  - erforderlich: `occurrence_id`, `cost_type`, `gross_amount`, `tax_status`
+  - `tax_status`: `tax_free` oder `taxable`
+- `market_management.delete_cost_item`
+  - erforderlich: `cost_item_id`
+
+## Beispiel: Markt anlegen
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "tools/call",
+  "params": {
+    "name": "market_management.create_market",
+    "arguments": {
+      "name": "Beispielmarkt Hermes Test",
+      "category_id": 1
+    }
+  }
+}
+```
+
+## Beispiel: Durchführung mit Tag anlegen
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 11,
+  "method": "tools/call",
+  "params": {
+    "name": "market_management.create_occurrence",
+    "arguments": {
+      "market_definition_id": 1,
+      "status": "open",
+      "place": "Beispielort",
+      "registration_deadline": "2026-10-01"
+    }
+  }
+}
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 12,
+  "method": "tools/call",
+  "params": {
+    "name": "market_management.create_day",
+    "arguments": {
+      "occurrence_id": 1,
+      "date": "2026-11-21",
+      "stand_start_time": "09:00",
+      "stand_end_time": "18:00"
+    }
+  }
+}
+```
+
+## Fachliche Grenzen
+
+- Hermes erhält keinen direkten Datenbankzugriff.
+- Hermes darf keine Kategorien anlegen.
+- Umsatz und Artikelmengen werden nicht über MCP geschrieben; sie werden aus
+  den OTC-Verkäufen abgeleitet.
+- Markt und Durchführung werden unabhängig archiviert.
+- Alle Schreibvorgänge werden serverseitig validiert.
+
+## Fehler
+
+Bei fehlender oder ungültiger Authentifizierung antwortet der Endpunkt mit
+HTTP 401. Ungültige JSON-RPC-Requests oder fachlich ungültige Eingaben werden
+als JSON-RPC-Fehlerantwort zurückgegeben.