@dpesch/mantisbt-mcp-server 1.14.1 → 1.15.0

package/dist/index.js

@@ -10,19 +10,8 @@ import { getConfig, getStartupConfig, assertHttpAuthConfigured } from './config.
 import { MantisClient } from './client.js';
 import { VersionHintService, setGlobalVersionHint } from './version-hint.js';
 import { MetadataCache } from './cache.js';
-import { registerIssueTools } from './tools/issues.js';
-import { registerNoteTools } from './tools/notes.js';
-import { registerFileTools } from './tools/files.js';
-import { registerRelationshipTools } from './tools/relationships.js';
-import { registerMonitorTools } from './tools/monitors.js';
-import { registerProjectTools } from './tools/projects.js';
-import { registerProjectVersionTools } from './tools/project-versions.js';
-import { registerUserTools } from './tools/users.js';
-import { registerFilterTools } from './tools/filters.js';
-import { registerConfigTools } from './tools/config.js';
-import { registerMetadataTools } from './tools/metadata.js';
-import { registerTagTools } from './tools/tags.js';
-import { registerVersionTools } from './tools/version.js';
+import { registerAllTools } from './tools/index.js';
+import { filterToolRegistration } from './toolsets.js';
 import { registerPrompts } from './prompts/index.js';
 import { registerResources } from './resources/index.js';
 // ---------------------------------------------------------------------------
@@ -55,26 +44,26 @@ async function createMcpServer(transport) {
         name: 'mantisbt-mcp-server',
         version,
     });
-    registerIssueTools(server, client, cache);
-    registerNoteTools(server, client);
-    registerFileTools(server, client, startupConfig.uploadDir, transport);
-    registerRelationshipTools(server, client);
-    registerMonitorTools(server, client);
-    registerProjectTools(server, client, cache);
-    registerProjectVersionTools(server, client, cache);
-    registerUserTools(server, client);
-    registerFilterTools(server, client);
-    registerConfigTools(server, client, cache);
-    registerMetadataTools(server, client, cache);
-    registerTagTools(server, client);
-    registerVersionTools(server, client, versionHint, version);
+    // Tools register through a filter for MANTIS_TOOLSETS / MANTIS_DISABLE_DESTRUCTIVE;
+    // prompts and resources use the server directly.
+    const tools = filterToolRegistration(server, startupConfig);
+    // Optional: Semantic search module — needs MANTIS_SEARCH_ENABLED=true and the
+    // "search" tool group (skipping it avoids loading the model and the index).
+    // Initialized first so get_metadata can report the index status.
+    const searchIndexStatus = startupConfig.search.enabled && startupConfig.toolsets.has('search')
+        ? await (await import('./search/index.js')).initializeSearchModule(tools, client, startupConfig.search)
+        : undefined;
+    registerAllTools(tools, {
+        client,
+        cache,
+        versionHint,
+        version,
+        uploadDir: startupConfig.uploadDir,
+        transport,
+        searchIndexStatus,
+    });
     registerPrompts(server);
     registerResources(server, client, cache, startupConfig.testEnvironment);
-    // Optional: Semantic search module
-    if (startupConfig.search.enabled) {
-        const { initializeSearchModule } = await import('./search/index.js');
-        await initializeSearchModule(server, client, startupConfig.search);
-    }
     return server;
 }
 // ---------------------------------------------------------------------------

package/dist/issue-enrich.js

@@ -0,0 +1,23 @@
+import { buildAttachmentDownloadUrl, buildIssueViewUrl, buildNoteViewUrl } from './client.js';
+/**
+ * Adds the links MantisBT's REST API leaves out: view_url for the issue and
+ * each note, download_url for each attachment (REST sends it only via SOAP).
+ * issueId is the fallback when a select projection excluded the id field.
+ */
+export function enrichIssue(issue, baseUrl, issueId) {
+    const id = issue.id ?? issueId;
+    if (id === undefined)
+        return issue;
+    return {
+        ...issue,
+        view_url: buildIssueViewUrl(baseUrl, id),
+        notes: issue.notes?.map(note => ({
+            ...note,
+            view_url: buildNoteViewUrl(baseUrl, id, note.id),
+        })),
+        attachments: issue.attachments?.map(file => ({
+            ...file,
+            download_url: buildAttachmentDownloadUrl(baseUrl, file.id),
+        })),
+    };
+}

package/dist/issue-envelope.js

@@ -0,0 +1,4 @@
+/** The issue from a MantisBT issue response, whichever of the two envelopes it uses. */
+export function firstIssue(response) {
+    return response?.issues?.[0] ?? response?.issue;
+}

package/dist/prompts/index.js

@@ -16,7 +16,7 @@ export function registerPrompts(server) {
         description: 'Guide the creation of a complete bug report in MantisBT. Project, category, summary, and description are required.',
         argsSchema: {
             project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            category: z.string().describe('Issue category (call get_project_categories to list valid values)'),
+            category: z.string().describe('Issue category (call get_project with include: ["categories"] to list valid values)'),
             summary: z.string().describe('Short, descriptive summary of the bug'),
             description: z.string().describe('Detailed description of the bug'),
             steps_to_reproduce: z.string().optional().describe('Step-by-step reproduction instructions'),
@@ -46,7 +46,7 @@ export function registerPrompts(server) {
         if (environment) {
             lines.push(``, `Environment:`, environment);
         }
-        lines.push(``, `Use the create_issue tool to submit this bug report.`, `Call get_issue_enums first if you need to look up valid severity and priority values.`, `Default to severity "minor" and priority "normal" unless the user specifies otherwise.`);
+        lines.push(``, `Use the create_issue tool to submit this bug report.`, `Call get_issue_schema first if you need to look up valid severity and priority values.`, `Default to severity "minor" and priority "normal" unless the user specifies otherwise.`);
         return userMessage(lines.join('\n'));
     });
     // ---------------------------------------------------------------------------
@@ -57,7 +57,7 @@ export function registerPrompts(server) {
         description: 'Guide the creation of a feature request in MantisBT. Project, category, summary, and description are required.',
         argsSchema: {
             project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            category: z.string().describe('Issue category (call get_project_categories to list valid values)'),
+            category: z.string().describe('Issue category (call get_project with include: ["categories"] to list valid values)'),
             summary: z.string().describe('Short description of the requested feature'),
             description: z.string().describe('Detailed description of the feature'),
             use_case: z.string().optional().describe('Business use case or motivation for the feature'),
@@ -75,7 +75,7 @@ export function registerPrompts(server) {
         if (use_case) {
             lines.push(``, `Use case / motivation:`, use_case);
         }
-        lines.push(``, `Use the create_issue tool to submit this feature request.`, `Call get_issue_enums first to look up valid severity values — use severity "feature" and priority "normal" unless the user specifies otherwise.`);
+        lines.push(``, `Use the create_issue tool to submit this feature request.`, `Call get_issue_schema first to look up valid severity values — use severity "feature" and priority "normal" unless the user specifies otherwise.`);
         return userMessage(lines.join('\n'));
     });
     // ---------------------------------------------------------------------------

package/dist/resources/index.js

@@ -1,7 +1,6 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { fetchIssueEnums } from '../tools/config.js';
-import { normalizeProject } from '../tools/metadata.js';
-import { ALL_PROJECTS_PREFIX } from '../constants.js';
+import { normalizeProject, stripAllProjectsPrefix } from '../tools/metadata.js';
 function jsonResource(uri, data) {
     return {
         contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data) }],
@@ -21,7 +20,7 @@ export function registerResources(server, client, cache, testEnvironment = false
     }, async (uri) => jsonResource(uri, await client.get('users/me')));
     server.registerResource('projects', 'mantis://projects', {
         title: 'Projects',
-        description: 'All MantisBT projects accessible to the current API user. Served from local cache when fresh; falls back to live fetch. Refresh via the sync_metadata tool.',
+        description: 'All MantisBT projects accessible to the current API user. Served from local cache when fresh; falls back to live fetch. Refresh via get_metadata with refresh: true.',
         mimeType: 'application/json',
     }, async (uri) => jsonResource(uri, await loadProjects()));
     server.registerResource('project-detail', new ResourceTemplate('mantis://projects/{id}', {
@@ -40,7 +39,7 @@ export function registerResources(server, client, cache, testEnvironment = false
         },
     }), {
         title: 'Project Detail',
-        description: 'Combined project view: fields (status, view_state, access_level, description) plus all associated users, versions, and categories. Served from local cache when fresh; falls back to live API fetch. Refresh via the sync_metadata tool.',
+        description: 'Combined project view: fields (status, view_state, access_level, description) plus all associated users, versions, and categories. Served from local cache when fresh; falls back to live API fetch. Refresh via get_metadata with refresh: true.',
         mimeType: 'application/json',
     }, async (uri, { id }) => {
         const numId = Number(id);
@@ -66,10 +65,7 @@ export function registerResources(server, client, cache, testEnvironment = false
             project = raw ? normalizeProject(raw) : undefined;
             users = usersResult.users ?? [];
             versions = versionsResult.versions ?? [];
-            categories = (raw?.categories ?? []).map((c) => ({
-                ...c,
-                name: c.name.startsWith(ALL_PROJECTS_PREFIX) ? c.name.slice(ALL_PROJECTS_PREFIX.length) : c.name,
-            }));
+            categories = stripAllProjectsPrefix(raw?.categories ?? []);
         }
         if (!project) {
             throw new Error(`Project ${numId} not found`);

package/dist/search/index.js

@@ -1,21 +1,22 @@
 import { createVectorStore } from './store.js';
 import { Embedder } from './embedder.js';
-import { registerSearchTools } from './tools.js';
+import { registerSearchTools, getSearchIndexStatus } from './tools.js';
 import { SearchSyncService, SyncLockedError } from './sync.js';
 // ---------------------------------------------------------------------------
 // initializeSearchModule
 // ---------------------------------------------------------------------------
 export async function initializeSearchModule(server, client, config) {
-    if (!config.enabled)
-        return;
     const store = createVectorStore(config.backend, config.dir);
     const embedder = new Embedder(config.modelName, config.numThreads);
     registerSearchTools(server, client, store, embedder, config.dir);
-    // Pre-initialize lastKnownTotal so get_search_index_status shows a value
+    // Pre-initialize lastKnownTotal so the index status (get_metadata) shows a value
     // immediately on startup, even while the background sync is still running.
-    const [startupCount, startupTotal] = await Promise.all([store.count(), store.getLastKnownTotal()]);
-    if (startupTotal === null && startupCount > 0) {
-        await store.setLastKnownTotal(startupCount);
+    // count() loads the whole index into memory, and this runs before the server
+    // connects — so only do it when there is no stored total yet.
+    if (await store.getLastKnownTotal() === null) {
+        const startupCount = await store.count();
+        if (startupCount > 0)
+            await store.setLastKnownTotal(startupCount);
     }
     // Non-blocking background sync on startup. If another server process (another
     // client session) is already syncing the shared index, this one skips it.
@@ -27,4 +28,5 @@ export async function initializeSearchModule(server, client, config) {
         }
         console.error('[mantisbt-search] sync error:', err instanceof Error ? err.message : String(err));
     });
+    return () => getSearchIndexStatus(store);
 }

package/dist/search/tools.js

@@ -1,7 +1,10 @@
 import { z } from 'zod';
+import { coerceBool } from '../coerce.js';
 import { buildIssueViewUrl } from '../client.js';
 import { SearchSyncService } from './sync.js';
 import { getVersionHint } from '../version-hint.js';
+import { firstIssue } from '../issue-envelope.js';
+import { deprecationNote } from '../deprecation.js';
 import { dateFilterSchema, matchesDateFilter, hasDateFilter } from '../date-filter.js';
 import { extractTerms, highlightText, extractSnippet, hasTermMatch } from './highlight.js';
 function buildHighlights(summary, description, terms) {
@@ -25,7 +28,17 @@ function errorText(msg) {
 // ---------------------------------------------------------------------------
 // registerSearchTools
 // ---------------------------------------------------------------------------
-const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
+/** Fill level of the search index (shared by get_metadata and get_search_index_status). */
+export async function getSearchIndexStatus(store) {
+    const [indexed, lastSyncedAt, total] = await Promise.all([
+        store.count(),
+        store.getLastSyncedAt(),
+        store.getLastKnownTotal(),
+    ]);
+    const percent = total !== null ? (total > 0 ? Math.round((indexed / total) * 100) : 0) : null;
+    const summary = total !== null ? `${indexed}/${total} (${percent} %)` : `${indexed}/? (total unknown)`;
+    return { summary, indexed, total, percent, last_synced_at: lastSyncedAt };
+}
 export function registerSearchTools(server, client, store, embedder, lockDir) {
     // ---------------------------------------------------------------------------
     // search_issues
@@ -107,7 +120,7 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
             const enriched = await Promise.all(results.map(async ({ id, score }) => {
                 try {
                     const issueResult = await client.get(`issues/${id}`);
-                    const issue = issueResult.issues?.[0] ?? {};
+                    const issue = (firstIssue(issueResult) ?? {});
                     if (filterActive && !matchesDateFilter(issue, dateFilter)) {
                         return null;
                     }
@@ -153,7 +166,8 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_search_index_status', {
         title: 'Search Index Status',
-        description: 'Returns the current fill level of the semantic search index: how many issues are ' +
+        description: `${deprecationNote('get_search_index_status', 'get_metadata')}\n\n` +
+            'Returns the current fill level of the semantic search index: how many issues are ' +
             'indexed vs. the total number of issues in MantisBT, plus the timestamp of the last sync.',
         inputSchema: z.object({}),
         annotations: {
@@ -163,24 +177,8 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
         },
     }, async () => {
         try {
-            const [indexed, lastSyncedAt, total] = await Promise.all([
-                store.count(),
-                store.getLastSyncedAt(),
-                store.getLastKnownTotal(),
-            ]);
-            const percent = total !== null
-                ? (total > 0 ? Math.round((indexed / total) * 100) : 0)
-                : null;
-            const summary = total !== null
-                ? `${indexed}/${total} (${percent} %)`
-                : `${indexed}/? (total unknown)`;
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ summary, indexed, total, percent, last_synced_at: lastSyncedAt }, null, 2),
-                    },
-                ],
+                content: [{ type: 'text', text: JSON.stringify(await getSearchIndexStatus(store), null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/config.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ISSUE_ENUM_OPTIONS, MANTIS_CANONICAL_ENUM_NAMES } from '../constants.js';
 import { getVersionHint } from '../version-hint.js';
+import { deprecationNote } from '../deprecation.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -127,7 +128,9 @@ Common option names:
     // ---------------------------------------------------------------------------
     server.registerTool('get_issue_enums', {
         title: 'Get Issue Enum Values',
-        description: `Return valid ID, name, and (if available) localized label for all issue enum fields.
+        description: `${deprecationNote('get_issue_enums', 'get_issue_schema')}
+
+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.
@@ -189,7 +192,9 @@ because there is no separate English original.`,
     // ---------------------------------------------------------------------------
     server.registerTool('list_languages', {
         title: 'List Supported Languages',
-        description: 'List all languages supported by the MantisBT installation.',
+        description: `${deprecationNote('list_languages', 'get_current_user (field "language")')}
+
+Despite its name, MantisBT's GET /lang returns only the language of the current user ({ strings, language }), not a list of all languages.`,
         inputSchema: z.object({}),
         annotations: {
             readOnlyHint: true,
@@ -217,7 +222,7 @@ because there is no separate English original.`,
 
 The MantisBT REST API exposes a GET /tags endpoint on some installations.
 If that endpoint is not available, this tool falls back to the local metadata
-cache populated by sync_metadata.`,
+cache populated by get_metadata.`,
         inputSchema: z.object({
             page: z.coerce.number().int().positive().default(1).describe('Page number (default: 1)'),
             page_size: z.coerce.number().int().min(1).max(200).default(50).describe('Tags per page (default: 50)'),
@@ -252,7 +257,7 @@ cache populated by sync_metadata.`,
                 return {
                     content: [{
                             type: 'text',
-                            text: `Error: ${msg}\n\nThe GET /tags endpoint is not available in this MantisBT installation. No cached tags found either — run sync_metadata to populate the cache if your installation provides this endpoint.`,
+                            text: `Error: ${msg}\n\nThe GET /tags endpoint is not available in this MantisBT installation. No cached tags found either — run get_metadata with refresh: true to populate the cache if your installation provides this endpoint.`,
                         }],
                     isError: true,
                 };

package/dist/tools/files.js

@@ -1,7 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { basename, resolve, sep } from 'node:path';
 import { z } from 'zod';
+import { enrichIssue } from '../issue-enrich.js';
 import { getVersionHint } from '../version-hint.js';
+import { firstIssue } from '../issue-envelope.js';
+import { deprecationNote } from '../deprecation.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -21,9 +24,9 @@ export function registerFileTools(server, client, uploadDir, transport = 'stdio'
     // ---------------------------------------------------------------------------
     server.registerTool('list_issue_files', {
         title: 'List Issue File Attachments',
-        description: `List all file attachments of a MantisBT issue. Returns an array of attachment objects, each containing id, filename, size in bytes, content_type, and download_url. Returns an empty array if the issue has no attachments.
+        description: `${deprecationNote('list_issue_files', 'get_issue with select: "attachments"')}
 
-Use this tool when you need to inspect or enumerate files attached to an issue. To add a new attachment, use upload_file instead. To retrieve full issue details that include attachments alongside other fields, use get_issue instead.`,
+List all file attachments of a MantisBT issue. Returns an array of attachment objects, each containing id, filename, size in bytes, content_type, and download_url. Returns an empty array if the issue has no attachments.`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
         }),
@@ -34,8 +37,12 @@ Use this tool when you need to inspect or enumerate files attached to an issue.
         },
     }, async ({ issue_id }) => {
         try {
-            const result = await client.get(`issues/${issue_id}`);
-            const attachments = result.issues?.[0]?.attachments ?? [];
+            const [result, baseUrl] = await Promise.all([
+                client.get(`issues/${issue_id}`, { select: 'id,attachments' }),
+                client.getBaseUrl(),
+            ]);
+            const issue = firstIssue(result);
+            const attachments = (issue && enrichIssue(issue, baseUrl, issue_id).attachments) ?? [];
             return {
                 content: [{ type: 'text', text: JSON.stringify(attachments, null, 2) }],
             };
@@ -58,7 +65,7 @@ Provide exactly one of the two input modes:
 
 The optional content_type sets the MIME type (e.g. "image/png"); defaults to "application/octet-stream". Use the optional description to annotate the attachment.
 
-Use this tool to attach files such as logs, screenshots, or patches to an existing issue. To list existing attachments, use list_issue_files. To retrieve issue details, use get_issue.`,
+Use this tool to attach files such as logs, screenshots, or patches to an existing issue. To list existing attachments, use get_issue with select: "attachments".`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
             file_path: z.string().min(1).optional().describe('Preferred: absolute path to the local file to upload — use this whenever the file exists on disk (mutually exclusive with content)'),

package/dist/tools/index.js

@@ -0,0 +1,34 @@
+import { registerIssueTools } from './issues.js';
+import { registerNoteTools } from './notes.js';
+import { registerFileTools } from './files.js';
+import { registerRelationshipTools } from './relationships.js';
+import { registerMonitorTools } from './monitors.js';
+import { registerProjectTools } from './projects.js';
+import { registerProjectVersionTools } from './project-versions.js';
+import { registerUserTools } from './users.js';
+import { registerFilterTools } from './filters.js';
+import { registerConfigTools } from './config.js';
+import { registerMetadataTools } from './metadata.js';
+import { registerTagTools } from './tags.js';
+import { registerVersionTools } from './version.js';
+/**
+ * Registers every tool except the optional search tools, which the search
+ * module registers itself. Shared by createMcpServer and the test that checks
+ * TOOL_GROUPS against the registered tools, so both see the same wiring.
+ */
+export function registerAllTools(server, deps) {
+    const { client, cache } = deps;
+    registerIssueTools(server, client, cache);
+    registerNoteTools(server, client);
+    registerFileTools(server, client, deps.uploadDir, deps.transport);
+    registerRelationshipTools(server, client);
+    registerMonitorTools(server, client);
+    registerProjectTools(server, client, cache);
+    registerProjectVersionTools(server, client, cache);
+    registerUserTools(server, client);
+    registerFilterTools(server, client);
+    registerConfigTools(server, client, cache);
+    registerMetadataTools(server, client, cache, deps.searchIndexStatus);
+    registerTagTools(server, client);
+    registerVersionTools(server, client, deps.versionHint, deps.version);
+}