@dpesch/mantisbt-mcp-server 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -11,6 +11,22 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
@@ -68,6 +70,7 @@ npm run build
 |---|---|---|---|
 | `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` |

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

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

@@ -43,7 +43,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({

package/docs/cookbook.de.md

@@ -4,6 +4,8 @@ Tool-orientierte Rezepte für den MantisBT MCP Server — jedes Rezept zeigt gen
 
 ---
 
+- [Verbindung einrichten](#verbindung-einrichten)
+  - [Installation ohne URL-Rewriting anbinden](#installation-ohne-url-rewriting-anbinden)
 - [Die eigene Instanz erkunden](#die-eigene-instanz-erkunden)
   - [Alle Projekte abrufen](#alle-projekte-abrufen)
   - [Gültige Enum-Werte ermitteln (Schweregrad, Status, Priorität)](#gültige-enum-werte-ermitteln-schweregrad-status-priorität)
@@ -72,6 +74,41 @@ Tool-orientierte Rezepte für den MantisBT MCP Server — jedes Rezept zeigt gen
 
 ---
 
+## Verbindung einrichten
+
+### Installation ohne URL-Rewriting anbinden
+
+Manche MantisBT-Installationen liefern die REST-API ausschließlich über ihren Front-Controller aus — typischerweise Apache ohne `mod_rewrite` oder IIS ohne Rewrite-Modul. Dort liefert `/api/rest/issues` einen 404, während `/api/rest/index.php/issues` funktioniert.
+
+**Variante A — Flag explizit setzen:**
+
+```json
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com",
+    "MANTIS_API_KEY": "dein-api-token",
+    "MANTIS_USE_INDEX_PHP": "true"
+  }
+}
+```
+
+**Variante B — vollständige REST-URL eintragen und erkennen lassen:**
+
+```json
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com/api/rest/index.php",
+    "MANTIS_API_KEY": "dein-api-token"
+  }
+}
+```
+
+Endet `MANTIS_BASE_URL` auf `/api/rest/index.php`, wird das index.php-Routing automatisch aktiviert. Ein explizit gesetztes `MANTIS_USE_INDEX_PHP` hat immer Vorrang vor der Erkennung — steht es zusammen mit einer solchen URL auf `false`, wird das normale `/api/rest/`-Routing erzwungen und eine Warnung auf stderr ausgegeben.
+
+**Prüfen:** `get_mantis_version` aufrufen. Kommt eine Antwort zurück, stimmt das Routing.
+
+---
+
 ## Die eigene Instanz erkunden
 
 ### Alle Projekte abrufen

package/docs/cookbook.md

@@ -4,6 +4,8 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
 
 ---
 
+- [Connection setup](#connection-setup)
+  - [Connect to an installation without URL rewriting](#connect-to-an-installation-without-url-rewriting)
 - [Discovering your instance](#discovering-your-instance)
   - [Get all projects](#get-all-projects)
   - [Discover valid enum values (severity, status, priority)](#discover-valid-enum-values-severity-status-priority)
@@ -72,6 +74,41 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
 
 ---
 
+## Connection setup
+
+### Connect to an installation without URL rewriting
+
+Some MantisBT installations serve the REST API only through its front controller — typically Apache without `mod_rewrite`, or IIS without a rewrite module. There, `/api/rest/issues` returns 404 while `/api/rest/index.php/issues` works.
+
+**Option A — set the flag explicitly:**
+
+```json
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com",
+    "MANTIS_API_KEY": "your-api-token",
+    "MANTIS_USE_INDEX_PHP": "true"
+  }
+}
+```
+
+**Option B — paste the full REST URL and let the server detect it:**
+
+```json
+{
+  "env": {
+    "MANTIS_BASE_URL": "https://mantis.example.com/api/rest/index.php",
+    "MANTIS_API_KEY": "your-api-token"
+  }
+}
+```
+
+When `MANTIS_BASE_URL` ends with `/api/rest/index.php`, index.php routing is enabled automatically. An explicitly set `MANTIS_USE_INDEX_PHP` always wins over the detection — setting it to `false` alongside such a URL forces plain `/api/rest/` routing and logs a warning on stderr.
+
+**Verify:** call `get_mantis_version`. A successful response means the routing is correct.
+
+---
+
 ## Discovering your instance
 
 ### Get all projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.dpesch/mantisbt-mcp-server",
   "title": "MantisBT MCP Server",
   "description": "MantisBT MCP server – manage issues, notes, files, tags, and relationships. With semantic search.",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.11.0",
+      "version": "1.12.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -29,6 +29,14 @@
           "isSecret": true,
           "format": "string"
         },
+        {
+          "name": "MANTIS_USE_INDEX_PHP",
+          "description": "Use /api/rest/index.php/ for MantisBT installations without URL rewriting. Detected automatically when MANTIS_BASE_URL ends with /api/rest/index.php",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "boolean",
+          "default": "false"
+        },
         {
           "name": "MANTIS_CACHE_DIR",
           "description": "Directory for the metadata cache. Defaults to ~/.cache/mantisbt-mcp",