@dpesch/mantisbt-mcp-server 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.4.0] – 2026-03-17
+
+### Added
+- `get_issue_enums` now includes a `label` field in each enum entry when it differs from `name`. On localized MantisBT installations (e.g. German UI) this provides a translation table from the UI language back to the API name/id: `{"id": 10, "name": "new", "label": "Neu"}`. When `label` and `name` are identical the field is omitted to keep the output compact. The tool description also clarifies that `name` may itself be localized on installations where enum values have been customized at the database level.
+
+### Fixed
+- `list_issues`: `assigned_to`, `reporter_id`, and `status` filters now reliably return matching issues regardless of the requested `page_size`. Previously, the tool fetched exactly `page_size` items from the API before filtering — so a small `page_size` combined with an active filter returned zero results if the matching issues were not at the top of the unfiltered list. The tool now internally fetches batches of 50 (API maximum) and scans up to 500 issues until enough matching results are found. All filter parameters are still forwarded to the API as a hint for installations that support server-side filtering.
+
+---
+
 ## [1.3.1] – 2026-03-16
 
 ### Fixed

package/dist/tools/config.js

@@ -66,12 +66,12 @@ Common option names:
     // ---------------------------------------------------------------------------
     server.registerTool('get_issue_enums', {
         title: 'Get Issue Enum Values',
-        description: `Return valid ID and name pairs for all issue enum fields.
+        description: `Return valid ID, name, and (if available) localized label for all issue enum fields.
 
 Use this tool before creating or updating issues to look up the correct value
 for severity, status, priority, resolution, or reproducibility.
 
-Example response:
+Example response (English installation):
 {
   "severity":         [{"id": 10, "name": "feature"}, {"id": 50, "name": "minor"}, ...],
   "status":           [{"id": 10, "name": "new"}, {"id": 20, "name": "feedback"}, ...],
@@ -80,7 +80,30 @@ Example response:
   "reproducibility":  [{"id": 10, "name": "always"}, {"id": 70, "name": "have not tried"}, ...]
 }
 
-The "name" field is the value to pass to create_issue or update_issue.`,
+Example response (localized installation, e.g. German):
+{
+  "status": [
+    {"id": 10, "name": "new",      "label": "Neu"},
+    {"id": 20, "name": "feedback", "label": "Feedback"},
+    {"id": 30, "name": "acknowledged", "label": "Bestätigt"},
+    ...
+  ],
+  ...
+}
+
+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")
+
+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.
+
+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.`,
         inputSchema: z.object({}),
         annotations: {
             readOnlyHint: true,
@@ -111,7 +134,12 @@ The "name" field is the value to pass to create_issue or update_issue.`,
                     enums[key] = parseEnumString(value);
                 }
                 else if (Array.isArray(value)) {
-                    enums[key] = value.map(({ id, name }) => ({ id, name }));
+                    enums[key] = value.map(({ id, name, label }) => {
+                        const entry = { id, name };
+                        if (label && label !== name)
+                            entry.label = label;
+                        return entry;
+                    });
                 }
             }
             return {

package/dist/tools/issues.js

@@ -40,7 +40,7 @@ export function registerIssueTools(server, client) {
     // ---------------------------------------------------------------------------
     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.',
+        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.',
         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)'),
@@ -60,9 +60,7 @@ export function registerIssueTools(server, client) {
         },
     }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status }) => {
         try {
-            const params = {
-                page,
-                page_size,
+            const baseParams = {
                 project_id,
                 assigned_to,
                 reporter_id,
@@ -71,19 +69,57 @@ export function registerIssueTools(server, client) {
                 direction,
                 select,
             };
-            const result = await client.get('issues', params);
-            if (status && result.issues) {
-                const statusLower = status.toLowerCase();
-                result.issues = result.issues.filter(issue => {
-                    if (!issue.status)
-                        return false;
-                    if (statusLower === 'open')
-                        return (issue.status.id ?? 0) < MANTIS_RESOLVED_STATUS_ID;
-                    return issue.status.name?.toLowerCase() === statusLower;
+            const needsClientFilter = status !== undefined || assigned_to !== undefined || reporter_id !== undefined;
+            if (!needsClientFilter) {
+                // No client-side filtering — single API call, pass pagination as-is
+                const result = await client.get('issues', { ...baseParams, page, page_size });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            // Client-side filtering active: scan multiple API pages until we have
+            // enough matching results for the requested logical page.
+            const API_PAGE_SIZE = 50; // always fetch max to minimise round-trips
+            const MAX_API_PAGES = 10; // hard cap: scan at most 500 issues
+            const neededTotal = page * page_size; // need this many matches to serve page N
+            const matching = [];
+            let serverPage = 1;
+            let hasMore = true;
+            const statusLower = status?.toLowerCase();
+            while (matching.length < neededTotal && serverPage <= MAX_API_PAGES && hasMore) {
+                const batch = await client.get('issues', {
+                    ...baseParams,
+                    page: serverPage,
+                    page_size: API_PAGE_SIZE,
                 });
+                const issues = batch.issues ?? [];
+                hasMore = issues.length === API_PAGE_SIZE;
+                for (const issue of issues) {
+                    if (statusLower) {
+                        if (!issue.status)
+                            continue;
+                        if (statusLower === 'open') {
+                            if ((issue.status.id ?? 0) >= MANTIS_RESOLVED_STATUS_ID)
+                                continue;
+                        }
+                        else if (issue.status.name?.toLowerCase() !== statusLower) {
+                            continue;
+                        }
+                    }
+                    if (assigned_to !== undefined && issue.handler?.id !== assigned_to)
+                        continue;
+                    if (reporter_id !== undefined && issue.reporter?.id !== reporter_id)
+                        continue;
+                    matching.push(issue);
+                }
+                serverPage++;
             }
+            const start = (page - 1) * page_size;
             return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ issues: matching.slice(start, start + page_size) }, null, 2),
+                    }],
             };
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
   "license": "MIT",

package/tests/tools/config.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+type EnumResult = Record<string, Array<{ id: number; name: string; label?: string }>>;
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -59,38 +61,63 @@ describe('get_issue_enums', () => {
     expect(mockServer.hasToolRegistered('get_issue_enums')).toBe(true);
   });
 
-  it('gibt strukturierte Enum-Arrays für alle 5 Felder zurück', async () => {
-    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(enumFixture)));
-
-    const result = await mockServer.callTool('get_issue_enums', {});
-
-    expect(result.isError).toBeUndefined();
-    const parsed = JSON.parse(result.content[0]!.text) as Record<string, Array<{ id: number; name: string }>>;
-
-    expect(Array.isArray(parsed.severity)).toBe(true);
-    expect(Array.isArray(parsed.status)).toBe(true);
-    expect(Array.isArray(parsed.priority)).toBe(true);
-    expect(Array.isArray(parsed.resolution)).toBe(true);
-    expect(Array.isArray(parsed.reproducibility)).toBe(true);
-  });
-
-  it('parst Array-Format (MantisBT 2.x): id und name korrekt, label wird verworfen', async () => {
-    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(enumFixture)));
-
-    const result = await mockServer.callTool('get_issue_enums', {});
-
-    const parsed = JSON.parse(result.content[0]!.text) as Record<string, Array<{ id: number; name: string }>>;
-
-    // Werte aus der echten Fixture prüfen
-    expect(parsed.severity).toContainEqual({ id: 50, name: 'kleinerer Fehler' });
-    expect(parsed.severity).toContainEqual({ id: 80, name: 'Blocker' });
-    expect(parsed.severity).toContainEqual({ id: 200, name: 'Technische Schuld' });
-    expect(parsed.status).toContainEqual({ id: 10, name: 'new' });
-    expect(parsed.status).toContainEqual({ id: 80, name: 'resolved' });
-    expect(parsed.priority).toContainEqual({ id: 30, name: 'normal' });
-    expect(parsed.reproducibility).toContainEqual({ id: 70, name: 'have not tried' });
-    // label darf nicht im Output enthalten sein
-    expect(Object.keys(parsed.severity[0]!)).toEqual(['id', 'name']);
+  describe('mit Array-Format (MantisBT 2.x)', () => {
+    let parsed: EnumResult;
+
+    beforeEach(async () => {
+      vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(enumFixture)));
+      const result = await mockServer.callTool('get_issue_enums', {});
+      parsed = JSON.parse(result.content[0]!.text) as EnumResult;
+    });
+
+    it('gibt strukturierte Enum-Arrays für alle 5 Felder zurück', () => {
+      expect(Array.isArray(parsed.severity)).toBe(true);
+      expect(Array.isArray(parsed.status)).toBe(true);
+      expect(Array.isArray(parsed.priority)).toBe(true);
+      expect(Array.isArray(parsed.resolution)).toBe(true);
+      expect(Array.isArray(parsed.reproducibility)).toBe(true);
+    });
+
+    it('id und name korrekt für alle Felder', () => {
+      expect(parsed.severity).toContainEqual(expect.objectContaining({ id: 50, name: 'kleinerer Fehler' }));
+      expect(parsed.severity).toContainEqual(expect.objectContaining({ id: 80, name: 'Blocker' }));
+      expect(parsed.severity).toContainEqual(expect.objectContaining({ id: 200, name: 'Technische Schuld' }));
+      expect(parsed.status).toContainEqual(expect.objectContaining({ id: 10, name: 'new' }));
+      expect(parsed.status).toContainEqual(expect.objectContaining({ id: 80, name: 'resolved' }));
+      expect(parsed.priority).toContainEqual(expect.objectContaining({ id: 30, name: 'normal' }));
+      expect(parsed.reproducibility).toContainEqual(expect.objectContaining({ id: 70, name: 'have not tried' }));
+    });
+
+    it('label wird ausgegeben wenn er sich von name unterscheidet (lokalisierte Installation)', () => {
+      // status: name="new", label="neu" → label muss im Output enthalten sein
+      expect(parsed.status).toContainEqual({ id: 10, name: 'new', label: 'neu' });
+      expect(parsed.status).toContainEqual({ id: 80, name: 'resolved', label: 'erledigt' });
+      // priority: name="none", label="keine" → label muss im Output enthalten sein
+      expect(parsed.priority).toContainEqual({ id: 10, name: 'none', label: 'keine' });
+      // reproducibility: name="always", label="immer" → label muss im Output enthalten sein
+      expect(parsed.reproducibility).toContainEqual({ id: 10, name: 'always', label: 'immer' });
+    });
+
+    it('label wird weggelassen wenn er identisch mit name ist', () => {
+      // severity: name === label (z.B. "Feature-Wunsch" === "Feature-Wunsch") → kein label-Feld
+      const severityFirst = parsed.severity.find(e => e.id === 10)!;
+      expect(severityFirst).toEqual({ id: 10, name: 'Feature-Wunsch' });
+      expect(severityFirst).not.toHaveProperty('label');
+
+      // priority: name="normal", label="normal" → kein label-Feld
+      const priorityNormal = parsed.priority.find(e => e.id === 30)!;
+      expect(priorityNormal).toEqual({ id: 30, name: 'normal' });
+      expect(priorityNormal).not.toHaveProperty('label');
+    });
+
+    it('fragt alle 5 Enum-Optionen ab', () => {
+      const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+      expect(calledUrl).toContain('severity_enum_string');
+      expect(calledUrl).toContain('status_enum_string');
+      expect(calledUrl).toContain('priority_enum_string');
+      expect(calledUrl).toContain('resolution_enum_string');
+      expect(calledUrl).toContain('reproducibility_enum_string');
+    });
   });
 
   it('parst String-Format (Legacy): "id:name,..."-Strings korrekt', async () => {
@@ -98,26 +125,13 @@ describe('get_issue_enums', () => {
 
     const result = await mockServer.callTool('get_issue_enums', {});
 
-    const parsed = JSON.parse(result.content[0]!.text) as Record<string, Array<{ id: number; name: string }>>;
+    const parsed = JSON.parse(result.content[0]!.text) as EnumResult;
 
     expect(parsed.severity).toContainEqual({ id: 50, name: 'minor' });
     expect(parsed.status).toContainEqual({ id: 80, name: 'resolved' });
     expect(parsed.reproducibility).toContainEqual({ id: 70, name: 'have not tried' });
   });
 
-  it('fragt alle 5 Enum-Optionen ab', async () => {
-    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(enumFixture)));
-
-    await mockServer.callTool('get_issue_enums', {});
-
-    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
-    expect(calledUrl).toContain('severity_enum_string');
-    expect(calledUrl).toContain('status_enum_string');
-    expect(calledUrl).toContain('priority_enum_string');
-    expect(calledUrl).toContain('resolution_enum_string');
-    expect(calledUrl).toContain('reproducibility_enum_string');
-  });
-
   it('gibt isError: true bei API-Fehler zurück', async () => {
     vi.mocked(fetch).mockResolvedValue(makeResponse(403, JSON.stringify({ message: 'Access denied' })));
 

package/tests/tools/issues.test.ts

@@ -215,6 +215,69 @@ describe('list_issues', () => {
     }
   });
 
+  it('assigned_to scans multiple API pages (small page_size does not miss results)', async () => {
+    // Regression: previously fetched only page_size items from the API before filtering,
+    // so assigned_to:X with page_size:1 returned 0 results when user's issue was not
+    // in the first page returned by the server.
+    // Now the tool always fetches API_PAGE_SIZE=50 internally when filters are active.
+    const fixtureWithUser51: typeof listIssuesFixture = {
+      ...listIssuesFixture,
+      issues: [
+        // first "slot" has a different user — previously this would have been the only
+        // item fetched with page_size:1, causing a false empty result
+        listIssuesFixture.issues.find(i => (i as { handler?: { id: number } }).handler?.id === 52)!,
+        ...listIssuesFixture.issues.filter(i => (i as { handler?: { id: number } }).handler?.id === 51),
+      ].filter(Boolean),
+    };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(fixtureWithUser51)));
+
+    const result = await mockServer.callTool('list_issues', { assigned_to: 51, page: 1, page_size: 1 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ handler: { id: number } }> };
+    // Must find results for user 51 despite page_size:1
+    expect(parsed.issues.length).toBeGreaterThan(0);
+    parsed.issues.forEach(issue => expect(issue.handler.id).toBe(51));
+  });
+
+  it('assigned_to filters issues by handler.id (client-side)', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { assigned_to: 51, page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ handler: { id: number } }> };
+    const expectedCount = listIssuesFixture.issues.filter(i => (i as { handler?: { id: number } }).handler?.id === 51).length;
+    expect(parsed.issues).toHaveLength(expectedCount);
+    parsed.issues.forEach(issue => {
+      expect(issue.handler.id).toBe(51);
+    });
+  });
+
+  it('assigned_to still sends the parameter to the API (server-side hint)', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    await mockServer.callTool('list_issues', { assigned_to: 51, page: 1, page_size: 50 });
+
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    const url = new URL(calledUrl);
+    expect(url.searchParams.get('assigned_to')).toBe('51');
+  });
+
+  it('reporter_id filters issues by reporter.id (client-side)', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { reporter_id: 52, page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ reporter: { id: number } }> };
+    const expectedCount = listIssuesFixture.issues.filter(i => (i as { reporter?: { id: number } }).reporter?.id === 52).length;
+    expect(parsed.issues).toHaveLength(expectedCount);
+    parsed.issues.forEach(issue => {
+      expect(issue.reporter.id).toBe(52);
+    });
+  });
+
   it('status filter is case-insensitive', async () => {
     vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
     const resultUpper = await mockServer.callTool('list_issues', { status: 'OPEN', page: 1, page_size: 50 });