@dpesch/mantisbt-mcp-server 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -11,6 +11,41 @@ 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
+
+- Added `MANTIS_USE_INDEX_PHP=true` for MantisBT installations without URL rewriting. REST requests use `/api/rest/index.php/` instead of `/api/rest/` when enabled. Thanks to [@iantrudell](https://github.com/iantrudell) for the contribution.
+- `MANTIS_USE_INDEX_PHP` is detected automatically when `MANTIS_BASE_URL` ends with `/api/rest/index.php`, so pasting the full REST URL of an installation without URL rewriting is enough. An explicitly set value always wins; a base URL contradicting an explicit `false` is reported on stderr instead of failing silently.
+- New cookbook section "Connect to an installation without URL rewriting" in `docs/cookbook.md` and `docs/cookbook.de.md`.
+
+### Changed
+
+- `MANTIS_BASE_URL` suffix normalization is now case-insensitive, so `/API/REST` is stripped like `/api/rest`.
+- `.env.local` is now read once per process instead of once per config path, removing a duplicate file read on every startup.
+- `README.md` and `README.de.md` now link to each other, making the German translation discoverable.
+
+---
+
 ## [1.11.0] – 2026-07-03
 
 ### Added

package/README.de.md

@@ -6,6 +6,8 @@
 [![MCP Badge](https://lobehub.com/badge/mcp/dpesch-mantisbt-mcp-server)](https://lobehub.com/mcp/dpesch-mantisbt-mcp-server)
 [![MantisBT MCP Server](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server)
 
+[English](README.md) · **Deutsch**
+
 Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) Server, der die [MantisBT REST API](https://documenter.getpostman.com/view/29959/mantis-bug-tracker-rest-api) in Claude Code und andere MCP-fähige Clients integriert. Issues lesen, erstellen und bearbeiten – direkt aus dem Editor heraus.
 
 ## Voraussetzungen
@@ -66,20 +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_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
 
@@ -89,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
@@ -136,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`.
 
@@ -187,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 |
 |---|---|
@@ -204,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 |
 |---|---|---|---|
@@ -215,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=... \
@@ -226,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

@@ -6,6 +6,8 @@
 [![MCP Badge](https://lobehub.com/badge/mcp/dpesch-mantisbt-mcp-server)](https://lobehub.com/mcp/dpesch-mantisbt-mcp-server)
 [![MantisBT MCP Server](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server)
 
+**English** · [Deutsch](README.de.md)
+
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that integrates the [MantisBT REST API](https://documenter.getpostman.com/view/29959/mantis-bug-tracker-rest-api) into Claude Code and other MCP-capable clients. Read, create, and update issues directly from your editor.
 
 ## Requirements
@@ -68,6 +70,7 @@ npm run build
 |---|---|---|---|
 | `MANTIS_BASE_URL` | ✅ | – | Base URL of your MantisBT installation. Both `https://your-mantis.example.com` and `https://your-mantis.example.com/api/rest` are accepted — the `/api/rest` suffix is normalized automatically. |
 | `MANTIS_API_KEY` | ✅ | – | API token for authentication |
+| `MANTIS_USE_INDEX_PHP` | – | auto | Set to `true` when URL rewriting is unavailable — REST requests then use `/api/rest/index.php/` instead of `/api/rest/`. Detected automatically when `MANTIS_BASE_URL` ends with `/api/rest/index.php`; an explicit value always wins. See the [cookbook](docs/cookbook.md#connect-to-an-installation-without-url-rewriting). |
 | `MANTIS_CACHE_DIR` | – | `~/.cache/mantisbt-mcp` | Directory for the metadata cache |
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache lifetime in seconds |
 | `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
@@ -136,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/client.js

@@ -2,13 +2,35 @@
 // Helpers
 // ---------------------------------------------------------------------------
 /**
- * Normalise a MANTIS_BASE_URL so that it never ends with "/api/rest" or a
- * trailing slash.  The client always appends "/api/rest/<path>" itself, so
- * users who follow README examples that include "/api/rest" in the URL must
- * not end up with a doubled prefix.
+ * Recognises a MANTIS_BASE_URL that already points at the REST API, with or
+ * without the index.php front controller. Single source of truth for both
+ * stripping the suffix and detecting the entry point, so the two can never
+ * disagree. Case-insensitive: MantisBT is commonly hosted on case-insensitive
+ * servers, which is exactly the IIS/Apache-without-rewrite crowd this matters
+ * for.
+ */
+const REST_API_SUFFIX = /\/api\/rest(\/index\.php)?\/?$/i;
+/**
+ * Normalise a MANTIS_BASE_URL so that it never ends with "/api/rest",
+ * "/api/rest/index.php", or a trailing slash. The client appends the REST API
+ * prefix itself, so URLs that already include it must not produce a doubled
+ * prefix.
+ *
+ * The "/index.php" part is stripped regardless of the useIndexPhp flag — this
+ * function only produces the bare host prefix. Whether requests then route
+ * through index.php is answered by usesIndexPhpEntryPoint() on the
+ * *unnormalised* URL.
  */
 export function normalizeBaseUrl(url) {
-    return url.replace(/\/api\/rest\/?$/, '').replace(/\/$/, '');
+    return url.replace(REST_API_SUFFIX, '').replace(/\/$/, '');
+}
+/**
+ * True when an unnormalised base URL already routes through the index.php
+ * front controller. Used by the config layer to default MANTIS_USE_INDEX_PHP
+ * for users who paste their full REST URL.
+ */
+export function usesIndexPhpEntryPoint(url) {
+    return REST_API_SUFFIX.exec(url)?.[1] !== undefined;
 }
 export function buildIssueViewUrl(baseUrl, issueId) {
     return `${baseUrl}/view.php?id=${issueId}`;
@@ -31,10 +53,17 @@ export class MantisClient {
     credentialFactory;
     responseObserver;
     resolvedCredentials;
-    constructor(baseUrlOrFactory, apiKeyOrObserver, responseObserver) {
+    constructor(baseUrlOrFactory, apiKeyOrObserver, useIndexPhpOrObserver, responseObserver) {
         if (typeof baseUrlOrFactory === 'string') {
-            this.resolvedCredentials = { baseUrl: normalizeBaseUrl(baseUrlOrFactory), apiKey: apiKeyOrObserver };
-            this.responseObserver = responseObserver;
+            const useIndexPhp = typeof useIndexPhpOrObserver === 'boolean' ? useIndexPhpOrObserver : false;
+            this.resolvedCredentials = {
+                baseUrl: normalizeBaseUrl(baseUrlOrFactory),
+                apiKey: apiKeyOrObserver,
+                useIndexPhp,
+            };
+            this.responseObserver = typeof useIndexPhpOrObserver === 'function'
+                ? useIndexPhpOrObserver
+                : responseObserver;
         }
         else {
             this.credentialFactory = baseUrlOrFactory;
@@ -46,8 +75,8 @@ export class MantisClient {
     // ---------------------------------------------------------------------------
     async getCredentials() {
         if (!this.resolvedCredentials) {
-            const { baseUrl, apiKey } = await this.credentialFactory();
-            this.resolvedCredentials = { baseUrl: normalizeBaseUrl(baseUrl), apiKey };
+            const { baseUrl, apiKey, useIndexPhp = false } = await this.credentialFactory();
+            this.resolvedCredentials = { baseUrl: normalizeBaseUrl(baseUrl), apiKey, useIndexPhp };
         }
         return this.resolvedCredentials;
     }
@@ -55,8 +84,9 @@ export class MantisClient {
         return (await this.getCredentials()).baseUrl;
     }
     async buildUrl(path, params) {
-        const { baseUrl } = await this.getCredentials();
-        const url = new URL(`${baseUrl}/api/rest/${path}`);
+        const { baseUrl, useIndexPhp } = await this.getCredentials();
+        const restPrefix = useIndexPhp ? '/api/rest/index.php/' : '/api/rest/';
+        const url = new URL(`${baseUrl}${restPrefix}${path}`);
         if (params) {
             for (const [key, value] of Object.entries(params)) {
                 if (value !== undefined) {

package/dist/config.js

@@ -2,11 +2,23 @@ import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { normalizeBaseUrl } from './client.js';
+import { normalizeBaseUrl, usesIndexPhpEntryPoint } from './client.js';
 // ---------------------------------------------------------------------------
 // .env.local loader
 // ---------------------------------------------------------------------------
-async function loadDotEnvLocal() {
+let cachedDotEnvLocal = null;
+/**
+ * Loads .env.local at most once per process. Both getStartupConfig() and
+ * getConfig() need it, and the HTTP transport calls them on separate paths —
+ * without memoising, the file is read twice on every startup. Caching the
+ * promise (not a boolean) also makes concurrent callers share one read.
+ */
+function loadDotEnvLocal() {
+    if (!cachedDotEnvLocal)
+        cachedDotEnvLocal = readDotEnvLocal();
+    return cachedDotEnvLocal;
+}
+async function readDotEnvLocal() {
     try {
         const envPath = join(dirname(fileURLToPath(import.meta.url)), '..', '.env.local');
         const content = await readFile(envPath, 'utf-8');
@@ -24,6 +36,9 @@ async function loadDotEnvLocal() {
         // .env.local not present — use environment variables directly
     }
 }
+// ---------------------------------------------------------------------------
+// Non-credential config (safe to read at startup without credentials)
+// ---------------------------------------------------------------------------
 function readNonCredentialConfig() {
     const defaultCacheDir = join(homedir(), '.cache', 'mantisbt-mcp');
     const cacheDir = process.env.MANTIS_CACHE_DIR ?? defaultCacheDir;
@@ -57,6 +72,26 @@ function readNonCredentialConfig() {
         testEnvironment: process.env.MCP_TEST_ENVIRONMENT === 'true',
     };
 }
+/**
+ * Resolves index.php routing from MANTIS_USE_INDEX_PHP and the shape of
+ * MANTIS_BASE_URL. An explicitly set env var always wins; the URL suffix is
+ * only consulted when the user said nothing, so copying the full REST URL
+ * from a MantisBT installation without URL rewriting just works. A base URL
+ * that contradicts an explicit "false" is reported on stderr — silently
+ * ignoring it would look like a broken server, not a misconfiguration.
+ */
+function resolveUseIndexPhp(rawBaseUrl) {
+    const explicit = process.env.MANTIS_USE_INDEX_PHP;
+    const urlImpliesIndexPhp = usesIndexPhpEntryPoint(rawBaseUrl);
+    if (explicit === undefined)
+        return urlImpliesIndexPhp;
+    const enabled = explicit === 'true';
+    if (urlImpliesIndexPhp && !enabled) {
+        process.stderr.write(`[mantisbt-config] MANTIS_BASE_URL ends with /api/rest/index.php, but MANTIS_USE_INDEX_PHP="${explicit}" — ` +
+            `using plain /api/rest/ routing as configured. Unset MANTIS_USE_INDEX_PHP to route through index.php.\n`);
+    }
+    return enabled;
+}
 /**
  * Returns all non-credential config values. Never throws, even when
  * MANTIS_BASE_URL / MANTIS_API_KEY are absent. Use this at server startup
@@ -102,6 +137,7 @@ export async function getConfig() {
     cachedConfig = {
         baseUrl: normalizeBaseUrl(baseUrl),
         apiKey,
+        useIndexPhp: resolveUseIndexPhp(baseUrl),
         ...readNonCredentialConfig(),
     };
     return cachedConfig;

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';
@@ -43,7 +44,11 @@ async function createMcpServer(transport) {
     setGlobalVersionHint(versionHint);
     const client = new MantisClient(async () => {
         const config = await getConfig();
-        return { baseUrl: config.baseUrl, apiKey: config.apiKey };
+        return {
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey,
+            useIndexPhp: config.useIndexPhp,
+        };
     }, (response) => versionHint.onSuccessfulResponse(response));
     const cache = new MetadataCache(startupConfig.cacheDir, startupConfig.cacheTtl);
     const server = new McpServer({
@@ -56,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).