@dpesch/mantisbt-mcp-server 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -11,6 +11,37 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.9.0] – 2026-03-28
+
+### Added
+- New tool `get_issues`: fetch multiple MantisBT issues by ID in a single MCP call. Requests run in parallel (max 5 concurrent). Missing or inaccessible IDs return `null` at their array position instead of failing the entire call. Response includes `requested`, `found`, and `failed` counters. Accepts 1–50 IDs per call.
+- `update_issue` now accepts an optional `dry_run` parameter. When `dry_run: true`, the tool returns the patch payload that would be sent without actually updating the issue — useful for previewing changes before committing them.
+- `list_issues` now accepts four date filter parameters: `updated_after`, `updated_before`, `created_after`, `created_before` (ISO-8601, exclusive). Filters are applied client-side with an early-exit optimisation: once a batch of results is fully older than `updated_after`, further pages are not fetched.
+- `search_issues` now accepts the same four date filter parameters. Without `select`, filtering uses VectraStore metadata (no extra API calls). With `select`, filtering uses the already-fetched issue object.
+- `search_issues` now accepts an optional `highlight` parameter (default: `false`). When `true`, each result gains a `highlights` field containing the issue summary with matching query terms wrapped in `**bold**` markdown, and a short description snippet (~300 chars) centered around the first match. Highlights are keyword-based (lexical), not semantic — results without a lexical overlap will not have a `highlights` field. Without `select`, highlights are built from the VectraStore metadata (no extra API calls); with `select`, from the fetched issue fields.
+- `VectorStore` interface extended with `getItem(id)` to support metadata lookups without re-fetching from the API.
+- New internal module `src/date-filter.ts` with shared `matchesDateFilter`, `hasDateFilter`, and `dateFilterSchema` — reused by both tools.
+- New internal module `src/search/highlight.ts` with `extractTerms`, `highlightText`, `hasTermMatch`, and `extractSnippet` — used by `search_issues` highlighting.
+
+### Changed
+- `get_issue` tool description now explicitly states that notes are always included in the response — no separate `list_notes` call needed.
+- `list_notes` tool description now clarifies it is only needed when fetching notes without the full issue object.
+- `create_issue` now accepts localized enum names for `severity`, `priority`, and `reproducibility` in addition to canonical English names. The server resolves the value against a static canonical table first; on a miss, it falls back to a live `get_issue_enums` lookup and matches against the `name` and `label` fields (case-insensitive). Only truly unknown values produce an error.
+- `update_issue` now resolves enum names for `status`, `priority`, `severity`, `resolution`, and `reproducibility` before sending the PATCH request. Pass a canonical English name, a localized name, or a numeric `id` — all are accepted. Unknown names are passed through unchanged and validated by the MantisBT API.
+- `list_issues` status filter now compares by ID when a canonical English status name is recognised (e.g. `"new"` → `id=10`). This makes the filter language-independent: it correctly matches issues on localized installations where the API returns translated status names. Non-canonical values (e.g. passing a localized name directly) fall back to name comparison as before.
+
+---
+
+## [1.8.3] – 2026-03-28
+
+### Added
+- New optional env var `MCP_TEST_ENVIRONMENT=true`. When set, `resources/list` skips live API calls and returns only static resources. Intended for automated inspection environments (e.g. Glama Docker builds) that start the server with placeholder credentials and restricted network access.
+
+### Fixed
+- All `MantisClient` fetch calls now use a 30-second timeout via `AbortSignal.timeout()`. Previously, a slow or unreachable MantisBT instance would cause fetch calls to hang indefinitely.
+
+---
+
 ## [1.8.2] – 2026-03-27
 
 ### Fixed

package/README.de.md

@@ -87,9 +87,9 @@ npm run build
 | Tool | Beschreibung |
 |---|---|
 | `get_issue` | Ein Issue anhand seiner ID abrufen |
-| `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern; optionales `select` für Feldprojektion und `status` für clientseitige Statusfilterung |
+| `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) |
-| `update_issue` | Bestehendes Issue bearbeiten |
+| `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 |
 | `delete_issue` | Issue löschen |
 
 ### Notizen
@@ -153,7 +153,7 @@ Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
 
 | Tool | Beschreibung |
 |---|---|
-| `search_issues` | Natürlichsprachige Suche über alle indizierten Issues – liefert Top-N-Ergebnisse mit Cosine-Similarity-Score; optionales `select` (kommagetrennte Feldnamen) reichert jedes Ergebnis mit den angeforderten Issue-Feldern an |
+| `search_issues` | Natürlichsprachige Suche über alle indizierten Issues – liefert Top-N-Ergebnisse mit Cosine-Similarity-Score; optionales `select` (kommagetrennte Feldnamen) reichert jedes Ergebnis mit den angeforderten Issue-Feldern an; optionales `highlight` (boolean, Standard `false`) fügt je Ergebnis ein `highlights`-Feld mit keyword-basierten Ausschnitten aus `summary` und `description` hinzu (Treffer werden in `**fett**` dargestellt) |
 | `rebuild_search_index` | Suchindex aufbauen oder aktualisieren; `full: true` löscht und baut ihn vollständig neu |
 | `get_search_index_status` | Aktuellen Füllstand des Suchindex zurückgeben: wie viele Issues bereits indiziert sind im Verhältnis zur Gesamtanzahl, plus Zeitstempel der letzten Synchronisation |
 

package/README.md

@@ -87,9 +87,9 @@ npm run build
 | Tool | Description |
 |---|---|
 | `get_issue` | Retrieve an issue by its numeric ID |
-| `list_issues` | Filter issues by project, status, author, and more; optional `select` for field projection and `status` for client-side status filtering |
+| `list_issues` | Filter issues by project, status, author, and more; optional `select` for field projection and `status` for client-side status filtering — canonical English status names (e.g. `"new"`, `"resolved"`) are matched by ID, making the filter language-independent on localized installations |
 | `create_issue` | Create a new issue; `severity` and `priority` must be canonical English names (e.g. `minor`, `major`, `normal`, `high`) — call `get_issue_enums` to see all valid values and their localized labels; optional `handler` parameter accepts a username as alternative to `handler_id` (resolved against project members) |
-| `update_issue` | Update an existing issue |
+| `update_issue` | Update an existing issue; enum fields (`status`, `priority`, `severity`, `resolution`, `reproducibility`) accept canonical English names, localized names, or numeric IDs — the server resolves names to IDs automatically |
 | `delete_issue` | Delete an issue |
 
 ### Notes
@@ -153,7 +153,7 @@ Activate with `MANTIS_SEARCH_ENABLED=true`.
 
 | Tool | Description |
 |---|---|
-| `search_issues` | Natural language search over all indexed issues — returns top-N results with cosine similarity score; optional `select` (comma-separated field names) enriches each result with the requested issue fields |
+| `search_issues` | Natural language search over all indexed issues — returns top-N results with cosine similarity score; optional `select` (comma-separated field names) enriches each result with the requested issue fields; optional `highlight` (boolean, default `false`) adds a `highlights` field per result with keyword-matched excerpts from `summary` and `description` (matched terms shown in `**bold**`) |
 | `rebuild_search_index` | Build or update the search index; `full: true` clears and rebuilds from scratch |
 | `get_search_index_status` | Return the current fill level of the search index: how many issues are indexed vs. total, and the timestamp of the last sync |
 

package/dist/client.js

@@ -96,10 +96,12 @@ export class MantisClient {
     // ---------------------------------------------------------------------------
     // Public API methods
     // ---------------------------------------------------------------------------
+    static TIMEOUT_MS = 30_000;
     async get(path, params) {
         const response = await fetch(await this.buildUrl(path, params), {
             method: 'GET',
             headers: await this.headers(),
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         return this.handleResponse(response);
     }
@@ -108,6 +110,7 @@ export class MantisClient {
             method: 'POST',
             headers: await this.headers(),
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         return this.handleResponse(response);
     }
@@ -116,6 +119,7 @@ export class MantisClient {
             method: 'PATCH',
             headers: await this.headers(),
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         return this.handleResponse(response);
     }
@@ -123,6 +127,7 @@ export class MantisClient {
         const response = await fetch(await this.buildUrl(path), {
             method: 'DELETE',
             headers: await this.headers(),
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         return this.handleResponse(response);
     }
@@ -137,6 +142,7 @@ export class MantisClient {
                 'Accept': 'application/json',
             },
             body: formData,
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         return this.handleResponse(response);
     }
@@ -144,6 +150,7 @@ export class MantisClient {
         const response = await fetch(await this.buildUrl('users/me'), {
             method: 'GET',
             headers: await this.headers(),
+            signal: AbortSignal.timeout(MantisClient.TIMEOUT_MS),
         });
         if (!response.ok) {
             throw new MantisApiError(response.status, response.statusText);

package/dist/config.js

@@ -54,6 +54,7 @@ function readNonCredentialConfig() {
             modelName: searchModelName,
             numThreads: searchNumThreads,
         },
+        testEnvironment: process.env.MCP_TEST_ENVIRONMENT === 'true',
     };
 }
 /**

package/dist/date-filter.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Shared Zod schema fragment — reuse in any tool's inputSchema
+// ---------------------------------------------------------------------------
+export const dateFilterSchema = {
+    updated_after: z.string().optional().describe('ISO-8601 timestamp — only return issues updated after this date (exclusive). Example: "2026-03-25T00:00:00Z"'),
+    updated_before: z.string().optional().describe('ISO-8601 timestamp — only return issues updated before this date (exclusive). Example: "2026-03-28T00:00:00Z"'),
+    created_after: z.string().optional().describe('ISO-8601 timestamp — only return issues created after this date (exclusive). Example: "2026-03-01T00:00:00Z"'),
+    created_before: z.string().optional().describe('ISO-8601 timestamp — only return issues created before this date (exclusive). Example: "2026-03-15T00:00:00Z"'),
+};
+// ---------------------------------------------------------------------------
+// matchesDateFilter
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the item's dates satisfy all active date constraints.
+ * All comparisons are exclusive (strictly greater / strictly less than).
+ * If a filter is set but the item's corresponding date field is absent, returns false.
+ */
+export function matchesDateFilter(item, filter) {
+    const { updated_after, updated_before, created_after, created_before } = filter;
+    if (updated_after !== undefined) {
+        if (!item.updated_at)
+            return false;
+        if (new Date(item.updated_at) <= new Date(updated_after))
+            return false;
+    }
+    if (updated_before !== undefined) {
+        if (!item.updated_at)
+            return false;
+        if (new Date(item.updated_at) >= new Date(updated_before))
+            return false;
+    }
+    if (created_after !== undefined) {
+        if (!item.created_at)
+            return false;
+        if (new Date(item.created_at) <= new Date(created_after))
+            return false;
+    }
+    if (created_before !== undefined) {
+        if (!item.created_at)
+            return false;
+        if (new Date(item.created_at) >= new Date(created_before))
+            return false;
+    }
+    return true;
+}
+/**
+ * Returns true if any date filter parameter is set.
+ */
+export function hasDateFilter(filter) {
+    return (filter.updated_after !== undefined ||
+        filter.updated_before !== undefined ||
+        filter.created_after !== undefined ||
+        filter.created_before !== undefined);
+}

package/dist/index.js

@@ -63,7 +63,7 @@ async function createMcpServer() {
     registerTagTools(server, client);
     registerVersionTools(server, client, versionHint, version);
     registerPrompts(server);
-    registerResources(server, client, cache);
+    registerResources(server, client, cache, startupConfig.testEnvironment);
     // Optional: Semantic search module
     if (startupConfig.search.enabled) {
         const { initializeSearchModule } = await import('./search/index.js');

package/dist/resources/index.js

@@ -7,7 +7,7 @@ function jsonResource(uri, data) {
         contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data) }],
     };
 }
-export function registerResources(server, client, cache) {
+export function registerResources(server, client, cache, testEnvironment = false) {
     async function loadProjects() {
         const cached = await cache.loadIfValid();
         return cached?.projects
@@ -25,12 +25,19 @@ export function registerResources(server, client, cache) {
         mimeType: 'application/json',
     }, async (uri) => jsonResource(uri, await loadProjects()));
     server.registerResource('project-detail', new ResourceTemplate('mantis://projects/{id}', {
-        list: async () => ({
-            resources: (await loadProjects()).map((p) => ({
-                uri: `mantis://projects/${p.id}`,
-                name: p.name,
-            })),
-        }),
+        list: async () => {
+            // In test environments (MCP_TEST_ENVIRONMENT=true, e.g. Glama inspection
+            // with placeholder credentials) skip the live API call and return an
+            // empty list so resources/list responds immediately without timing out.
+            if (testEnvironment)
+                return { resources: [] };
+            return {
+                resources: (await loadProjects()).map((p) => ({
+                    uri: `mantis://projects/${p.id}`,
+                    name: p.name,
+                })),
+            };
+        },
     }), {
         title: 'Project Detail',
         description: 'Combined project view: fields (status, view_state, access_level, description) plus all associated users, versions, and categories. Served from local cache when fresh; falls back to live API fetch. Refresh via the sync_metadata tool.',

package/dist/search/highlight.js

@@ -0,0 +1,63 @@
+/**
+ * Keyword highlighting utilities for search_issues results.
+ *
+ * Note: highlights are keyword-based (lexical), not semantic.
+ * A result may have no highlighted terms even if it is semantically relevant.
+ */
+function escapeRegex(term) {
+    return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function combinedPattern(terms, flags) {
+    return new RegExp(`\\b(${terms.map(escapeRegex).join('|')})\\b`, flags);
+}
+/**
+ * Extracts meaningful search terms from a query string.
+ * Sorted longest-first to prevent shorter terms from matching inside
+ * already-bolded longer ones during sequential replacement.
+ */
+export function extractTerms(query) {
+    const seen = new Set();
+    const terms = [];
+    for (const raw of query.trim().split(/\s+/)) {
+        if (raw.length < 3)
+            continue;
+        const key = raw.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            terms.push(raw);
+        }
+    }
+    terms.sort((a, b) => b.length - a.length);
+    return terms;
+}
+export function highlightText(text, terms) {
+    if (!terms.length)
+        return text;
+    return text.replace(combinedPattern(terms, 'gi'), '**$1**');
+}
+export function hasTermMatch(text, terms) {
+    if (!terms.length)
+        return false;
+    return combinedPattern(terms, 'i').test(text);
+}
+/**
+ * Returns a highlighted snippet centered around the first term match.
+ * Falls back to first `contextChars` chars when no term matches.
+ */
+export function extractSnippet(text, terms, contextChars = 300) {
+    if (text.length <= contextChars) {
+        return highlightText(text, terms);
+    }
+    const match = terms.length > 0 ? text.match(combinedPattern(terms, 'i')) : null;
+    const matchIndex = match?.index ?? -1;
+    if (matchIndex === -1) {
+        return text.slice(0, contextChars) + '…';
+    }
+    const half = Math.floor(contextChars / 2);
+    const start = Math.max(0, matchIndex - half);
+    const end = Math.min(text.length, start + contextChars);
+    const snippet = text.slice(start, end);
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < text.length ? '…' : '';
+    return prefix + highlightText(snippet, terms) + suffix;
+}

package/dist/search/store.js

@@ -64,6 +64,10 @@ export class VectraStore {
         results.sort((a, b) => b.score - a.score);
         return results.slice(0, topN);
     }
+    async getItem(id) {
+        await this.ensureLoaded();
+        return this.items.get(id) ?? null;
+    }
     async delete(id) {
         await this.ensureLoaded();
         this.items.delete(id);

package/dist/search/tools.js

@@ -1,6 +1,20 @@
 import { z } from 'zod';
 import { SearchSyncService } from './sync.js';
 import { getVersionHint } from '../version-hint.js';
+import { dateFilterSchema, matchesDateFilter, hasDateFilter } from '../date-filter.js';
+import { extractTerms, highlightText, extractSnippet, hasTermMatch } from './highlight.js';
+function buildHighlights(summary, description, terms) {
+    const h = {};
+    if (summary) {
+        const highlighted = highlightText(summary, terms);
+        if (highlighted !== summary)
+            h['summary'] = highlighted;
+    }
+    if (description && hasTermMatch(description, terms)) {
+        h['description'] = extractSnippet(description, terms);
+    }
+    return Object.keys(h).length > 0 ? h : null;
+}
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -30,13 +44,20 @@ export function registerSearchTools(server, client, store, embedder) {
             select: z.string().optional().describe('Comma-separated list of fields to include for each result (e.g. "id,summary,status,handler,priority"). ' +
                 'When provided, each matching issue is fetched from MantisBT and enriched with the requested fields. ' +
                 'The relevance score is always included. Without this parameter only id and score are returned.'),
+            highlight: z
+                .boolean()
+                .default(false)
+                .describe('If true, adds a "highlights" field per result with query terms bolded (**term**) ' +
+                'in the issue summary and a short description snippet. ' +
+                'Note: highlights are keyword-based, not semantic — some results may have no highlighted terms.'),
+            ...dateFilterSchema,
         }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ query, top_n, select }) => {
+    }, async ({ query, top_n, select, highlight, updated_after, updated_before, created_after, created_before }) => {
         try {
             const count = await store.count();
             if (count === 0) {
@@ -50,11 +71,32 @@ export function registerSearchTools(server, client, store, embedder) {
                     isError: true,
                 };
             }
+            const dateFilter = { updated_after, updated_before, created_after, created_before };
+            const filterActive = hasDateFilter(dateFilter);
+            const terms = highlight ? extractTerms(query) : [];
             const queryVector = await embedder.embed(query);
             const results = await store.search(queryVector, top_n);
             if (!select) {
+                // For filtering or highlighting we need store metadata per result
+                if (!filterActive && !terms.length) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+                    };
+                }
+                const filtered = await Promise.all(results.map(async ({ id, score }) => {
+                    const item = await store.getItem(id);
+                    if (filterActive && !matchesDateFilter(item?.metadata ?? {}, dateFilter))
+                        return null;
+                    const result = { id, score };
+                    if (terms.length > 0 && item) {
+                        const h = buildHighlights(item.metadata.summary, item.metadata.description, terms);
+                        if (h)
+                            result['highlights'] = h;
+                    }
+                    return result;
+                }));
                 return {
-                    content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+                    content: [{ type: 'text', text: JSON.stringify(filtered.filter(Boolean), null, 2) }],
                 };
             }
             const fields = select.split(',').map(f => f.trim()).filter(Boolean);
@@ -62,20 +104,39 @@ export function registerSearchTools(server, client, store, embedder) {
                 try {
                     const issueResult = await client.get(`issues/${id}`);
                     const issue = issueResult.issues?.[0] ?? {};
+                    if (filterActive && !matchesDateFilter(issue, dateFilter)) {
+                        return null;
+                    }
                     const projected = { id, score };
                     for (const field of fields) {
                         if (field !== 'id' && field in issue) {
                             projected[field] = issue[field];
                         }
                     }
+                    if (terms.length > 0) {
+                        const summary = typeof issue['summary'] === 'string' ? issue['summary'] : undefined;
+                        const description = typeof issue['description'] === 'string' ? issue['description'] : undefined;
+                        const h = buildHighlights(summary, description, terms);
+                        if (h)
+                            projected['highlights'] = h;
+                    }
                     return projected;
                 }
                 catch {
-                    return { id, score };
+                    const result = { id, score };
+                    if (terms.length > 0) {
+                        const item = await store.getItem(id);
+                        if (item) {
+                            const h = buildHighlights(item.metadata.summary, item.metadata.description, terms);
+                            if (h)
+                                result['highlights'] = h;
+                        }
+                    }
+                    return result;
                 }
             }));
             return {
-                content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(enriched.filter(Boolean), null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/config.js

@@ -68,6 +68,20 @@ export async function fetchIssueEnums(client) {
     }
     return enums;
 }
+let _enumDataCache = null;
+const ENUM_DATA_CACHE_TTL_MS = 5 * 60 * 1000;
+export async function fetchIssueEnumsWithCache(client) {
+    if (_enumDataCache && (Date.now() - _enumDataCache.fetchedAt) < ENUM_DATA_CACHE_TTL_MS) {
+        return _enumDataCache.data;
+    }
+    const data = await fetchIssueEnums(client);
+    _enumDataCache = { data, fetchedAt: Date.now() };
+    return data;
+}
+/** Resets the in-memory enum cache. Intended for use in tests. */
+export function clearIssueEnumCache() {
+    _enumDataCache = null;
+}
 export function registerConfigTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     // get_config
@@ -139,18 +153,19 @@ Example response (localized installation, e.g. German):
 }
 
 Fields:
-- "id"    — numeric ID accepted by the API
-- "name"  — the API value to pass to create_issue or update_issue; normally English, but may be
-            localized if the installation has customized enum values in the database
-- "label" — localized display label shown in the UI (only present when it differs from "name")
+- "id"             — numeric ID accepted by the API
+- "name"           — localized or canonical name from the MantisBT database
+- "label"          — UI display label (only present when it differs from "name")
+- "canonical_name" — English canonical name (only present on localized installs)
+
+For create_issue (severity, priority, reproducibility): pass the canonical English name, the
+localized "name", or the "label" — all are accepted. The server resolves them to the correct ID.
 
-Always pass either the "id" or the "name" value to create_issue or update_issue — never the "label".
-Use the "label" to map user input in the UI language back to the correct "name"/"id" for the API.
+For update_issue: pass either "id" or "name" in the field reference object.
 
 Note: on some installations enum values are customized at the database level. In that case "name"
 itself may be localized (e.g. "kleinerer Fehler" instead of "minor") and no "label" will be present
-because there is no separate English original. The "name" value returned is always the correct one
-to use for API calls — regardless of language.`,
+because there is no separate English original.`,
         inputSchema: z.object({}),
         annotations: {
             readOnlyHint: true,