@dpesch/mantisbt-mcp-server 1.13.0 → 1.14.1

package/CHANGELOG.md

@@ -11,6 +11,35 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.14.1] – 2026-10-24
+
+### Fixed
+
+- Semantic search: the background sync on server start re-fetched and re-embedded **every** issue instead of only the changed ones. The MantisBT REST API ignores the `updated_after` filter the sync relied on, so each start of each client session caused minutes of full CPU load and rewrote the whole index file. The sync now filters by `updated_at` itself and stops paging at the first unchanged issue; issues whose indexed version is already current are not re-embedded. With an up-to-date index a start now fetches a single page.
+- Semantic search: only one server process syncs the shared index at a time (lock file `sync.lock` in the search directory, stale locks from crashed processes are taken over). Other processes skip the startup sync; `rebuild_search_index` returns an error while another sync is running. Previously concurrent syncs overwrote each other's `index.json`.
+- Semantic search: a server process now reloads the index when another process has rewritten it, instead of writing its outdated copy back on the next flush.
+- Semantic search: the embedding model is unloaded after 10 minutes without embedding and reloaded on the next use (a few seconds). Previously each server process kept it loaded until exit — about 0.9 GB RAM per client session once it had searched or indexed anything. An idle process now drops back to roughly the size of the loaded index.
+- Semantic search: `last_synced_at` is now taken from the newest `updated_at` reported by the server instead of the local clock, so a client clock running ahead of the server can no longer skip changes. A sync limited to `project_id` no longer advances it, so changes in other projects are not lost.
+
+---
+
+## [1.14.0] – 2026-09-27
+
+### Fixed
+
+- `create_issue` / `update_issue`: a `custom_fields` entry without `value` is now rejected with a validation error. Previously it was accepted and the literal string `"undefined"` was written to the custom field.
+
+### Changed
+
+- **Minimum Node.js version is now 22** (`engines: >=22`). Node.js 18 and 20 are end-of-life and no longer receive security updates; the test toolchain (vitest 5) no longer runs on them, so they could not be tested anymore. CI now runs on Node.js 22. Users on Node.js 20 or older should upgrade — npm only warns about the `engines` mismatch, but these versions are no longer tested.
+- Dependencies: `zod` 4 (the MCP SDK supports `^3.25 || ^4`). Tool parameters, types and defaults are unchanged. The published JSON schemas differ slightly: nested `$ref`s are inlined, integer IDs carry an explicit `maximum`, and objects no longer declare `additionalProperties: false` (unknown keys were and still are ignored).
+- Dependencies: `@huggingface/transformers` 4 for the optional semantic search. Embeddings are numerically identical to version 3 (verified with the default model), so existing search indexes stay valid — no rebuild needed. This also resolves the `sharp` security advisories reported by `npm audit`.
+- Dependencies: `@modelcontextprotocol/sdk` minimum raised to ^1.30.1; transitive dependencies updated to resolve all `npm audit` advisories (including a critical one in `tar`).
+- Dev dependencies: vitest and `@vitest/coverage-v8` 5, `@types/node` 22 (matching the minimum Node.js version).
+- CI: the publish job now checks `NPM_TOKEN` and `GH_RELEASE_TOKEN` before `npm publish`, so an empty or invalid token stops the release before anything is published. Each publish step (npm, Codeberg release, GitHub release) is skipped when its target already exists, so re-running a failed job only catches up on what is missing.
+
+---
+
 ## [1.13.0] – 2026-09-27
 
 ### Added

package/README.de.md

@@ -12,7 +12,7 @@ Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) Server, der
 
 ## Voraussetzungen
 
-- Node.js ≥ 18
+- Node.js ≥ 22
 - MantisBT-Installation mit aktivierter REST-API (ab Version 2.23)
 - MantisBT API-Token (unter *Mein Konto → API-Token* erstellen)
 
@@ -156,7 +156,7 @@ Statt einfachem Keyword-Matching versteht die semantische Suche die *Bedeutung*
 - *„Performance-Probleme auf der Checkout-Seite"* – liefert verwandte Meldungen unabhängig von der verwendeten Terminologie
 - *„doppelte Einträge in der Rechnungsliste"* – erkennt auch Issues, die als „zweifach angezeigt", „dupliziert" o.ä. beschrieben sind
 
-Das Embedding-Modell (~80 MB) läuft vollständig **offline** – kein OpenAI-Key, keine externe API. Es wird beim ersten Start einmalig heruntergeladen und lokal gecacht. Issues werden bei jedem Serverstart inkrementell indexiert (nur neue und geänderte Issues werden neu verarbeitet).
+Das Embedding-Modell (~80 MB) läuft vollständig **offline** – kein OpenAI-Key, keine externe API. Es wird beim ersten Start einmalig heruntergeladen und lokal gecacht. Issues werden bei jedem Serverstart inkrementell indexiert (nur neue und geänderte Issues werden neu verarbeitet). Starten mehrere Client-Sitzungen gleichzeitig einen Server, synchronisiert nur einer davon den gemeinsamen Index. Das Modell wird bei der ersten Nutzung geladen und nach 10 Minuten ohne Einbetten wieder entladen, damit ruhende Sitzungen seinen Speicher (~0,9 GB pro Serverprozess) nicht dauerhaft belegen.
 
 Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
 

package/README.md

@@ -12,7 +12,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that i
 
 ## Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 22
 - MantisBT installation with REST API enabled (version 2.23+)
 - MantisBT API token (create under *My Account → API Tokens*)
 
@@ -156,7 +156,7 @@ Instead of exact keyword matching, semantic search understands the *meaning* beh
 - *"performance problems on the checkout page"* — surfaces related reports regardless of the exact terminology used
 - *"duplicate entries in the invoice list"* — catches issues described as "shown twice", "double records", etc.
 
-The embedding model (~80 MB) runs entirely **offline** — no OpenAI key, no external API. It is downloaded once on first start and cached locally. Issues are indexed incrementally on every server start (only new and updated issues are re-indexed).
+The embedding model (~80 MB) runs entirely **offline** — no OpenAI key, no external API. It is downloaded once on first start and cached locally. Issues are indexed incrementally on every server start (only new and updated issues are re-indexed). When several client sessions start a server at the same time, only one of them syncs the shared index. The model is loaded on first use and unloaded again after 10 minutes without embedding, so idle sessions do not hold on to its memory (~0.9 GB per server process).
 
 Activate with `MANTIS_SEARCH_ENABLED=true`.
 

package/dist/search/embedder.js

@@ -6,17 +6,51 @@
 // @huggingface/transformers is an optional dependency. The import is
 // guarded with a try/catch so the server starts without it.
 // ---------------------------------------------------------------------------
+// A loaded model takes ~0.9 GB RAM, and every client session runs its own
+// server process. An idle process releases the model; the next use reloads it.
+const IDLE_UNLOAD_MS = 10 * 60 * 1000;
 export class Embedder {
     modelName;
     numThreads;
     pipe = null;
+    running = 0;
+    idleTimer = null;
     constructor(modelName, numThreads = 1) {
         this.modelName = modelName;
         this.numThreads = numThreads;
     }
+    async withPipeline(fn) {
+        this.running++;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        try {
+            if (!this.pipe) {
+                const loading = this.load();
+                // Never keep a failed load around — the next call retries.
+                loading.catch(() => { if (this.pipe === loading)
+                    this.pipe = null; });
+                this.pipe = loading;
+            }
+            return await fn(await this.pipe);
+        }
+        finally {
+            // The timer only runs while nothing is embedding; unref() keeps it from
+            // holding the process alive.
+            if (--this.running === 0 && this.pipe) {
+                this.idleTimer = setTimeout(() => void this.unload(), IDLE_UNLOAD_MS).unref();
+            }
+        }
+    }
+    async unload() {
+        const pipe = this.pipe;
+        this.idleTimer = null;
+        this.pipe = null;
+        process.stderr.write(`[mantisbt-search] Unloading idle embedding model ${this.modelName}\n`);
+        await (await pipe).dispose?.();
+    }
     async load() {
-        if (this.pipe)
-            return this.pipe;
         process.stderr.write(`[mantisbt-search] Loading embedding model ${this.modelName} (threads: ${this.numThreads})...\n`);
         let transformers;
         try {
@@ -27,29 +61,30 @@ export class Embedder {
             const msg = err instanceof Error ? err.message : String(err);
             throw new Error(`Failed to load @huggingface/transformers: ${msg}`);
         }
-        this.pipe = await transformers.pipeline('feature-extraction', this.modelName, {
+        return transformers.pipeline('feature-extraction', this.modelName, {
             session_options: {
                 intra_op_num_threads: this.numThreads,
                 inter_op_num_threads: 1, // Transformer graphs are sequential — no benefit from inter-op parallelism
             },
         });
-        return this.pipe;
     }
     async embed(text) {
-        const extractor = await this.load();
-        const output = await extractor(text, { pooling: 'mean', normalize: true });
-        return extractVector(output);
+        return this.withPipeline(async (extractor) => {
+            const output = await extractor(text, { pooling: 'mean', normalize: true });
+            return extractVector(output);
+        });
     }
     async embedBatch(texts) {
         if (texts.length === 0)
             return [];
-        const extractor = await this.load();
-        const output = await extractor(texts, { pooling: 'mean', normalize: true });
-        if (Array.isArray(output)) {
-            return output.map(extractVector);
-        }
-        // Some versions return a single tensor for batch input
-        return extractBatchVectors(output, texts.length);
+        return this.withPipeline(async (extractor) => {
+            const output = await extractor(texts, { pooling: 'mean', normalize: true });
+            if (Array.isArray(output)) {
+                return output.map(extractVector);
+            }
+            // Some versions return a single tensor for batch input
+            return extractBatchVectors(output, texts.length);
+        });
     }
 }
 // ---------------------------------------------------------------------------

package/dist/search/index.js

@@ -1,7 +1,7 @@
 import { createVectorStore } from './store.js';
 import { Embedder } from './embedder.js';
 import { registerSearchTools } from './tools.js';
-import { SearchSyncService } from './sync.js';
+import { SearchSyncService, SyncLockedError } from './sync.js';
 // ---------------------------------------------------------------------------
 // initializeSearchModule
 // ---------------------------------------------------------------------------
@@ -10,16 +10,21 @@ export async function initializeSearchModule(server, client, config) {
         return;
     const store = createVectorStore(config.backend, config.dir);
     const embedder = new Embedder(config.modelName, config.numThreads);
-    registerSearchTools(server, client, store, embedder);
+    registerSearchTools(server, client, store, embedder, config.dir);
     // Pre-initialize lastKnownTotal so get_search_index_status 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);
     }
-    // Non-blocking background sync on startup
-    const syncService = new SearchSyncService(client, store, embedder);
+    // Non-blocking background sync on startup. If another server process (another
+    // client session) is already syncing the shared index, this one skips it.
+    const syncService = new SearchSyncService(client, store, embedder, config.dir);
     syncService.sync().catch((err) => {
+        if (err instanceof SyncLockedError) {
+            console.error('[mantisbt-search] another process is syncing the index, skipping startup sync');
+            return;
+        }
         console.error('[mantisbt-search] sync error:', err instanceof Error ? err.message : String(err));
     });
 }

package/dist/search/store.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { readFile, writeFile, rename, mkdir, unlink, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 // VectraStore
@@ -10,19 +10,39 @@ export class VectraStore {
     lastTotalFile;
     items = new Map();
     loaded = false;
+    // Version of index.json the in-memory items correspond to (null: no file).
+    // Every client session runs its own server process on the same index, so
+    // another process may have rewritten the file since it was loaded.
+    loadedVersion = null;
+    // Unflushed addBatch() changes — never discard them by reloading.
+    dirty = false;
     constructor(dir) {
         this.dir = dir;
         this.vectraDir = join(dir, 'vectra');
         this.lastSyncFile = join(dir, 'last_sync.txt');
         this.lastTotalFile = join(dir, 'last_total.txt');
     }
+    get indexFile() {
+        return join(this.vectraDir, 'index.json');
+    }
+    async fileVersion() {
+        try {
+            const { mtimeMs, size } = await stat(this.indexFile);
+            return `${mtimeMs}:${size}`;
+        }
+        catch {
+            return null;
+        }
+    }
     async ensureLoaded() {
-        if (this.loaded)
+        if (this.loaded && this.dirty)
+            return;
+        const version = await this.fileVersion();
+        if (this.loaded && version === this.loadedVersion)
             return;
         await mkdir(this.vectraDir, { recursive: true });
-        const indexFile = join(this.vectraDir, 'index.json');
         try {
-            const raw = await readFile(indexFile, 'utf-8');
+            const raw = await readFile(this.indexFile, 'utf-8');
             const parsed = JSON.parse(raw);
             this.items = new Map(parsed.map(item => [item.id, item]));
         }
@@ -31,13 +51,15 @@ export class VectraStore {
             this.items = new Map();
         }
         this.loaded = true;
+        this.loadedVersion = version;
     }
     async persist() {
-        const indexFile = join(this.vectraDir, 'index.json');
-        const tmpFile = indexFile + '.tmp';
+        const tmpFile = this.indexFile + '.tmp';
         const data = JSON.stringify([...this.items.values()]);
         await writeFile(tmpFile, data, 'utf-8');
-        await rename(tmpFile, indexFile);
+        await rename(tmpFile, this.indexFile);
+        this.loadedVersion = await this.fileVersion();
+        this.dirty = false;
     }
     async add(item) {
         await this.ensureLoaded();
@@ -49,6 +71,7 @@ export class VectraStore {
         for (const item of items) {
             this.items.set(item.id, item);
         }
+        this.dirty = items.length > 0 || this.dirty;
         // No persist() here — call flush() once after all batches are processed.
     }
     async flush() {

package/dist/search/sync-lock.js

@@ -0,0 +1,66 @@
+import { open, readFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Sync lock
+// ---------------------------------------------------------------------------
+// Every MCP client session starts its own server process, and all of them share
+// one index directory. The lock makes sure only one process syncs at a time —
+// concurrent syncs would overwrite each other's index.json.
+const LOCK_FILE = 'sync.lock';
+// Fallback for a lock whose PID was reused by an unrelated process.
+const STALE_AFTER_MS = 2 * 60 * 60 * 1000;
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: the process exists but belongs to another user.
+        return err.code === 'EPERM';
+    }
+}
+async function isStale(lockFile) {
+    try {
+        const content = JSON.parse(await readFile(lockFile, 'utf-8'));
+        const age = Date.now() - new Date(content.started_at).getTime();
+        return !isProcessAlive(content.pid) || Number.isNaN(age) || age >= STALE_AFTER_MS;
+    }
+    catch {
+        // Unreadable, half-written or already removed — safe to (re)try taking it.
+        return true;
+    }
+}
+/**
+ * Tries to take the sync lock in `dir`. Returns a release function, or null if
+ * another live process currently holds the lock. Stale locks are taken over.
+ */
+export async function acquireSyncLock(dir) {
+    await mkdir(dir, { recursive: true });
+    const lockFile = join(dir, LOCK_FILE);
+    const content = { pid: process.pid, started_at: new Date().toISOString() };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const handle = await open(lockFile, 'wx');
+            await handle.writeFile(JSON.stringify(content), 'utf-8');
+            await handle.close();
+            return () => unlinkIfExists(lockFile);
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (!(await isStale(lockFile)))
+                return null;
+            await unlinkIfExists(lockFile);
+        }
+    }
+    return null;
+}
+async function unlinkIfExists(file) {
+    try {
+        await unlink(file);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+}

package/dist/search/sync.js

@@ -1,19 +1,50 @@
+import { acquireSyncLock } from './sync-lock.js';
 // ---------------------------------------------------------------------------
 // SearchSyncService
 // ---------------------------------------------------------------------------
 const PAGE_SIZE = 50;
 const EMBED_BATCH_SIZE = 10;
 const CHECKPOINT_INTERVAL = 100; // flush to disk every N indexed issues
+export class SyncLockedError extends Error {
+    constructor() {
+        super('A search index sync is already running — try again once it has finished');
+        this.name = 'SyncLockedError';
+    }
+}
 export class SearchSyncService {
     client;
     store;
     embedder;
-    constructor(client, store, embedder) {
+    lockDir;
+    constructor(client, store, embedder, lockDir) {
         this.client = client;
         this.store = store;
         this.embedder = embedder;
+        this.lockDir = lockDir;
+    }
+    /**
+     * Indexes all issues changed since the last sync. With `full`, the index is
+     * cleared first — inside the lock, so a running sync of another process is
+     * never wiped underneath it.
+     */
+    async sync(projectId, { full = false } = {}) {
+        if (this.lockDir === undefined)
+            return this.syncUnlocked(projectId, full);
+        const release = await acquireSyncLock(this.lockDir);
+        if (!release)
+            throw new SyncLockedError();
+        try {
+            return await this.syncUnlocked(projectId, full);
+        }
+        finally {
+            await release();
+        }
     }
-    async sync(projectId) {
+    async syncUnlocked(projectId, full) {
+        if (full) {
+            await this.store.clear();
+            await this.store.resetLastSyncedAt();
+        }
         const lastSyncedAt = await this.store.getLastSyncedAt();
         const { issues: allIssues, totalFromApi } = await this.fetchAllIssues(lastSyncedAt ?? undefined, projectId);
         let indexed = 0;
@@ -28,6 +59,9 @@ export class SearchSyncService {
                     skipped++;
                     continue;
                 }
+                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 });
             }
@@ -57,19 +91,28 @@ export class SearchSyncService {
         if (indexedSinceCheckpoint > 0) {
             await this.store.flush();
         }
-        await this.store.setLastSyncedAt(new Date().toISOString());
+        // The watermark is the newest updated_at the server reported, not the local
+        // clock: a client clock running ahead of the server would otherwise skip
+        // 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) {
+            await this.store.setLastSyncedAt(newestUpdatedAt);
+        }
         // Persist the best known total for get_search_index_status.
         // Priority: API total_count > full-rebuild count > current store size.
         // The store size fallback handles MantisBT installations that never return
         // total_count and ensures the status tool never shows "total unknown" after
         // any sync has completed.
         const storeCount = await this.store.count();
-        const total = totalFromApi ?? (lastSyncedAt === null ? indexed + skipped : storeCount);
+        const total = totalFromApi ?? (lastSyncedAt === null ? allIssues.length : storeCount);
         await this.store.setLastKnownTotal(total);
         return { indexed, skipped, total };
     }
     async fetchAllIssues(updatedAfter, projectId) {
-        const allIssues = [];
+        const changedIssues = [];
+        const updatedAfterMs = updatedAfter ? new Date(updatedAfter).getTime() : undefined;
+        let fetchedCount = 0;
         let totalFromApi = null;
         let page = 1;
         while (true) {
@@ -88,16 +131,31 @@ export class SearchSyncService {
             }
             const response = await this.client.get('issues', params);
             const pageIssues = response.issues ?? [];
-            allIssues.push(...pageIssues);
+            fetchedCount += pageIssues.length;
+            // The MantisBT REST API ignores updated_after, sort and direction (they are
+            // still sent for API versions that honour them). It always returns issues
+            // ordered by last_updated DESC without pulling sticky issues to the top
+            // (see filter_get_default() and mc_filter_get_issues()), so the first issue
+            // older than the watermark marks the end of the changes. Ties are kept:
+            // timestamps have one-second resolution, and sync() skips issues whose
+            // indexed version is already current.
+            const cut = updatedAfterMs === undefined
+                ? -1
+                : pageIssues.findIndex(issue => issue.updated_at && new Date(issue.updated_at).getTime() < updatedAfterMs);
+            const reachedWatermark = cut !== -1;
+            changedIssues.push(...(reachedWatermark ? pageIssues.slice(0, cut) : pageIssues));
             // Capture total_count from the first page that provides it
             if (totalFromApi === null && response.total_count != null) {
                 totalFromApi = response.total_count;
             }
-            // Stop when we have fetched all issues:
+            // Stop when we have fetched all changed issues:
+            // - the watermark was reached on this page, or
             // - total_count is provided and reached, or
             // - page returned fewer items than requested (last page)
+            if (reachedWatermark)
+                break;
             if (totalFromApi !== null) {
-                if (allIssues.length >= totalFromApi)
+                if (fetchedCount >= totalFromApi)
                     break;
             }
             else if (pageIssues.length < PAGE_SIZE) {
@@ -105,6 +163,6 @@ export class SearchSyncService {
             }
             page++;
         }
-        return { issues: allIssues, totalFromApi };
+        return { issues: changedIssues, totalFromApi };
     }
 }

package/dist/search/tools.js

@@ -26,7 +26,7 @@ function errorText(msg) {
 // registerSearchTools
 // ---------------------------------------------------------------------------
 const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
-export function registerSearchTools(server, client, store, embedder) {
+export function registerSearchTools(server, client, store, embedder, lockDir) {
     // ---------------------------------------------------------------------------
     // search_issues
     // ---------------------------------------------------------------------------
@@ -47,8 +47,7 @@ export function registerSearchTools(server, client, store, embedder) {
                 'When provided, each matching issue is fetched from MantisBT and enriched with the requested fields. ' +
                 'The relevance score is always included. Without this parameter only id and score are returned.'),
             highlight: z
-                .preprocess(coerceBool, z.boolean())
-                .default(false)
+                .preprocess(coerceBool, z.boolean().default(false))
                 .describe('If true, adds a "highlights" field per result with query terms bolded (**term**) ' +
                 'in the issue summary and a short description snippet. ' +
                 'Note: highlights are keyword-based, not semantic — some results may have no highlighted terms.'),
@@ -215,13 +214,9 @@ export function registerSearchTools(server, client, store, embedder) {
         },
     }, 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, total } = await syncService.sync(project_id);
+            const syncService = new SearchSyncService(client, store, embedder, lockDir);
+            const { indexed, skipped, total } = await syncService.sync(project_id, { full });
             const duration_ms = Date.now() - startMs;
             return {
                 content: [

package/dist/tools/projects.js

@@ -85,8 +85,8 @@ By default, obsolete and inherited parent-project versions are excluded. Set obs
 Prerequisites: obtain project_id from list_projects.`,
         inputSchema: z.object({
             project_id: z.coerce.number().int().positive().describe('Numeric project ID — use list_projects to discover project IDs'),
-            obsolete: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include obsolete (deprecated) versions in the response. Default: false. Set to true to see all versions including those no longer actively used.'),
-            inherit: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include versions inherited from parent projects. Default: false. Set to true for sub-projects that share versions with a parent project.'),
+            obsolete: z.preprocess(coerceBool, z.boolean().default(false)).describe('Include obsolete (deprecated) versions in the response. Default: false. Set to true to see all versions including those no longer actively used.'),
+            inherit: z.preprocess(coerceBool, z.boolean().default(false)).describe('Include versions inherited from parent projects. Default: false. Set to true for sub-projects that share versions with a parent project.'),
         }),
         annotations: {
             readOnlyHint: true,

package/dist/tools/version.js

@@ -27,7 +27,7 @@ export function registerVersionTools(server, client, versionHint, mcpVersion) {
 The version is read from the X-Mantis-Version response header sent by every API call.
 The GitHub comparison requires an outbound HTTPS request to the GitHub API.`,
         inputSchema: z.object({
-            check_latest: z.preprocess(coerceBool, z.boolean()).default(true).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
+            check_latest: z.preprocess(coerceBool, z.boolean().default(true)).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
         }),
         annotations: {
             readOnlyHint: true,

package/docs/cookbook.de.md

@@ -1351,7 +1351,9 @@ Baut den vollständigen Vektor-Suchindex von Grund auf neu auf. Einmalig nach de
 
 ### Inkrementelles Index-Update
 
-Aktualisiert den Index mit Issues, die seit dem letzten Aufbau hinzugekommen oder geändert wurden. Schneller als ein vollständiger Neuaufbau.
+Aktualisiert den Index mit Issues, die seit der letzten Synchronisation hinzugekommen oder geändert wurden. Schneller als ein vollständiger Neuaufbau: Nur die seitdem geänderten Issues werden abgerufen und neu eingebettet.
+
+Es synchronisiert immer nur ein Serverprozess den gemeinsamen Index. Läuft bereits eine Synchronisation in einem anderen Prozess (etwa einer anderen Client-Sitzung), gibt das Tool einen Fehler zurück – nach deren Ende einfach erneut aufrufen. Eine auf `project_id` beschränkte Synchronisation verschiebt `last_synced_at` nicht, damit Änderungen in anderen Projekten beim nächsten Sync trotzdem erfasst werden.
 
 **Tool:** `rebuild_search_index`
 
@@ -1372,7 +1374,7 @@ Aktualisiert den Index mit Issues, die seit dem letzten Aufbau hinzugekommen ode
 ```json
 {
   "indexed": 14,
-  "skipped": 298,
+  "skipped": 0,
   "total": 312,
   "duration_ms": 2104
 }
@@ -1382,7 +1384,7 @@ Aktualisiert den Index mit Issues, die seit dem letzten Aufbau hinzugekommen ode
 
 ### Index-Status prüfen
 
-Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeitstempel der letzten Synchronisation zurück.
+Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeitstempel der letzten Synchronisation zurück. `last_synced_at` ist das jüngste `updated_at`, das der MantisBT-Server bei dieser Synchronisation gemeldet hat (Serverzeit), und kann daher vor dem tatsächlichen Zeitpunkt der Synchronisation liegen.
 
 **Tool:** `get_search_index_status`
 
@@ -1402,7 +1404,7 @@ Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeit
   "indexed": 312,
   "total": 312,
   "percent": 100,
-  "last_synced_at": "2024-11-05T14:00:00.000Z"
+  "last_synced_at": "2024-11-05T14:00:00+01:00"
 }
 ```
 

package/docs/cookbook.md

@@ -1351,7 +1351,9 @@ Builds the full vector search index from scratch. Run this once after enabling s
 
 ### Incremental index update
 
-Updates the index with issues added or changed since the last build. Faster than a full rebuild.
+Updates the index with issues added or changed since the last sync. Faster than a full rebuild: only issues changed since then are fetched and re-embedded.
+
+Only one server process syncs the shared index at a time. If another process (for example another client session) is already syncing, the tool returns an error ("A search index sync is already running") — try again once that sync has finished. A sync limited to `project_id` does not advance `last_synced_at`, so changes in other projects are still picked up by the next sync.
 
 **Tool:** `rebuild_search_index`
 
@@ -1372,7 +1374,7 @@ Updates the index with issues added or changed since the last build. Faster than
 ```json
 {
   "indexed": 14,
-  "skipped": 298,
+  "skipped": 0,
   "total": 312,
   "duration_ms": 2104
 }
@@ -1382,7 +1384,7 @@ Updates the index with issues added or changed since the last build. Faster than
 
 ### Check index status
 
-Returns the number of indexed issues, total issue count, and the timestamp of the last sync.
+Returns the number of indexed issues, total issue count, and the timestamp of the last sync. `last_synced_at` is the newest `updated_at` the MantisBT server reported at that sync (server time), so it can lie before the actual time of the sync.
 
 **Tool:** `get_search_index_status`
 
@@ -1402,7 +1404,7 @@ Returns the number of indexed issues, total issue count, and the timestamp of th
   "indexed": 312,
   "total": 312,
   "percent": 100,
-  "last_synced_at": "2024-11-05T14:00:00.000Z"
+  "last_synced_at": "2024-11-05T14:00:00+01:00"
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
@@ -44,18 +44,18 @@
     "init": "node scripts/init.mjs"
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.0.0",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.22.4"
+    "@huggingface/transformers": "^4.3.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@vitest/coverage-v8": "^4.1.5",
-    "tsx": "^4.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.5"
+    "@types/node": "^22.20.4",
+    "@vitest/coverage-v8": "^5.0.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.dpesch/mantisbt-mcp-server",
   "title": "MantisBT MCP Server",
   "description": "MantisBT MCP server – manage issues, notes, files, tags, and relationships. With semantic search.",
-  "version": "1.13.0",
+  "version": "1.14.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.13.0",
+      "version": "1.14.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"