@dpesch/mantisbt-mcp-server 1.0.3 → 1.1.0

package/.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Description
+
+<!-- Why is this change needed? What problem does it solve? -->
+
+## Changes
+
+<!-- Brief summary of what was changed -->
+
+## Testing
+
+<!-- How did you test this? -->
+
+---
+
+> **Note:** This repository is a public mirror. Your PR will be reviewed and
+> integrated via cherry-pick — it will not be merged directly through Codeberg.
+> You will be credited in the commit message and CHANGELOG.

package/CHANGELOG.md

@@ -7,6 +7,15 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.1.0] – 2026-03-15
+
+### Added
+- `list_issues`: new optional `select` parameter — passes a comma-separated field list to the MantisBT `select` query parameter for server-side field projection. Significantly reduces response size when only a subset of fields is needed (e.g. `"id,summary,status,priority,handler,updated_at"`).
+- `list_issues`: new optional `status` parameter — client-side filter by status name (e.g. `"new"`, `"assigned"`, `"resolved"`) or the shorthand `"open"` for all statuses with id < 80. Note: applied after fetching, so a page may contain fewer results than `page_size` when active.
+- New tool `get_issue_fields`: returns all field names valid for the `select` parameter. Fetches a sample issue to reflect the server's active configuration, merges with fields MantisBT omits when empty (notes, attachments, etc.), and caches the result.
+
+---
+
 ## [1.0.3] – 2026-03-15
 
 ### Fixed

package/README.de.md

@@ -1,6 +1,5 @@
 # MantisBT MCP Server
 
-[![CI](https://codeberg.org/dpesch/mantisbt-mcp-server/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/dpesch/mantisbt-mcp-server/actions)
 [![npm version](https://img.shields.io/npm/v/@dpesch/mantisbt-mcp-server)](https://www.npmjs.com/package/@dpesch/mantisbt-mcp-server)
 [![license](https://img.shields.io/npm/l/@dpesch/mantisbt-mcp-server)](LICENSE)
 
@@ -89,7 +88,7 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | Tool | Beschreibung |
 |---|---|
 | `get_issue` | Ein Issue anhand seiner ID abrufen |
-| `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern |
+| `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 |
 | `update_issue` | Bestehendes Issue bearbeiten |
 | `delete_issue` | Issue löschen |
@@ -141,6 +140,7 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 
 | Tool | Beschreibung |
 |---|---|
+| `get_issue_fields` | Alle gültigen Feldnamen für den `select`-Parameter von `list_issues` zurückgeben |
 | `get_metadata` | Gecachte Metadaten abrufen (Projekte, Benutzer, Versionen, Kategorien) |
 | `sync_metadata` | Metadaten-Cache neu befüllen |
 | `list_filters` | Gespeicherte Filter auflisten |

package/README.md

@@ -1,6 +1,5 @@
 # MantisBT MCP Server
 
-[![CI](https://codeberg.org/dpesch/mantisbt-mcp-server/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/dpesch/mantisbt-mcp-server/actions)
 [![npm version](https://img.shields.io/npm/v/@dpesch/mantisbt-mcp-server)](https://www.npmjs.com/package/@dpesch/mantisbt-mcp-server)
 [![license](https://img.shields.io/npm/l/@dpesch/mantisbt-mcp-server)](LICENSE)
 
@@ -89,7 +88,7 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | Tool | Description |
 |---|---|
 | `get_issue` | Retrieve an issue by its numeric ID |
-| `list_issues` | Filter issues by project, status, author, and more |
+| `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 |
 | `update_issue` | Update an existing issue |
 | `delete_issue` | Delete an issue |
@@ -141,6 +140,7 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 
 | Tool | Description |
 |---|---|
+| `get_issue_fields` | Return all field names valid for the `select` parameter of `list_issues` |
 | `get_metadata` | Retrieve cached metadata (projects, users, versions, categories) |
 | `sync_metadata` | Refresh the metadata cache |
 | `list_filters` | List saved filters |

package/dist/cache.js

@@ -5,11 +5,13 @@ import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 export class MetadataCache {
     filePath;
+    issueFieldsFilePath;
     ttlSeconds;
     cacheDir;
     constructor(cacheDir, ttlSeconds) {
         this.cacheDir = cacheDir;
         this.filePath = join(cacheDir, 'metadata.json');
+        this.issueFieldsFilePath = join(cacheDir, 'issue_fields.json');
         this.ttlSeconds = ttlSeconds;
     }
     async isValid() {
@@ -33,6 +35,19 @@ export class MetadataCache {
             return null;
         }
     }
+    async loadIfValid() {
+        try {
+            const raw = await readFile(this.filePath, 'utf-8');
+            const file = JSON.parse(raw);
+            const ageSeconds = (Date.now() - file.timestamp) / 1000;
+            if (ageSeconds >= this.ttlSeconds)
+                return null;
+            return file.data;
+        }
+        catch {
+            return null;
+        }
+    }
     async save(data) {
         await mkdir(this.cacheDir, { recursive: true });
         const file = {
@@ -49,4 +64,22 @@ export class MetadataCache {
             // Already gone — that is fine
         }
     }
+    async loadIssueFields() {
+        try {
+            const raw = await readFile(this.issueFieldsFilePath, 'utf-8');
+            const file = JSON.parse(raw);
+            const ageSeconds = (Date.now() - file.timestamp) / 1000;
+            if (ageSeconds >= this.ttlSeconds)
+                return null;
+            return file.fields;
+        }
+        catch {
+            return null;
+        }
+    }
+    async saveIssueFields(fields) {
+        await mkdir(this.cacheDir, { recursive: true });
+        const file = { timestamp: Date.now(), fields };
+        await writeFile(this.issueFieldsFilePath, JSON.stringify(file, null, 2), 'utf-8');
+    }
 }

package/dist/constants.js

@@ -12,6 +12,9 @@ export const RELATIONSHIP_TYPES = {
 // ---------------------------------------------------------------------------
 // Status names (internal English names used in API calls)
 // ---------------------------------------------------------------------------
+// MantisBT default status ID for "resolved". Issues with status.id strictly
+// below this value are considered open (new/feedback/acknowledged/confirmed/assigned).
+export const MANTIS_RESOLVED_STATUS_ID = 80;
 export const STATUS_NAMES = [
     'new',
     'feedback',

package/dist/tools/issues.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
+import { MANTIS_RESOLVED_STATUS_ID } from '../constants.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -39,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.',
+        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.',
         inputSchema: z.object({
             project_id: z.number().int().positive().optional().describe('Filter by project ID'),
             page: z.number().int().positive().default(1).describe('Page number (default: 1)'),
@@ -49,13 +50,15 @@ export function registerIssueTools(server, client) {
             filter_id: z.number().int().positive().optional().describe('Use a saved MantisBT filter ID'),
             sort: z.string().optional().describe('Sort field (e.g. "last_updated", "id")'),
             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.'),
         }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction }) => {
+    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status }) => {
         try {
             const params = {
                 page,
@@ -66,8 +69,19 @@ export function registerIssueTools(server, client) {
                 filter_id,
                 sort,
                 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;
+                });
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };

package/dist/tools/metadata.js

@@ -1,5 +1,55 @@
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
+// Fields MantisBT strips from issue responses when the array is empty.
+// They are always valid 'select' values even if absent in a sample issue.
+const EMPTY_STRIPPED_FIELDS = [
+    'attachments',
+    'custom_fields',
+    'history',
+    'monitors',
+    'notes',
+    'relationships',
+    'tags',
+];
+// Fallback static list used when no issues are available to sample.
+const STATIC_ISSUE_FIELDS = [
+    'additional_information',
+    'attachments',
+    'build',
+    'category',
+    'created_at',
+    'custom_fields',
+    'description',
+    'due_date',
+    'eta',
+    'fixed_in_version',
+    'handler',
+    'history',
+    'id',
+    'monitors',
+    'notes',
+    'os',
+    'os_build',
+    'platform',
+    'priority',
+    'profile',
+    'project',
+    'projection',
+    'relationships',
+    'reporter',
+    'reproducibility',
+    'resolution',
+    'severity',
+    'status',
+    'steps_to_reproduce',
+    'sticky',
+    'summary',
+    'tags',
+    'target_version',
+    'updated_at',
+    'version',
+    'view_state',
+];
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -100,15 +150,60 @@ Use sync_metadata to force a refresh.`,
         },
     }, async () => {
         try {
-            let data = null;
-            if (await cache.isValid()) {
-                data = await cache.load();
+            const data = await cache.loadIfValid() ?? await fetchAndCacheMetadata(client, cache);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // get_issue_fields
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_issue_fields', {
+        title: 'Get Issue Fields',
+        description: `Return all field names that are valid for the "select" parameter of list_issues and get_issue.
+
+Fields are discovered by fetching a sample issue from MantisBT (which reflects the server's active configuration — e.g. whether eta, projection, or profile fields are enabled) and merging the result with fields that MantisBT omits when empty (notes, attachments, relationships, etc.). The result is cached with the same TTL as the metadata cache.
+
+Use this tool before constructing a "select" string to ensure you only request fields that exist on this server.`,
+        inputSchema: z.object({
+            project_id: z.number().int().positive().optional().describe('Optional project ID to scope the sample issue fetch'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id }) => {
+        try {
+            const cached = await cache.loadIssueFields();
+            if (cached) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ fields: cached, source: 'cache' }, null, 2) }],
+                };
             }
-            if (!data) {
-                data = await fetchAndCacheMetadata(client, cache);
+            const params = {
+                page: 1,
+                page_size: 1,
+                project_id,
+            };
+            const result = await client.get('issues', params);
+            const issues = result.issues ?? [];
+            let fields;
+            if (issues.length === 0) {
+                fields = STATIC_ISSUE_FIELDS;
             }
+            else {
+                const discovered = Object.keys(issues[0]);
+                fields = Array.from(new Set([...discovered, ...EMPTY_STRIPPED_FIELDS])).sort();
+            }
+            await cache.saveIssueFields(fields);
             return {
-                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({ fields, source: issues.length > 0 ? 'live' : 'static' }, null, 2) }],
             };
         }
         catch (error) {

package/package.json

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

package/scripts/record-fixtures.ts

@@ -103,6 +103,17 @@ async function recordFixtures(): Promise<void> {
     console.error('Failed to fetch issues:', err instanceof Error ? err.message : String(err));
   }
 
+  // GET issues?page=1&page_size=1 — single issue sample for get_issue_fields field discovery
+  try {
+    const sampleResult = await client.get<{ issues: unknown[] }>('issues', {
+      page: 1,
+      page_size: 1,
+    });
+    saveFixture('get_issue_fields_sample.json', sampleResult);
+  } catch (err) {
+    console.error('Failed to fetch issues sample:', err instanceof Error ? err.message : String(err));
+  }
+
   // GET issues/{id}
   if (firstIssueId !== undefined) {
     try {

package/tests/cache.test.ts

@@ -147,3 +147,118 @@ describe('MetadataCache – invalidate()', () => {
     await expect(cache.invalidate()).resolves.toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// loadIfValid()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – loadIfValid()', () => {
+  it('returns null when file does not exist', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await expect(cache.loadIfValid()).resolves.toBeNull();
+  });
+
+  it('returns data when file is fresh (within TTL)', async () => {
+    const metadata = makeSampleMetadata();
+    const file = { timestamp: Date.now(), data: metadata };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    const result = await cache.loadIfValid();
+    expect(result).toEqual(metadata);
+  });
+
+  it('returns null when file has expired', async () => {
+    const expiredTimestamp = Date.now() - (TTL + 1) * 1000;
+    const metadata = makeSampleMetadata();
+    const file = { timestamp: expiredTimestamp, data: metadata };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    await expect(cache.loadIfValid()).resolves.toBeNull();
+  });
+
+  it('reads from metadata.json path', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await cache.loadIfValid();
+
+    expect(readFile).toHaveBeenCalledOnce();
+    const calledPath = vi.mocked(readFile).mock.calls[0][0] as string;
+    expect(calledPath).toContain('metadata.json');
+    expect(calledPath).not.toContain('issue_fields.json');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// loadIssueFields()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – loadIssueFields()', () => {
+  it('returns null when file does not exist', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await expect(cache.loadIssueFields()).resolves.toBeNull();
+  });
+
+  it('returns fields array when file is fresh', async () => {
+    const fields = ['id', 'summary', 'status'];
+    const file = { timestamp: Date.now(), fields };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    const result = await cache.loadIssueFields();
+    expect(result).toEqual(fields);
+  });
+
+  it('returns null when file has expired', async () => {
+    const expiredTimestamp = Date.now() - (TTL + 1) * 1000;
+    const file = { timestamp: expiredTimestamp, fields: ['id', 'summary'] };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    await expect(cache.loadIssueFields()).resolves.toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// saveIssueFields()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – saveIssueFields()', () => {
+  it('calls mkdir with recursive:true and writes to issue_fields.json', async () => {
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const cache = makeCache();
+    const fields = ['id', 'summary', 'status', 'priority'];
+    await cache.saveIssueFields(fields);
+
+    expect(mkdir).toHaveBeenCalledWith(CACHE_DIR, { recursive: true });
+    expect(writeFile).toHaveBeenCalledOnce();
+
+    const calledPath = vi.mocked(writeFile).mock.calls[0][0] as string;
+    expect(calledPath).toContain('issue_fields.json');
+  });
+
+  it('written JSON contains the fields array and a timestamp', async () => {
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const cache = makeCache();
+    const fields = ['id', 'summary', 'status'];
+    const before = Date.now();
+    await cache.saveIssueFields(fields);
+    const after = Date.now();
+
+    const writtenContent = vi.mocked(writeFile).mock.calls[0][1] as string;
+    const parsed = JSON.parse(writtenContent) as { timestamp: number; fields: string[] };
+    expect(parsed.fields).toEqual(fields);
+    expect(parsed.timestamp).toBeGreaterThanOrEqual(before);
+    expect(parsed.timestamp).toBeLessThanOrEqual(after);
+  });
+});

package/tests/fixtures/get_issue_fields_sample.json

@@ -0,0 +1,110 @@
+{
+  "issues": [
+    {
+      "id": 7857,
+      "summary": "Issue summary 1",
+      "description": "Issue description 1",
+      "project": {
+        "id": 54,
+        "name": "Project 2"
+      },
+      "category": {
+        "id": 394,
+        "name": "Hooks"
+      },
+      "reporter": {
+        "id": 51,
+        "name": "user_1",
+        "real_name": "User One",
+        "email": "user1@example.com"
+      },
+      "handler": {
+        "id": 51,
+        "name": "user_1",
+        "real_name": "User One",
+        "email": "user1@example.com"
+      },
+      "status": {
+        "id": 80,
+        "name": "resolved",
+        "label": "erledigt",
+        "color": "#e8e8e8"
+      },
+      "resolution": {
+        "id": 20,
+        "name": "fixed",
+        "label": "erledigt"
+      },
+      "view_state": {
+        "id": 10,
+        "name": "public",
+        "label": "öffentlich"
+      },
+      "priority": {
+        "id": 30,
+        "name": "normal",
+        "label": "normal"
+      },
+      "severity": {
+        "id": 0,
+        "name": "@0@",
+        "label": "@0@"
+      },
+      "reproducibility": {
+        "id": 70,
+        "name": "have not tried",
+        "label": "nicht getestet"
+      },
+      "sticky": false,
+      "created_at": "2026-03-15T22:11:31+01:00",
+      "updated_at": "2026-03-15T22:23:08+01:00",
+      "history": [
+        {
+          "created_at": "2026-03-15T22:11:31+01:00",
+          "user": {
+            "id": 51,
+            "name": "user_1",
+            "real_name": "User One",
+            "email": "user1@example.com"
+          },
+          "type": {
+            "id": 1,
+            "name": "issue-new"
+          },
+          "message": "Neuer Eintrag"
+        },
+        {
+          "created_at": "2026-03-15T22:23:08+01:00",
+          "user": {
+            "id": 51,
+            "name": "user_1",
+            "real_name": "User One",
+            "email": "user1@example.com"
+          },
+          "field": {
+            "name": "status",
+            "label": "Status"
+          },
+          "type": {
+            "id": 0,
+            "name": "field-updated"
+          },
+          "old_value": {
+            "id": 50,
+            "name": "assigned",
+            "label": "zugewiesen",
+            "color": "#afbed5"
+          },
+          "new_value": {
+            "id": 80,
+            "name": "resolved",
+            "label": "erledigt",
+            "color": "#e8e8e8"
+          },
+          "message": "Status",
+          "change": "zugewiesen => erledigt"
+        }
+      ]
+    }
+  ]
+}

package/tests/fixtures/list_issues.json

@@ -62,6 +62,40 @@
       "sticky": false,
       "created_at": "2026-03-13T09:58:23+01:00",
       "updated_at": "2026-03-13T11:25:19+01:00"
+    },
+    {
+      "id": 7900,
+      "summary": "Issue summary 4 (open)",
+      "description": "Issue description 4",
+      "project": { "id": 54, "name": "Project 2" },
+      "category": { "id": 350, "name": "Konfiguration" },
+      "reporter": { "id": 52, "name": "user_2" },
+      "handler": {
+        "id": 51,
+        "name": "user_1",
+        "real_name": "User One",
+        "email": "user1@example.com"
+      },
+      "status": { "id": 50, "name": "assigned", "label": "zugewiesen", "color": "#e8e8e8" },
+      "priority": { "id": 30, "name": "normal", "label": "normal" },
+      "severity": { "id": 210, "name": "Wartung", "label": "Wartung" },
+      "sticky": false,
+      "created_at": "2026-03-14T10:00:00+01:00",
+      "updated_at": "2026-03-14T10:00:00+01:00"
+    },
+    {
+      "id": 7901,
+      "summary": "Issue summary 5 (open, new)",
+      "description": "Issue description 5",
+      "project": { "id": 54, "name": "Project 2" },
+      "category": { "id": 350, "name": "Konfiguration" },
+      "reporter": { "id": 52, "name": "user_2" },
+      "status": { "id": 10, "name": "new", "label": "neu", "color": "#fcbdbd" },
+      "priority": { "id": 30, "name": "normal", "label": "normal" },
+      "severity": { "id": 210, "name": "Wartung", "label": "Wartung" },
+      "sticky": false,
+      "created_at": "2026-03-14T11:00:00+01:00",
+      "updated_at": "2026-03-14T11:00:00+01:00"
     }
   ]
 }

package/tests/helpers/mock-server.ts

@@ -1,3 +1,13 @@
+export function makeResponse(status: number, body: string): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: `Status ${status}`,
+    text: () => Promise.resolve(body),
+    headers: { get: (_key: string) => null },
+  } as unknown as Response;
+}
+
 // Typ für das Result-Objekt das die Tools zurückgeben
 export interface ToolResult {
   content: Array<{ type: string; text: string }>;

package/tests/tools/issues.test.ts

@@ -4,7 +4,8 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MantisClient } from '../../src/client.js';
 import { registerIssueTools } from '../../src/tools/issues.js';
-import { MockMcpServer } from '../helpers/mock-server.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
+import { MANTIS_RESOLVED_STATUS_ID } from '../../src/constants.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,22 +23,13 @@ const getIssueFixture = existsSync(getIssueFixturePath)
   : { issues: [{ id: 42, summary: 'Test Issue' }] };
 
 const listIssuesFixture = existsSync(listIssuesFixturePath)
-  ? (JSON.parse(readFileSync(listIssuesFixturePath, 'utf-8')) as { issues: Array<{ id: number; summary: string }>; total_count: number })
-  : { issues: [{ id: 42, summary: 'Test Issue' }], total_count: 1 };
+  ? (JSON.parse(readFileSync(listIssuesFixturePath, 'utf-8')) as { issues: Array<{ id: number; summary: string; status: { id: number; name: string } }>; total_count: number })
+  : { issues: [{ id: 42, summary: 'Test Issue', status: { id: 80, name: 'resolved' } }], total_count: 1 };
 
-// ---------------------------------------------------------------------------
-// Helper: minimale Response nachbauen
-// ---------------------------------------------------------------------------
-
-function makeResponse(status: number, body: string): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    statusText: `Status ${status}`,
-    text: () => Promise.resolve(body),
-    headers: { get: (_key: string) => null },
-  } as unknown as Response;
-}
+const recordedListIssuesPath = join(fixturesDir, 'recorded', 'list_issues.json');
+const recordedListIssuesFixture = existsSync(recordedListIssuesPath)
+  ? (JSON.parse(readFileSync(recordedListIssuesPath, 'utf-8')) as { issues: Array<{ id: number; summary: string; status: { id: number; name: string } }> })
+  : null;
 
 // ---------------------------------------------------------------------------
 // Setup
@@ -127,4 +119,92 @@ describe('list_issues', () => {
     const url = new URL(calledUrl);
     expect(url.searchParams.get('project_id')).toBe('7');
   });
+
+  it('passes select as query parameter', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    await mockServer.callTool('list_issues', { select: 'id,summary,status', page: 1, page_size: 10 });
+
+    const calledUrl = vi.mocked(fetch).mock.calls[0]![0] as string;
+    const url = new URL(calledUrl);
+    expect(url.searchParams.get('select')).toBe('id,summary,status');
+  });
+
+  it('status "open" filters to issues with status.id < 80', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ status: { id: number } }> };
+    expect(parsed.issues.length).toBeGreaterThan(0);
+    parsed.issues.forEach(issue => {
+      expect(issue.status.id).toBeLessThan(MANTIS_RESOLVED_STATUS_ID);
+    });
+  });
+
+  it('status "resolved" filters to resolved issues only', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'resolved', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ status: { name: string } }> };
+    expect(parsed.issues.length).toBeGreaterThan(0);
+    parsed.issues.forEach(issue => {
+      expect(issue.status.name).toBe('resolved');
+    });
+  });
+
+  it('status "new" filters to new issues only', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'new', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: Array<{ id: number; status: { name: string } }> };
+    expect(parsed.issues).toHaveLength(1);
+    expect(parsed.issues[0]!.id).toBe(7901);
+    expect(parsed.issues[0]!.status.name).toBe('new');
+  });
+
+  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 });
+
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(listIssuesFixture)));
+    const resultLower = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    const parsedUpper = JSON.parse(resultUpper.content[0]!.text) as { issues: unknown[] };
+    const parsedLower = JSON.parse(resultLower.content[0]!.text) as { issues: unknown[] };
+    expect(parsedUpper.issues.length).toBe(parsedLower.issues.length);
+    expect(parsedUpper.issues).toEqual(parsedLower.issues);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// list_issues – recorded fixtures
+// ---------------------------------------------------------------------------
+
+describe('list_issues – recorded fixtures', () => {
+  it.skipIf(!recordedListIssuesFixture)('status "open" on all-resolved recorded fixture yields 0 results', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedListIssuesFixture!)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'open', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: unknown[] };
+    // Recorded fixture contains only resolved issues (status.id=80)
+    expect(parsed.issues).toHaveLength(0);
+  });
+
+  it.skipIf(!recordedListIssuesFixture)('status "resolved" on recorded fixture yields same count as total recorded issues', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedListIssuesFixture!)));
+
+    const result = await mockServer.callTool('list_issues', { status: 'resolved', page: 1, page_size: 50 });
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { issues: unknown[] };
+    expect(parsed.issues).toHaveLength(recordedListIssuesFixture!.issues.length);
+  });
 });

package/tests/tools/metadata.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// vi.mock must be at module top level — vitest hoists it automatically
+vi.mock('node:fs/promises');
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { MantisClient } from '../../src/client.js';
+import { MetadataCache, type CachedMetadata } from '../../src/cache.js';
+import { registerMetadataTools } from '../../src/tools/metadata.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const recordedFixturesDir = join(__dirname, '..', 'fixtures', 'recorded');
+
+// Recorded fixture: single issue returned by issues?page=1&page_size=1
+const sampleFixturePath = join(recordedFixturesDir, 'get_issue_fields_sample.json');
+const recordedSampleFixture = existsSync(sampleFixturePath)
+  ? (JSON.parse(readFileSync(sampleFixturePath, 'utf-8')) as { issues: Array<Record<string, unknown>> })
+  : null;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const CACHE_DIR = '/tmp/test-cache-metadata';
+const TTL = 3600;
+
+function makeServer(): MockMcpServer {
+  return new MockMcpServer();
+}
+
+function makeClient(): MantisClient {
+  return new MantisClient('https://mantis.example.com', 'test-token');
+}
+
+function makeCache(): MetadataCache {
+  return new MetadataCache(CACHE_DIR, TTL);
+}
+
+function makeSampleMetadata(): CachedMetadata {
+  return {
+    timestamp: Date.now(),
+    projects: [{ id: 1, name: 'Test Project' }],
+    byProject: {},
+  };
+}
+
+function makeValidMetadataCacheFile(data: CachedMetadata): string {
+  return JSON.stringify({ timestamp: Date.now(), data });
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+let mockServer: MockMcpServer;
+let client: MantisClient;
+let cache: MetadataCache;
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  mockServer = makeServer();
+  client = makeClient();
+  cache = makeCache();
+  registerMetadataTools(mockServer as never, client, cache);
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// get_metadata
+// ---------------------------------------------------------------------------
+
+describe('get_metadata', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('get_metadata')).toBe(true);
+  });
+
+  it('loads from cache when valid (single file read — no re-fetch)', async () => {
+    const metadata = makeSampleMetadata();
+    vi.mocked(readFile).mockResolvedValue(makeValidMetadataCacheFile(metadata) as any);
+
+    const result = await mockServer.callTool('get_metadata', {});
+
+    expect(result.isError).toBeUndefined();
+    // fetch must NOT have been called — data came from cache
+    expect(fetch).not.toHaveBeenCalled();
+    const parsed = JSON.parse(result.content[0]!.text) as CachedMetadata;
+    expect(parsed.projects).toEqual(metadata.projects);
+  });
+
+  it('fetches and caches when cache is missing', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const projectsResponse = { projects: [{ id: 1, name: 'Test Project' }] };
+    const emptyResponse = { users: [], versions: [], categories: [] };
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(makeResponse(200, JSON.stringify(projectsResponse)))
+      .mockResolvedValue(makeResponse(200, JSON.stringify(emptyResponse)));
+
+    const result = await mockServer.callTool('get_metadata', {});
+
+    expect(result.isError).toBeUndefined();
+    expect(fetch).toHaveBeenCalled();
+    expect(writeFile).toHaveBeenCalled();
+    const writtenPath = vi.mocked(writeFile).mock.calls[0]![0] as string;
+    expect(writtenPath).toContain('metadata.json');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// get_issue_fields
+// ---------------------------------------------------------------------------
+
+describe('get_issue_fields', () => {
+  it('is registered', () => {
+    expect(mockServer.hasToolRegistered('get_issue_fields')).toBe(true);
+  });
+
+  it('returns cached fields when cache is valid', async () => {
+    const cachedFields = ['id', 'summary', 'status', 'priority', 'attachments'];
+    const cacheFile = JSON.stringify({ timestamp: Date.now(), fields: cachedFields });
+
+    // loadIssueFields reads from issue_fields.json
+    vi.mocked(readFile).mockImplementation(async (path) => {
+      if (String(path).includes('issue_fields.json')) {
+        return cacheFile as any;
+      }
+      throw new Error('ENOENT');
+    });
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    // fetch must NOT have been called — data came from cache
+    expect(fetch).not.toHaveBeenCalled();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('cache');
+    expect(parsed.fields).toEqual(cachedFields);
+  });
+
+  it('fetches sample issue and discovers fields', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const sampleIssue = {
+      id: 42,
+      summary: 'Sample',
+      status: { id: 10, name: 'new' },
+      priority: { id: 30, name: 'normal' },
+      reporter: { id: 1, name: 'user' },
+    };
+    const issuesResponse = { issues: [sampleIssue] };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(issuesResponse)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('live');
+    // Fields from sample issue
+    expect(parsed.fields).toContain('id');
+    expect(parsed.fields).toContain('summary');
+    expect(parsed.fields).toContain('status');
+    // Fields from EMPTY_STRIPPED_FIELDS that are always merged in
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+    expect(parsed.fields).toContain('relationships');
+  });
+
+  it('falls back to static list when no issues available', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const emptyIssuesResponse = { issues: [] };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(emptyIssuesResponse)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('static');
+    // Static list must contain common fields
+    expect(parsed.fields).toContain('id');
+    expect(parsed.fields).toContain('summary');
+    expect(parsed.fields).toContain('status');
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+  });
+
+  it('caches discovered fields after fetching', async () => {
+    // Cache miss
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const sampleIssue = { id: 1, summary: 'Test', status: { id: 10, name: 'new' } };
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ issues: [sampleIssue] })));
+
+    await mockServer.callTool('get_issue_fields', {});
+
+    // writeFile must have been called with issue_fields.json path
+    expect(writeFile).toHaveBeenCalled();
+    const writtenPath = vi.mocked(writeFile).mock.calls.find(
+      call => String(call[0]).includes('issue_fields.json')
+    );
+    expect(writtenPath).toBeDefined();
+
+    // Written content must be valid JSON with a fields array
+    const writtenContent = writtenPath![1] as string;
+    const parsed = JSON.parse(writtenContent) as { timestamp: number; fields: string[] };
+    expect(Array.isArray(parsed.fields)).toBe(true);
+    expect(parsed.fields.length).toBeGreaterThan(0);
+    expect(typeof parsed.timestamp).toBe('number');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// get_issue_fields – recorded fixtures
+// ---------------------------------------------------------------------------
+
+describe('get_issue_fields – recorded fixtures', () => {
+  it.skipIf(!recordedSampleFixture)('discovers fields from recorded sample issue', async () => {
+    // Cache miss — force live discovery
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify(recordedSampleFixture!)));
+
+    const result = await mockServer.callTool('get_issue_fields', {});
+
+    expect(result.isError).toBeUndefined();
+    const parsed = JSON.parse(result.content[0]!.text) as { fields: string[]; source: string };
+    expect(parsed.source).toBe('live');
+
+    // Every top-level key of the recorded sample issue must be in the discovered fields
+    const sampleKeys = Object.keys(recordedSampleFixture!.issues[0]!);
+    for (const key of sampleKeys) {
+      expect(parsed.fields).toContain(key);
+    }
+
+    // EMPTY_STRIPPED_FIELDS must always be present even if absent from the sample
+    expect(parsed.fields).toContain('attachments');
+    expect(parsed.fields).toContain('notes');
+    expect(parsed.fields).toContain('relationships');
+  });
+});

package/tests/tools/projects.test.ts

@@ -4,7 +4,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MantisClient } from '../../src/client.js';
 import { registerProjectTools } from '../../src/tools/projects.js';
-import { MockMcpServer } from '../helpers/mock-server.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -22,20 +22,6 @@ const listProjectsFixture = existsSync(listProjectsFixturePath)
 
 const firstProjectId = listProjectsFixture.projects[0]?.id ?? 1;
 
-// ---------------------------------------------------------------------------
-// Helper
-// ---------------------------------------------------------------------------
-
-function makeResponse(status: number, body: string): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    statusText: `Status ${status}`,
-    text: () => Promise.resolve(body),
-    headers: { get: (_key: string) => null },
-  } as unknown as Response;
-}
-
 // ---------------------------------------------------------------------------
 // Setup
 // ---------------------------------------------------------------------------

package/tests/tools/users.test.ts

@@ -4,7 +4,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MantisClient } from '../../src/client.js';
 import { registerUserTools } from '../../src/tools/users.js';
-import { MockMcpServer } from '../helpers/mock-server.js';
+import { MockMcpServer, makeResponse } from '../helpers/mock-server.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -20,20 +20,6 @@ const getCurrentUserFixture = existsSync(getCurrentUserFixturePath)
   ? (JSON.parse(readFileSync(getCurrentUserFixturePath, 'utf-8')) as { id: number; name: string; real_name?: string; email?: string })
   : { id: 5, name: 'testuser', real_name: 'Test User', email: 'test@example.com' };
 
-// ---------------------------------------------------------------------------
-// Helper
-// ---------------------------------------------------------------------------
-
-function makeResponse(status: number, body: string): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    statusText: `Status ${status}`,
-    text: () => Promise.resolve(body),
-    headers: { get: (_key: string) => null },
-  } as unknown as Response;
-}
-
 // ---------------------------------------------------------------------------
 // Setup
 // ---------------------------------------------------------------------------