@dpesch/mantisbt-mcp-server 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -11,6 +11,25 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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

@@ -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

@@ -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/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).