@dpesch/mantisbt-mcp-server 1.0.3 → 1.2.0

package/dist/search/tools.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { SearchSyncService } from './sync.js';
+// ---------------------------------------------------------------------------
+// registerSearchTools
+// ---------------------------------------------------------------------------
+export function registerSearchTools(server, client, store, embedder) {
+    // ---------------------------------------------------------------------------
+    // search_issues
+    // ---------------------------------------------------------------------------
+    server.registerTool('search_issues', {
+        title: 'Semantic Issue Search',
+        description: 'Search MantisBT issues using natural language. Returns the most relevant issues ' +
+            'by semantic similarity. The search index must be populated first via rebuild_search_index.',
+        inputSchema: z.object({
+            query: z.string().describe('Natural language search query'),
+            top_n: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .default(10)
+                .describe('Number of results to return (default: 10, max: 50)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ query, top_n }) => {
+        try {
+            const count = await store.count();
+            if (count === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Search index is empty. Run rebuild_search_index first.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const queryVector = await embedder.embed(query);
+            const results = await store.search(queryVector, top_n);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // rebuild_search_index
+    // ---------------------------------------------------------------------------
+    server.registerTool('rebuild_search_index', {
+        title: 'Rebuild Semantic Search Index',
+        description: 'Build or update the semantic search index for MantisBT issues. ' +
+            'Use full: true to clear the existing index and rebuild from scratch.',
+        inputSchema: z.object({
+            project_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Optional: only index issues from this project'),
+            full: z
+                .boolean()
+                .default(false)
+                .describe('If true, clears the existing index and rebuilds from scratch'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id, full }) => {
+        try {
+            if (full) {
+                await store.clear();
+                await store.resetLastSyncedAt();
+            }
+            const startMs = Date.now();
+            const syncService = new SearchSyncService(client, store, embedder);
+            const { indexed, skipped } = await syncService.sync(project_id);
+            const duration_ms = Date.now() - startMs;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ indexed, skipped, duration_ms }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}

package/dist/tools/files.js

@@ -1,3 +1,5 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
 function errorText(msg) {
@@ -34,4 +36,72 @@ export function registerFileTools(server, client) {
             return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
         }
     });
+    // ---------------------------------------------------------------------------
+    // upload_file
+    // ---------------------------------------------------------------------------
+    server.registerTool('upload_file', {
+        title: 'Upload File Attachment',
+        description: `Upload a file as an attachment to a MantisBT issue via multipart/form-data.
+
+Two input modes (exactly one must be provided):
+- file_path: absolute path to a local file — filename is derived from the path automatically
+- content: Base64-encoded file content — filename must be supplied explicitly via the filename parameter
+
+The optional content_type parameter sets the MIME type (e.g. "image/png"). If omitted, "application/octet-stream" is used.`,
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+            file_path: z.string().min(1).optional().describe('Absolute path to the local file to upload (mutually exclusive with content)'),
+            content: z.string().min(1).optional().describe('Base64-encoded file content (mutually exclusive with file_path)'),
+            filename: z.string().min(1).optional().describe('File name for the attachment (required when using content; overrides the derived name when using file_path)'),
+            content_type: z.string().optional().describe('MIME type of the file, e.g. "image/png" (default: "application/octet-stream")'),
+            description: z.string().optional().describe('Optional description for the attachment'),
+        }).refine(d => !!(d.file_path ?? d.content), {
+            message: 'Either file_path or content must be provided',
+        }).refine(d => !(d.file_path && d.content), {
+            message: 'Only one of file_path or content may be provided',
+        }).refine(d => !d.content || !!d.filename, {
+            message: 'filename is required when using content',
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, file_path, content, filename, content_type, description }) => {
+        try {
+            if (!file_path && !content) {
+                return { content: [{ type: 'text', text: 'Error: Either file_path or content must be provided' }], isError: true };
+            }
+            if (file_path && content) {
+                return { content: [{ type: 'text', text: 'Error: Only one of file_path or content may be provided' }], isError: true };
+            }
+            let fileBuffer;
+            let fileName;
+            if (file_path) {
+                fileBuffer = await readFile(file_path);
+                fileName = filename ?? basename(file_path);
+            }
+            else {
+                if (!filename) {
+                    return { content: [{ type: 'text', text: 'Error: filename is required when using content' }], isError: true };
+                }
+                fileBuffer = Buffer.from(content, 'base64');
+                fileName = filename;
+            }
+            const blob = new Blob([new Uint8Array(fileBuffer)], { type: content_type ?? 'application/octet-stream' });
+            const formData = new FormData();
+            formData.append('file', blob, fileName);
+            if (description) {
+                formData.append('description', description);
+            }
+            const result = await client.postFormData(`issues/${issue_id}/files`, formData);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result ?? { success: true }, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
 }

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/dist/tools/monitors.js

@@ -35,4 +35,31 @@ export function registerMonitorTools(server, client) {
             return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
         }
     });
+    // ---------------------------------------------------------------------------
+    // remove_monitor
+    // ---------------------------------------------------------------------------
+    server.registerTool('remove_monitor', {
+        title: 'Remove Issue Monitor',
+        description: 'Remove a user from the monitor list of a MantisBT issue. The user will no longer receive email notifications for updates to this issue.',
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+            username: z.string().min(1).describe('Username of the monitor to remove'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, username }) => {
+        try {
+            await client.delete(`issues/${issue_id}/monitors/${username}`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true }, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
 }

package/dist/tools/relationships.js

@@ -51,4 +51,33 @@ Important: The API only accepts numeric type IDs, not string names.`,
             return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
         }
     });
+    // ---------------------------------------------------------------------------
+    // remove_relationship
+    // ---------------------------------------------------------------------------
+    server.registerTool('remove_relationship', {
+        title: 'Remove Issue Relationship',
+        description: `Remove a relationship from a MantisBT issue.
+
+Use get_issue first to retrieve the relationship IDs. The relationship_id is the numeric id field of a relationship object in the issue's relationships array (not the type ID).`,
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('The issue ID the relationship belongs to'),
+            relationship_id: z.number().int().positive().describe('The numeric ID of the relationship to remove (from the relationships array in get_issue)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, relationship_id }) => {
+        try {
+            await client.delete(`issues/${issue_id}/relationships/${relationship_id}`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true }, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
   "license": "MIT",
@@ -19,13 +19,16 @@
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "dev": "tsc -p tsconfig.build.json --watch",
+    "dev:start": "npm run typecheck && npm run build && node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:record": "tsx scripts/record-fixtures.ts"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "vectra": "^0.4.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {

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);
+  });
+});