@dpesch/mantisbt-mcp-server 1.14.1 → 1.16.0

package/docs/cookbook.de.md

@@ -6,10 +6,10 @@ Tool-orientierte Rezepte für den MantisBT MCP Server – jedes Rezept zeigt gen
 
 - [Verbindung einrichten](#verbindung-einrichten)
   - [Installation ohne URL-Rewriting anbinden](#installation-ohne-url-rewriting-anbinden)
+  - [Nur bestimmte Tool-Gruppen anbieten](#nur-bestimmte-tool-gruppen-anbieten)
 - [Die eigene Instanz erkunden](#die-eigene-instanz-erkunden)
   - [Alle Projekte abrufen](#alle-projekte-abrufen)
-  - [Gültige Enum-Werte ermitteln (Schweregrad, Status, Priorität)](#gültige-enum-werte-ermitteln-schweregrad-status-priorität)
-  - [Gültige Feldnamen für `select` ermitteln](#gültige-feldnamen-für-select-ermitteln)
+  - [Gültige select-Felder und Enum-Werte ermitteln](#gültige-select-felder-und-enum-werte-ermitteln)
 - [Issues](#issues)
   - [Einzelnes Issue abrufen](#einzelnes-issue-abrufen)
   - [Mehrere Issues in einem Aufruf abrufen](#mehrere-issues-in-einem-aufruf-abrufen)
@@ -18,6 +18,7 @@ Tool-orientierte Rezepte für den MantisBT MCP Server – jedes Rezept zeigt gen
   - [Nach Status filtern](#nach-status-filtern)
   - [Nach Bearbeiter oder Melder filtern](#nach-bearbeiter-oder-melder-filtern)
   - [Gespeicherten Filter anwenden](#gespeicherten-filter-anwenden)
+  - [Issues je Status, Bearbeiter, Priorität oder Kategorie zählen](#issues-je-status-bearbeiter-priorität-oder-kategorie-zählen)
   - [Issue erstellen](#issue-erstellen)
   - [Issue schließen (Status + Auflösung)](#issue-schließen-status--auflösung)
   - [Issue auflösen mit Begründungs-Notiz (ein Aufruf)](#issue-auflösen-mit-begründungs-notiz-ein-aufruf)
@@ -25,9 +26,11 @@ Tool-orientierte Rezepte für den MantisBT MCP Server – jedes Rezept zeigt gen
   - [Issue neu zuweisen](#issue-neu-zuweisen)
   - [Fix-Version setzen](#fix-version-setzen)
 - [Notizen](#notizen)
+  - [Notizen eines Issues abrufen](#notizen-eines-issues-abrufen)
   - [Öffentliche Notiz hinzufügen](#öffentliche-notiz-hinzufügen)
   - [Private Notiz hinzufügen](#private-notiz-hinzufügen)
   - [Notiz löschen](#notiz-löschen)
+  - [Notiz ändern](#notiz-ändern)
 - [Dateianhänge](#dateianhänge)
   - [Lokale Datei hochladen](#lokale-datei-hochladen)
   - [Dateiinhalt hochladen (Base64)](#dateiinhalt-hochladen-base64)
@@ -41,8 +44,9 @@ Tool-orientierte Rezepte für den MantisBT MCP Server – jedes Rezept zeigt gen
   - [Tags per Name anhängen](#tags-per-name-anhängen)
   - [Tag entfernen](#tag-entfernen)
 - [Monitore (Beobachter)](#monitore-beobachter)
-  - [Beobachter hinzufügen](#beobachter-hinzufügen)
-  - [Beobachter entfernen](#beobachter-entfernen)
+  - [Beobachter via update_issue ändern](#beobachter-via-update_issue-ändern)
+  - [Beobachter hinzufügen (veraltet)](#beobachter-hinzufügen-veraltet)
+  - [Beobachter entfernen (veraltet)](#beobachter-entfernen-veraltet)
 - [Semantische Suche](#semantische-suche)
   - [Initialen Index aufbauen](#initialen-index-aufbauen)
   - [Inkrementelles Index-Update](#inkrementelles-index-update)
@@ -50,18 +54,19 @@ Tool-orientierte Rezepte für den MantisBT MCP Server – jedes Rezept zeigt gen
   - [Nach Bedeutung suchen](#nach-bedeutung-suchen)
   - [Suche mit Felderweiterung](#suche-mit-felderweiterung)
 - [Projekte & Kategorien](#projekte--kategorien)
+  - [Projekt mit Kategorien, Nutzern und Versionen abrufen](#projekt-mit-kategorien-nutzern-und-versionen-abrufen)
   - [Projektkategorien auflisten](#projektkategorien-auflisten)
   - [Projektmitglied suchen](#projektmitglied-suchen)
   - [Projektversion erstellen](#projektversion-erstellen)
   - [Projektversion aktualisieren](#projektversion-aktualisieren)
-  - [Version freigeben und nächsten Bugfix-Platzhalter erstellen](#version-freigeben-und-nächsten-bugfix-platzhalter-erstellen)
+  - [Version freigeben und nächsten Bugfix-Platzhalter erstellen (veraltet)](#version-freigeben-und-nächsten-bugfix-platzhalter-erstellen-veraltet)
   - [Projektversion löschen](#projektversion-löschen)
 - [Metadaten](#metadaten)
   - [Metadaten-Zusammenfassung abrufen](#metadaten-zusammenfassung-abrufen)
+  - [Metadaten-Cache aktualisieren](#metadaten-cache-aktualisieren)
   - [Vollständigen Metadaten-Cache abrufen](#vollständigen-metadaten-cache-abrufen)
 - [Version & Diagnose](#version--diagnose)
-  - [MCP-Server-Version abrufen](#mcp-server-version-abrufen)
-  - [MantisBT-Version abrufen](#mantisbt-version-abrufen)
+  - [Versionen abrufen (MCP-Server und MantisBT)](#versionen-abrufen-mcp-server-und-mantisbt)
   - [Aktuellen Benutzer abrufen](#aktuellen-benutzer-abrufen)
 - [Ressourcen](#ressourcen)
   - [Eigenes Benutzerprofil lesen](#eigenes-benutzerprofil-lesen)
@@ -109,42 +114,52 @@ Manche MantisBT-Installationen liefern die REST-API ausschließlich über ihren
 
 Endet `MANTIS_BASE_URL` auf `/api/rest/index.php`, wird das index.php-Routing automatisch aktiviert. Ein explizit gesetztes `MANTIS_USE_INDEX_PHP` hat immer Vorrang vor der Erkennung – steht es zusammen mit einer solchen URL auf `false`, wird das normale `/api/rest/`-Routing erzwungen und eine Warnung auf stderr ausgegeben.
 
-**Prüfen:** `get_mantis_version` aufrufen. Kommt eine Antwort zurück, stimmt das Routing.
+**Prüfen:** `get_version` aufrufen. Kommt eine Antwort zurück, stimmt das Routing.
 
 ---
 
-## Die eigene Instanz erkunden
-
-### Alle Projekte abrufen
+### Nur bestimmte Tool-Gruppen anbieten
 
-Gibt die vollständige Liste der mit dem API-Key zugänglichen Projekte zurück.
+Standardmäßig sind alle 41 Tools aktiv (Suche deaktiviert). Mit `MANTIS_TOOLSETS` lassen sich nur die benötigten Gruppen laden – das hält den Kontext des Modells kürzer. Mit `MANTIS_DISABLE_DESTRUCTIVE=true` werden alle destruktiven Tools ausgeblendet, unabhängig von den aktiven Gruppen.
 
-**Tool:** `list_projects`
-
-**Parameter:** _(keine)_
+Gültige Gruppennamen: `issues`, `notes`, `links`, `files`, `projects`, `versions`, `meta`, `search`. Ein unbekannter Name stoppt den Server beim Start mit einer Meldung, die die gültigen Namen auflistet. Veraltete Tools gehören immer zur gleichen Gruppe wie ihr Ersatz. Die vollständige Zuordnung von Gruppe zu Tools findet sich unter [Angebotene Tools einschränken im README](../README.de.md#angebotene-tools-einschränken).
 
-**Request:**
+**Beispiel A – Triage-Setup** (`issues`, `notes`, `meta`; keine destruktiven Operationen):
 
 ```json
-{}
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com",
+    "MANTIS_API_KEY": "dein-api-token",
+    "MANTIS_TOOLSETS": "issues,notes,meta",
+    "MANTIS_DISABLE_DESTRUCTIVE": "true"
+  }
+}
 ```
 
-**Response:**
+**Beispiel B – alle Gruppen, nur Löschschutz** (36 von 41 Standard-Tools):
 
 ```json
-[
-  { "id": 3, "name": "Webshop", "status": { "id": 10, "name": "development" }, "enabled": true },
-  { "id": 5, "name": "Backend API", "status": { "id": 10, "name": "development" }, "enabled": true }
-]
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com",
+    "MANTIS_API_KEY": "dein-api-token",
+    "MANTIS_DISABLE_DESTRUCTIVE": "true"
+  }
+}
 ```
 
+Die Gruppe `search` erfordert zusätzlich `MANTIS_SEARCH_ENABLED=true`. Fehlt `search` in `MANTIS_TOOLSETS`, wird das Such-Modul – Index, Embedding-Modell, Hintergrund-Sync – gar nicht gestartet, auch wenn `MANTIS_SEARCH_ENABLED=true` gesetzt ist.
+
 ---
 
-### Gültige Enum-Werte ermitteln (Schweregrad, Status, Priorität)
+## Die eigene Instanz erkunden
 
-Gibt die auf der eigenen MantisBT-Instanz konfigurierten Enum-Werte zurück. Vor dem Erstellen oder Aktualisieren von Issues aufrufen, um gültige Werte zu kennen.
+### Alle Projekte abrufen
 
-**Tool:** `get_issue_enums`
+Gibt die vollständige Liste der mit dem API-Key zugänglichen Projekte zurück.
+
+**Tool:** `list_projects`
 
 **Parameter:** _(keine)_
 
@@ -157,57 +172,27 @@ Gibt die auf der eigenen MantisBT-Instanz konfigurierten Enum-Werte zurück. Vor
 **Response:**
 
 ```json
-{
-  "priorities": [
-    { "id": 10, "name": "none" },
-    { "id": 20, "name": "low" },
-    { "id": 30, "name": "normal" },
-    { "id": 40, "name": "high" },
-    { "id": 50, "name": "urgent" },
-    { "id": 60, "name": "immediate" }
-  ],
-  "severities": [
-    { "id": 10, "name": "feature" },
-    { "id": 20, "name": "trivial" },
-    { "id": 50, "name": "major" },
-    { "id": 60, "name": "crash" }
-    // ...
-  ],
-  "statuses": [
-    { "id": 10, "name": "new" },
-    { "id": 50, "name": "assigned" },
-    { "id": 80, "name": "resolved" },
-    { "id": 90, "name": "closed" }
-    // ...
-  ],
-  "resolutions": [
-    { "id": 10, "name": "open" },
-    { "id": 20, "name": "fixed" },
-    { "id": 60, "name": "duplicate" }
-    // ...
-  ]
-}
+[
+  { "id": 3, "name": "Webshop", "status": { "id": 10, "name": "development" }, "enabled": true },
+  { "id": 5, "name": "Backend API", "status": { "id": 10, "name": "development" }, "enabled": true }
+]
 ```
 
-> **Hinweis:** Auf lokalisierten Instanzen liefert `get_issue_enums()` im Feld `name` den lokalisierten Begriff und optional im Feld `canonical_name` den englischen Originalnamen. `create_issue` akzeptiert **beides** – sowohl den kanonischen englischen Namen (z.B. `minor`) als auch den lokalisierten Namen (z.B. `Unschönheit`). Der Server löst den Wert automatisch auf.
-
 ---
 
-### Gültige Feldnamen für `select` ermitteln
+### Gültige select-Felder und Enum-Werte ermitteln
 
-Gibt alle Feldnamen zurück, die dem `select`-Parameter von `list_issues` übergeben werden können.
+Gibt die gültigen `select`-Feldnamen und die Enum-Werte (severity, status, priority, resolution, reproducibility) für diesen MantisBT-Server in einem Aufruf zurück. Vor dem Aufbau eines `select`-Strings oder dem Setzen von Enum-Feldern in `create_issue` / `update_issue` aufrufen.
 
-**Tool:** `get_issue_fields`
+**Tool:** `get_issue_schema`
 
 **Parameter:**
-- `project_id` – _(optional)_ auf Felder eines bestimmten Projekts beschränken
+- `project_id` – _(optional)_ Feldermittlung auf ein bestimmtes Projekt einschränken
 
 **Request:**
 
 ```json
-{
-  "project_id": 3
-}
+{}
 ```
 
 **Response:**
@@ -221,10 +206,46 @@ Gibt alle Feldnamen zurück, die dem `select`-Parameter von `list_issues` überg
     "severity", "status", "summary", "tags", "target_version",
     "updated_at", "version", "view_state"
   ],
-  "source": "live"
+  "fields_source": "live",
+  "enums": {
+    "severity": [
+      { "id": 10, "name": "feature" },
+      { "id": 20, "name": "trivial" },
+      { "id": 50, "name": "major" },
+      { "id": 60, "name": "crash" }
+    ],
+    "status": [
+      { "id": 10, "name": "new" },
+      { "id": 50, "name": "assigned" },
+      { "id": 80, "name": "resolved" },
+      { "id": 90, "name": "closed" }
+    ],
+    "priority": [
+      { "id": 10, "name": "none" },
+      { "id": 20, "name": "low" },
+      { "id": 30, "name": "normal" },
+      { "id": 40, "name": "high" },
+      { "id": 50, "name": "urgent" },
+      { "id": 60, "name": "immediate" }
+    ],
+    "resolution": [
+      { "id": 10, "name": "open" },
+      { "id": 20, "name": "fixed" },
+      { "id": 60, "name": "duplicate" }
+    ],
+    "reproducibility": [
+      { "id": 10, "name": "always" },
+      { "id": 30, "name": "sometimes" },
+      { "id": 70, "name": "have not tried" }
+    ]
+  }
 }
 ```
 
+`fields_source` ist `"cache"`, `"live"` oder `"static"`. Auf lokalisierten Installationen kann jeder Enum-Eintrag ein `label` (lokalisiert) und einen `canonical_name` (englischer Standardname) enthalten. `create_issue` akzeptiert beides – kanonische englische Namen (z.B. `minor`) wie auch lokalisierte Namen; der Server löst den Wert automatisch auf.
+
+> **Veraltet:** `get_issue_fields` (nur Felder) und `get_issue_enums` (nur Enums) werden durch `get_issue_schema` abgelöst – sie werden in 2.0.0 entfernt. Die Ressource `mantis://enums` bleibt erhalten.
+
 ---
 
 ## Issues
@@ -287,10 +308,11 @@ Kompakte Variante (nur die benötigten Felder):
 
 Ruft bis zu 50 Issues in einem einzigen MCP-Aufruf ab. Die Anfragen laufen parallel (max. 5 gleichzeitig). Nicht zugängliche IDs liefern `null` an ihrer Position – der Aufruf schlägt nie wegen einzelner fehlender IDs fehl.
 
-**Tool:** `get_issues`
+**Tool:** `get_issue`
 
 **Parameter:**
 - `ids` – Array numerischer Issue-IDs (1–50)
+- `select` – _(optional)_ kommagetrennte Feldliste
 
 **Request:**
 
@@ -327,6 +349,8 @@ Ruft bis zu 50 Issues in einem einzigen MCP-Aufruf ab. Die Anfragen laufen paral
 
 > **Hinweis:** `null`-Einträge zeigen IDs an, die nicht gefunden oder nicht zugänglich waren. `failed` gibt an, wie viele IDs nicht abgerufen werden konnten.
 
+> **Veraltet:** `get_issues` bietet dieselbe Funktion, ist aber veraltet – stattdessen `get_issue` mit `ids` wie oben gezeigt verwenden; `get_issues` wird in 2.0.0 entfernt.
+
 ---
 
 ### Issues auflisten (paginiert)
@@ -412,7 +436,7 @@ Eine kommagetrennte Liste von Feldnamen übergeben, um nur die benötigten Felde
 }
 ```
 
-> **Hinweis:** Mit `get_issue_fields()` lassen sich alle verfügbaren Feldnamen anzeigen.
+> **Hinweis:** Mit `get_issue_schema()` lassen sich alle verfügbaren Feldnamen anzeigen.
 
 > **Hinweis:** `view_url` ist in allen Issue-Responses immer vorhanden – es wird vom MCP-Server injiziert und wird durch den `select`-Parameter nicht beeinflusst.
 
@@ -553,6 +577,71 @@ Einen in MantisBT vorgespeicherten Filter anhand seiner ID verwenden. Dies ist d
 
 ---
 
+### Issues je Status, Bearbeiter, Priorität oder Kategorie zählen
+
+Gibt die Anzahl der passenden Issues gruppiert nach einem einzelnen Feld zurück, anstatt einzelne Issues aufzulisten – deutlich weniger Tokens als das Lesen aller Seiten.
+
+**Tool:** `list_issues`
+
+**Parameter:**
+- `project_id` – _(optional)_ numerische Projekt-ID
+- `group_by` – `"status"`, `"handler"`, `"priority"` oder `"category"`
+- `status`, `assigned_to`, `reporter_id`, Datumsfilter – _(optional)_ alle Filter greifen weiterhin; `page`, `page_size` und `select` werden ignoriert
+
+**Request:**
+
+```json
+{
+  "project_id": 3,
+  "group_by": "status"
+}
+```
+
+**Response:**
+
+```json
+{
+  "group_by": "status",
+  "total": 604,
+  "groups": [
+    { "id": 80, "name": "resolved", "label": "erledigt", "count": 412 },
+    { "id": 50, "name": "assigned", "label": "zugewiesen", "count": 98 },
+    { "id": 40, "name": "confirmed", "label": "bestätigt", "count": 57 },
+    { "id": 20, "name": "feedback", "label": "Rückmeldung", "count": 37 }
+  ]
+}
+```
+
+Die Gruppen sind absteigend nach Anzahl, danach aufsteigend nach Name sortiert. Das Feld `label` enthält den lokalisierten Anzeigenamen und entfällt bei Gruppen ohne Label (z.B. Bearbeiter).
+
+**Request (Bearbeiter, nur offene Issues):**
+
+```json
+{
+  "project_id": 3,
+  "group_by": "handler",
+  "status": "open"
+}
+```
+
+**Response:**
+
+```json
+{
+  "group_by": "handler",
+  "total": 185,
+  "groups": [
+    { "id": 7, "name": "jdoe", "count": 72 },
+    { "id": 4, "name": "jsmith", "count": 68 },
+    { "id": null, "name": "(unassigned)", "count": 45 }
+  ]
+}
+```
+
+> **Hinweis:** Der Server durchsucht alle passenden Issues bis zu einem Limit von 50.000. Wird das Limit erreicht, enthält die Antwort `"truncated": true` und die Zählwerte sind unvollständig. Das ist ein deutlich größerer Scan als das 500-Issue-Limit der clientseitigen Filter in `list_issues`.
+
+---
+
 ### Issue erstellen
 
 Legt ein neues Issue in MantisBT an.
@@ -564,8 +653,8 @@ Legt ein neues Issue in MantisBT an.
 - `project_id` – numerische Projekt-ID
 - `category` – Kategoriename als Zeichenkette
 - `description` – _(optional)_ ausführliche Beschreibung
-- `priority` – _(optional)_ Priorität: kanonischer englischer Name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) oder lokalisierter Begriff. Standard: `"normal"`. Alle verfügbaren Werte über `get_issue_enums()` ermitteln.
-- `severity` – _(optional)_ Schweregrad: kanonischer englischer Name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) oder lokalisierter Begriff. Standard: `"minor"`. Alle verfügbaren Werte über `get_issue_enums()` ermitteln.
+- `priority` – _(optional)_ Priorität: kanonischer englischer Name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) oder lokalisierter Begriff. Standard: `"normal"`. Alle verfügbaren Werte über `get_issue_schema()` ermitteln.
+- `severity` – _(optional)_ Schweregrad: kanonischer englischer Name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) oder lokalisierter Begriff. Standard: `"minor"`. Alle verfügbaren Werte über `get_issue_schema()` ermitteln.
 - `handler` – _(optional)_ Benutzername des Bearbeiters (wird automatisch in eine ID aufgelöst)
 - `handler_id` – _(optional)_ numerische Benutzer-ID des Bearbeiters (Alternative zu `handler`)
 
@@ -609,11 +698,11 @@ Legt ein neues Issue in MantisBT an.
 
 **Fehler: unbekannter Schweregrad oder unbekannte Priorität**
 
-Der Server prüft zuerst kanonische englische Namen und fällt dann auf einen Live-`get_issue_enums`-Lookup zurück. Ein Fehler wird nur zurückgegeben, wenn der Wert weder kanonisch noch lokalisiert erkannt wird:
+Der Server prüft zuerst kanonische englische Namen und fällt dann auf einen Live-Enum-Lookup zurück. Ein Fehler wird nur zurückgegeben, wenn der Wert weder kanonisch noch lokalisiert erkannt wird:
 
-> Error: Invalid severity "xyz". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_enums to see localized labels.
+> Error: Invalid severity "xyz". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_schema to see localized labels.
 
-Mit `get_issue_enums` lassen sich alle akzeptierten Werte ermitteln – sowohl kanonische als auch lokalisierte Namen funktionieren.
+Mit `get_issue_schema` lassen sich alle akzeptierten Werte ermitteln – sowohl kanonische als auch lokalisierte Namen funktionieren.
 
 ---
 
@@ -655,7 +744,7 @@ Löst ein Issue auf und schließt es. **Immer beide Felder** `status` und `resol
 }
 ```
 
-> **Hinweis:** Auflösungs-ID 20 entspricht in einer Standard-MantisBT-Installation »behoben«. Mit `get_issue_enums()` die korrekte ID für die eigene Instanz prüfen.
+> **Hinweis:** Auflösungs-ID 20 entspricht in einer Standard-MantisBT-Installation »behoben«. Mit `get_issue_schema()` die korrekte ID für die eigene Instanz prüfen.
 
 ---
 
@@ -710,7 +799,7 @@ Schreibt Custom-Field-Werte beim Anlegen oder Aktualisieren. Dasselbe `custom_fi
 }
 ```
 
-> **Hinweis:** Nur die aufgeführten Custom Fields werden geändert – alle anderen bleiben unangetastet. Verfügbare Felder pro Projekt mit `get_issue_fields()` oder `get_metadata()` ermitteln. Werte sind immer Strings.
+> **Hinweis:** Nur die aufgeführten Custom Fields werden geändert – alle anderen bleiben unangetastet. Verfügbare Felder pro Projekt mit `get_issue_schema()` oder `get_metadata()` ermitteln. Werte sind immer Strings.
 
 ---
 
@@ -783,12 +872,54 @@ Setzt das Feld `fixed_in_version` eines Issues.
 }
 ```
 
-> **Hinweis:** Mit `get_project_versions(project_id)` lassen sich gültige Versionsnamen für ein Projekt auflisten.
+> **Hinweis:** Mit `get_project` und `include: ["versions"]` lassen sich gültige Versionsnamen für ein Projekt auflisten.
 
 ---
 
 ## Notizen
 
+### Notizen eines Issues abrufen
+
+Ruft nur die Notizen eines Issues über serverseitige Feldprojektion ab. Dies ist die bevorzugte Alternative zum veralteten `list_notes`-Tool.
+
+**Tool:** `get_issue`
+
+**Parameter:**
+- `id` – numerische Issue-ID
+- `select` – `"id,notes"` (`id` einschließen, damit `view_url` auch bei Projektionen immer gesetzt wird)
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "select": "id,notes"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "notes": [
+    {
+      "id": 88,
+      "reporter": { "id": 7, "name": "jdoe" },
+      "text": "In Version 2.0.3 reproduziert. Ursache in der Auth-Middleware identifiziert.",
+      "view_state": { "id": 10, "name": "public" },
+      "created_at": "2024-11-05T14:02:11+00:00",
+      "view_url": "https://mantis.example.com/view.php?id=1042#bugnote88"
+    }
+  ],
+  "view_url": "https://mantis.example.com/view.php?id=1042"
+}
+```
+
+> **Veraltet:** `list_notes` wird in 2.0.0 entfernt – stattdessen `get_issue` mit `select: "id,notes"` wie oben gezeigt verwenden.
+
+---
+
 ### Öffentliche Notiz hinzufügen
 
 Fügt eine öffentlich sichtbare Notiz zu einem Issue hinzu.
@@ -868,7 +999,7 @@ Entfernt eine Notiz dauerhaft von einem Issue.
 
 **Parameter:**
 - `issue_id` – numerische Issue-ID
-- `note_id` – numerische Notiz-ID (aus `list_notes` oder `get_issue`)
+- `note_id` – numerische Notiz-ID (aus `get_issue`)
 
 **Request:**
 
@@ -889,6 +1020,51 @@ Entfernt eine Notiz dauerhaft von einem Issue.
 
 ---
 
+### Notiz ändern
+
+Bearbeitet Text und/oder Sichtbarkeit einer bestehenden Notiz über `update_issue`. Die Notiz-ID stammt aus `get_issue`. Mindestens eines von `text` oder `view_state` muss angegeben werden. Mehrere Notizen können in einem Aufruf bearbeitet werden.
+
+**Tool:** `update_issue`
+
+**Parameter:**
+- `id` – numerische Issue-ID
+- `fields.notes` – Array von Notiz-Änderungen: `{ id, text?, view_state? }`; ein weggelassenes `view_state` behält die aktuelle Sichtbarkeit der Notiz
+
+**Request:** _(nur Text ändern)_
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "notes": [
+      { "id": 88, "text": "Auf Version 2.0.4 reproduziert – Null-Check in der Auth-Middleware fehlt." }
+    ]
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "summary": "Login-Button reagiert auf Mobile Safari nicht",
+  "notes": [
+    {
+      "id": 88,
+      "text": "Auf Version 2.0.4 reproduziert – Null-Check in der Auth-Middleware fehlt.",
+      "view_state": { "id": 10, "name": "public" },
+      "updated_at": "2024-11-06T12:00:00+00:00"
+    }
+  ],
+  "view_url": "https://mantis.example.com/view.php?id=1042"
+}
+```
+
+> **Hinweis:** Unbekannte Notiz-IDs werden vor dem Schreiben abgelehnt. Hat MantisBT eine Änderung nicht übernommen, enthält die Antwort `notes_error` mit Details statt den gesamten Aufruf abzubrechen – nur wenn die Notizbearbeitung die einzige angeforderte Änderung war, wird ein Fehler zurückgegeben. Zum Hinzufügen einer neuen Notiz den `note`-Parameter oder `add_note` verwenden.
+
+---
+
 ## Dateianhänge
 
 ### Lokale Datei hochladen
@@ -969,36 +1145,45 @@ Hängt eine Datei an, indem ihr base64-kodierter Inhalt direkt übergeben wird.
 
 ### Anhänge auflisten
 
-Gibt alle Dateianhänge eines Issues zurück.
+Gibt alle Dateianhänge eines Issues über serverseitige Feldprojektion zurück. Jeder Anhang enthält eine `download_url`, die über den MantisBT-File-Download-Endpoint aufgebaut wird.
 
-**Tool:** `list_issue_files`
+**Tool:** `get_issue`
 
 **Parameter:**
-- `issue_id` – numerische Issue-ID
+- `id` – numerische Issue-ID
+- `select` – `"id,attachments"`
 
 **Request:**
 
 ```json
 {
-  "issue_id": 1042
+  "id": 1042,
+  "select": "id,attachments"
 }
 ```
 
 **Response:**
 
 ```json
-[
-  {
-    "id": 23,
-    "filename": "login-error.png",
-    "size": 42318,
-    "content_type": "image/png",
-    "description": "Login error on mobile Safari",
-    "created_at": "2024-11-05T15:30:00+00:00"
-  }
-]
+{
+  "id": 1042,
+  "attachments": [
+    {
+      "id": 23,
+      "filename": "login-error.png",
+      "size": 42318,
+      "content_type": "image/png",
+      "created_at": "2024-11-05T15:30:00+00:00",
+      "reporter": { "id": 4, "name": "jsmith" },
+      "download_url": "https://mantis.example.com/file_download.php?file_id=23&type=bug"
+    }
+  ],
+  "view_url": "https://mantis.example.com/view.php?id=1042"
+}
 ```
 
+> **Veraltet:** `list_issue_files` wird in 2.0.0 entfernt – stattdessen `get_issue` mit `select: "id,attachments"` wie oben gezeigt verwenden.
+
 ---
 
 ## Verknüpfungen
@@ -1261,7 +1446,70 @@ Entfernt einen Tag von einem Issue. Erfordert die numerische Tag-ID.
 
 ## Monitore (Beobachter)
 
-### Beobachter hinzufügen
+### Beobachter via update_issue ändern
+
+Fügt Beobachter (Monitore) eines Issues hinzu und/oder entfernt sie in einem einzigen `update_issue`-Aufruf. `fields` darf entfallen – es genügt `add_monitors`, `remove_monitors` oder beides. Namen werden ohne Rücksicht auf Groß-/Kleinschreibung abgeglichen.
+
+**Tool:** `update_issue`
+
+**Parameter:**
+- `id` – numerische Issue-ID
+- `add_monitors` – _(optional)_ Array von MantisBT-Login-Namen, die als Beobachter eingetragen werden sollen
+- `remove_monitors` – _(optional)_ Array von MantisBT-Login-Namen, die aus den Beobachtern entfernt werden sollen; Namen, die das Issue nicht beobachten, werden still übergangen
+- Ein Name in beiden Arrays wird abgelehnt.
+
+**Request:** _(einen Beobachter hinzufügen)_
+
+```json
+{
+  "id": 1042,
+  "add_monitors": ["jsmith"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "view_url": "https://mantis.example.com/view.php?id=1042",
+  "monitors": {
+    "added": ["jsmith"],
+    "current": ["asmith", "jsmith"]
+  }
+}
+```
+
+**Request:** _(einen Beobachter entfernen)_
+
+```json
+{
+  "id": 1042,
+  "remove_monitors": ["jsmith"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "view_url": "https://mantis.example.com/view.php?id=1042",
+  "monitors": {
+    "removed": ["jsmith"],
+    "not_monitoring": [],
+    "current": ["asmith"]
+  }
+}
+```
+
+`monitors.current` listet stets alle verbleibenden Beobachter. `monitors.added` enthält erfolgreich hinzugefügte, `monitors.removed` erfolgreich entfernte Namen; `monitors.not_monitoring` enthält Namen, die das Issue nicht beobachtet haben und daher übersprungen wurden. Andere Benutzer hinzuzufügen oder zu entfernen erfordert die Zugriffsstufe `monitor_add_others_bug_threshold` bzw. `monitor_delete_others_bug_threshold`. Die Schritte laufen nacheinander – `fields`, Beobachter, `note`. Sobald einer davon geklappt hat, wird ein späterer Fehler in der Antwort als `monitors_error` bzw. `note_error` gemeldet (nichts wird zurückgenommen); nur wenn alle angeforderten Schritte fehlschlagen, liefert der Aufruf einen Fehler.
+
+---
+
+### Beobachter hinzufügen (veraltet)
+
+> **Veraltet:** stattdessen `update_issue` mit `add_monitors` verwenden – `add_monitor` wird in 2.0.0 entfernt.
 
 Abonniert einen Benutzer für Benachrichtigungen zu einem Issue.
 
@@ -1269,7 +1517,7 @@ Abonniert einen Benutzer für Benachrichtigungen zu einem Issue.
 
 **Parameter:**
 - `issue_id` – numerische Issue-ID
-- `username` – Benutzername als Zeichenkette
+- `username` – MantisBT-Login-Name
 
 **Request:**
 
@@ -1283,12 +1531,19 @@ Abonniert einen Benutzer für Benachrichtigungen zu einem Issue.
 **Response:**
 
 ```json
-{ "success": true }
+{
+  "success": true,
+  "monitors": ["asmith", "jsmith"]
+}
 ```
 
+`monitors` listet alle Benutzer, die das Issue jetzt beobachten. Ist der Benutzer bereits Beobachter, ändert sich nichts, und der Aufruf gelingt trotzdem. Andere Benutzer hinzuzufügen erfordert die Zugriffsstufe `monitor_add_others_bug_threshold`.
+
 ---
 
-### Beobachter entfernen
+### Beobachter entfernen (veraltet)
+
+> **Veraltet:** stattdessen `update_issue` mit `remove_monitors` verwenden – `remove_monitor` wird in 2.0.0 entfernt.
 
 Deabonniert einen Benutzer von Benachrichtigungen zu einem Issue.
 
@@ -1296,7 +1551,7 @@ Deabonniert einen Benutzer von Benachrichtigungen zu einem Issue.
 
 **Parameter:**
 - `issue_id` – numerische Issue-ID
-- `username` – Benutzername als Zeichenkette
+- `username` – MantisBT-Login-Name (Groß-/Kleinschreibung egal)
 
 **Request:**
 
@@ -1310,9 +1565,15 @@ Deabonniert einen Benutzer von Benachrichtigungen zu einem Issue.
 **Response:**
 
 ```json
-{ "success": true }
+{
+  "success": true,
+  "removed": true,
+  "monitors": ["asmith"]
+}
 ```
 
+`monitors` listet die Benutzer, die das Issue weiterhin beobachten. War `jsmith` gar kein Beobachter, ändert sich nichts, und die Antwort enthält `"removed": false` sowie eine `message`. Andere Benutzer zu entfernen erfordert die Zugriffsstufe `monitor_delete_others_bug_threshold`; fehlt sie, liefert das Tool einen Fehler.
+
 ---
 
 ## Semantische Suche
@@ -1323,6 +1584,8 @@ Deabonniert einen Benutzer von Benachrichtigungen zu einem Issue.
 
 Baut den vollständigen Vektor-Suchindex von Grund auf neu auf. Einmalig nach der Aktivierung der semantischen Suche ausführen.
 
+Der Server baut den Index außerdem von selbst neu auf, wenn er mit einem anderen Embedding-Modell oder auf andere Weise erstellt wurde – nach einer Änderung von `MANTIS_SEARCH_MODEL` oder nach einem Update, das die Art der Einbettung ändert. Ein vollständiger Neuaufbau von 7.700 Issues dauerte mit dem Standard von 1 Thread etwa 6 Minuten, mit `MANTIS_SEARCH_THREADS=4` keine 3 Minuten.
+
 **Tool:** `rebuild_search_index`
 
 **Parameter:**
@@ -1353,7 +1616,7 @@ Baut den vollständigen Vektor-Suchindex von Grund auf neu auf. Einmalig nach de
 
 Aktualisiert den Index mit Issues, die seit der letzten Synchronisation hinzugekommen oder geändert wurden. Schneller als ein vollständiger Neuaufbau: Nur die seitdem geänderten Issues werden abgerufen und neu eingebettet.
 
-Es synchronisiert immer nur ein Serverprozess den gemeinsamen Index. Läuft bereits eine Synchronisation in einem anderen Prozess (etwa einer anderen Client-Sitzung), gibt das Tool einen Fehler zurück – nach deren Ende einfach erneut aufrufen. Eine auf `project_id` beschränkte Synchronisation verschiebt `last_synced_at` nicht, damit Änderungen in anderen Projekten beim nächsten Sync trotzdem erfasst werden.
+Es synchronisiert immer nur ein Serverprozess den gemeinsamen Index. Läuft bereits eine Synchronisation in einem anderen Prozess (etwa einer anderen Client-Sitzung), gibt das Tool einen Fehler zurück – nach deren Ende einfach erneut aufrufen. Eine auf `project_id` beschränkte Synchronisation verschiebt `last_synced_at` nicht, damit Änderungen in anderen Projekten beim nächsten Sync trotzdem erfasst werden. Wurde der Index mit einem anderen Embedding-Modell oder einer anderen Version erstellt, baut der Sync ihn für alle Projekte neu auf, auch mit `project_id`.
 
 **Tool:** `rebuild_search_index`
 
@@ -1386,7 +1649,7 @@ Es synchronisiert immer nur ein Serverprozess den gemeinsamen Index. Läuft bere
 
 Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeitstempel der letzten Synchronisation zurück. `last_synced_at` ist das jüngste `updated_at`, das der MantisBT-Server bei dieser Synchronisation gemeldet hat (Serverzeit), und kann daher vor dem tatsächlichen Zeitpunkt der Synchronisation liegen.
 
-**Tool:** `get_search_index_status`
+**Tool:** `get_metadata`
 
 **Parameter:** _(keine)_
 
@@ -1396,23 +1659,32 @@ Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeit
 {}
 ```
 
-**Response:**
+**Response (relevanter Ausschnitt):**
 
 ```json
 {
-  "summary": "312/312 (100 %)",
-  "indexed": 312,
-  "total": 312,
-  "percent": 100,
-  "last_synced_at": "2024-11-05T14:00:00+01:00"
+  "projects": 24,
+  "tags": 15,
+  "byProject": { "3": { "name": "Webshop", "users": 8, "versions": 12, "categories": 4 } },
+  "cached_at": "2026-03-27T09:00:00.000Z",
+  "ttl_seconds": 82800,
+  "search_index": {
+    "summary": "312/312 (100 %)",
+    "indexed": 312,
+    "total": 312,
+    "percent": 100,
+    "last_synced_at": "2024-11-05T14:00:00+01:00"
+  }
 }
 ```
 
+> **Veraltet:** `get_search_index_status` wird in 2.0.0 entfernt – stattdessen `get_metadata` (Feld `search_index`) wie oben gezeigt verwenden.
+
 ---
 
 ### Nach Bedeutung suchen
 
-Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich sind. Gibt Issue-IDs und Relevanz-Scores zurück.
+Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich sind, kombiniert mit einer Stichwortsuche, damit auch exakte Begriffe (Bezeichner, Fehlercodes, Versionsnummern) gefunden werden. Gibt Issue-IDs und Relevanz-Scores zurück. `score` ist die semantische Ähnlichkeit; die Reihenfolge folgt der kombinierten Rangfolge, ein Ergebnis mit exaktem Stichworttreffer kann also vor einem mit höherem `score` stehen.
 
 **Tool:** `search_issues`
 
@@ -1542,68 +1814,159 @@ Zeigt, welcher Teil eines Issues mit der Suchanfrage übereinstimmt. Jedes Ergeb
 
 ## Projekte & Kategorien
 
+### Projekt mit Kategorien, Nutzern und Versionen abrufen
+
+Ruft die Stammdaten eines Projekts sowie beliebige Kombinationen von Kategorien, Nutzern und Versionen in einem Aufruf ab. Kategorienamen werden ohne das Prefix `[All Projects]` geliefert und können direkt in `create_issue` verwendet werden. `member_query` filtert Nutzer per Teilstring-Suche in Login-Name, Realname und E-Mail und liefert alle Treffer.
+
+**Tool:** `get_project`
+
+**Parameter:**
+- `project_id` – numerische Projekt-ID (mit `list_projects` ermitteln)
+- `include` – _(optional)_ Array aus `"categories"`, `"users"`, `"versions"` (beliebige Kombination)
+- `access_level` – _(optional)_ nur Nutzer ab dieser Zugriffsstufe (10=Betrachter, 25=Reporter, 40=Bearbeiter, 55=Entwickler, 70=Manager, 90=Administrator); impliziert `"users"`
+- `member_query` – _(optional)_ Teilstring für die Nutzersuche; impliziert `"users"`, liefert alle Treffer
+- `obsolete` – _(optional)_ veraltete Versionen einschließen; impliziert `"versions"`
+- `inherit` – _(optional)_ Versionen des Elternprojekts einschließen; impliziert `"versions"`
+
+**Request:** _(Stammdaten + Kategorien + Nutzer + Versionen)_
+
+```json
+{
+  "project_id": 3,
+  "include": ["categories", "users", "versions"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 3,
+  "name": "Webshop",
+  "description": "Kundenportal",
+  "status": { "id": 10, "name": "development" },
+  "enabled": true,
+  "view_state": { "id": 10, "name": "public" },
+  "categories": [
+    { "id": 1, "name": "General" },
+    { "id": 2, "name": "UI" },
+    { "id": 3, "name": "Backend" }
+  ],
+  "users": [
+    { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com", "access_level": { "id": 55, "name": "developer" } },
+    { "id": 7, "name": "jdoe", "real_name": "Jane Doe", "email": "jdoe@example.com", "access_level": { "id": 70, "name": "manager" } }
+  ],
+  "versions": [
+    { "id": 42, "name": "1.2.0", "released": false, "obsolete": false, "timestamp": "2026-10-31T00:00:00+00:00" },
+    { "id": 43, "name": "1.2.1", "released": false, "obsolete": false, "timestamp": "2026-10-31T00:00:00+00:00" }
+  ]
+}
+```
+
+**Request:** _(Mitgliedersuche)_
+
+```json
+{
+  "project_id": 3,
+  "member_query": "smith"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 3,
+  "name": "Webshop",
+  "status": { "id": 10, "name": "development" },
+  "enabled": true,
+  "users": [
+    { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com", "access_level": { "id": 55, "name": "developer" } },
+    { "id": 11, "name": "asmith", "real_name": "Alice Smith", "email": "asmith@example.com", "access_level": { "id": 40, "name": "updater" } }
+  ]
+}
+```
+
+> **Hinweis:** `get_project_categories`, `get_project_users`, `get_project_versions` und `find_project_member` sind zugunsten von `get_project` mit `include` bzw. `member_query` veraltet und werden in 2.0.0 entfernt.
+
+---
+
 ### Projektkategorien auflisten
 
 Gibt alle verfügbaren Kategorien eines MantisBT-Projekts zurück. Die zurückgegebenen Namen können direkt beim Erstellen von Issues verwendet werden.
 
-**Tool:** `get_project_categories`
+**Tool:** `get_project`
 
 **Parameter:**
 - `project_id` – numerische Projekt-ID
+- `include` – `["categories"]`
 
 **Request:**
 
 ```json
 {
-  "project_id": 3
+  "project_id": 3,
+  "include": ["categories"]
 }
 ```
 
 **Response:**
 
 ```json
-[
-  { "id": 1, "name": "General" },
-  { "id": 2, "name": "UI" },
-  { "id": 3, "name": "Backend" }
-]
+{
+  "id": 3,
+  "name": "Webshop",
+  "status": { "id": 10, "name": "development" },
+  "enabled": true,
+  "categories": [
+    { "id": 1, "name": "General" },
+    { "id": 2, "name": "UI" },
+    { "id": 3, "name": "Backend" }
+  ]
+}
 ```
 
 > **Hinweis:** Kategorienamen mit dem Prefix `[All Projects]` (aus dem globalen Projekt geerbt) werden in der Antwort automatisch ohne diesen Prefix zurückgegeben.
 
+> **Veraltet:** `get_project_categories` wird in 2.0.0 entfernt – stattdessen `get_project` mit `include: ["categories"]` wie oben gezeigt verwenden.
+
 ---
 
 ### Projektmitglied suchen
 
-Sucht Projektmitglieder nach Name, Realname oder E-Mail. Die Suche ist Groß-/Kleinschreibungsunabhängig und findet Teilstrings. Ergebnisse werden bevorzugt aus dem Metadaten-Cache geliefert; bei leerem Cache wird die live API verwendet.
+Sucht Projektmitglieder nach Name, Realname oder E-Mail. Die Suche ist Groß-/Kleinschreibungsunabhängig und findet Teilstrings. Alle Treffer werden zurückgegeben – es gibt kein `limit`.
 
-**Tool:** `find_project_member`
+**Tool:** `get_project`
 
 **Parameter:**
 - `project_id` – numerische Projekt-ID
-- `query` – _(optional)_ Suchbegriff für `name`, `real_name` oder `email`
-- `limit` – _(optional)_ maximale Trefferanzahl, Standard 10, max. 100
+- `member_query` – Suchbegriff für `name`, `real_name` oder `email`
 
 **Request:**
 
 ```json
 {
   "project_id": 3,
-  "query": "smith",
-  "limit": 5
+  "member_query": "smith"
 }
 ```
 
 **Response:**
 
 ```json
-[
-  { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com", "access_level": { "id": 55, "name": "developer" } },
-  { "id": 11, "name": "asmith", "real_name": "Alice Smith", "email": "asmith@example.com", "access_level": { "id": 40, "name": "reporter" } }
-]
+{
+  "id": 3,
+  "name": "Webshop",
+  "status": { "id": 10, "name": "development" },
+  "enabled": true,
+  "users": [
+    { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com", "access_level": { "id": 55, "name": "developer" } },
+    { "id": 11, "name": "asmith", "real_name": "Alice Smith", "email": "asmith@example.com", "access_level": { "id": 40, "name": "updater" } }
+  ]
+}
 ```
 
-> **Tipp:** `query` weglassen, um alle Mitglieder des Projekts aufzulisten (bis zu `limit`).
+> **Veraltet:** `find_project_member` wird in 2.0.0 entfernt – stattdessen `get_project` mit `member_query` wie oben gezeigt verwenden. Anders als `find_project_member` hat `get_project` kein `limit` und gibt alle Treffer zurück.
 
 ---
 
@@ -1658,12 +2021,13 @@ Aktualisiert eine bestehende Version eines MantisBT-Projekts. Es werden nur die
 
 **Parameter:**
 - `project_id` – numerische Projekt-ID
-- `version_id` – numerische Versions-ID (mit `get_project_versions` ermittelbar)
+- `version_id` – numerische Versions-ID (mit `get_project` und `include: ["versions"]` ermittelbar)
 - `name` – _(optional)_ neuer Versionsname (muss im Projekt eindeutig sein)
 - `description` – _(optional)_ neue Versionsbeschreibung
 - `released` – _(optional)_ Veröffentlichungs-Flag
 - `obsolete` – _(optional)_ Veraltet-Flag
 - `timestamp` – _(optional)_ Versionsdatum als ISO-8601-String
+- `next_version` – _(optional, nur zusammen mit `released: true`)_ Name der Folgeversion, die als unveröffentlichter Platzhalter angelegt wird, z.B. `"1.2.1"`; wird unverändert übernommen – keine automatische Nummerierung
 
 **Request:** _(Version als veraltet markieren)_
 
@@ -1687,9 +2051,46 @@ Aktualisiert eine bestehende Version eines MantisBT-Projekts. Es werden nur die
 }
 ```
 
+**Request:** _(Version freigeben und Folgeversion anlegen)_
+
+```json
+{
+  "project_id": 3,
+  "version_id": 42,
+  "released": true,
+  "timestamp": "2026-10-31",
+  "next_version": "1.2.1"
+}
+```
+
+**Response:**
+
+```json
+{
+  "version": {
+    "id": 42,
+    "name": "1.2.0",
+    "released": true,
+    "obsolete": false,
+    "timestamp": "2026-10-31T00:00:00+00:00"
+  },
+  "next_version": {
+    "id": 43,
+    "name": "1.2.1",
+    "released": false,
+    "obsolete": false,
+    "timestamp": "2026-10-31T00:00:00+00:00"
+  }
+}
+```
+
+Das Setzen von `released=true` ändert das Versionsdatum nicht – `timestamp` mit dem Freigabedatum immer mitübergeben. Schlägt das Anlegen der Folgeversion fehl, bleibt der Update wirksam und der Fehler wird als `next_version_error` in der Antwort gemeldet.
+
 ---
 
-### Version freigeben und nächsten Bugfix-Platzhalter erstellen
+### Version freigeben und nächsten Bugfix-Platzhalter erstellen (veraltet)
+
+> **Veraltet:** stattdessen `update_version` mit `released: true`, `timestamp` und optional `next_version` verwenden – `release_version` wird in 2.0.0 entfernt. Das Ersatzrezept steht unter [Projektversion aktualisieren](#projektversion-aktualisieren).
 
 Markiert eine Version als veröffentlicht (mit Datumsangabe) und erstellt im selben Aufruf optional eine Folgeversion als Platzhalter. Der Name der Folgeversion wird unverändert übernommen – keine automatische Nummerierung. Schlägt das Erstellen der Folgeversion fehl, bleibt die Freigabe wirksam und der Fehler wird in `next_version_error` gemeldet.
 
@@ -1735,7 +2136,7 @@ Markiert eine Version als veröffentlicht (mit Datumsangabe) und erstellt im sel
 }
 ```
 
-> **Hinweis:** Das Setzen von `released=true` via `update_version` ändert das Versionsdatum nicht – `release_version` verwenden, wenn beides in einem Schritt erledigt werden soll.
+> **Hinweis:** Das Setzen von `released=true` via `update_version` ändert das Versionsdatum nicht – `timestamp` mit dem Freigabedatum immer mitübergeben. Mit `next_version` lässt sich die Folgeversion im selben Aufruf anlegen.
 
 ---
 
@@ -1776,9 +2177,11 @@ Gibt eine kompakte Übersicht aller gecachten Metadaten zurück: Gesamtzahl der
 
 **Tool:** `get_metadata`
 
-**Parameter:** _(keine)_
+**Parameter:**
+- `detail` – _(optional)_ `"summary"` (Standard) für Zählwerte; `"full"` für den vollständigen rohen Cache
+- `refresh` – _(optional)_ `true`, um alle Metadaten vor der Antwort von MantisBT neu zu laden; Standard `false`
 
-**Request:**
+**Request:** _(Zusammenfassung, aus Cache)_
 
 ```json
 {}
@@ -1799,36 +2202,75 @@ Gibt eine kompakte Übersicht aller gecachten Metadaten zurück: Gesamtzahl der
 }
 ```
 
-> **Hinweis:** Für vollständige Listen `list_projects`, `get_project_users`, `get_project_versions`, `get_project_categories`, `list_tags` oder `get_metadata_full` verwenden.
+Mit `MANTIS_SEARCH_ENABLED=true` enthält die Antwort zusätzlich einen `search_index`-Block:
+
+```json
+{
+  "projects": 24,
+  "tags": 15,
+  "byProject": { "3": { "name": "Webshop", "users": 8, "versions": 12, "categories": 4 } },
+  "cached_at": "2026-03-27T09:00:00.000Z",
+  "ttl_seconds": 82800,
+  "search_index": {
+    "summary": "312/312 (100 %)",
+    "indexed": 312,
+    "total": 312,
+    "percent": 100,
+    "last_synced_at": "2026-03-27T08:55:00+01:00"
+  }
+}
+```
+
+> **Hinweis:** Für vollständige Listen `list_projects`, `get_project` (mit `include`) oder `list_tags` verwenden.
+
+---
+
+### Metadaten-Cache aktualisieren
+
+Erzwingt einen Neu-Abruf aller Metadaten von MantisBT, bevor die Zusammenfassung zurückgegeben wird.
+
+**Tool:** `get_metadata`
+
+**Parameter:**
+- `refresh` – `true`
+
+**Request:**
+
+```json
+{ "refresh": true }
+```
+
+**Response:** gleiche Struktur wie die Zusammenfassung oben, mit aktualisiertem `cached_at`.
 
 ---
 
 ### Vollständigen Metadaten-Cache abrufen
 
-Gibt den vollständigen rohen Metadaten-Cache als minifiziertes JSON zurück. Enthält alle Projekte mit vollständigen Feldern sowie Benutzer, Versionen und Kategorien je Projekt und alle Tags. Geeignet, wenn alle Daten in einem einzigen Aufruf benötigt werden.
+Gibt den vollständigen rohen Metadaten-Cache als minifiziertes JSON zurück. Die Cache-Struktur lautet `{ timestamp, projects, byProject: {"<id>": { users, versions, categories }}, tags }`.
 
-**Tool:** `get_metadata_full`
+**Tool:** `get_metadata`
 
-**Parameter:** _(keine)_
+**Parameter:**
+- `detail` – `"full"`
 
 **Request:**
 
 ```json
-{}
+{ "detail": "full" }
 ```
 
 **Response:**
 
 ```json
 {
+  "timestamp": 1743066000000,
   "projects": [
-    {
-      "id": 3,
-      "name": "Webshop",
-      "status": { "id": 10, "name": "development" },
-      "enabled": true,
+    { "id": 3, "name": "Webshop", "status": { "id": 10, "name": "development" }, "enabled": true }
+  ],
+  "byProject": {
+    "3": {
       "users": [
-        { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com", "access_level": { "id": 55, "name": "developer" } }
+        { "id": 4, "name": "jsmith", "real_name": "John Smith", "email": "jsmith@example.com" }
       ],
       "versions": [
         { "id": 21, "name": "2.4.0", "released": false, "obsolete": false }
@@ -1838,81 +2280,57 @@ Gibt den vollständigen rohen Metadaten-Cache als minifiziertes JSON zurück. En
         { "id": 2, "name": "UI" }
       ]
     }
-  ],
+  },
   "tags": [
     { "id": 1, "name": "regression" },
     { "id": 2, "name": "hotfix" }
-  ],
-  "cached_at": "2026-03-27T09:00:00.000Z"
+  ]
 }
 ```
 
-> **Tipp:** `get_metadata` liefert dieselben Daten als kompakte Zusammenfassung (nur Zählwerte). `get_metadata_full` verwenden, wenn die eigentlichen Arrays benötigt werden.
+> **Veraltet:** `get_metadata_full` wird in 2.0.0 entfernt – stattdessen `get_metadata` mit `detail: "full"` wie oben gezeigt verwenden.
 
 ---
 
 ## Version & Diagnose
 
-### MCP-Server-Version abrufen
-
-Gibt die Version dieser mantisbt-mcp-server-Instanz zurück.
-
-**Tool:** `get_mcp_version`
-
-**Parameter:** _(keine)_
-
-**Request:**
+### Versionen abrufen (MCP-Server und MantisBT)
 
-```json
-{}
-```
+Gibt die Version dieses mantisbt-mcp-servers und der verbundenen MantisBT-Installation in einer Antwort zurück. Mit `check_latest: true` (Standard) wird die MantisBT-Version mit dem neuesten Release auf GitHub verglichen (ausgehende HTTPS-Verbindung, max. 5 s). Ist MantisBT nicht erreichbar, enthält `mantis` ein `error`-Feld; die MCP-Server-Version wird trotzdem zurückgegeben.
 
-**Response:**
-
-```json
-{
-  "version": "1.5.8"
-}
-```
-
----
-
-### MantisBT-Version abrufen
-
-Gibt die Version der verbundenen MantisBT-Installation zurück und vergleicht sie optional mit dem neuesten offiziellen Release auf GitHub.
-
-**Tool:** `get_mantis_version`
+**Tool:** `get_version`
 
 **Parameter:**
-- `check_latest` – _(optional)_ ob gegen das neueste GitHub-Release verglichen werden soll; Standard `true`
+- `check_latest` – _(optional)_ MantisBT gegen das neueste GitHub-Release vergleichen; Standard `true`
 
 **Request:**
 
 ```json
-{
-  "check_latest": true
-}
+{}
 ```
 
 **Response:**
 
 ```json
 {
-  "installed_version": "2.27.0",
-  "latest_version": "2.27.1",
-  "status": "update-available"
+  "mcp_server": { "version": "1.15.0" },
+  "mantis": {
+    "installed_version": "2.27.0",
+    "latest_version": "2.27.1",
+    "status": "update-available"
+  }
 }
 ```
 
-Mögliche Werte für `status`: `up-to-date`, `update-available`, `newer-than-release`, `unknown`.
+Mögliche Werte für `status`: `up-to-date`, `update-available`, `newer-than-release`, `unknown`. Mit `check_latest: false` den GitHub-Vergleich überspringen.
 
-> **Hinweis:** Der GitHub-Vergleich erfordert eine ausgehende HTTPS-Verbindung. Mit `check_latest: false` lässt er sich überspringen.
+> **Veraltet:** `get_mcp_version` und `get_mantis_version` werden in 2.0.0 entfernt – stattdessen `get_version` wie oben gezeigt verwenden.
 
 ---
 
 ### Aktuellen Benutzer abrufen
 
-Gibt das Profil des Benutzers zurück, der dem konfigurierten API-Key zugeordnet ist. Nützlich, um die Verbindung zu prüfen und das verwendete Konto zu bestätigen.
+Gibt das Profil des Benutzers zurück, der dem konfigurierten API-Key zugeordnet ist. Nützlich, um die Verbindung zu prüfen und das verwendete Konto zu bestätigen. Das Feld `language` gibt die MantisBT-Sprache des Benutzers an – als Hinweis, in welcher Sprache Issue-Texte und Notizen verfasst werden sollten und welche Sprache die lokalisierten Enum-Bezeichnungen haben.
 
 **Tool:** `get_current_user`
 
@@ -1932,6 +2350,7 @@ Gibt das Profil des Benutzers zurück, der dem konfigurierten API-Key zugeordnet
   "name": "jsmith",
   "real_name": "John Smith",
   "email": "jsmith@example.com",
+  "language": "german",
   "access_level": { "id": 55, "name": "developer" }
 }
 ```
@@ -1974,7 +2393,7 @@ Gibt alle MantisBT-Projekte zurück, auf die der konfigurierte API-Key Zugriff h
 
 **Ressource-URI:** `mantis://projects`
 
-**Abrufverhalten:** Wird aus dem MetadataCache bedient (Standard-TTL 24 h). Fällt auf einen Live-API-Aufruf zurück, wenn der Cache leer ist. `sync_metadata` aufrufen, um eine Aktualisierung zu erzwingen.
+**Abrufverhalten:** Wird aus dem MetadataCache bedient (Standard-TTL 24 h). Fällt auf einen Live-API-Aufruf zurück, wenn der Cache leer ist. `get_metadata` mit `refresh: true` aufrufen, um eine Aktualisierung zu erzwingen.
 
 **Response:**
 
@@ -2064,7 +2483,7 @@ Gibt gültige ID/Name-Paare für alle Issue-Enum-Felder zurück (Severity, Prior
 }
 ```
 
-> **Tipp:** Das Tool `get_issue_enums` liefert dieselben Daten für Clients ohne Ressourcen-Unterstützung.
+> **Tipp:** Das Tool `get_issue_schema` liefert Enum-Werte für Clients ohne Ressourcen-Unterstützung (und gibt zusätzlich die gültigen `select`-Felder zurück).
 
 ---
 
@@ -2090,7 +2509,7 @@ Sammelt strukturierte Bug-Daten und ruft `create_issue` auf.
 - `actual` – tatsächliches (beobachtetes) Verhalten
 - `environment` – Umgebungsangaben (Betriebssystem, Browser, Version usw.)
 
-**Ablauf:** Der Prompt liefert eine Nachricht, die den LLM anweist, zunächst `get_issue_enums` aufzurufen (um gültige Schweregrad- und Prioritätswerte zu ermitteln) und anschließend `create_issue` mit den übergebenen Daten auszuführen.
+**Ablauf:** Der Prompt liefert eine Nachricht, die den LLM anweist, zunächst `get_issue_schema` aufzurufen (um gültige Schweregrad- und Prioritätswerte zu ermitteln) und anschließend `create_issue` mit den übergebenen Daten auszuführen.
 
 **Beispielaufruf:**
 
@@ -2184,6 +2603,8 @@ Listet alle Issues eines Projekts auf und erstellt einen Status-Report nach Schw
 
 ## Destruktive Operationen
 
+> Um alle destruktiven Tools auf einmal auszublenden – etwa für eine Sitzung, die nie etwas löschen soll –, `MANTIS_DISABLE_DESTRUCTIVE=true` setzen; siehe [Nur bestimmte Tool-Gruppen anbieten](#nur-bestimmte-tool-gruppen-anbieten).
+
 ### Issue löschen
 
 Löscht ein MantisBT-Issue dauerhaft. Diese Aktion kann nicht rückgängig gemacht werden.