@dpesch/mantisbt-mcp-server 1.14.1 → 1.16.0

package/dist/search/sync.js

@@ -41,12 +41,24 @@ export class SearchSyncService {
         }
     }
     async syncUnlocked(projectId, full) {
-        if (full) {
+        // Vectors made with another model or token limit are not comparable with
+        // new query vectors, and an incremental sync never replaces them — their
+        // issues are unchanged. Such an index is rebuilt, for all projects, since
+        // it is useless as it stands. An empty index only takes the signature.
+        const signature = this.embedder.signature;
+        const mismatch = (await this.store.getEmbeddingSignature()) !== signature;
+        const outdated = mismatch && (await this.store.count()) > 0;
+        const scope = outdated ? undefined : projectId;
+        if (full || outdated) {
             await this.store.clear();
             await this.store.resetLastSyncedAt();
         }
+        // Stored before indexing: an interrupted rebuild then resumes on the next
+        // sync instead of starting over.
+        if (full || mismatch)
+            await this.store.setEmbeddingSignature(signature);
         const lastSyncedAt = await this.store.getLastSyncedAt();
-        const { issues: allIssues, totalFromApi } = await this.fetchAllIssues(lastSyncedAt ?? undefined, projectId);
+        const { issues: allIssues, totalFromApi } = await this.fetchAllIssues(lastSyncedAt ?? undefined, scope);
         let indexed = 0;
         let skipped = 0;
         let indexedSinceCheckpoint = 0;
@@ -62,21 +74,20 @@ export class SearchSyncService {
                 if (issue.updated_at && (await this.store.getItem(issue.id))?.metadata.updated_at === issue.updated_at) {
                     continue; // already indexed in this exact version
                 }
-                const text = `${issue.summary}\n${issue.description ?? ''}`.trim();
-                toEmbed.push({ issue, text });
+                toEmbed.push({ issue, doc: { summary: issue.summary, description: issue.description } });
             }
             if (toEmbed.length === 0)
                 continue;
-            const vectors = await this.embedder.embedBatch(toEmbed.map(e => e.text));
-            const batchItems = toEmbed.map((e, j) => ({
-                id: e.issue.id,
-                vector: vectors[j],
-                metadata: {
-                    summary: e.issue.summary,
-                    description: e.issue.description,
-                    updated_at: e.issue.updated_at,
-                },
-            }));
+            const vectors = await this.embedder.embedDocuments(toEmbed.map(e => e.doc));
+            const batchItems = toEmbed.map(({ issue, doc }, j) => {
+                const [vector, ...chunks] = vectors[j];
+                return {
+                    id: issue.id,
+                    vector: vector,
+                    ...(chunks.length > 0 && { chunks }),
+                    metadata: { ...doc, updated_at: issue.updated_at },
+                };
+            });
             await this.store.addBatch(batchItems);
             indexed += batchItems.length;
             indexedSinceCheckpoint += batchItems.length;
@@ -96,7 +107,7 @@ export class SearchSyncService {
         // changes for good. A project-scoped sync must not move the shared watermark,
         // since changes in the other projects were not looked at.
         const newestUpdatedAt = allIssues.find(issue => issue.updated_at)?.updated_at;
-        if (projectId === undefined && newestUpdatedAt && newestUpdatedAt !== lastSyncedAt) {
+        if (scope === undefined && newestUpdatedAt && newestUpdatedAt !== lastSyncedAt) {
             await this.store.setLastSyncedAt(newestUpdatedAt);
         }
         // Persist the best known total for get_search_index_status.

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
@@ -33,7 +46,10 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
     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.',
+            'by combining semantic similarity with keyword matching, so exact terms such as identifiers, ' +
+            'error codes or version numbers are found as well. "score" is the semantic similarity; results ' +
+            'are ordered by the combined ranking, so a keyword match can precede a higher score. ' +
+            '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
@@ -79,7 +95,7 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
                 embedder.embed(query),
                 client.getBaseUrl(),
             ]);
-            const results = await store.search(queryVector, top_n);
+            const results = await store.search(queryVector, top_n, query);
             if (!select) {
                 // For filtering or highlighting we need store metadata per result
                 if (!filterActive && !terms.length) {
@@ -107,7 +123,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 +169,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 +180,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);
+}