@dpesch/mantisbt-mcp-server 1.5.8 → 1.5.9

package/CHANGELOG.md

@@ -7,6 +7,18 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.5.9] – 2026-03-20
+
+### Fixed
+- `create_issue` now validates `severity` and `priority` against canonical English names and returns a clear error for unknown values; sends `{ id }` instead of `{ name }` to work correctly on localized MantisBT installations
+
+### Added
+- Cookbook (EN + DE): tool-oriented recipes with copy-paste-ready parameter examples for all registered tools ([docs/cookbook.md](docs/cookbook.md), [docs/cookbook.de.md](docs/cookbook.de.md))
+- Usage examples (EN + DE): natural language prompt examples for everyday use cases ([docs/examples.md](docs/examples.md), [docs/examples.de.md](docs/examples.de.md))
+- README: documentation section linking to cookbook and examples
+
+---
+
 ## [1.5.8] – 2026-03-18
 
 ### Added

package/README.de.md

@@ -98,7 +98,7 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 |---|---|
 | `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 |
-| `create_issue` | Neues Issue anlegen; optionaler `handler`-Parameter akzeptiert einen Benutzernamen als Alternative zu `handler_id` (wird gegen die Projektmitglieder aufgelöst) |
+| `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 |
 | `delete_issue` | Issue löschen |
 
@@ -211,6 +211,11 @@ MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.
 
 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)
+
 ## Entwicklung
 
 ```bash

package/README.md

@@ -98,7 +98,7 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 |---|---|
 | `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 |
-| `create_issue` | Create a new issue; optional `handler` parameter accepts a username as alternative to `handler_id` (resolved against project members) |
+| `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 |
 | `delete_issue` | Delete an issue |
 
@@ -211,6 +211,11 @@ MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.
 
 Health check: `GET http://localhost:3456/health` (always public, no token required)
 
+## Documentation
+
+- [**Cookbook**](docs/cookbook.md) — tool-oriented recipes with copy-paste-ready parameter examples for all registered tools
+- [**Usage Examples**](docs/examples.md) — natural language prompt examples for everyday use cases (no tool names required)
+
 ## Development
 
 ```bash

package/dist/constants.js

@@ -93,6 +93,18 @@ export const MANTIS_CANONICAL_ENUM_NAMES = {
     },
 };
 // ---------------------------------------------------------------------------
+// Reverse lookup: canonical English enum name → numeric ID.
+// Case-insensitive. Returns undefined when the name is not in the table.
+// ---------------------------------------------------------------------------
+export function resolveEnumId(group, name) {
+    if (!name)
+        return undefined;
+    const map = MANTIS_CANONICAL_ENUM_NAMES[group];
+    const lower = name.toLowerCase();
+    const entry = Object.entries(map).find(([, n]) => n.toLowerCase() === lower);
+    return entry ? Number(entry[0]) : undefined;
+}
+// ---------------------------------------------------------------------------
 // Issue enum config option names
 // ---------------------------------------------------------------------------
 export const ISSUE_ENUM_OPTIONS = [

package/dist/tools/issues.js

@@ -1,12 +1,21 @@
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
-import { MANTIS_RESOLVED_STATUS_ID } from '../constants.js';
+import { MANTIS_CANONICAL_ENUM_NAMES, MANTIS_RESOLVED_STATUS_ID, resolveEnumId } from '../constants.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 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.`;
+    }
+    return { id };
+}
 export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     // get_issue
@@ -138,8 +147,8 @@ export function registerIssueTools(server, client, cache) {
             description: z.string().default('').describe('Detailed issue description'),
             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().optional().describe('Priority name (e.g. "normal", "high", "urgent", "immediate", "low", "none")'),
-            severity: z.string().default('minor').describe('Severity name (e.g. "minor", "major", "crash", "block", "feature", "trivial", "text") — default: "minor"'),
+            priority: z.string().optional().describe('Priority name — must be a canonical English name: none, low, normal, high, urgent, immediate. 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.'),
             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.'),
         }),
@@ -180,9 +189,16 @@ export function registerIssueTools(server, client, cache) {
                 project: { id: project_id },
                 category: { name: category },
             };
-            if (priority)
-                body.priority = { name: priority };
-            body.severity = { name: severity };
+            if (priority) {
+                const priorityResolved = resolveEnum('priority', priority);
+                if (typeof priorityResolved === 'string')
+                    return { content: [{ type: 'text', text: errorText(priorityResolved) }], isError: true };
+                body.priority = priorityResolved;
+            }
+            const severityResolved = resolveEnum('severity', severity);
+            if (typeof severityResolved === 'string')
+                return { content: [{ type: 'text', text: errorText(severityResolved) }], isError: true };
+            body.severity = severityResolved;
             if (resolvedHandlerId)
                 body.handler = { id: resolvedHandlerId };
             const raw = await client.post('issues', body);