@dpesch/mantisbt-mcp-server 1.8.3 → 1.9.1

package/dist/tools/issues.js

@@ -1,20 +1,48 @@
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
 import { MANTIS_CANONICAL_ENUM_NAMES, MANTIS_RESOLVED_STATUS_ID, resolveEnumId } from '../constants.js';
+import { dateFilterSchema, matchesDateFilter, hasDateFilter } from '../date-filter.js';
+import { fetchIssueEnumsWithCache } from './config.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
-// Resolves a canonical enum name to { id } or returns an error string.
-function resolveEnum(group, value) {
+const GET_ISSUES_CONCURRENCY = 5;
+// Worker-pool: runs `fn` over all `items` with at most `concurrency` in-flight at once.
+// nextIndex is only incremented inside microtasks, so the ++ is safe without a lock.
+async function runWithConcurrency(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const i = nextIndex++;
+            results[i] = await fn(items[i]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+    return results;
+}
+// Resolves an enum name (canonical or localized) to { id } or returns an error string.
+async function resolveEnum(group, value, client) {
     const id = resolveEnumId(group, value);
-    if (id === undefined) {
-        const valid = Object.values(MANTIS_CANONICAL_ENUM_NAMES[group]).join(', ');
-        return `Invalid ${group} "${value}". Valid canonical names: ${valid}. Call get_issue_enums to see localized labels.`;
+    if (id !== undefined)
+        return { id };
+    try {
+        const enums = await fetchIssueEnumsWithCache(client);
+        const entries = enums[group] ?? [];
+        const lower = value.toLowerCase();
+        const entry = entries.find(e => e.name.toLowerCase() === lower ||
+            (e.label !== undefined && e.label.toLowerCase() === lower));
+        if (entry !== undefined)
+            return { id: entry.id };
+    }
+    catch {
+        // localized lookup unavailable — fall through to static error
     }
-    return { id };
+    const valid = Object.values(MANTIS_CANONICAL_ENUM_NAMES[group]).join(', ');
+    return `Invalid ${group} "${value}". Valid canonical names: ${valid}. Call get_issue_enums to see localized labels.`;
 }
 export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
@@ -22,7 +50,7 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_issue', {
         title: 'Get Issue',
-        description: 'Retrieve a single MantisBT issue by its numeric ID. Returns all issue fields including notes, attachments, and relationships.',
+        description: 'Retrieve a single MantisBT issue by its numeric ID. Returns all issue fields including notes, attachments, and relationships. Notes are always included — no separate list_notes call needed.',
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID'),
         }),
@@ -45,11 +73,51 @@ export function registerIssueTools(server, client, cache) {
         }
     });
     // ---------------------------------------------------------------------------
+    // get_issues
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_issues', {
+        title: 'Get Multiple Issues',
+        description: 'Retrieve multiple MantisBT issues by their numeric IDs in a single MCP call. ' +
+            'Requests run in parallel (max 5 concurrent). ' +
+            'Missing or inaccessible IDs return null at their array position — ' +
+            'the call never fails due to individual missing IDs. ' +
+            'Response includes "requested", "found", and "failed" counters for quick validation.',
+        inputSchema: z.object({
+            ids: z
+                .array(z.coerce.number().int().positive())
+                .min(1)
+                .max(50)
+                .describe('Array of numeric issue IDs to fetch (1–50). null is returned per ID on 404/403/error instead of failing the whole call.'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ ids }) => {
+        const results = await runWithConcurrency(ids, GET_ISSUES_CONCURRENCY, async (id) => {
+            try {
+                const result = await client.get(`issues/${id}`);
+                return result.issues?.[0] ?? result;
+            }
+            catch {
+                return null;
+            }
+        });
+        const found = results.filter((r) => r !== null).length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ issues: results, requested: ids.length, found, failed: ids.length - found }, null, 2),
+                }],
+        };
+    });
+    // ---------------------------------------------------------------------------
     // list_issues
     // ---------------------------------------------------------------------------
     server.registerTool('list_issues', {
         title: 'List Issues',
-        description: 'List MantisBT issues with optional filtering. Returns a paginated list of issues. Use the "select" parameter to limit returned fields and reduce response size significantly.\n\nNote: "assigned_to", "reporter_id", and "status" filters are applied client-side (the MantisBT REST API does not reliably support these as server-side filters). When any of these filters are active the tool automatically fetches multiple pages internally until enough matching results are found (up to 500 issues scanned). The "page" and "page_size" parameters refer to the resulting filtered list.',
+        description: 'List MantisBT issues with optional filtering. Returns a paginated list of issues. Use the "select" parameter to limit returned fields and reduce response size significantly.\n\nNote: "assigned_to", "reporter_id", "status", and date filters are applied client-side (the MantisBT REST API does not support these as server-side filters). When any of these filters are active the tool automatically fetches multiple pages internally until enough matching results are found (up to 500 issues scanned). The "page" and "page_size" parameters refer to the resulting filtered list.\n\nTip for date queries: fetching with select="id,updated_at,created_at" plus a date filter is very compact and efficient.',
         inputSchema: z.object({
             project_id: z.coerce.number().int().positive().optional().describe('Filter by project ID'),
             page: z.coerce.number().int().positive().default(1).describe('Page number (default: 1)'),
@@ -61,13 +129,14 @@ export function registerIssueTools(server, client, cache) {
             direction: z.enum(['ASC', 'DESC']).optional().describe('Sort direction'),
             select: z.string().optional().describe('Comma-separated list of fields to include in the response (server-side projection). Significantly reduces response size. Example: "id,summary,status,priority,handler,updated_at"'),
             status: z.string().optional().describe('Filter issues by status name (e.g. "new", "feedback", "acknowledged", "confirmed", "assigned", "resolved", "closed") or use "open" as shorthand for all statuses with id < 80 (i.e. not yet resolved or closed). Applied client-side after fetching — when combined with pagination, a page may contain fewer results than page_size.'),
+            ...dateFilterSchema,
         }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status }) => {
+    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status, updated_after, updated_before, created_after, created_before }) => {
         try {
             const baseParams = {
                 project_id,
@@ -78,7 +147,8 @@ export function registerIssueTools(server, client, cache) {
                 direction,
                 select,
             };
-            const needsClientFilter = status !== undefined || assigned_to !== undefined || reporter_id !== undefined;
+            const dateFilter = { updated_after, updated_before, created_after, created_before };
+            const needsClientFilter = status !== undefined || assigned_to !== undefined || reporter_id !== undefined || hasDateFilter(dateFilter);
             if (!needsClientFilter) {
                 // No client-side filtering — single API call, pass pagination as-is
                 const result = await client.get('issues', { ...baseParams, page, page_size });
@@ -95,6 +165,9 @@ export function registerIssueTools(server, client, cache) {
             let serverPage = 1;
             let hasMore = true;
             const statusLower = status?.toLowerCase();
+            const statusId = status ? resolveEnumId('status', status) : undefined;
+            // Pre-parse date thresholds once — avoids repeated new Date() inside the scan loop
+            const updatedAfterMs = updated_after ? new Date(updated_after).getTime() : undefined;
             while (matching.length < neededTotal && serverPage <= MAX_API_PAGES && hasMore) {
                 const batch = await client.get('issues', {
                     ...baseParams,
@@ -103,6 +176,7 @@ export function registerIssueTools(server, client, cache) {
                 });
                 const issues = batch.issues ?? [];
                 hasMore = issues.length === API_PAGE_SIZE;
+                let stopAfterBatch = false;
                 for (const issue of issues) {
                     if (statusLower) {
                         if (!issue.status)
@@ -111,6 +185,10 @@ export function registerIssueTools(server, client, cache) {
                             if ((issue.status.id ?? 0) >= MANTIS_RESOLVED_STATUS_ID)
                                 continue;
                         }
+                        else if (statusId !== undefined) {
+                            if (issue.status.id !== statusId)
+                                continue;
+                        }
                         else if (issue.status.name?.toLowerCase() !== statusLower) {
                             continue;
                         }
@@ -119,8 +197,20 @@ export function registerIssueTools(server, client, cache) {
                         continue;
                     if (reporter_id !== undefined && issue.reporter?.id !== reporter_id)
                         continue;
+                    if (!matchesDateFilter(issue, dateFilter)) {
+                        // MantisBT returns results newest-first. Once updated_at drops below
+                        // updated_after, all subsequent pages are guaranteed to be older too.
+                        // Finish the current batch first (items within it may still be newer),
+                        // then stop fetching further pages.
+                        if (updatedAfterMs && issue.updated_at && new Date(issue.updated_at).getTime() <= updatedAfterMs) {
+                            stopAfterBatch = true;
+                        }
+                        continue;
+                    }
                     matching.push(issue);
                 }
+                if (stopAfterBatch)
+                    break;
                 serverPage++;
             }
             const start = (page - 1) * page_size;
@@ -147,8 +237,8 @@ export function registerIssueTools(server, client, cache) {
             description: z.string().min(1).describe('Detailed issue description. Required — do not create issues without a description. Plain text or Markdown.'),
             project_id: z.coerce.number().int().positive().describe('Project ID the issue belongs to'),
             category: z.string().min(1).describe('Category name (use get_project_categories to list available categories)'),
-            priority: z.string().default('normal').describe('Priority name — must be a canonical English name: none, low, normal, high, urgent, immediate. Default: "normal". Call get_issue_enums to see localized labels.'),
-            severity: z.string().default('minor').describe('Severity name — must be a canonical English name: feature, trivial, text, tweak, minor, major, crash, block. Default: "minor". Call get_issue_enums to see localized labels.'),
+            priority: z.string().default('normal').describe('Priority: canonical English name (none, low, normal, high, urgent, immediate) or localized label. Default: "normal". Use get_issue_enums to see all available values.'),
+            severity: z.string().default('minor').describe('Severity: canonical English name (feature, trivial, text, tweak, minor, major, crash, block) or localized label. Default: "minor". Use get_issue_enums to see all available values.'),
             handler_id: z.coerce.number().int().positive().optional().describe('User ID of the person to assign the issue to'),
             handler: z.string().optional().describe('Username (login name) of the person to assign the issue to. Alternative to handler_id — the server resolves the name to a user ID from the project members. Use get_project_users to see available users.'),
             version: z.string().optional().describe('Affected product version name (use get_project_versions to list available versions)'),
@@ -156,7 +246,7 @@ export function registerIssueTools(server, client, cache) {
             fixed_in_version: z.string().optional().describe('Version name in which the issue was fixed (use get_project_versions to list available versions)'),
             steps_to_reproduce: z.string().optional().describe('Steps to reproduce the issue. Plain text or Markdown.'),
             additional_information: z.string().optional().describe('Additional information about the issue. Plain text or Markdown.'),
-            reproducibility: z.string().optional().describe('Reproducibility — must be a canonical English name: always, sometimes, random, have not tried, unable to reproduce, N/A. Call get_issue_enums to see localized labels.'),
+            reproducibility: z.string().optional().describe('Reproducibility: canonical English name or localized label (always, sometimes, random, have not tried, unable to reproduce, N/A). Use get_issue_enums to see all available values.'),
             view_state: z.enum(['public', 'private']).optional().describe('Visibility of the issue: "public" (default) or "private"'),
         }),
         annotations: {
@@ -196,11 +286,11 @@ export function registerIssueTools(server, client, cache) {
                 project: { id: project_id },
                 category: { name: category },
             };
-            const priorityResolved = resolveEnum('priority', priority);
+            const priorityResolved = await resolveEnum('priority', priority, client);
             if (typeof priorityResolved === 'string')
                 return { content: [{ type: 'text', text: errorText(priorityResolved) }], isError: true };
             body.priority = priorityResolved;
-            const severityResolved = resolveEnum('severity', severity);
+            const severityResolved = await resolveEnum('severity', severity, client);
             if (typeof severityResolved === 'string')
                 return { content: [{ type: 'text', text: errorText(severityResolved) }], isError: true };
             body.severity = severityResolved;
@@ -217,7 +307,7 @@ export function registerIssueTools(server, client, cache) {
             if (additional_information !== undefined)
                 body.additional_information = additional_information;
             if (reproducibility !== undefined) {
-                const reproducibilityResolved = resolveEnum('reproducibility', reproducibility);
+                const reproducibilityResolved = await resolveEnum('reproducibility', reproducibility, client);
                 if (typeof reproducibilityResolved === 'string')
                     return { content: [{ type: 'text', text: errorText(reproducibilityResolved) }], isError: true };
                 body.reproducibility = reproducibilityResolved;
@@ -252,6 +342,7 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     // update_issue
     // ---------------------------------------------------------------------------
+    const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
     // MantisBT reference shape: at least one of id or name must be provided
     const ref = z.object({ id: z.number().optional(), name: z.string().optional() })
         .refine(o => o.id !== undefined || o.name !== undefined, { message: "At least one of 'id' or 'name' must be provided" });
@@ -279,7 +370,17 @@ The "fields" object accepts any combination of:
 Important: when resolving an issue, always set BOTH status and resolution to avoid leaving resolution as "open".`,
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID to update'),
-            fields: z.object({
+            dry_run: z.preprocess(coerceBool, z.boolean().optional()).describe('If true, return the patch payload that would be sent without actually updating the issue. Useful for previewing changes before committing them.'),
+            fields: z.preprocess((v) => {
+                if (typeof v !== 'string')
+                    return v;
+                try {
+                    return JSON.parse(v);
+                }
+                catch {
+                    return v;
+                }
+            }, z.object({
                 summary: z.string().optional(),
                 description: z.string().optional(),
                 steps_to_reproduce: z.string().optional(),
@@ -295,16 +396,30 @@ Important: when resolving an issue, always set BOTH status and resolution to avo
                 target_version: ref.optional(),
                 fixed_in_version: ref.optional(),
                 view_state: ref.optional(),
-            }).strict().describe('Fields to update (partial update — only provided fields are changed; unknown keys are rejected)'),
+            }).strict().describe('Fields to update (partial update — only provided fields are changed; unknown keys are rejected)')),
         }),
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
         },
-    }, async ({ id, fields }) => {
+    }, async ({ id, fields, dry_run }) => {
+        if (dry_run) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ dry_run: true, id, would_patch: fields }, null, 2) }],
+            };
+        }
         try {
-            const result = await client.patch(`issues/${id}`, fields);
+            const patch = { ...fields };
+            for (const field of ['status', 'priority', 'severity', 'resolution', 'reproducibility']) {
+                const val = fields[field];
+                if (val?.name !== undefined && val.id === undefined) {
+                    const resolved = await resolveEnum(field, val.name, client);
+                    if (typeof resolved !== 'string')
+                        patch[field] = resolved;
+                }
+            }
+            const result = await client.patch(`issues/${id}`, patch);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result.issue ?? result, null, 2) }],
             };

package/dist/tools/notes.js

@@ -12,7 +12,7 @@ export function registerNoteTools(server, client) {
     // ---------------------------------------------------------------------------
     server.registerTool('list_notes', {
         title: 'List Issue Notes',
-        description: 'List all notes (comments) attached to a MantisBT issue.',
+        description: 'List all notes (comments) attached to a MantisBT issue. Note: get_issue already includes notes in its response — use list_notes only when you need notes without fetching the full issue.',
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
         }),

package/dist/tools/projects.js

@@ -8,6 +8,7 @@ function errorText(msg) {
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
+const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
 export function registerProjectTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     // list_projects
@@ -72,8 +73,8 @@ export function registerProjectTools(server, client, cache) {
         description: 'List all versions defined for a MantisBT project.',
         inputSchema: z.object({
             project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            obsolete: z.boolean().default(false).describe('Include obsolete (deprecated) versions (default: false)'),
-            inherit: z.boolean().default(false).describe('Include versions inherited from parent projects (default: false)'),
+            obsolete: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include obsolete (deprecated) versions (default: false)'),
+            inherit: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include versions inherited from parent projects (default: false)'),
         }),
         annotations: {
             readOnlyHint: true,

package/dist/tools/version.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { parseVersion, compareVersions } from '../version-hint.js';
+const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
 export function registerVersionTools(server, client, versionHint, mcpVersion) {
     // ---------------------------------------------------------------------------
     // get_mcp_version
@@ -26,7 +27,7 @@ export function registerVersionTools(server, client, versionHint, mcpVersion) {
 The version is read from the X-Mantis-Version response header sent by every API call.
 The GitHub comparison requires an outbound HTTPS request to the GitHub API.`,
         inputSchema: z.object({
-            check_latest: z.boolean().default(true).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
+            check_latest: z.preprocess(coerceBool, z.boolean()).default(true).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
         }),
         annotations: {
             readOnlyHint: true,

package/docs/cookbook.de.md

@@ -145,7 +145,7 @@ Gibt die auf der eigenen MantisBT-Instanz konfigurierten Enum-Werte zurück. Vor
 }
 ```
 
-> **Hinweis:** Die von `get_issue_enums()` zurückgegebenen Namen können lokalisiert sein. `create_issue` und `update_issue` erwarten für `severity` und `priority` **kanonische englische Namen** (z.B. `minor`, `major`, `normal`) — bei Unsicherheit das `canonical_name`-Feld in der Antwort prüfen.
+> **Hinweis:** Auf lokalisierten Instanzen liefert `get_issue_enums()` im Feld `name` den lokalisierten Begriff und optional im Feld `canonical_name` den englischen Originalnamen. `create_issue` akzeptiert **beides** — sowohl den kanonischen englischen Namen (z.B. `minor`) als auch den lokalisierten Namen (z.B. `Unschönheit`). Der Server löst den Wert automatisch auf.
 
 ---
 
@@ -347,6 +347,8 @@ Gibt nur Issues mit einem bestimmten Status zurück. Der Filter wird clientseiti
 }
 ```
 
+> **Hinweis:** Kanonische Statusnamen (z.B. `"new"`, `"resolved"`) werden zur numerischen ID aufgelöst und per `issue.status.id` gefiltert — funktioniert auch auf lokalisierten Installationen, bei denen die API übersetzte Statusnamen zurückgibt. Direkt übergebene lokalisierte Namen (z.B. `"Neu"`) werden als Fallback über den Namen abgeglichen. Das Kürzel `"open"` (alle Status mit id < 80) steht unabhängig von der Installationssprache immer zur Verfügung.
+
 > **Hinweis:** Bei großen Projekten mit vielen Issues stattdessen einen vorgespeicherten MantisBT-Filter über `filter_id` verwenden — die clientseitige Filterung durchsucht nur die ersten 500 Issues (10 Seiten × 50).
 
 ---
@@ -456,8 +458,8 @@ Legt ein neues Issue in MantisBT an.
 - `project_id` — numerische Projekt-ID
 - `category` — Kategoriename als Zeichenkette
 - `description` — _(optional)_ ausführliche Beschreibung
-- `priority` — _(optional)_ kanonischer englischer Prioritätsname: `none`, `low`, `normal`, `high`, `urgent`, `immediate` — lokalisierte Bezeichnungen über `get_issue_enums()` ermitteln
-- `severity` — _(optional)_ kanonischer englischer Schweregrad-Name: `feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`; Standard ist `"minor"` — lokalisierte Bezeichnungen über `get_issue_enums()` ermitteln
+- `priority` — _(optional)_ Priorität: kanonischer englischer Name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) oder lokalisierter Begriff. Standard: `"normal"`. Alle verfügbaren Werte über `get_issue_enums()` ermitteln.
+- `severity` — _(optional)_ Schweregrad: kanonischer englischer Name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) oder lokalisierter Begriff. Standard: `"minor"`. Alle verfügbaren Werte über `get_issue_enums()` ermitteln.
 - `handler` — _(optional)_ Benutzername des Bearbeiters (wird automatisch in eine ID aufgelöst)
 - `handler_id` — _(optional)_ numerische Benutzer-ID des Bearbeiters (Alternative zu `handler`)
 
@@ -500,11 +502,11 @@ Legt ein neues Issue in MantisBT an.
 
 **Fehler: unbekannter Schweregrad oder unbekannte Priorität**
 
-Wird ein nicht erkannter Name für `severity` oder `priority` übergeben, gibt der Server einen Fehler zurück, der die gültigen Werte auflistet:
+Der Server prüft zuerst kanonische englische Namen und fällt dann auf einen Live-`get_issue_enums`-Lookup zurück. Ein Fehler wird nur zurückgegeben, wenn der Wert weder kanonisch noch lokalisiert erkannt wird:
 
-> Error: Invalid severity "schwerer Fehler". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_enums to see localized labels.
+> Error: Invalid severity "xyz". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_enums to see localized labels.
 
-Mit `get_issue_enums` lassen sich die kanonischen Namen ermitteln, die `create_issue` akzeptiert.
+Mit `get_issue_enums` lassen sich alle akzeptierten Werte ermitteln — sowohl kanonische als auch lokalisierte Namen funktionieren.
 
 ---
 
@@ -519,6 +521,8 @@ Löst ein Issue auf und schließt es. **Immer beide Felder** `status` und `resol
 - `fields.status` — Status-Objekt mit Name
 - `fields.resolution` — Auflösungs-Objekt mit ID
 
+> **Hinweis:** Alle 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 — dadurch ist die Übergabe sprachunabhängig.
+
 **Request:**
 
 ```json
@@ -1246,6 +1250,7 @@ Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich si
 **Parameter:**
 - `query` — Suchanfrage in natürlicher Sprache
 - `top_n` — _(optional)_ Anzahl zurückzugebender Ergebnisse; Standard 10
+- `highlight` — _(optional)_ bei `true` werden keyword-basierte Ausschnitte je Ergebnis ergänzt; Standard `false`
 
 **Request:**
 
@@ -1280,6 +1285,7 @@ Reichert Suchergebnisse mit bestimmten Feldern aus MantisBT an. Ohne `select` we
 - `query` — Suchanfrage in natürlicher Sprache
 - `top_n` — _(optional)_ Anzahl der Ergebnisse
 - `select` — kommagetrennte Feldnamen, die für jedes Ergebnis abgerufen werden
+- `highlight` — _(optional)_ bei `true` werden keyword-basierte Ausschnitte je Ergebnis ergänzt; Standard `false`
 
 **Request:**
 
@@ -1310,6 +1316,57 @@ Reichert Suchergebnisse mit bestimmten Feldern aus MantisBT an. Ohne `select` we
 
 ---
 
+### Suche mit Keyword-Highlights
+
+Zeigt, welcher Teil eines Issues mit der Suchanfrage übereinstimmt. Jedes Ergebnis, das lexikalisch mit der Anfrage übereinstimmt, erhält ein `highlights`-Feld mit fett hervorgehobenen Ausschnitten. Highlights sind keyword-basiert (lexikalisch), nicht semantisch — Ergebnisse ohne lexikalische Übereinstimmung haben kein `highlights`-Feld.
+
+**Tool:** `search_issues`
+
+**Parameter:**
+- `query` — Suchanfrage in natürlicher Sprache
+- `top_n` — _(optional)_ Anzahl der Ergebnisse; Standard 10
+- `highlight` — auf `true` setzen, um Highlights zu aktivieren
+
+**Request:**
+
+```json
+{
+  "query": "Login-Fehler nach Passwort-Reset",
+  "top_n": 5,
+  "highlight": true
+}
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": 1042,
+    "score": 0.91,
+    "highlights": {
+      "summary": "**Login**-Button reagiert nach **Passwort**-**Reset** auf Mobile Safari nicht",
+      "description": "…Benutzer tippt auf **Login** und es passiert nichts. Reproduzierbar nach einem **Passwort**-**Reset**-Vorgang…"
+    }
+  },
+  {
+    "id": 987,
+    "score": 0.84,
+    "highlights": {
+      "summary": "**Login** schlägt mit 401 fehl — Token ungültig"
+    }
+  },
+  {
+    "id": 1015,
+    "score": 0.79
+  }
+]
+```
+
+> **Hinweis:** Nur Ergebnisse mit mindestens einer Keyword-Übereinstimmung in `summary` oder `description` erhalten ein `highlights`-Feld. Der `description`-Ausschnitt umfasst ca. 300 Zeichen, zentriert um den ersten Treffer. Wenn zusätzlich `select` gesetzt ist und `summary` oder `description` enthält, werden die Highlights aus den abgerufenen Feldern generiert; andernfalls stammen sie aus den indizierten Metadaten.
+
+---
+
 ## Projekte & Kategorien
 
 ### Projektkategorien auflisten
@@ -1635,7 +1692,7 @@ Gibt eine kombinierte Ansicht eines einzelnen Projekts zurück: Projektfelder so
 
 ### Issue-Enum-Werte lesen
 
-Gibt gültige ID/Name-Paare für alle Issue-Enum-Felder zurück (Severity, Priority, Status, Resolution, Reproducibility). Vor `create_issue` oder `update_issue` verwenden, um kanonische englische Namen nachzuschlagen.
+Gibt gültige ID/Name-Paare für alle Issue-Enum-Felder zurück (Severity, Priority, Status, Resolution, Reproducibility). Bei `create_issue` werden sowohl kanonische englische Namen als auch lokalisierte `name`/`label`-Werte akzeptiert — diese Ressource hilft, alle verfügbaren Werte zu ermitteln.
 
 **Ressource-URI:** `mantis://enums`
 

package/docs/cookbook.md

@@ -145,7 +145,7 @@ Returns the enum values configured on your specific MantisBT instance. Use this
 }
 ```
 
-> **Note:** The names returned by `get_issue_enums()` may be localized. `create_issue` and `update_issue` require **canonical English names** for `severity` and `priority` (e.g. `minor`, `major`, `normal`) — look at the `canonical_name` field in the response if you are unsure.
+> **Note:** On localized installations, `get_issue_enums()` returns a `name` in the local language and an optional `canonical_name` with the English original. `create_issue` accepts **both** — pass either the canonical English name (e.g. `minor`) or the localized name (e.g. `Unschönheit`). The server resolves the value automatically.
 
 ---
 
@@ -347,6 +347,8 @@ Returns only issues with a specific status. The filter is applied client-side
 }
 ```
 
+> **Note:** Canonical status names (e.g. `"new"`, `"resolved"`) are resolved to their numeric ID and matched by `issue.status.id` — this works correctly even on localized installations where the API returns translated status names. Localized names passed directly (e.g. `"Neu"`) are matched by name as a fallback. The `"open"` shorthand (all statuses with id < 80) is always available regardless of installation language.
+
 > **Note:** For large projects with many issues, use a pre-saved MantisBT filter via `filter_id` instead — client-side filtering only scans the first 500 issues (10 pages × 50).
 
 ---
@@ -456,8 +458,8 @@ Creates a new issue in MantisBT.
 - `project_id` — numeric project ID
 - `category` — category name string
 - `description` — _(optional)_ detailed description
-- `priority` — _(optional)_ canonical English priority name: `none`, `low`, `normal`, `high`, `urgent`, `immediate` — call `get_issue_enums()` to see localized labels
-- `severity` — _(optional)_ canonical English severity name: `feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`; default is `"minor"` — call `get_issue_enums()` to see localized labels
+- `priority` — _(optional)_ priority: canonical English name (`none`, `low`, `normal`, `high`, `urgent`, `immediate`) or localized label. Default: `"normal"`. Use `get_issue_enums()` to see all available values.
+- `severity` — _(optional)_ severity: canonical English name (`feature`, `trivial`, `text`, `tweak`, `minor`, `major`, `crash`, `block`) or localized label. Default: `"minor"`. Use `get_issue_enums()` to see all available values.
 - `handler` — _(optional)_ assignee username (resolved to ID automatically)
 - `handler_id` — _(optional)_ assignee numeric user ID (alternative to `handler`)
 
@@ -500,11 +502,11 @@ Creates a new issue in MantisBT.
 
 **Error: unknown severity or priority**
 
-If an unrecognized name is passed for `severity` or `priority`, the server returns an error listing valid values:
+The server first checks canonical English names, then falls back to a live `get_issue_enums` lookup. An error is only returned if the value matches neither:
 
-> Error: Invalid severity "schwerer Fehler". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_enums to see localized labels.
+> Error: Invalid severity "xyz". Valid canonical names: feature, trivial, text, tweak, minor, major, crash, block. Call get_issue_enums to see localized labels.
 
-Use `get_issue_enums` to discover the canonical names accepted by `create_issue`.
+Use `get_issue_enums` to discover all accepted values — both canonical and localized names work.
 
 ---
 
@@ -519,6 +521,8 @@ Resolves and closes an issue. Always set **both** `status` and `resolution` —
 - `fields.status` — status object with name
 - `fields.resolution` — resolution object with id
 
+> **Note:** All enum fields (`status`, `priority`, `severity`, `resolution`, `reproducibility`) accept the canonical English name, a localized name, or a numeric `id`. The server resolves names to IDs automatically — IDs are always sent to the API, ensuring language-independence.
+
 **Request:**
 
 ```json
@@ -1246,6 +1250,7 @@ Finds issues semantically similar to a natural language query. Returns issue IDs
 **Parameters:**
 - `query` — natural language search query
 - `top_n` — _(optional)_ number of results to return; default 10
+- `highlight` — _(optional)_ when `true`, adds keyword-matched excerpts to each result; default `false`
 
 **Request:**
 
@@ -1280,6 +1285,7 @@ Enriches search results with specific fields fetched from MantisBT. Without `sel
 - `query` — natural language search query
 - `top_n` — _(optional)_ number of results
 - `select` — comma-separated field names to fetch for each result
+- `highlight` — _(optional)_ when `true`, adds keyword-matched excerpts to each result; default `false`
 
 **Request:**
 
@@ -1310,6 +1316,57 @@ Enriches search results with specific fields fetched from MantisBT. Without `sel
 
 ---
 
+### Search with keyword highlights
+
+Shows which part of an issue matched the search query. Each result that has keyword overlap with the query receives a `highlights` field with bold-marked excerpts. Highlights are keyword-based (lexical), not semantic — results with no lexical overlap will not have a `highlights` field.
+
+**Tool:** `search_issues`
+
+**Parameters:**
+- `query` — natural language search query
+- `top_n` — _(optional)_ number of results; default 10
+- `highlight` — set to `true` to enable highlights
+
+**Request:**
+
+```json
+{
+  "query": "login error after password reset",
+  "top_n": 5,
+  "highlight": true
+}
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": 1042,
+    "score": 0.91,
+    "highlights": {
+      "summary": "**Login** button unresponsive after **password** **reset** on mobile Safari",
+      "description": "…user taps **login** and nothing happens. Reproducible after a **password** **reset** flow…"
+    }
+  },
+  {
+    "id": 987,
+    "score": 0.84,
+    "highlights": {
+      "summary": "**Login** fails with 401 — token invalidated"
+    }
+  },
+  {
+    "id": 1015,
+    "score": 0.79
+  }
+]
+```
+
+> **Note:** Only results with at least one keyword match in `summary` or `description` receive a `highlights` field. The `description` excerpt is approximately 300 characters, centred around the first match. When `select` is also set and includes `summary` or `description`, highlights are generated from the fetched fields; otherwise they come from the indexed metadata.
+
+---
+
 ## Projects & Categories
 
 ### List project categories
@@ -1635,7 +1692,7 @@ Returns a combined view of a single project: its fields plus all members, versio
 
 ### Read issue enum values
 
-Returns valid ID/name pairs for all issue enum fields (severity, priority, status, resolution, reproducibility). Use this to look up canonical English names before calling `create_issue` or `update_issue`.
+Returns valid ID/name pairs for all issue enum fields (severity, priority, status, resolution, reproducibility). For `create_issue`, both the canonical English name and the localized `name`/`label` are accepted — this resource helps discover all available values.
 
 **Resource URI:** `mantis://enums`
 

package/docs/examples.de.md

@@ -155,6 +155,18 @@ Die semantische Suche versteht die *Bedeutung* deiner Frage — nicht nur einzel
 
 ---
 
+### Keyword-Highlights
+
+> »Suche nach Login-Fehlern und zeige mir, welche Stelle im Ticket relevant ist.«
+
+> »Finde Issues zum Passwort-Reset-Ablauf und hebe die passenden Stellen hervor, damit ich die Ergebnisse schnell überfliegen kann.«
+
+> »Suche nach 'Rechnungsexport' und markiere die relevanten Ausschnitte in Titel und Beschreibung.«
+
+Exakte Parameter und Response-Shape: [Cookbook — Suche mit Keyword-Highlights](cookbook.de.md#suche-mit-keyword-highlights).
+
+---
+
 ### Unscharfe / terminologieunabhängige Suche
 
 > »Finde Issues zu 'doppelten Einträgen' — sie könnten auch als 'zweimal angezeigt', 'doppelte Datensätze' oder 'Phantom-Zeilen' beschrieben sein.«