@dpesch/mantisbt-mcp-server 1.5.8 → 1.6.0

package/docs/examples.de.md

@@ -0,0 +1,200 @@
+# 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.«
+
+---
+
+## Geführte Prompt-Workflows
+
+Der Server enthält Prompt-Templates, die Claude durch strukturierte Arbeitsabläufe führen — Tool-Namen oder Parameter müssen nicht manuell angegeben werden. Die Prompts werden aus einem MCP-fähigen Client beim Namen aufgerufen.
+
+### Issues über Prompt-Templates anlegen
+
+> »Verwende den Prompt `create-bug-report` für das Safari-Login-Issue: Projekt 3, Kategorie UI, Titel 'Login-Button reagiert auf Mobile Safari nicht', Beschreibung 'Ein Tipp auf den Login-Button auf iPhone 14 / Safari 17 bewirkt nichts', Schritte: Login-Seite öffnen → Anmelden antippen → nichts passiert, Erwartet: Weiterleitung zum Dashboard, Tatsächlich: Formular bleibt geöffnet.«
+
+> »Nutze `create-feature-request` für Projekt 5, Kategorie UX: Dunkelmodus-Schalter auf der Einstellungsseite hinzufügen.«
+
+### Zusammenfassen und Berichten
+
+> »Führe den Prompt `summarize-issue` für Issue #1042 aus.«
+
+> »Verwende den Prompt `project-status` für Projekt 3, um einen Überblick über offene Issues nach Schweregrad zu erhalten.«
+
+---
+
+## 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?«
+
+---
+
+## Ressourcen
+
+MCP-Ressourcen sind URI-adressierbare, schreibgeschützte Daten, die Clients direkt per URI abrufen können — kein Tool-Aufruf nötig. Die Ressourcen-Unterstützung variiert je nach Client; wenn der verwendete Client keine Ressourcen unterstützt, das entsprechende Tool als Alternative verwenden.
+
+### Server-Zustand über Ressourcen abrufen
+
+> »Lese `mantis://me`, um zu sehen, welches Konto der MCP-Server verwendet.«
+
+> »Rufe `mantis://projects` ab, um die Liste der verfügbaren Projekte zu erhalten.«
+
+> »Lade `mantis://enums`, um die gültigen Severity- und Priority-Werte einzusehen, bevor ein Issue erstellt wird.«
+
+### Alternative Tools für Clients ohne Ressourcen-Unterstützung
+
+Wenn der Client keine Ressourcen unterstützt, Claude einfach das entsprechende Tool verwenden lassen:
+
+> »Zeig mir mein Benutzerprofil.« *(verwendet `get_current_user`)*
+
+> »Welche Projekte sind verfügbar?« *(verwendet `list_projects`)*
+
+> »Welche Prioritätswerte sind gültig?« *(verwendet `get_issue_enums`)*

package/docs/examples.md

@@ -0,0 +1,200 @@
+# 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."
+
+---
+
+## Guided Prompt Workflows
+
+The server ships with prompt templates that guide Claude through structured workflows — no need to specify tool names or parameters manually. Invoke them by name from a MCP-capable client.
+
+### Creating issues from a prompt template
+
+> "Use the `create-bug-report` prompt to file the Safari login issue: project 3, category UI, summary 'Login button unresponsive on mobile Safari', description 'Tapping login on iPhone 14 / Safari 17 does nothing', steps: open login page → tap Login → nothing happens, expected: redirect to dashboard, actual: form stays open."
+
+> "Use `create-feature-request` for project 5, category UX: add a dark mode toggle to the settings page."
+
+### Summarizing and reporting
+
+> "Run the `summarize-issue` prompt for issue #1042."
+
+> "Use the `project-status` prompt for project 3 to get an overview of open issues grouped by severity."
+
+---
+
+## 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?"
+
+---
+
+## Resources
+
+MCP Resources are URI-addressable, read-only data that clients can fetch directly by URI — no tool invocation required. Resource support varies by client; if your client does not support Resources, use the equivalent tool instead.
+
+### Reading server state via resources
+
+> "Read `mantis://me` to see which account the MCP server is using."
+
+> "Fetch `mantis://projects` to get the list of available projects."
+
+> "Load `mantis://enums` to see valid severity and priority values before creating an issue."
+
+### Equivalent tool fallbacks
+
+If your client does not support Resources, ask Claude to use the corresponding tool:
+
+> "Show me my user profile." *(uses `get_current_user`)*
+
+> "Which projects are available?" *(uses `list_projects`)*
+
+> "What are the valid priority values?" *(uses `get_issue_enums`)*

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.5.8",
+  "version": "1.6.0",
   "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"
   },
-  "keywords": ["mcp", "mantisbt", "bugtracker", "mantis", "model-context-protocol"],
+  "keywords": ["mcp", "mcp-server", "mantisbt", "bugtracker", "mantis", "model-context-protocol"],
   "main": "dist/index.js",
   "bin": {
     "mantisbt-mcp-server": "dist/index.js"

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

package/tests/client.test.ts

@@ -209,6 +209,76 @@ describe('MantisClient – HTTP methods', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Credential factory (lazy constructor)
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – credential factory', () => {
+  it('does not call the factory until the first API method', async () => {
+    const factory = vi.fn().mockResolvedValue({
+      baseUrl: 'https://lazy.example.com',
+      apiKey: 'lazy-key',
+    });
+
+    new MantisClient(factory);
+
+    expect(factory).not.toHaveBeenCalled();
+  });
+
+  it('calls the factory on first API method and uses the returned credentials', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const factory = vi.fn().mockResolvedValue({
+      baseUrl: 'https://lazy.example.com',
+      apiKey: 'lazy-key',
+    });
+
+    const client = new MantisClient(factory);
+    await client.get('issues');
+
+    expect(factory).toHaveBeenCalledOnce();
+    const calledUrl: string = fetchMock.mock.calls[0][0] as string;
+    expect(calledUrl).toBe('https://lazy.example.com/api/rest/issues');
+    const options = fetchMock.mock.calls[0][1] as RequestInit;
+    expect((options.headers as Record<string, string>)['Authorization']).toBe('lazy-key');
+  });
+
+  it('caches credentials after the first call and does not call the factory again', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const factory = vi.fn().mockResolvedValue({
+      baseUrl: 'https://lazy.example.com',
+      apiKey: 'lazy-key',
+    });
+
+    const client = new MantisClient(factory);
+    await client.get('issues');
+    await client.get('projects');
+
+    expect(factory).toHaveBeenCalledOnce();
+  });
+
+  it('forwards the responseObserver when using factory constructor', async () => {
+    const observer = vi.fn();
+    const fakeResponse = makeResponse(200, '{}');
+    const fetchMock = vi.fn().mockResolvedValue(fakeResponse);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const factory = vi.fn().mockResolvedValue({
+      baseUrl: 'https://lazy.example.com',
+      apiKey: 'lazy-key',
+    });
+
+    const client = new MantisClient(factory, observer);
+    await client.get('issues');
+
+    expect(observer).toHaveBeenCalledOnce();
+    expect(observer).toHaveBeenCalledWith(fakeResponse);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // responseObserver
 // ---------------------------------------------------------------------------

package/tests/config.test.ts

@@ -19,6 +19,12 @@ async function freshGetConfig(): Promise<(typeof import('../src/config.js'))['ge
   return mod.getConfig;
 }
 
+async function freshGetStartupConfig(): Promise<(typeof import('../src/config.js'))['getStartupConfig']> {
+  vi.resetModules();
+  const mod = await import('../src/config.js');
+  return mod.getStartupConfig;
+}
+
 // ---------------------------------------------------------------------------
 // Setup
 // ---------------------------------------------------------------------------
@@ -87,60 +93,26 @@ describe('getConfig() – ENV variables', () => {
   });
 });
 
-// ---------------------------------------------------------------------------
-// JSON fallback
-// ---------------------------------------------------------------------------
-
-describe('getConfig() – mantis.json fallback', () => {
-  it('falls back to ~/.claude/mantis.json when ENV vars are missing', async () => {
-    const json = JSON.stringify({ base_url: 'https://from-json.example.com', api_key: 'json-key' });
-    vi.mocked(readFile).mockResolvedValue(json as any);
-
-    const getConfig = await freshGetConfig();
-    const config = await getConfig();
-
-    expect(config.baseUrl).toBe('https://from-json.example.com');
-    expect(config.apiKey).toBe('json-key');
-  });
-
-  it('prefers ENV vars over mantis.json values', async () => {
-    vi.stubEnv('MANTIS_BASE_URL', 'https://from-env.example.com');
-    vi.stubEnv('MANTIS_API_KEY', 'env-key');
-    const json = JSON.stringify({ base_url: 'https://from-json.example.com', api_key: 'json-key' });
-    vi.mocked(readFile).mockResolvedValue(json as any);
-
-    const getConfig = await freshGetConfig();
-    const config = await getConfig();
-
-    expect(config.baseUrl).toBe('https://from-env.example.com');
-    expect(config.apiKey).toBe('env-key');
-  });
-});
-
 // ---------------------------------------------------------------------------
 // Error cases
 // ---------------------------------------------------------------------------
 
 describe('getConfig() – errors', () => {
-  it('throws when neither ENV nor mantis.json provides baseUrl', async () => {
+  it('throws when MANTIS_BASE_URL is not set', async () => {
     vi.stubEnv('MANTIS_API_KEY', 'some-key');
-    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
 
     const getConfig = await freshGetConfig();
     await expect(getConfig()).rejects.toThrow('MANTIS_BASE_URL');
   });
 
-  it('throws when neither ENV nor mantis.json provides apiKey', async () => {
+  it('throws when MANTIS_API_KEY is not set', async () => {
     vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
-    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
 
     const getConfig = await freshGetConfig();
     await expect(getConfig()).rejects.toThrow('MANTIS_API_KEY');
   });
 
-  it('throws when no configuration is available at all', async () => {
-    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
-
+  it('throws when no configuration is provided at all', async () => {
     const getConfig = await freshGetConfig();
     await expect(getConfig()).rejects.toThrow('Missing required MantisBT configuration');
   });
@@ -215,6 +187,44 @@ describe('getConfig() – HTTP transport', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// getStartupConfig — never throws without credentials
+// ---------------------------------------------------------------------------
+
+describe('getStartupConfig()', () => {
+  it('succeeds without MANTIS_BASE_URL and MANTIS_API_KEY', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getStartupConfig = await freshGetStartupConfig();
+    const config = await getStartupConfig();
+
+    expect(config).toBeDefined();
+    expect(config.cacheTtl).toBe(3600);
+    expect(config.httpHost).toBe('127.0.0.1');
+    expect(config.httpPort).toBe(3000);
+  });
+
+  it('does not include baseUrl or apiKey', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getStartupConfig = await freshGetStartupConfig();
+    const config = await getStartupConfig();
+
+    expect(config).not.toHaveProperty('baseUrl');
+    expect(config).not.toHaveProperty('apiKey');
+  });
+
+  it('reads MANTIS_CACHE_DIR from environment', async () => {
+    vi.stubEnv('MANTIS_CACHE_DIR', '/tmp/test-cache');
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getStartupConfig = await freshGetStartupConfig();
+    const config = await getStartupConfig();
+
+    expect(config.cacheDir).toBe('/tmp/test-cache');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Singleton caching
 // ---------------------------------------------------------------------------