@dpesch/mantisbt-mcp-server 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.14.0] – 2026-09-27
+
+### Fixed
+
+- `create_issue` / `update_issue`: a `custom_fields` entry without `value` is now rejected with a validation error. Previously it was accepted and the literal string `"undefined"` was written to the custom field.
+
+### Changed
+
+- **Minimum Node.js version is now 22** (`engines: >=22`). Node.js 18 and 20 are end-of-life and no longer receive security updates; the test toolchain (vitest 5) no longer runs on them, so they could not be tested anymore. CI now runs on Node.js 22. Users on Node.js 20 or older should upgrade — npm only warns about the `engines` mismatch, but these versions are no longer tested.
+- Dependencies: `zod` 4 (the MCP SDK supports `^3.25 || ^4`). Tool parameters, types and defaults are unchanged. The published JSON schemas differ slightly: nested `$ref`s are inlined, integer IDs carry an explicit `maximum`, and objects no longer declare `additionalProperties: false` (unknown keys were and still are ignored).
+- Dependencies: `@huggingface/transformers` 4 for the optional semantic search. Embeddings are numerically identical to version 3 (verified with the default model), so existing search indexes stay valid — no rebuild needed. This also resolves the `sharp` security advisories reported by `npm audit`.
+- Dependencies: `@modelcontextprotocol/sdk` minimum raised to ^1.30.1; transitive dependencies updated to resolve all `npm audit` advisories (including a critical one in `tar`).
+- Dev dependencies: vitest and `@vitest/coverage-v8` 5, `@types/node` 22 (matching the minimum Node.js version).
+- CI: the publish job now checks `NPM_TOKEN` and `GH_RELEASE_TOKEN` before `npm publish`, so an empty or invalid token stops the release before anything is published. Each publish step (npm, Codeberg release, GitHub release) is skipped when its target already exists, so re-running a failed job only catches up on what is missing.
+
+---
+
+## [1.13.0] – 2026-09-27
+
+### Added
+
+- `create_version` — create a new version in a MantisBT project; returns the created version object (id, name, description, released, obsolete, timestamp)
+- `update_version` — update an existing version; only passed fields change (at least one required); renaming rewrites version/target_version/fixed_in_version on all referencing issues; requires `manage_project_threshold` (default: manager)
+- `release_version` — mark a version as released (sets its date, default now) and optionally create a follow-up version in the same step via `next_version`; requires `manage_project_threshold` (default: manager)
+- `delete_version` — permanently delete a version; irreversible — MantisBT clears version/target_version/fixed_in_version on all referencing issues; requires `manage_project_threshold` (default: manager)
+- Version writes are mirrored into the local metadata cache without resetting its timestamp, so `get_metadata` and the project resources stay current without extending the cache TTL.
+- New cookbook recipes (EN/DE) for creating, updating, releasing and deleting versions, plus matching prompt examples in `docs/examples.md` and `docs/examples.de.md`.
+
+### Changed
+
+- `get_project_versions` description now documents the `timestamp` field returned per version and cross-references the new version write tools (`create_version`, `update_version`, `release_version`, `delete_version`)
+- German documentation (`README.de.md`, `docs/cookbook.de.md`, `docs/examples.de.md`) now uses the en dash (–) as Gedankenstrich instead of the em dash.
+- CI: the release job checks the npm token before publishing, and failing Codeberg/GitHub release API calls now fail the job instead of passing silently.
+
+---
+
 ## [1.12.0] – 2026-08-28
 
 ### Added

package/README.de.md

@@ -12,7 +12,7 @@ Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) Server, der
 
 ## Voraussetzungen
 
-- Node.js ≥ 18
+- Node.js ≥ 22
 - MantisBT-Installation mit aktivierter REST-API (ab Version 2.23)
 - MantisBT API-Token (unter *Mein Konto → API-Token* erstellen)
 
@@ -68,21 +68,21 @@ npm run build
 
 | Variable | Pflicht | Standard | Beschreibung |
 |---|---|---|---|
-| `MANTIS_BASE_URL` | ✅ | – | Basis-URL der MantisBT-Installation. Beide Formate werden akzeptiert: `https://deine-mantis-instanz.example.com` und `https://deine-mantis-instanz.example.com/api/rest` — das `/api/rest`-Suffix wird automatisch normalisiert. |
+| `MANTIS_BASE_URL` | ✅ | – | Basis-URL der MantisBT-Installation. Beide Formate werden akzeptiert: `https://deine-mantis-instanz.example.com` und `https://deine-mantis-instanz.example.com/api/rest` – das `/api/rest`-Suffix wird automatisch normalisiert. |
 | `MANTIS_API_KEY` | ✅ | – | API-Token für die Authentifizierung |
-| `MANTIS_USE_INDEX_PHP` | – | auto | Auf `true` setzen, wenn URL-Rewriting nicht verfügbar ist — REST-Anfragen verwenden dann `/api/rest/index.php/` statt `/api/rest/`. Wird automatisch erkannt, wenn `MANTIS_BASE_URL` auf `/api/rest/index.php` endet; ein explizit gesetzter Wert hat immer Vorrang. Siehe [Cookbook](docs/cookbook.de.md#installation-ohne-url-rewriting-anbinden). |
+| `MANTIS_USE_INDEX_PHP` | – | auto | Auf `true` setzen, wenn URL-Rewriting nicht verfügbar ist – REST-Anfragen verwenden dann `/api/rest/index.php/` statt `/api/rest/`. Wird automatisch erkannt, wenn `MANTIS_BASE_URL` auf `/api/rest/index.php` endet; ein explizit gesetzter Wert hat immer Vorrang. Siehe [Cookbook](docs/cookbook.de.md#installation-ohne-url-rewriting-anbinden). |
 | `MANTIS_CACHE_DIR` | – | `~/.cache/mantisbt-mcp` | Verzeichnis für den Metadaten-Cache |
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache-Lebensdauer in Sekunden |
 | `TRANSPORT` | – | `stdio` | Transport-Modus: `stdio` oder `http` |
 | `PORT` | – | `3000` | Port für HTTP-Modus |
-| `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind-Adresse für HTTP-Modus. **Geändert von `0.0.0.0` auf `127.0.0.1`** — der Server horcht standardmäßig nur auf localhost. Für Docker oder Remote-Zugriff `0.0.0.0` setzen. |
-| `MCP_HTTP_TOKEN` | ✅ (HTTP-Modus) | – | Bearer-Token für den `/mcp`-Endpunkt (`Authorization: Bearer <token>`). **Pflicht bei `TRANSPORT=http`** — der Server startet im HTTP-Modus ohne diesen Wert nicht, damit Tools nie unauthentifiziert erreichbar sind. Im stdio-Modus ohne Bedeutung. `/health` ist immer öffentlich. |
+| `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind-Adresse für HTTP-Modus. **Geändert von `0.0.0.0` auf `127.0.0.1`** – der Server horcht standardmäßig nur auf localhost. Für Docker oder Remote-Zugriff `0.0.0.0` setzen. |
+| `MCP_HTTP_TOKEN` | ✅ (HTTP-Modus) | – | Bearer-Token für den `/mcp`-Endpunkt (`Authorization: Bearer <token>`). **Pflicht bei `TRANSPORT=http`** – der Server startet im HTTP-Modus ohne diesen Wert nicht, damit Tools nie unauthentifiziert erreichbar sind. Im stdio-Modus ohne Bedeutung. `/health` ist immer öffentlich. |
 | `MANTIS_SEARCH_ENABLED` | – | `false` | Auf `true` setzen, um die semantische Suche zu aktivieren |
 | `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vektorspeicher: `vectra` (reines JS) oder `sqlite-vec` (manuelle Installation erforderlich) |
 | `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Verzeichnis für den Suchindex |
 | `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding-Modell (wird beim ersten Start einmalig heruntergeladen, ~80 MB) |
 | `MANTIS_SEARCH_THREADS` | – | `1` | Anzahl der ONNX-Intra-Op-Threads für das Embedding-Modell. Standard ist 1, um CPU-Sättigung auf Mehrkernsystemen und in WSL zu verhindern. Nur erhöhen, wenn die Indexierungsgeschwindigkeit kritisch ist und der Host ausschließlich für diese Last vorgesehen ist. |
-| `MANTIS_UPLOAD_DIR` | – | – | Schränkt den `file_path` von `upload_file` auf dieses Verzeichnis ein (Pfad-Traversal via `../` wird blockiert). Im **stdio-Modus** ist `file_path` ohne diese Variable unbeschränkt. Im **HTTP-Modus** liest `file_path` aus dem Dateisystem des Servers und ist deshalb **deaktiviert, sofern diese Variable nicht gesetzt ist** — HTTP-Clients sollten stattdessen den Parameter `content` (Base64) verwenden. |
+| `MANTIS_UPLOAD_DIR` | – | – | Schränkt den `file_path` von `upload_file` auf dieses Verzeichnis ein (Pfad-Traversal via `../` wird blockiert). Im **stdio-Modus** ist `file_path` ohne diese Variable unbeschränkt. Im **HTTP-Modus** liest `file_path` aus dem Dateisystem des Servers und ist deshalb **deaktiviert, sofern diese Variable nicht gesetzt ist** – HTTP-Clients sollten stattdessen den Parameter `content` (Base64) verwenden. |
 
 ## Verfügbare Tools
 
@@ -92,9 +92,9 @@ npm run build
 |---|---|
 | `get_issue` | Ein Issue anhand seiner ID abrufen; optionales `select` zur Feldauswahl reduziert die Antwortgröße |
 | `get_issues` | Mehrere Issues per ID in einem Aufruf abrufen (1–50 IDs); nicht zugängliche IDs liefern `null` an ihrer Position, statt den gesamten Aufruf abzubrechen |
-| `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern; optionales `select` für Feldprojektion und `status` für clientseitige Statusfilterung — kanonische englische Statusnamen (z.B. `"new"`, `"resolved"`) werden per ID abgeglichen und funktionieren damit sprachunabhängig auf lokalisierten Installationen |
-| `create_issue` | Neues Issue anlegen; `severity` und `priority` müssen kanonische englische Namen sein (z.B. `minor`, `major`, `normal`, `high`) — `get_issue_enums` aufrufen, um alle gültigen Werte und deren lokalisierte Bezeichnungen zu sehen; optionaler `handler`-Parameter akzeptiert einen Benutzernamen als Alternative zu `handler_id` (wird gegen die Projektmitglieder aufgelöst); optionales `custom_fields` zum Setzen benutzerdefinierter Felder |
-| `update_issue` | Bestehendes Issue bearbeiten; Enum-Felder (`status`, `priority`, `severity`, `resolution`, `reproducibility`) akzeptieren kanonische englische Namen, lokalisierte Namen oder numerische IDs — der Server löst Namen automatisch zu IDs auf; unterstützt `custom_fields` sowie einen optionalen `note`-Parameter, der im selben Aufruf eine Notiz anhängt (z.B. die Begründung eines Status-Wechsels) |
+| `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern; optionales `select` für Feldprojektion und `status` für clientseitige Statusfilterung – kanonische englische Statusnamen (z.B. `"new"`, `"resolved"`) werden per ID abgeglichen und funktionieren damit sprachunabhängig auf lokalisierten Installationen |
+| `create_issue` | Neues Issue anlegen; `severity` und `priority` müssen kanonische englische Namen sein (z.B. `minor`, `major`, `normal`, `high`) – `get_issue_enums` aufrufen, um alle gültigen Werte und deren lokalisierte Bezeichnungen zu sehen; optionaler `handler`-Parameter akzeptiert einen Benutzernamen als Alternative zu `handler_id` (wird gegen die Projektmitglieder aufgelöst); optionales `custom_fields` zum Setzen benutzerdefinierter Felder |
+| `update_issue` | Bestehendes Issue bearbeiten; Enum-Felder (`status`, `priority`, `severity`, `resolution`, `reproducibility`) akzeptieren kanonische englische Namen, lokalisierte Namen oder numerische IDs – der Server löst Namen automatisch zu IDs auf; unterstützt `custom_fields` sowie einen optionalen `note`-Parameter, der im selben Aufruf eine Notiz anhängt (z.B. die Begründung eines Status-Wechsels) |
 | `delete_issue` | Issue löschen |
 
 ### Notizen
@@ -139,20 +139,24 @@ npm run build
 | Tool | Beschreibung |
 |---|---|
 | `list_projects` | Alle zugänglichen Projekte auflisten; gibt normalisierte Projektdaten zurück (konsistent mit dem `sync_metadata`-Cache) |
-| `get_project_versions` | Versionen eines Projekts abrufen; optionale Booleans `obsolete` und `inherit` für veraltete bzw. vom Elternprojekt geerbte Versionen |
+| `get_project_versions` | Versionen eines Projekts abrufen; optionale Booleans `obsolete` und `inherit` für veraltete bzw. vom Elternprojekt geerbte Versionen; jede Version enthält ein `timestamp`-Feld (Versionsdatum); zum Ändern siehe `create_version`, `update_version`, `release_version`, `delete_version` |
+| `create_version` | Neue Version in einem Projekt erstellen; gibt das erstellte Versionsobjekt zurück (id, name, description, released, obsolete, timestamp); erfordert `manage_project_threshold` (Standard: Manager) |
+| `update_version` | Bestehende Version aktualisieren; nur übergebene Felder werden geändert (mindestens eines erforderlich); Umbenennen schreibt version/target_version/fixed_in_version aller referenzierenden Issues neu; erfordert `manage_project_threshold` (Standard: Manager) |
+| `release_version` | Version als veröffentlicht markieren und Datum setzen (Standard: jetzt); optional eine Folgeversion im gleichen Schritt anlegen via `next_version`; erfordert `manage_project_threshold` (Standard: Manager) |
+| `delete_version` | Version dauerhaft löschen – nicht umkehrbar, MantisBT leert version/target_version/fixed_in_version aller referenzierenden Issues; `update_version` mit `obsolete=true` als nicht-destruktive Alternative bevorzugen; erfordert `manage_project_threshold` (Standard: Manager) |
 | `get_project_categories` | Kategorien eines Projekts abrufen |
 | `get_project_users` | Benutzer eines Projekts abrufen |
 | `find_project_member` | Projektmitglieder nach Name, Realname oder E-Mail suchen (Teilstring-Suche, Groß-/Kleinschreibung ignoriert); optionale Parameter `query` und `limit` (Standard 10, max. 100); Cache-first |
 
 ### Semantische Suche *(optional)*
 
-Statt einfachem Keyword-Matching versteht die semantische Suche die *Bedeutung* einer Anfrage. Formuliere in natürlicher Sprache — die Suche findet konzeptuell verwandte Issues, auch wenn die genauen Begriffe nicht übereinstimmen:
+Statt einfachem Keyword-Matching versteht die semantische Suche die *Bedeutung* einer Anfrage. Formuliere in natürlicher Sprache – die Suche findet konzeptuell verwandte Issues, auch wenn die genauen Begriffe nicht übereinstimmen:
 
-- *„Login funktioniert nach Passwort-Reset nicht"* — findet Issues rund um Authentifizierungsgrenzfälle
-- *„Performance-Probleme auf der Checkout-Seite"* — liefert verwandte Meldungen unabhängig von der verwendeten Terminologie
-- *„doppelte Einträge in der Rechnungsliste"* — erkennt auch Issues, die als „zweifach angezeigt", „dupliziert" o.ä. beschrieben sind
+- *„Login funktioniert nach Passwort-Reset nicht"* – findet Issues rund um Authentifizierungsgrenzfälle
+- *„Performance-Probleme auf der Checkout-Seite"* – liefert verwandte Meldungen unabhängig von der verwendeten Terminologie
+- *„doppelte Einträge in der Rechnungsliste"* – erkennt auch Issues, die als „zweifach angezeigt", „dupliziert" o.ä. beschrieben sind
 
-Das Embedding-Modell (~80 MB) läuft vollständig **offline** — kein OpenAI-Key, keine externe API. Es wird beim ersten Start einmalig heruntergeladen und lokal gecacht. Issues werden bei jedem Serverstart inkrementell indexiert (nur neue und geänderte Issues werden neu verarbeitet).
+Das Embedding-Modell (~80 MB) läuft vollständig **offline** – kein OpenAI-Key, keine externe API. Es wird beim ersten Start einmalig heruntergeladen und lokal gecacht. Issues werden bei jedem Serverstart inkrementell indexiert (nur neue und geänderte Issues werden neu verarbeitet).
 
 Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
 
@@ -190,13 +194,13 @@ npm install sqlite-vec better-sqlite3
 | `get_current_user` | Eigenes Benutzerprofil abrufen |
 | `list_languages` | Verfügbare Sprachen auflisten |
 | `get_config` | Server-Konfiguration (Basis-URL, Cache-TTL) anzeigen |
-| `get_issue_enums` | Gültige ID/Name-Paare für alle Enum-Felder zurückgeben (Severity, Status, Priority, Resolution, Reproducibility) — vor `create_issue` / `update_issue` verwenden, um korrekte Werte nachzuschlagen; auf lokalisierten Installationen kann jeder Eintrag ein `canonical_name`-Feld mit dem englischen Standard-API-Namen enthalten |
+| `get_issue_enums` | Gültige ID/Name-Paare für alle Enum-Felder zurückgeben (Severity, Status, Priority, Resolution, Reproducibility) – vor `create_issue` / `update_issue` verwenden, um korrekte Werte nachzuschlagen; auf lokalisierten Installationen kann jeder Eintrag ein `canonical_name`-Feld mit dem englischen Standard-API-Namen enthalten |
 | `get_mantis_version` | MantisBT-Version abrufen und auf Updates prüfen |
 | `get_mcp_version` | Version dieser mantisbt-mcp-server-Instanz zurückgeben |
 
 ## Verfügbare Ressourcen
 
-MCP-Ressourcen sind URI-adressierbare, schreibgeschützte Daten, die Clients direkt abrufen können, ohne ein Tool aufzurufen. Sie sind das dritte MCP-Primitiv neben Tools und Prompts. Hinweis: Ressourcen werden von MCP-Clients weniger breit unterstützt als Tools — bitte die Dokumentation des jeweiligen Clients prüfen.
+MCP-Ressourcen sind URI-adressierbare, schreibgeschützte Daten, die Clients direkt abrufen können, ohne ein Tool aufzurufen. Sie sind das dritte MCP-Primitiv neben Tools und Prompts. Hinweis: Ressourcen werden von MCP-Clients weniger breit unterstützt als Tools – bitte die Dokumentation des jeweiligen Clients prüfen.
 
 | Ressource-URI | Beschreibung |
 |---|---|
@@ -207,7 +211,7 @@ MCP-Ressourcen sind URI-adressierbare, schreibgeschützte Daten, die Clients dir
 
 ## Verfügbare Prompts
 
-MCP-Prompt-Templates sind Gesprächseinstiege, die den LLM anweisen, strukturierte Eingaben zu sammeln und dann das passende Tool aufzurufen. Es handelt sich nicht um Tools — sie starten einen geführten Arbeitsablauf.
+MCP-Prompt-Templates sind Gesprächseinstiege, die den LLM anweisen, strukturierte Eingaben zu sammeln und dann das passende Tool aufzurufen. Es handelt sich nicht um Tools – sie starten einen geführten Arbeitsablauf.
 
 | Prompt | Pflichtargumente | Optionale Argumente | Beschreibung |
 |---|---|---|---|
@@ -218,7 +222,7 @@ MCP-Prompt-Templates sind Gesprächseinstiege, die den LLM anweisen, strukturier
 
 ## HTTP-Modus
 
-Für den Einsatz als eigenständiger Server (z.B. in Remote-Setups). `MCP_HTTP_TOKEN` ist im HTTP-Modus **Pflicht** — der Server startet ohne diesen Wert nicht:
+Für den Einsatz als eigenständiger Server (z.B. in Remote-Setups). `MCP_HTTP_TOKEN` ist im HTTP-Modus **Pflicht** – der Server startet ohne diesen Wert nicht:
 
 ```bash
 MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
@@ -229,14 +233,14 @@ MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
 #   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
 ```
 
-Jede `/mcp`-Anfrage muss `Authorization: Bearer <token>` senden. Im HTTP-Modus ist der `file_path` von `upload_file` deaktiviert, sofern `MANTIS_UPLOAD_DIR` nicht gesetzt ist — stattdessen den Parameter `content` (Base64) verwenden.
+Jede `/mcp`-Anfrage muss `Authorization: Bearer <token>` senden. Im HTTP-Modus ist der `file_path` von `upload_file` deaktiviert, sofern `MANTIS_UPLOAD_DIR` nicht gesetzt ist – stattdessen den Parameter `content` (Base64) verwenden.
 
 Healthcheck: `GET http://localhost:3456/health` (immer öffentlich, kein Token erforderlich)
 
 ## Dokumentation
 
-- [**Cookbook**](docs/cookbook.de.md) — Tool-orientierte Rezepte mit direkt verwendbaren Parameter-Beispielen für alle registrierten Tools
-- [**Anwendungsbeispiele**](docs/examples.de.md) — Beispiele in natürlicher Sprache für alltägliche Anwendungsfälle (keine Tool-Namen erforderlich)
+- [**Cookbook**](docs/cookbook.de.md) – Tool-orientierte Rezepte mit direkt verwendbaren Parameter-Beispielen für alle registrierten Tools
+- [**Anwendungsbeispiele**](docs/examples.de.md) – Beispiele in natürlicher Sprache für alltägliche Anwendungsfälle (keine Tool-Namen erforderlich)
 
 ## Entwicklung
 

package/README.md

@@ -12,7 +12,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that i
 
 ## Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 22
 - MantisBT installation with REST API enabled (version 2.23+)
 - MantisBT API token (create under *My Account → API Tokens*)
 
@@ -139,7 +139,11 @@ npm run build
 | Tool | Description |
 |---|---|
 | `list_projects` | List all accessible projects; returns normalized project data (consistent with `sync_metadata` cache) |
-| `get_project_versions` | Get versions of a project; optional `obsolete` and `inherit` booleans to include obsolete or parent-inherited versions |
+| `get_project_versions` | Get versions of a project; optional `obsolete` and `inherit` booleans to include obsolete or parent-inherited versions; each version includes a `timestamp` field (version date); see `create_version`, `update_version`, `release_version`, `delete_version` to modify versions |
+| `create_version` | Create a new version in a project; returns the created version object (id, name, description, released, obsolete, timestamp); requires `manage_project_threshold` (default: manager) |
+| `update_version` | Update an existing version; only the fields you pass are changed (at least one required); renaming rewrites version/target_version/fixed_in_version on all referencing issues; requires `manage_project_threshold` (default: manager) |
+| `release_version` | Mark a version as released and set its date (default: now); optionally create a follow-up version in the same step via `next_version`; requires `manage_project_threshold` (default: manager) |
+| `delete_version` | Permanently delete a version — irreversible, MantisBT clears version/target_version/fixed_in_version on all referencing issues; prefer `update_version` with `obsolete=true` as the non-destructive alternative; requires `manage_project_threshold` (default: manager) |
 | `get_project_categories` | Get categories of a project |
 | `get_project_users` | Get users of a project |
 | `find_project_member` | Search project members by name, real name, or email (case-insensitive substring match); optional `query` and `limit` (default 10, max 100); cache-first |

package/dist/cache.js

@@ -56,6 +56,24 @@ export class MetadataCache {
         };
         await writeFile(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
     }
+    /**
+     * Applies `mutate` to the cached version list of every project and writes the
+     * result back with the original timestamp — a partial update must not extend
+     * the TTL of the remaining metadata. No-op when no cache file exists.
+     */
+    async patchVersions(mutate) {
+        let file;
+        try {
+            file = JSON.parse(await readFile(this.filePath, 'utf-8'));
+        }
+        catch {
+            return;
+        }
+        for (const [projectId, meta] of Object.entries(file.data.byProject)) {
+            meta.versions = mutate(Number(projectId), meta.versions);
+        }
+        await writeFile(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+    }
     async invalidate() {
         try {
             await unlink(this.filePath);

package/dist/index.js

@@ -16,6 +16,7 @@ import { registerFileTools } from './tools/files.js';
 import { registerRelationshipTools } from './tools/relationships.js';
 import { registerMonitorTools } from './tools/monitors.js';
 import { registerProjectTools } from './tools/projects.js';
+import { registerProjectVersionTools } from './tools/project-versions.js';
 import { registerUserTools } from './tools/users.js';
 import { registerFilterTools } from './tools/filters.js';
 import { registerConfigTools } from './tools/config.js';
@@ -60,6 +61,7 @@ async function createMcpServer(transport) {
     registerRelationshipTools(server, client);
     registerMonitorTools(server, client);
     registerProjectTools(server, client, cache);
+    registerProjectVersionTools(server, client, cache);
     registerUserTools(server, client);
     registerFilterTools(server, client);
     registerConfigTools(server, client, cache);

package/dist/search/tools.js

@@ -47,8 +47,7 @@ export function registerSearchTools(server, client, store, embedder) {
                 'When provided, each matching issue is fetched from MantisBT and enriched with the requested fields. ' +
                 'The relevance score is always included. Without this parameter only id and score are returned.'),
             highlight: z
-                .preprocess(coerceBool, z.boolean())
-                .default(false)
+                .preprocess(coerceBool, z.boolean().default(false))
                 .describe('If true, adds a "highlights" field per result with query terms bolded (**term**) ' +
                 'in the issue summary and a short description snippet. ' +
                 'Note: highlights are keyword-based, not semantic — some results may have no highlighted terms.'),

package/dist/tools/project-versions.js

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
+/** Drops undefined values so PATCH only touches the fields the caller set. */
+function definedFields(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+}
+const PERMISSION_NOTE = 'Requires the manage_project_threshold access level in the project (MantisBT default: manager).';
+const OWNING_PROJECT_NOTE = 'The version must belong to project_id itself: versions inherited from a parent project can only be changed via the parent\'s project_id (otherwise MantisBT answers "Version not found"). get_project_versions with inherit=false (the default) lists the project\'s own versions.';
+const projectIdSchema = z.coerce.number().int().positive().describe('Numeric ID of the project the version belongs to — use list_projects to discover project IDs');
+const versionIdSchema = z.coerce.number().int().positive().describe('Numeric version ID — use get_project_versions to discover version IDs');
+const timestampSchema = z.string().min(1).describe('Version date as ISO 8601 string, e.g. "2026-09-27" or "2026-09-27T10:00:00+02:00". Determines the order in roadmap and changelog.');
+const boolFlag = z.preprocess(coerceBool, z.boolean());
+export function registerProjectVersionTools(server, client, cache) {
+    // A failing cache update must never turn a successful API write into an error.
+    async function patchCachedVersions(mutate) {
+        try {
+            await cache?.patchVersions(mutate);
+        }
+        catch {
+            // Cache is a best-effort mirror; sync_metadata repairs it
+        }
+    }
+    async function createVersion(projectId, fields) {
+        const result = await client.post(`projects/${projectId}/versions`, definedFields(fields));
+        // Only the owning project gets the new entry — whether subprojects inherit it depends on server config
+        await patchCachedVersions((pid, versions) => (pid === projectId ? [...versions, result.version] : versions));
+        return result.version;
+    }
+    async function updateVersion(projectId, versionId, fields) {
+        const result = await client.patch(`projects/${projectId}/versions/${versionId}`, definedFields(fields));
+        // Version IDs are global, so inherited copies in subprojects are updated as well
+        await patchCachedVersions((_pid, versions) => versions.map((v) => (v.id === versionId ? result.version : v)));
+        return result.version;
+    }
+    // ---------------------------------------------------------------------------
+    // create_version
+    // ---------------------------------------------------------------------------
+    server.registerTool('create_version', {
+        title: 'Create Version',
+        description: `Create a new version in a MantisBT project. Returns the created version object (id, name, description, released, obsolete, timestamp).
+
+Version names must be unique within the project. Without timestamp, MantisBT uses the current date.
+
+${PERMISSION_NOTE}`,
+        inputSchema: z.object({
+            project_id: projectIdSchema,
+            name: z.string().trim().min(1).describe('Version name, e.g. "1.2.0"'),
+            description: z.string().optional().describe('Optional version description'),
+            released: boolFlag.optional().describe('Mark the version as released. MantisBT default: false'),
+            obsolete: boolFlag.optional().describe('Mark the version as obsolete. MantisBT default: false'),
+            timestamp: timestampSchema.optional(),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ project_id, ...fields }) => {
+        try {
+            const created = await createVersion(project_id, fields);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(created, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // update_version
+    // ---------------------------------------------------------------------------
+    server.registerTool('update_version', {
+        title: 'Update Version',
+        description: `Update an existing version of a MantisBT project. Only the fields you pass are changed. Returns the updated version object.
+
+Renaming a version also rewrites the version, target_version and fixed_in_version fields of all issues that reference it (including subprojects if versions are inherited).
+
+Setting released=true does not change the version date — pass timestamp as well, or use release_version, which does both.
+
+${OWNING_PROJECT_NOTE}
+
+${PERMISSION_NOTE}`,
+        inputSchema: z.object({
+            project_id: projectIdSchema,
+            version_id: versionIdSchema,
+            name: z.string().trim().min(1).optional().describe('New version name (must be unique within the project)'),
+            description: z.string().optional().describe('New version description'),
+            released: boolFlag.optional().describe('Released flag'),
+            obsolete: boolFlag.optional().describe('Obsolete flag'),
+            timestamp: timestampSchema.optional(),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id, version_id, ...fields }) => {
+        if (Object.keys(definedFields(fields)).length === 0) {
+            return {
+                content: [{ type: 'text', text: errorText('No fields to update — pass at least one of name, description, released, obsolete, timestamp.') }],
+                isError: true,
+            };
+        }
+        try {
+            const updated = await updateVersion(project_id, version_id, fields);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(updated, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // release_version
+    // ---------------------------------------------------------------------------
+    server.registerTool('release_version', {
+        title: 'Release Version',
+        description: `Mark a version as released and set its date (default: now). Optionally create a follow-up version in the same step.
+
+The follow-up version is only created when next_version is given; its name is used as-is — no automatic numbering.
+
+Returns { released: <version> } plus either next_version: <version> or next_version_error: <message>. The two steps are separate API calls: if creating the follow-up version fails, the release itself stays in effect and the error is reported in next_version_error.
+
+${OWNING_PROJECT_NOTE}
+
+${PERMISSION_NOTE}`,
+        inputSchema: z.object({
+            project_id: projectIdSchema,
+            version_id: versionIdSchema,
+            timestamp: timestampSchema.optional().describe('Release date as ISO 8601 string. Default: now.'),
+            next_version: z.string().trim().min(1).optional().describe('Name of a follow-up version to create as unreleased placeholder, e.g. "1.2.1". Omit to only release.'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ project_id, version_id, timestamp, next_version }) => {
+        let released;
+        try {
+            released = await updateVersion(project_id, version_id, {
+                released: true,
+                timestamp: timestamp ?? new Date().toISOString(),
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+        const result = { released };
+        if (next_version !== undefined) {
+            try {
+                result.next_version = await createVersion(project_id, { name: next_version });
+            }
+            catch (error) {
+                result.next_version_error = error instanceof Error ? error.message : String(error);
+            }
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // delete_version
+    // ---------------------------------------------------------------------------
+    server.registerTool('delete_version', {
+        title: 'Delete Version',
+        description: `Permanently delete a version of a MantisBT project. This action is irreversible.
+
+MantisBT clears the version, target_version and fixed_in_version fields of all issues that reference the deleted version (including subprojects if versions are inherited). To retire a version without touching issues, set obsolete=true via update_version instead.
+
+${OWNING_PROJECT_NOTE}
+
+${PERMISSION_NOTE}`,
+        inputSchema: z.object({
+            project_id: projectIdSchema,
+            version_id: versionIdSchema,
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ project_id, version_id }) => {
+        try {
+            await client.delete(`projects/${project_id}/versions/${version_id}`);
+            await patchCachedVersions((_pid, versions) => versions.filter((v) => v.id !== version_id));
+            return {
+                content: [{ type: 'text', text: `Version ${version_id} deleted successfully.` }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/projects.js

@@ -76,7 +76,7 @@ Prerequisites: obtain project_id from list_projects.`,
     // ---------------------------------------------------------------------------
     server.registerTool('get_project_versions', {
         title: 'Get Project Versions',
-        description: `List all versions defined for a MantisBT project. Returns an array of version objects, each containing id, name, released (boolean), obsolete (boolean), and optionally a date field.
+        description: `List all versions defined for a MantisBT project. Returns an array of version objects, each containing id, name, released (boolean), obsolete (boolean), and timestamp (version date). To create, change, release or delete versions use create_version, update_version, release_version and delete_version.
 
 Use the returned version names directly when creating or updating issues via create_issue and update_issue (version, target_version, fixed_in_version fields).
 
@@ -85,8 +85,8 @@ By default, obsolete and inherited parent-project versions are excluded. Set obs
 Prerequisites: obtain project_id from list_projects.`,
         inputSchema: z.object({
             project_id: z.coerce.number().int().positive().describe('Numeric project ID — use list_projects to discover project IDs'),
-            obsolete: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include obsolete (deprecated) versions in the response. Default: false. Set to true to see all versions including those no longer actively used.'),
-            inherit: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include versions inherited from parent projects. Default: false. Set to true for sub-projects that share versions with a parent project.'),
+            obsolete: z.preprocess(coerceBool, z.boolean().default(false)).describe('Include obsolete (deprecated) versions in the response. Default: false. Set to true to see all versions including those no longer actively used.'),
+            inherit: z.preprocess(coerceBool, z.boolean().default(false)).describe('Include versions inherited from parent projects. Default: false. Set to true for sub-projects that share versions with a parent project.'),
         }),
         annotations: {
             readOnlyHint: true,

package/dist/tools/version.js

@@ -27,7 +27,7 @@ export function registerVersionTools(server, client, versionHint, mcpVersion) {
 The version is read from the X-Mantis-Version response header sent by every API call.
 The GitHub comparison requires an outbound HTTPS request to the GitHub API.`,
         inputSchema: z.object({
-            check_latest: z.preprocess(coerceBool, z.boolean()).default(true).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
+            check_latest: z.preprocess(coerceBool, z.boolean().default(true)).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
         }),
         annotations: {
             readOnlyHint: true,