mcp support

listify-api/README.md

@@ -57,6 +57,77 @@ $ npm run test:e2e
 $ npm run test:cov
 ```
 
+## MCP-Agent anbinden
+
+Die API enthaelt einen Remote-MCP-Server unter `/mcp`. Er nutzt den bestehenden JWT-Login der REST-API. Ein Agent oder MCP-Client darf deshalb nur mit einem gueltigen Access Token eines verifizierten Users auf die Tools zugreifen.
+
+### Ablauf
+
+1. User ueber die normale Auth-API anmelden, z. B. `POST /auth/login`.
+2. `accessToken` aus der Login-Antwort speichern.
+3. MCP-Client auf den Streamable-HTTP-Endpunkt konfigurieren:
+
+```text
+http://localhost:3000/mcp
+```
+
+4. Bei jedem MCP-Request diesen Header senden:
+
+```http
+Authorization: Bearer <accessToken>
+```
+
+Der Server erzeugt beim MCP-Initialize eine Session. Folge-Requests muessen den vom Server gelieferten `mcp-session-id` Header mitsenden. Die Session ist an den User aus dem JWT gebunden; ein Token eines anderen Users kann dieselbe MCP-Session nicht weiterverwenden.
+
+### Verfuegbare Tools
+
+- `list_existing_lists`
+  - Liest die Listen des angemeldeten Users.
+  - Input: `{ "includeItems": true | false }`
+  - Schreibt keine Daten.
+
+- `list_templates`
+  - Liest die Listenvorlagen des angemeldeten Users.
+  - Input: optional `{ "kind": "packing" | "shopping" | "todo" | "custom" }`
+  - Schreibt keine Daten.
+
+- `suggest_lists`
+  - Erzeugt strukturierte Vorschlaege fuer neue Listen.
+  - Input:
+
+```json
+{
+  "goal": "Sommerurlaub mit Handgepaeck",
+  "kind": "packing",
+  "constraints": ["Nur Handgepaeck", "Reisedokumente nicht vergessen"]
+}
+```
+
+  - Output enthaelt `suggestions` mit `name`, `description`, `kind`, `items`, optionalem Template-Bezug und `rationale`.
+  - Schreibt keine Daten und legt keine Liste an.
+
+### Minimaler MCP-Request
+
+Ein MCP-Client uebernimmt normalerweise Initialize, Session-Header und Tool-Calls selbst. Fuer eigene Tests sieht ein Tool-Call nach erfolgreicher Initialisierung sinngemaess so aus:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "suggest_lists",
+    "arguments": {
+      "goal": "Sommerurlaub mit Handgepaeck",
+      "kind": "packing",
+      "constraints": ["Nur Handgepaeck"]
+    }
+  }
+}
+```
+
+Wichtig: Der aktuelle Ausbau ist absichtlich read-only. Wenn ein Agent spaeter Listen direkt erstellen darf, sollte dafuer ein separates MCP-Tool mit expliziter Bestaetigung und Audit-Logging ergaenzt werden.
+
 ## Deployment
 
 When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.