@dpesch/mantisbt-mcp-server 1.14.0 → 1.15.0

package/docs/cookbook.md

@@ -6,10 +6,10 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
 
 - [Connection setup](#connection-setup)
   - [Connect to an installation without URL rewriting](#connect-to-an-installation-without-url-rewriting)
+  - [Offer only some tool groups](#offer-only-some-tool-groups)
 - [Discovering your instance](#discovering-your-instance)
   - [Get all projects](#get-all-projects)
-  - [Discover valid enum values (severity, status, priority)](#discover-valid-enum-values-severity-status-priority)
-  - [Discover valid field names for `select`](#discover-valid-field-names-for-select)
+  - [Valid select fields and enum values](#valid-select-fields-and-enum-values)
 - [Issues](#issues)
   - [Fetch a single issue](#fetch-a-single-issue)
   - [Fetch multiple issues in one call](#fetch-multiple-issues-in-one-call)
@@ -18,6 +18,7 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
   - [Filter by status](#filter-by-status)
   - [Filter by assignee or reporter](#filter-by-assignee-or-reporter)
   - [Apply a saved filter](#apply-a-saved-filter)
+  - [Count issues per status, handler, priority or category](#count-issues-per-status-handler-priority-or-category)
   - [Create an issue](#create-an-issue)
   - [Close an issue (status + resolution)](#close-an-issue-status--resolution)
   - [Resolve an issue with a reason note (single call)](#resolve-an-issue-with-a-reason-note-single-call)
@@ -25,9 +26,11 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
   - [Reassign an issue](#reassign-an-issue)
   - [Set fix version](#set-fix-version)
 - [Notes](#notes)
+  - [Get notes for an issue](#get-notes-for-an-issue)
   - [Add a public note](#add-a-public-note)
   - [Add a private note](#add-a-private-note)
   - [Delete a note](#delete-a-note)
+  - [Edit a note](#edit-a-note)
 - [File Attachments](#file-attachments)
   - [Upload a local file](#upload-a-local-file)
   - [Upload file content (base64)](#upload-file-content-base64)
@@ -41,8 +44,9 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
   - [Attach tags by name](#attach-tags-by-name)
   - [Detach a tag](#detach-a-tag)
 - [Monitors (Watchers)](#monitors-watchers)
-  - [Add a watcher](#add-a-watcher)
-  - [Remove a watcher](#remove-a-watcher)
+  - [Change watchers via update_issue](#change-watchers-via-update_issue)
+  - [Add a watcher (deprecated)](#add-a-watcher-deprecated)
+  - [Remove a watcher (deprecated)](#remove-a-watcher-deprecated)
 - [Semantic Search](#semantic-search)
   - [Build the initial index](#build-the-initial-index)
   - [Incremental index update](#incremental-index-update)
@@ -50,18 +54,19 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
   - [Search by meaning](#search-by-meaning)
   - [Search with field enrichment](#search-with-field-enrichment)
 - [Projects & Categories](#projects--categories)
+  - [Get a project with categories, users and versions](#get-a-project-with-categories-users-and-versions)
   - [List project categories](#list-project-categories)
   - [Find a project member](#find-a-project-member)
   - [Create a project version](#create-a-project-version)
   - [Update a project version](#update-a-project-version)
-  - [Release a version and create the next bugfix placeholder](#release-a-version-and-create-the-next-bugfix-placeholder)
+  - [Release a version and create the next bugfix placeholder (deprecated)](#release-a-version-and-create-the-next-bugfix-placeholder-deprecated)
   - [Delete a project version](#delete-a-project-version)
 - [Metadata](#metadata)
   - [Get a metadata summary](#get-a-metadata-summary)
+  - [Refresh the metadata cache](#refresh-the-metadata-cache)
   - [Get the full metadata cache](#get-the-full-metadata-cache)
 - [Version & Diagnostics](#version--diagnostics)
-  - [Get MCP server version](#get-mcp-server-version)
-  - [Get MantisBT version](#get-mantis-version)
+  - [Get versions (MCP server and MantisBT)](#get-versions-mcp-server-and-mantisbt)
   - [Get the current user](#get-the-current-user)
 - [Resources](#resources)
   - [Read the current user profile](#read-the-current-user-profile)
@@ -109,42 +114,52 @@ Some MantisBT installations serve the REST API only through its front controller
 
 When `MANTIS_BASE_URL` ends with `/api/rest/index.php`, index.php routing is enabled automatically. An explicitly set `MANTIS_USE_INDEX_PHP` always wins over the detection — setting it to `false` alongside such a URL forces plain `/api/rest/` routing and logs a warning on stderr.
 
-**Verify:** call `get_mantis_version`. A successful response means the routing is correct.
+**Verify:** call `get_version`. A successful response means the routing is correct.
 
 ---
 
-## Discovering your instance
-
-### Get all projects
+### Offer only some tool groups
 
-Returns the full list of projects accessible with your API key.
+By default all 41 tools are active (search off). Restrict them with `MANTIS_TOOLSETS` to keep the model's context shorter and load only what is needed for the task. Use `MANTIS_DISABLE_DESTRUCTIVE=true` to hide every destructive tool regardless of the active groups.
 
-**Tool:** `list_projects`
-
-**Parameters:** _(none)_
+Valid group names: `issues`, `notes`, `links`, `files`, `projects`, `versions`, `meta`, `search`. An unknown name stops the server at startup with a message listing the valid ones. Deprecated tools always belong to the same group as their replacement. For the complete group-to-tool mapping see [Limit the offered tools in the README](../README.md#limit-the-offered-tools).
 
-**Request:**
+**Example A — triage setup** (`issues`, `notes`, `meta`; no destructive operations):
 
 ```json
-{}
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com",
+    "MANTIS_API_KEY": "your-api-token",
+    "MANTIS_TOOLSETS": "issues,notes,meta",
+    "MANTIS_DISABLE_DESTRUCTIVE": "true"
+  }
+}
 ```
 
-**Response:**
+**Example B — all groups, delete-protection only** (36 of the 41 default 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": "your-api-token",
+    "MANTIS_DISABLE_DESTRUCTIVE": "true"
+  }
+}
 ```
 
+The `search` group additionally requires `MANTIS_SEARCH_ENABLED=true`. Without the `search` group in `MANTIS_TOOLSETS`, the search module — index, embedding model, background sync — is not started at all, even if `MANTIS_SEARCH_ENABLED=true` is set.
+
 ---
 
-### Discover valid enum values (severity, status, priority)
+## Discovering your instance
 
-Returns the enum values configured on your specific MantisBT instance. Use this before creating or updating issues to know which values are valid.
+### Get all projects
+
+Returns the full list of projects accessible with your API key.
 
-**Tool:** `get_issue_enums`
+**Tool:** `list_projects`
 
 **Parameters:** _(none)_
 
@@ -157,57 +172,27 @@ Returns the enum values configured on your specific MantisBT instance. Use this
 **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 }
+]
 ```
 
-> **Note:** On localized installations, `get_issue_enums()` returns a `name` in the local language and an optional `canonical_name` with the English original. `create_issue` accepts **both** — pass either the canonical English name (e.g. `minor`) or the localized name (e.g. `Unschönheit`). The server resolves the value automatically.
-
 ---
 
-### Discover valid field names for `select`
+### Valid select fields and enum values
 
-Returns all field names that can be passed to the `select` parameter of `list_issues`.
+Returns the valid `select` field names and the enum values (severity, status, priority, resolution, reproducibility) for this MantisBT server in one call. Use this before building a `select` string or before setting enum fields on `create_issue` / `update_issue`.
 
-**Tool:** `get_issue_fields`
+**Tool:** `get_issue_schema`
 
 **Parameters:**
-- `project_id` — _(optional)_ restrict to fields available for a specific project
+- `project_id` — _(optional)_ restrict the field discovery sample to a specific project
 
 **Request:**
 
 ```json
-{
-  "project_id": 3
-}
+{}
 ```
 
 **Response:**
@@ -221,10 +206,46 @@ Returns all field names that can be passed to the `select` parameter of `list_is
     "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` is `"cache"`, `"live"`, or `"static"`. On localized installations each enum entry may include a `label` (localized) and a `canonical_name` (standard English). `create_issue` accepts both — pass the canonical English name (e.g. `minor`) or the localized name; the server resolves it automatically.
+
+> **Deprecated:** `get_issue_fields` (fields only) and `get_issue_enums` (enums only) are superseded by `get_issue_schema` — they will be removed in 2.0.0. The resource `mantis://enums` stays.
+
 ---
 
 ## Issues
@@ -287,10 +308,11 @@ Compact variant (only the fields you need):
 
 Fetches up to 50 issues in a single MCP call. Requests run in parallel (max 5 concurrent). Missing or inaccessible IDs return `null` at their position — the call never fails due to individual missing IDs.
 
-**Tool:** `get_issues`
+**Tool:** `get_issue`
 
 **Parameters:**
 - `ids` — array of numeric issue IDs (1–50)
+- `select` — _(optional)_ comma-separated field list
 
 **Request:**
 
@@ -327,6 +349,8 @@ Fetches up to 50 issues in a single MCP call. Requests run in parallel (max 5 co
 
 > **Note:** `null` entries indicate IDs that were not found or could not be accessed. Check `failed` to see how many IDs could not be retrieved.
 
+> **Deprecated:** `get_issues` provides the same functionality but is deprecated — use `get_issue` with `ids` as shown above; `get_issues` will be removed in 2.0.0.
+
 ---
 
 ### List issues (paginated)
@@ -412,7 +436,7 @@ Pass a comma-separated list of field names to receive only the fields you need.
 }
 ```
 
-> **Note:** Use `get_issue_fields()` to see all available field names.
+> **Note:** Use `get_issue_schema()` to see all available field names.
 
 > **Note:** `view_url` is always present in all issue responses — it is injected by the MCP server and is not affected by the `select` parameter.
 
@@ -553,6 +577,71 @@ Use a pre-saved MantisBT filter by its ID. This is the recommended approach for
 
 ---
 
+### Count issues per status, handler, priority or category
+
+Returns the number of matching issues grouped by a single field instead of listing individual issues — far fewer tokens than reading all pages.
+
+**Tool:** `list_issues`
+
+**Parameters:**
+- `project_id` — _(optional)_ numeric project ID
+- `group_by` — `"status"`, `"handler"`, `"priority"`, or `"category"`
+- `status`, `assigned_to`, `reporter_id`, date filters — _(optional)_ all filters still apply; `page`, `page_size`, and `select` are ignored
+
+**Request:**
+
+```json
+{
+  "project_id": 3,
+  "group_by": "status"
+}
+```
+
+**Response:**
+
+```json
+{
+  "group_by": "status",
+  "total": 604,
+  "groups": [
+    { "id": 80, "name": "resolved", "label": "resolved", "count": 412 },
+    { "id": 50, "name": "assigned", "label": "assigned", "count": 98 },
+    { "id": 40, "name": "confirmed", "label": "confirmed", "count": 57 },
+    { "id": 20, "name": "feedback", "label": "feedback", "count": 37 }
+  ]
+}
+```
+
+Groups are sorted by count descending, then by name ascending. The `label` field contains the localized display name and is omitted for groups that have no label (e.g. handler).
+
+**Request (handler, open issues only):**
+
+```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 }
+  ]
+}
+```
+
+> **Note:** The server scans all matching issues up to a limit of 50,000. If the limit is reached, the response contains `"truncated": true` and the counts are incomplete. This is a much larger scan than the 500-issue limit of client-side filters in `list_issues`.
+
+---
+
 ### Create an issue
 
 Creates a new issue in MantisBT.
@@ -564,8 +653,8 @@ Creates a new issue in MantisBT.
 - `project_id` — numeric project ID
 - `category` — category name string
 - `description` — _(optional)_ detailed description
-- `priority` — _(optional)_ priority: canonical English name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) or localized label. Default: `"normal"`. Use `get_issue_enums()` to see all available values.
-- `severity` — _(optional)_ severity: canonical English name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) or localized label. Default: `"minor"`. Use `get_issue_enums()` to see all available values.
+- `priority` — _(optional)_ priority: canonical English name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) or localized label. Default: `"normal"`. Use `get_issue_schema()` to see all available values.
+- `severity` — _(optional)_ severity: canonical English name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) or localized label. Default: `"minor"`. Use `get_issue_schema()` to see all available values.
 - `handler` — _(optional)_ assignee username (resolved to ID automatically)
 - `handler_id` — _(optional)_ assignee numeric user ID (alternative to `handler`)
 
@@ -609,11 +698,11 @@ Creates a new issue in MantisBT.
 
 **Error: unknown severity or priority**
 
-The server first checks canonical English names, then falls back to a live `get_issue_enums` lookup. An error is only returned if the value matches neither:
+The server first checks canonical English names, then falls back to a live enum lookup. An error is only returned if the value matches neither:
 
-> 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.
 
-Use `get_issue_enums` to discover all accepted values — both canonical and localized names work.
+Use `get_issue_schema` to discover all accepted values — both canonical and localized names work.
 
 ---
 
@@ -655,7 +744,7 @@ Resolves and closes an issue. Always set **both** `status` and `resolution` —
 }
 ```
 
-> **Note:** Resolution ID 20 is "fixed" in a default MantisBT installation. Use `get_issue_enums()` to confirm the correct ID for your instance.
+> **Note:** Resolution ID 20 is "fixed" in a default MantisBT installation. Use `get_issue_schema()` to confirm the correct ID for your instance.
 
 ---
 
@@ -710,7 +799,7 @@ Writes custom field values on create or update. The same `custom_fields` format
 }
 ```
 
-> **Note:** Only the listed custom fields are changed — others stay untouched. Use `get_issue_fields()` or `get_metadata()` to discover available custom fields per project. Values are always strings.
+> **Note:** Only the listed custom fields are changed — others stay untouched. Use `get_issue_schema()` or `get_metadata()` to discover available custom fields per project. Values are always strings.
 
 ---
 
@@ -783,12 +872,54 @@ Sets the `fixed_in_version` field on an issue.
 }
 ```
 
-> **Note:** Use `get_project_versions(project_id)` to list valid version names for a project.
+> **Note:** Use `get_project` with `include: ["versions"]` to list valid version names for a project.
 
 ---
 
 ## Notes
 
+### Get notes for an issue
+
+Retrieves only the notes of an issue using server-side field projection. This is the preferred alternative to the deprecated `list_notes` tool.
+
+**Tool:** `get_issue`
+
+**Parameters:**
+- `id` — numeric issue ID
+- `select` — `"id,notes"` (include `id` so `view_url` is always set even when the projection omits it)
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "select": "id,notes"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "notes": [
+    {
+      "id": 88,
+      "reporter": { "id": 7, "name": "jdoe" },
+      "text": "Reproduced on version 2.0.3. Root cause identified in the auth middleware.",
+      "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"
+}
+```
+
+> **Deprecated:** `list_notes` will be removed in 2.0.0 — use `get_issue` with `select: "id,notes"` as shown above.
+
+---
+
 ### Add a public note
 
 Adds a publicly visible note to an issue.
@@ -868,7 +999,7 @@ Permanently removes a note from an issue.
 
 **Parameters:**
 - `issue_id` — numeric issue ID
-- `note_id` — numeric note ID (from `list_notes` or `get_issue`)
+- `note_id` — numeric note ID (from `get_issue`)
 
 **Request:**
 
@@ -889,6 +1020,51 @@ Permanently removes a note from an issue.
 
 ---
 
+### Edit a note
+
+Edits the text and/or visibility of an existing note via `update_issue`. The note ID comes from `get_issue`. At least one of `text` or `view_state` must be given. Multiple notes can be edited in a single call.
+
+**Tool:** `update_issue`
+
+**Parameters:**
+- `id` — numeric issue ID
+- `fields.notes` — array of note edits: `{ id, text?, view_state? }`; omitting `view_state` keeps the note's current visibility
+
+**Request:** _(text-only edit)_
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "notes": [
+      { "id": 88, "text": "Reproduced on version 2.0.4 — auth middleware is missing a null check." }
+    ]
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 1042,
+  "summary": "Login button unresponsive on mobile Safari",
+  "notes": [
+    {
+      "id": 88,
+      "text": "Reproduced on version 2.0.4 — auth middleware is missing a null check.",
+      "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"
+}
+```
+
+> **Note:** Unknown note IDs are rejected before any write. If MantisBT did not apply an edit, the response contains `notes_error` with the details instead of failing the call — only when the note edit was the only requested change does the call return an error. To add a new note use the `note` parameter or `add_note`.
+
+---
+
 ## File Attachments
 
 ### Upload a local file
@@ -969,36 +1145,45 @@ Attaches a file by passing its base64-encoded content directly. Use this **only*
 
 ### List attachments
 
-Returns all file attachments for an issue.
+Returns all file attachments for an issue using server-side field projection. Each attachment includes a `download_url` built from the MantisBT file download endpoint.
 
-**Tool:** `list_issue_files`
+**Tool:** `get_issue`
 
 **Parameters:**
-- `issue_id` — numeric issue ID
+- `id` — numeric 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"
+}
 ```
 
+> **Deprecated:** `list_issue_files` will be removed in 2.0.0 — use `get_issue` with `select: "id,attachments"` as shown above.
+
 ---
 
 ## Relationships
@@ -1261,7 +1446,70 @@ Read `tags[].id` from the response.
 
 ## Monitors (Watchers)
 
-### Add a watcher
+### Change watchers via update_issue
+
+Adds and/or removes watchers (monitors) of an issue in a single `update_issue` call. `fields` may be omitted — only `add_monitors`, `remove_monitors`, or both are required. Names are matched case-insensitively.
+
+**Tool:** `update_issue`
+
+**Parameters:**
+- `id` — numeric issue ID
+- `add_monitors` — _(optional)_ array of MantisBT login names to add as watchers
+- `remove_monitors` — _(optional)_ array of MantisBT login names to remove from watchers; names not currently watching are silently skipped
+- A user listed in both arrays is rejected.
+
+**Request:** _(add one watcher)_
+
+```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:** _(remove one watcher)_
+
+```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` always lists all remaining watchers. `monitors.added` lists names successfully added; `monitors.removed` lists names successfully removed; `monitors.not_monitoring` lists names that were not watching and were therefore skipped. Adding or removing other users requires the `monitor_add_others_bug_threshold` / `monitor_delete_others_bug_threshold` access level. The steps run in order — `fields`, monitors, `note`. Once one of them succeeded, a later failure is reported inline as `monitors_error` or `note_error` (nothing is rolled back); only when every requested step failed does the call return an error.
+
+---
+
+### Add a watcher (deprecated)
+
+> **Deprecated:** use `update_issue` with `add_monitors` instead — `add_monitor` will be removed in 2.0.0.
 
 Subscribes a user to notifications for an issue.
 
@@ -1269,7 +1517,7 @@ Subscribes a user to notifications for an issue.
 
 **Parameters:**
 - `issue_id` — numeric issue ID
-- `username` — username string
+- `username` — MantisBT login name
 
 **Request:**
 
@@ -1283,12 +1531,19 @@ Subscribes a user to notifications for an issue.
 **Response:**
 
 ```json
-{ "success": true }
+{
+  "success": true,
+  "monitors": ["asmith", "jsmith"]
+}
 ```
 
+`monitors` lists all users now watching the issue. Adding a user who already watches it changes nothing and still succeeds. Adding another user requires the `monitor_add_others_bug_threshold` access level.
+
 ---
 
-### Remove a watcher
+### Remove a watcher (deprecated)
+
+> **Deprecated:** use `update_issue` with `remove_monitors` instead — `remove_monitor` will be removed in 2.0.0.
 
 Unsubscribes a user from notifications for an issue.
 
@@ -1296,7 +1551,7 @@ Unsubscribes a user from notifications for an issue.
 
 **Parameters:**
 - `issue_id` — numeric issue ID
-- `username` — username string
+- `username` — MantisBT login name (case-insensitive)
 
 **Request:**
 
@@ -1310,9 +1565,15 @@ Unsubscribes a user from notifications for an issue.
 **Response:**
 
 ```json
-{ "success": true }
+{
+  "success": true,
+  "removed": true,
+  "monitors": ["asmith"]
+}
 ```
 
+`monitors` lists the users still watching the issue. If `jsmith` was not a monitor, nothing is changed and the response contains `"removed": false` plus a `message`. Removing another user requires the `monitor_delete_others_bug_threshold` access level; without it the tool returns an error.
+
 ---
 
 ## Semantic Search
@@ -1351,7 +1612,9 @@ Builds the full vector search index from scratch. Run this once after enabling s
 
 ### Incremental index update
 
-Updates the index with issues added or changed since the last build. Faster than a full rebuild.
+Updates the index with issues added or changed since the last sync. Faster than a full rebuild: only issues changed since then are fetched and re-embedded.
+
+Only one server process syncs the shared index at a time. If another process (for example another client session) is already syncing, the tool returns an error ("A search index sync is already running") — try again once that sync has finished. A sync limited to `project_id` does not advance `last_synced_at`, so changes in other projects are still picked up by the next sync.
 
 **Tool:** `rebuild_search_index`
 
@@ -1372,7 +1635,7 @@ Updates the index with issues added or changed since the last build. Faster than
 ```json
 {
   "indexed": 14,
-  "skipped": 298,
+  "skipped": 0,
   "total": 312,
   "duration_ms": 2104
 }
@@ -1382,9 +1645,9 @@ Updates the index with issues added or changed since the last build. Faster than
 
 ### Check index status
 
-Returns the number of indexed issues, total issue count, and the timestamp of the last sync.
+Returns the number of indexed issues, total issue count, and the timestamp of the last sync. `last_synced_at` is the newest `updated_at` the MantisBT server reported at that sync (server time), so it can lie before the actual time of the sync.
 
-**Tool:** `get_search_index_status`
+**Tool:** `get_metadata`
 
 **Parameters:** _(none)_
 
@@ -1394,18 +1657,27 @@ Returns the number of indexed issues, total issue count, and the timestamp of th
 {}
 ```
 
-**Response:**
+**Response (relevant excerpt):**
 
 ```json
 {
-  "summary": "312/312 (100 %)",
-  "indexed": 312,
-  "total": 312,
-  "percent": 100,
-  "last_synced_at": "2024-11-05T14:00:00.000Z"
+  "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"
+  }
 }
 ```
 
+> **Deprecated:** `get_search_index_status` will be removed in 2.0.0 — use `get_metadata` (field `search_index`) as shown above.
+
 ---
 
 ### Search by meaning
@@ -1540,68 +1812,159 @@ Shows which part of an issue matched the search query. Each result that has keyw
 
 ## Projects & Categories
 
+### Get a project with categories, users and versions
+
+Retrieves a project's master data plus any combination of its categories, users and versions in one call. Categories come without the `[All Projects]` prefix — ready for use in `create_issue`. `member_query` filters users by a case-insensitive substring in login name, real name or email, and returns all matches.
+
+**Tool:** `get_project`
+
+**Parameters:**
+- `project_id` — numeric project ID (use `list_projects` to discover)
+- `include` — _(optional)_ array of `"categories"`, `"users"`, `"versions"` (any combination)
+- `access_level` — _(optional)_ only users at or above this level (10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator); implies `"users"`
+- `member_query` — _(optional)_ case-insensitive substring; implies `"users"`, returns all matches
+- `obsolete` — _(optional)_ include obsolete versions; implies `"versions"`
+- `inherit` — _(optional)_ include versions inherited from parent projects; implies `"versions"`
+
+**Request:** _(master data + categories + users + versions)_
+
+```json
+{
+  "project_id": 3,
+  "include": ["categories", "users", "versions"]
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": 3,
+  "name": "Webshop",
+  "description": "Main customer-facing storefront",
+  "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:** _(member search)_
+
+```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" } }
+  ]
+}
+```
+
+> **Note:** `get_project_categories`, `get_project_users`, `get_project_versions`, and `find_project_member` are deprecated in favour of `get_project` with `include` / `member_query` and will be removed in 2.0.0.
+
+---
+
 ### List project categories
 
 Returns all categories available for a MantisBT project. Use the returned names directly when creating issues.
 
-**Tool:** `get_project_categories`
+**Tool:** `get_project`
 
 **Parameters:**
 - `project_id` — numeric project 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" }
+  ]
+}
 ```
 
 > **Note:** Category names prefixed with `[All Projects]` (inherited from the global project) have the prefix automatically stripped in the response.
 
+> **Deprecated:** `get_project_categories` will be removed in 2.0.0 — use `get_project` with `include: ["categories"]` as shown above.
+
 ---
 
 ### Find a project member
 
-Searches project members by name, real name, or email. The search is case-insensitive and matches any substring. Results are served from the metadata cache when available; falls back to a live API call on a cold cache.
+Searches project members by name, real name, or email. The search is case-insensitive and matches any substring. All matching users are returned — there is no `limit`.
 
-**Tool:** `find_project_member`
+**Tool:** `get_project`
 
 **Parameters:**
 - `project_id` — numeric project ID
-- `query` — _(optional)_ substring to match against `name`, `real_name`, or `email`
-- `limit` — _(optional)_ maximum number of results, default 10, max 100
+- `member_query` — substring to match against `name`, `real_name`, or `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" } }
+  ]
+}
 ```
 
-> **Tip:** Omit `query` to list all members of the project (up to `limit`).
+> **Deprecated:** `find_project_member` will be removed in 2.0.0 — use `get_project` with `member_query` as shown above. Unlike `find_project_member`, `get_project` has no `limit` and returns all matching users.
 
 ---
 
@@ -1656,12 +2019,13 @@ Updates an existing version of a MantisBT project. Only the fields you pass are
 
 **Parameters:**
 - `project_id` — numeric project ID
-- `version_id` — numeric version ID (use `get_project_versions` to discover)
+- `version_id` — numeric version ID (use `get_project` with `include: ["versions"]` to discover)
 - `name` — _(optional)_ new version name (must be unique within the project)
 - `description` — _(optional)_ new version description
 - `released` — _(optional)_ released flag
 - `obsolete` — _(optional)_ obsolete flag
 - `timestamp` — _(optional)_ version date as ISO 8601 string
+- `next_version` — _(optional, only with `released: true`)_ name of a follow-up version to create as an unreleased placeholder, e.g. `"1.2.1"`; used as-is — no automatic numbering
 
 **Request:** _(mark a version as obsolete)_
 
@@ -1685,9 +2049,46 @@ Updates an existing version of a MantisBT project. Only the fields you pass are
 }
 ```
 
+**Request:** _(release a version and create a follow-up placeholder)_
+
+```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"
+  }
+}
+```
+
+Setting `released=true` does not change the version date — always pass `timestamp` with the release date. If creating the follow-up version fails, the update itself stays in effect and the error is reported as `next_version_error` in the response.
+
 ---
 
-### Release a version and create the next bugfix placeholder
+### Release a version and create the next bugfix placeholder (deprecated)
+
+> **Deprecated:** use `update_version` with `released: true`, `timestamp`, and optionally `next_version` instead — `release_version` will be removed in 2.0.0. See [Update a project version](#update-a-project-version) for the replacement recipe.
 
 Marks a version as released (setting its date) and creates a follow-up version placeholder in the same call. The follow-up version name is used as-is — no automatic numbering. If the follow-up creation fails, the release stays in effect and the error is reported in `next_version_error`.
 
@@ -1733,7 +2134,7 @@ Marks a version as released (setting its date) and creates a follow-up version p
 }
 ```
 
-> **Note:** Setting `released=true` via `update_version` does not change the version date — use `release_version` when you want to set both in one step.
+> **Note:** Setting `released=true` via `update_version` does not change the version date — always pass `timestamp` for the release date. Use `next_version` to create a follow-up version in the same call.
 
 ---
 
@@ -1774,9 +2175,11 @@ Returns a compact overview of all cached metadata: total project and tag counts,
 
 **Tool:** `get_metadata`
 
-**Parameters:** _(none)_
+**Parameters:**
+- `detail` — _(optional)_ `"summary"` (default) for counts only; `"full"` for the complete raw cache
+- `refresh` — _(optional)_ `true` to re-fetch all metadata from MantisBT before answering; default `false`
 
-**Request:**
+**Request:** _(summary, from cache)_
 
 ```json
 {}
@@ -1797,36 +2200,75 @@ Returns a compact overview of all cached metadata: total project and tag counts,
 }
 ```
 
-> **Note:** For full lists use `list_projects`, `get_project_users`, `get_project_versions`, `get_project_categories`, `list_tags`, or `get_metadata_full`.
+With `MANTIS_SEARCH_ENABLED=true` the response also contains a `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"
+  }
+}
+```
+
+> **Note:** For full lists use `list_projects`, `get_project` (with `include`), or `list_tags`.
+
+---
+
+### Refresh the metadata cache
+
+Forces a fresh fetch of all metadata from MantisBT before returning the summary.
+
+**Tool:** `get_metadata`
+
+**Parameters:**
+- `refresh` — `true`
+
+**Request:**
+
+```json
+{ "refresh": true }
+```
+
+**Response:** same shape as the summary above, with `cached_at` updated to now.
 
 ---
 
 ### Get the full metadata cache
 
-Returns the complete raw metadata cache as minified JSON. Contains all projects with their full field set, plus users, versions, and categories per project, and all tags. Use this when you need the complete data in a single call.
+Returns the complete raw metadata cache as minified JSON. The cache structure is `{ timestamp, projects, byProject: {"<id>": { users, versions, categories }}, tags }`.
 
-**Tool:** `get_metadata_full`
+**Tool:** `get_metadata`
 
-**Parameters:** _(none)_
+**Parameters:**
+- `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 }
@@ -1836,81 +2278,57 @@ Returns the complete raw metadata cache as minified JSON. Contains all projects
         { "id": 2, "name": "UI" }
       ]
     }
-  ],
+  },
   "tags": [
     { "id": 1, "name": "regression" },
     { "id": 2, "name": "hotfix" }
-  ],
-  "cached_at": "2026-03-27T09:00:00.000Z"
+  ]
 }
 ```
 
-> **Tip:** `get_metadata` provides the same data as a compact summary (counts only). Use `get_metadata_full` when you need the actual arrays.
+> **Deprecated:** `get_metadata_full` will be removed in 2.0.0 — use `get_metadata` with `detail: "full"` as shown above.
 
 ---
 
 ## Version & Diagnostics
 
-### Get MCP server version
-
-Returns the version of this mantisbt-mcp-server instance.
-
-**Tool:** `get_mcp_version`
-
-**Parameters:** _(none)_
-
-**Request:**
+### Get versions (MCP server and MantisBT)
 
-```json
-{}
-```
+Returns the version of this mantisbt-mcp-server and of the connected MantisBT installation in one response. With `check_latest: true` (default) the MantisBT version is compared against the latest release on GitHub (outbound HTTPS, up to 5 s). If MantisBT cannot be reached, `mantis` holds an `error` and the MCP server version is still returned.
 
-**Response:**
-
-```json
-{
-  "version": "1.5.8"
-}
-```
-
----
-
-### Get MantisBT version
-
-Returns the version of the connected MantisBT installation and optionally compares it against the latest official release on GitHub.
-
-**Tool:** `get_mantis_version`
+**Tool:** `get_version`
 
 **Parameters:**
-- `check_latest` — _(optional)_ whether to compare against the latest GitHub release; default `true`
+- `check_latest` — _(optional)_ compare MantisBT against the latest GitHub release; default `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"
+  }
 }
 ```
 
-Possible values for `status`: `up-to-date`, `update-available`, `newer-than-release`, `unknown`.
+Possible values for `status`: `up-to-date`, `update-available`, `newer-than-release`, `unknown`. Set `check_latest: false` to skip the GitHub comparison.
 
-> **Note:** The GitHub comparison requires an outbound HTTPS request. Set `check_latest` to `false` to skip it.
+> **Deprecated:** `get_mcp_version` and `get_mantis_version` will be removed in 2.0.0 — use `get_version` as shown above.
 
 ---
 
 ### Get the current user
 
-Returns the profile of the user associated with the configured API key. Useful to verify the connection and confirm which account is being used.
+Returns the profile of the user associated with the configured API key. Useful to verify the connection and confirm which account is being used. The `language` field tells you which MantisBT language is configured for this user — use it as a hint for the language to write issue texts and notes in, and expect localized enum labels in that language.
 
 **Tool:** `get_current_user`
 
@@ -1930,6 +2348,7 @@ Returns the profile of the user associated with the configured API key. Useful t
   "name": "jsmith",
   "real_name": "John Smith",
   "email": "jsmith@example.com",
+  "language": "english",
   "access_level": { "id": 55, "name": "developer" }
 }
 ```
@@ -1972,7 +2391,7 @@ Returns all MantisBT projects accessible with the configured API key.
 
 **Resource URI:** `mantis://projects`
 
-**Fetch behaviour:** Served from the MetadataCache (default TTL 24 h). Falls back to a live API call when the cache is empty. Run `sync_metadata` to force a refresh.
+**Fetch behaviour:** Served from the MetadataCache (default TTL 24 h). Falls back to a live API call when the cache is empty. Run `get_metadata` with `refresh: true` to force a refresh.
 
 **Response:**
 
@@ -2062,7 +2481,7 @@ Returns valid ID/name pairs for all issue enum fields (severity, priority, statu
 }
 ```
 
-> **Tip:** The `get_issue_enums` tool provides the same data for clients that do not support Resources.
+> **Tip:** The `get_issue_schema` tool provides enum values for clients that do not support Resources (and also returns the valid `select` fields).
 
 ---
 
@@ -2088,7 +2507,7 @@ Collects structured bug data and calls `create_issue`.
 - `actual` — actual (observed) behavior
 - `environment` — environment details (OS, browser, version, etc.)
 
-**What happens:** The prompt returns a message that instructs the LLM to call `get_issue_enums` (to resolve valid severity/priority values) and then `create_issue` with the provided data.
+**What happens:** The prompt returns a message that instructs the LLM to call `get_issue_schema` (to resolve valid severity/priority values) and then `create_issue` with the provided data.
 
 **Example call:**
 
@@ -2182,6 +2601,8 @@ Lists all issues for a project and generates a status report grouped by severity
 
 ## Destructive Operations
 
+> To hide all destructive tools at once — e.g. for a session that should never delete anything — set `MANTIS_DISABLE_DESTRUCTIVE=true`; see [Offer only some tool groups](#offer-only-some-tool-groups).
+
 ### Delete an issue
 
 Permanently deletes a MantisBT issue. This action cannot be undone.