@dpesch/mantisbt-mcp-server 1.5.7 → 1.5.9

package/docs/examples.de.md

@@ -0,0 +1,158 @@
+# Anwendungsbeispiele
+
+Praktische Beispiele für die Interaktion mit MantisBT über Claude, sobald der MCP-Server verbunden ist. Einfach in natürlicher Sprache fragen — keine Tool-Namen oder Parameter erforderlich. Für exakte Tool-Aufrufe und Parameter siehe das [Cookbook](cookbook.de.md).
+
+---
+
+## Alltägliche Anwendungsfälle
+
+### Issues durchsuchen und filtern
+
+> »Zeige mir alle offenen Issues im Projekt Webshop.«
+
+> »Welche Bugs sind mir aktuell zugewiesen?«
+
+> »Liste alle ungelösten Issues mit Priorität 'dringend' im Backend-Projekt.«
+
+> »Was ist der Status von Issue #1042?«
+
+> »Zeige mir alle Issues, die jsmith diesen Monat gemeldet hat.«
+
+> »Welche Issues im Webshop-Projekt blockieren das Release 2.4.0?«
+
+---
+
+### Issues erstellen
+
+> »Erstelle einen Bug-Report: Auf der Checkout-Seite wird die Bestellung doppelt abgeschickt, wenn man zweimal auf 'Bestellen' klickt. Kategorie: Shop, Schweregrad: schwerwiegend.«
+
+> »Öffne ein neues Issue im API-Projekt — der Token-Refresh-Endpoint gibt 500 zurück, wenn das Refresh-Token abgelaufen ist. Dem Backend-Team zuweisen.«
+
+> »Erstelle einen Feature-Request im Frontend-Projekt für einen Dunkelmodus in den Benutzereinstellungen. Niedrige Priorität, kein Fälligkeitsdatum.«
+
+---
+
+### Issues aktualisieren
+
+> »Markiere Issue #1042 als gelöst.«
+
+> »Weise Issue #887 an jdoe neu zu.«
+
+> »Ändere den Schweregrad von #1099 auf 'schwerwiegend' und füge eine Notiz hinzu: auf Produktion reproduziert.«
+
+> »Setze die Fix-Version von Issues #901 und #902 auf 2.4.1.«
+
+---
+
+### Notizen und Kommentare
+
+> »Füge einen Kommentar zu #1042 hinzu: Fix auf Staging ausgerollt, warte auf QA-Freigabe.«
+
+> »Zeige mir alle Notizen zu Issue #774.«
+
+> »Füge eine private Notiz zu #512 hinzu: Kundenreferenz AC-2291, nicht weitergeben.«
+
+---
+
+### Anhänge
+
+> »Hänge die Datei /tmp/error.log an Issue #1042 an.«
+
+> »Welche Dateien sind an Issue #930 angehängt?«
+
+---
+
+### Beziehungen
+
+> »Markiere Issue #1044 als Duplikat von #1042.«
+
+> »Verknüpfe #901 und #902 als verwandte Issues.«
+
+> »Issue #1100 blockiert #1101 — bitte diese Beziehung anlegen.« 
+> *(Richtung ist entscheidend: #1100 ist das blockierende Issue)*
+
+---
+
+### Tags
+
+> »Versehe Issue #1042 mit den Tags 'regression' und 'hotfix'.«
+
+> »Entferne den Tag 'wontfix' von Issue #887.«
+
+> »Welche Tags gibt es in dieser MantisBT-Instanz?«
+
+---
+
+### Projektmetadaten
+
+> »Auf welche Projekte habe ich Zugriff?«
+
+> »Welche Versionen sind im Webshop-Projekt definiert?«
+
+> »Liste alle Kategorien im Backend-Projekt.«
+
+> »Wer sind die Mitglieder des API-Projekts?«
+
+---
+
+### Triage und Auswertung
+
+> »Gib mir einen Überblick über alle kritischen und dringenden offenen Issues in allen Projekten.«
+
+> »Welche Issues im Backend-Projekt sind seit mehr als 30 Tagen ohne Aktivität offen?«
+
+> »Was sind die häufigsten Bug-Typen der letzten sechs Monate?«
+
+> »Fasse die Notizen zu Issue #774 zusammen und schlage einen nächsten Schritt vor.«
+
+> »Liste alle Issues mit dem Tag 'regression' und fasse zusammen, was schiefgelaufen ist.«
+
+---
+
+## Semantische Suche
+
+Die semantische Suche versteht die *Bedeutung* deiner Frage — nicht nur einzelne Schlüsselwörter. Sie findet konzeptionell verwandte Issues, auch wenn die genaue Formulierung abweicht. Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
+
+### Duplikaterkennung vor dem Anlegen
+
+> »Bevor ich ein neues Issue anlege: Hat jemand schon ein Problem mit dem Login-Formular nach einem Passwort-Reset gemeldet?«
+
+> »Gibt es bereits ein Ticket wegen langsamer PDF-Generierung bei großen Rechnungen?«
+
+> »Suche nach Issues ähnlich wie: 'Die Benutzersitzung geht verloren, wenn man den Browser-Tab wechselt'.«
+
+---
+
+### Thematische Übersichten
+
+> »Zeig mir relevante Issues rund um die Zahlungsabwicklung — projektübergreifend.«
+
+> »Zeig mir Beispiele für gemeldete E-Mail-Zustellungsfehler.«
+
+> »Welche Issues erwähnen Performance-Probleme auf Mobilgeräten?«
+
+---
+
+### 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.«
+
+> »Suche nach authentifizierungsbezogenen Issues — die Berichte verwenden möglicherweise 'Login', 'Anmeldung', 'Token', 'Session' oder 'Auth'.«
+
+---
+
+### Projektübergreifende Recherche
+
+> »Wurde der Bild-Upload-Bug, den wir im Webshop behoben haben, auch im Mobile-Projekt gemeldet?«
+
+> »Welche Projekte haben offene Issues zu DSGVO oder Datenexport?«
+
+---
+
+### Einarbeitung und Wissenstransfer
+
+> »Zeig mir Tickets, die erklären warum der Authentifizierungsfluss so gebaut wurde wie er ist.«
+
+> »Gibt es bekannte Fallstricke beim Einrichten der Deployment-Pipeline?«
+
+> »Welche Issues beschreiben Probleme, die beim ersten Einrichten der Entwicklungsumgebung auftreten?«

package/docs/examples.md

@@ -0,0 +1,158 @@
+# Usage Examples
+
+Practical examples of how to interact with MantisBT through Claude once the MCP server is connected. Just ask in natural language — no tool names or parameters required. For exact tool calls and parameters, see the [Cookbook](cookbook.md).
+
+---
+
+## Everyday Use Cases
+
+### Browsing and searching issues
+
+> "Show me all open issues in the Webshop project."
+
+> "What bugs are currently assigned to me?"
+
+> "List the unresolved issues with priority 'urgent' in the Backend project."
+
+> "What's the status of issue #1042?"
+
+> "Show me all issues reported by jsmith this month."
+
+> "Which issues in the Webshop project are blocking the 2.4.0 release?"
+
+---
+
+### Creating issues
+
+> "Create a bug report: on the checkout page, clicking 'Place order' twice submits the order twice. Category: Shop, severity: major."
+
+> "Open a new issue in the API project — the token refresh endpoint returns 500 when the refresh token has expired. Assign it to the backend team."
+
+> "Create a feature request in the Frontend project for a dark mode in the user settings. Low priority, no due date."
+
+---
+
+### Updating issues
+
+> "Mark issue #1042 as resolved."
+
+> "Reassign issue #887 to jdoe."
+
+> "Change the severity of #1099 to 'major' and add a note: reproduced on production."
+
+> "Set the fix version of issues #901 and #902 to 2.4.1."
+
+---
+
+### Notes and comments
+
+> "Add a comment to #1042: fix deployed to staging, awaiting QA sign-off."
+
+> "Show me all notes on issue #774."
+
+> "Add a private note to #512: customer reference AC-2291, do not disclose."
+
+---
+
+### Attachments
+
+> "Attach the file /tmp/error.log to issue #1042."
+
+> "What files are attached to issue #930?"
+
+---
+
+### Relationships
+
+> "Mark issue #1044 as a duplicate of #1042."
+
+> "Link #901 and #902 as related issues."
+
+> "Issue #1100 blocks #1101 — please create that relationship."
+> *(direction matters: #1100 is the blocking issue)*
+
+---
+
+### Tags
+
+> "Tag issue #1042 with 'regression' and 'hotfix'."
+
+> "Remove the 'wontfix' tag from issue #887."
+
+> "Which tags are available in this MantisBT instance?"
+
+---
+
+### Project metadata
+
+> "Which projects do I have access to?"
+
+> "What versions are defined in the Webshop project?"
+
+> "List all categories in the Backend project."
+
+> "Who are the members of the API project?"
+
+---
+
+### Triage and reporting
+
+> "Give me an overview of all critical and urgent open issues across all projects."
+
+> "Which issues in the Backend project have been open for more than 30 days without any activity?"
+
+> "What are the most common types of bugs reported in the last six months?"
+
+> "Summarise the notes on issue #774 and suggest a next step."
+
+> "List all issues tagged 'regression' and summarise what went wrong."
+
+---
+
+## Semantic Search
+
+Semantic search understands the *meaning* of your question — not just keywords. It finds conceptually related issues even when the exact wording differs. Enable it with `MANTIS_SEARCH_ENABLED=true`.
+
+### Duplicate detection before filing a report
+
+> "Before I create a new issue: has anyone reported a problem with the login form after a password reset?"
+
+> "Is there already a ticket about slow PDF generation for large invoices?"
+
+> "Search for issues similar to: 'user session is lost when switching browser tabs'."
+
+---
+
+### Thematic overviews
+
+> "Show me relevant issues related to payment processing — across all projects."
+
+> "Show me examples of reported email delivery failures."
+
+> "Which issues mention performance problems on mobile devices?"
+
+---
+
+### Fuzzy / terminology-independent search
+
+> "Find issues about 'duplicate entries' — they might also be described as 'shown twice', 'double records', or 'phantom rows'."
+
+> "Search for authentication-related issues — the reports might use 'login', 'sign-in', 'token', 'session', or 'auth'."
+
+---
+
+### Cross-project research
+
+> "Is the image upload bug we fixed in the Webshop also reported in the Mobile project?"
+
+> "Which projects have open issues related to GDPR or data export?"
+
+---
+
+### Onboarding and knowledge transfer
+
+> "Show me tickets that explain why the authentication flow was built this way."
+
+> "Are there any known pitfalls when setting up the deployment pipeline?"
+
+> "Which issues describe problems that occur during initial environment setup?"

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
   "license": "MIT",
+  "homepage": "https://codeberg.org/dpesch/mantisbt-mcp-server",
+  "bugs": {
+    "url": "https://codeberg.org/dpesch/mantisbt-mcp-server/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://codeberg.org/dpesch/mantisbt-mcp-server"

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.5.7",
+  "version": "1.5.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.5.7",
+      "version": "1.5.9",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tests/tools/issues.test.ts

@@ -112,8 +112,10 @@ describe('create_issue', () => {
     expect(mockServer.hasToolRegistered('create_issue')).toBe(true);
   });
 
-  it('sends severity: { name: "minor" } by default when no severity is provided', async () => {
+  it('sends severity as { id: 50 } (minor) by default when no severity is provided', async () => {
     // Regression: omitting severity caused MantisBT to store 0 → displayed as "@0@".
+    // The server now resolves canonical English names to IDs so MantisBT language setting
+    // does not affect how the value is stored.
     // validate: true ensures Zod defaults are applied before the handler runs.
     vi.mocked(fetch).mockResolvedValue(
       makeResponse(201, JSON.stringify({ issue: { id: 100, summary: 'Test' } }))
@@ -126,7 +128,7 @@ describe('create_issue', () => {
     }, { validate: true });
 
     const body = JSON.parse(vi.mocked(fetch).mock.calls[0]![1]!.body as string) as Record<string, unknown>;
-    expect(body.severity).toEqual({ name: 'minor' });
+    expect(body.severity).toEqual({ id: 50 });
   });
 
   it('returns full issue object when API responds with complete issue', async () => {
@@ -137,7 +139,7 @@ describe('create_issue', () => {
 
     const result = await mockServer.callTool('create_issue', {
       summary: 'New issue', project_id: 1, category: 'General',
-    });
+    }, { validate: true });
 
     expect(result.isError).toBeUndefined();
     const parsed = JSON.parse(result.content[0]!.text) as typeof fullIssue;
@@ -155,7 +157,7 @@ describe('create_issue', () => {
 
     const result = await mockServer.callTool('create_issue', {
       summary: 'Created issue', project_id: 1, category: 'General',
-    });
+    }, { validate: true });
 
     expect(result.isError).toBeUndefined();
     const parsed = JSON.parse(result.content[0]!.text) as typeof fullIssue;
@@ -173,7 +175,7 @@ describe('create_issue', () => {
 
     const result = await mockServer.callTool('create_issue', {
       summary: 'Test', project_id: 1, category: 'General',
-    });
+    }, { validate: true });
 
     expect(result.isError).toBeUndefined();
     const parsed = JSON.parse(result.content[0]!.text) as { id: number };
@@ -193,7 +195,21 @@ describe('create_issue', () => {
     }, { validate: true });
 
     const body = JSON.parse(vi.mocked(fetch).mock.calls[0]![1]!.body as string) as Record<string, unknown>;
-    expect(body.severity).toEqual({ name: 'crash' });
+    expect(body.severity).toEqual({ id: 70 });
+  });
+
+  it('returns an error for an unknown severity name', async () => {
+    const result = await mockServer.callTool('create_issue', {
+      summary: 'Test',
+      project_id: 1,
+      category: 'General',
+      severity: 'schwerer Fehler',
+    }, { validate: true });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('schwerer Fehler');
+    expect(result.content[0]!.text).toContain('minor');
+    expect(fetch).not.toHaveBeenCalled();
   });
 });
 
@@ -213,7 +229,7 @@ describe('create_issue – handler username', () => {
 
     await server.callTool('create_issue', {
       summary: 'Test', project_id: 1, category: 'General', handler: 'dom',
-    });
+    }, { validate: true });
 
     const body = JSON.parse(vi.mocked(fetch).mock.calls[0]![1]!.body as string) as { handler: { id: number } };
     expect(body.handler).toEqual({ id: 7 });
@@ -230,7 +246,7 @@ describe('create_issue – handler username', () => {
 
     await server.callTool('create_issue', {
       summary: 'Test', project_id: 1, category: 'General', handler: 'John Doe',
-    });
+    }, { validate: true });
 
     const body = JSON.parse(vi.mocked(fetch).mock.calls[0]![1]!.body as string) as { handler: { id: number } };
     expect(body.handler).toEqual({ id: 9 });
@@ -247,7 +263,7 @@ describe('create_issue – handler username', () => {
 
     await server.callTool('create_issue', {
       summary: 'Test', project_id: 1, category: 'General', handler: 'alice',
-    });
+    }, { validate: true });
 
     const projectUsersCall = vi.mocked(fetch).mock.calls[0]![0] as string;
     expect(projectUsersCall).toContain('projects/1/users');
@@ -282,7 +298,7 @@ describe('create_issue – handler username', () => {
 
     await server.callTool('create_issue', {
       summary: 'Test', project_id: 1, category: 'General', handler_id: 99, handler: 'dom',
-    });
+    }, { validate: true });
 
     const body = JSON.parse(vi.mocked(fetch).mock.calls[0]![1]!.body as string) as { handler: { id: number } };
     expect(body.handler).toEqual({ id: 99 });