@dpesch/mantisbt-mcp-server 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.3.0] – 2026-03-16
+
+### Added
+- New tool `get_search_index_status`: returns the current fill level of the semantic search index — how many issues are indexed vs. total, plus the timestamp of the last sync. Only active when `MANTIS_SEARCH_ENABLED=true`.
+- New tool `get_issue_enums`: returns structured ID/name pairs for all issue enum fields (severity, status, priority, resolution, reproducibility) — ready for direct use in `create_issue` / `update_issue` without requiring knowledge of MantisBT-internal config option names.
+- `sync_metadata` now fetches and caches all tags globally (`tags` field at root level of the cached metadata). When the dedicated `GET /tags` endpoint is unavailable (MantisBT < 2.26), tags are collected by scanning all issues across all projects (`select=id,tags`).
+- New tool `get_mcp_version`: returns the version of the running mantisbt-mcp-server instance.
+
+### Fixed
+- `list_tags` now falls back to the metadata cache when `GET /tags` returns 404 instead of returning an error. Run `sync_metadata` first to populate the cache.
+- Numeric ID parameters now accept string inputs (e.g. `"1940"`) — MCP clients that pass IDs as strings no longer receive error -32602.
+- `create_issue` now always sends a `severity` to MantisBT (default: `"minor"`). Previously omitting severity caused MantisBT to store `0`, which was displayed as `@0@`.
+- `get_search_index_status` now correctly reports the total issue count on MantisBT installations that do not return `total_count` in the issues list API. The total is persisted after every sync: `total_count` from the API takes precedence, otherwise the current store size is used as a best-effort estimate. The status tool will therefore no longer show "total unknown" after any sync has completed.
+- `sync_metadata` tags endpoint failure now degrades gracefully to an empty array instead of propagating an error.
+- `sync_metadata` now correctly populates `byProject[id].categories`.
+- `sync_metadata` now fetches all versions including obsolete and inherited ones (`obsolete=1&inherit=1`). Previously only non-obsolete versions were returned, causing the version count in the cache to be far too low.
+- `get_project_versions` now accepts optional `obsolete` and `inherit` boolean parameters to include obsolete and/or inherited versions (both default to `false`). Previously the wrong endpoint (`projects/{id}/categories`) was called, which returned an empty array on many installations. Categories are now read from the project detail response (`projects/{id}`), identical to the source used by `get_project_categories`.
+
+---
+
+## [1.2.0] – 2026-03-16
+
+### Added
+- New tool `remove_relationship`: removes a relationship from an issue. The `relationship_id` is the numeric `id` field on the relationship object returned by `get_issue` (not the type id).
+- New tool `remove_monitor`: removes a user as a monitor of an issue by username.
+- New tool `upload_file`: uploads a file to an issue via multipart/form-data. Supports two input modes: a local `file_path` (filename derived from path) or Base64-encoded `content` with an explicit `filename`. Optional parameters: `filename` (overrides derived name), `content_type` (default: `application/octet-stream`), `description`.
+- New optional semantic search module (`MANTIS_SEARCH_ENABLED=true`): indexes all MantisBT issues as local vector embeddings using `@huggingface/transformers` (ONNX, no external API required). Two new tools:
+  - `search_issues` — natural language search over all indexed issues, returns top-N results by cosine similarity score.
+  - `rebuild_search_index` — build or incrementally update the search index; `full: true` clears and rebuilds from scratch.
+  - Vector store: `vectra` (pure JS, default) or `sqlite-vec` (optional, requires manual installation).
+  - Incremental sync on every server start via `updated_at` timestamp.
+  - Configuration: `MANTIS_SEARCH_ENABLED`, `MANTIS_SEARCH_BACKEND`, `MANTIS_SEARCH_DIR`, `MANTIS_SEARCH_MODEL`.
+
+### Fixed
+- `list_issues` recorded-fixture tests were fragile: status filter counts are now derived dynamically from the fixture instead of hardcoded assumptions.
+
+---
+
 ## [1.1.0] – 2026-03-15
 
 ### Added

package/README.de.md

@@ -69,6 +69,10 @@ npm run build
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache-Lebensdauer in Sekunden |
 | `TRANSPORT` | – | `stdio` | Transport-Modus: `stdio` oder `http` |
 | `PORT` | – | `3000` | Port für HTTP-Modus |
+| `MANTIS_SEARCH_ENABLED` | – | `false` | Auf `true` setzen, um die semantische Suche zu aktivieren |
+| `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vektorspeicher: `vectra` (reines JS) oder `sqlite-vec` (manuelle Installation erforderlich) |
+| `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Verzeichnis für den Suchindex |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding-Modell (wird beim ersten Start einmalig heruntergeladen, ~80 MB) |
 
 ### Config-Datei (Fallback)
 
@@ -106,24 +110,27 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | Tool | Beschreibung |
 |---|---|
 | `list_issue_files` | Anhänge eines Issues auflisten |
+| `upload_file` | Datei an ein Issue anhängen – entweder per lokalem `file_path` oder Base64-kodiertem `content` + `filename` |
 
 ### Beziehungen
 
 | Tool | Beschreibung |
 |---|---|
 | `add_relationship` | Beziehung zwischen zwei Issues erstellen |
+| `remove_relationship` | Beziehung von einem Issue entfernen (die `id` aus dem Beziehungsobjekt verwenden, nicht die type-ID) |
 
 ### Beobachter
 
 | Tool | Beschreibung |
 |---|---|
 | `add_monitor` | Sich selbst als Beobachter eines Issues eintragen |
+| `remove_monitor` | Benutzer als Beobachter eines Issues austragen |
 
 ### Tags
 
 | Tool | Beschreibung |
 |---|---|
-| `list_tags` | Alle verfügbaren Tags auflisten |
+| `list_tags` | Alle verfügbaren Tags auflisten; greift auf den Metadaten-Cache zurück, wenn `GET /tags` mit 404 antwortet (vorher `sync_metadata` ausführen) |
 | `attach_tags` | Tags an ein Issue hängen |
 | `detach_tag` | Tag von einem Issue entfernen |
 
@@ -132,10 +139,44 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | Tool | Beschreibung |
 |---|---|
 | `list_projects` | Alle zugänglichen Projekte auflisten |
-| `get_project_versions` | Versionen eines Projekts abrufen |
+| `get_project_versions` | Versionen eines Projekts abrufen; optionale Booleans `obsolete` und `inherit` für veraltete bzw. vom Elternprojekt geerbte Versionen |
 | `get_project_categories` | Kategorien eines Projekts abrufen |
 | `get_project_users` | Benutzer eines Projekts abrufen |
 
+### Semantische Suche *(optional)*
+
+Statt einfachem Keyword-Matching versteht die semantische Suche die *Bedeutung* einer Anfrage. Formuliere in natürlicher Sprache — die Suche findet konzeptuell verwandte Issues, auch wenn die genauen Begriffe nicht übereinstimmen:
+
+- *„Login funktioniert nach Passwort-Reset nicht"* — findet Issues rund um Authentifizierungsgrenzfälle
+- *„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).
+
+Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
+
+| Tool | Beschreibung |
+|---|---|
+| `search_issues` | Natürlichsprachige Suche über alle indizierten Issues – liefert Top-N-Ergebnisse mit Cosine-Similarity-Score |
+| `rebuild_search_index` | Suchindex aufbauen oder aktualisieren; `full: true` löscht und baut ihn vollständig neu |
+| `get_search_index_status` | Aktuellen Füllstand des Suchindex zurückgeben: wie viele Issues bereits indiziert sind im Verhältnis zur Gesamtanzahl, plus Zeitstempel der letzten Synchronisation |
+
+#### Welches Backend wählen?
+
+| | `vectra` *(Standard)* | `sqlite-vec` |
+|---|---|---|
+| Abhängigkeiten | Keine (reines JS) | Benötigt native Build-Tools |
+| Installation | Enthalten | `npm install sqlite-vec better-sqlite3` |
+| Geeignet für | Bis ~10.000 Issues | Ab 10.000 Issues |
+| Performance | Für die meisten Instanzen ausreichend | Schneller bei großen Datenmengen |
+
+Mit `vectra` starten. Zu `sqlite-vec` wechseln, wenn Indexierungszeiten oder Abfragen spürbar langsam werden.
+
+```bash
+npm install sqlite-vec better-sqlite3
+# dann MANTIS_SEARCH_BACKEND=sqlite-vec setzen
+```
+
 ### Metadaten & System
 
 | Tool | Beschreibung |
@@ -147,7 +188,9 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | `get_current_user` | Eigenes Benutzerprofil abrufen |
 | `list_languages` | Verfügbare Sprachen auflisten |
 | `get_config` | Server-Konfiguration (Basis-URL, Cache-TTL) anzeigen |
+| `get_issue_enums` | Gültige ID/Name-Paare für alle Enum-Felder zurückgeben (Severity, Status, Priority, Resolution, Reproducibility) — vor `create_issue` / `update_issue` verwenden, um korrekte Werte nachzuschlagen |
 | `get_mantis_version` | MantisBT-Version abrufen und auf Updates prüfen |
+| `get_mcp_version` | Version dieser mantisbt-mcp-server-Instanz zurückgeben |
 
 ## HTTP-Modus
 

package/README.md

@@ -69,6 +69,10 @@ npm run build
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache lifetime in seconds |
 | `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | – | `3000` | Port for HTTP mode |
+| `MANTIS_SEARCH_ENABLED` | – | `false` | Set to `true` to enable semantic search |
+| `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vector store backend: `vectra` (pure JS) or `sqlite-vec` (requires manual install) |
+| `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Directory for the search index |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding model name (downloaded once on first use, ~80 MB) |
 
 ### Config file (fallback)
 
@@ -106,24 +110,27 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | Tool | Description |
 |---|---|
 | `list_issue_files` | List attachments of an issue |
+| `upload_file` | Upload a file to an issue — either by local `file_path` or Base64-encoded `content` + `filename` |
 
 ### Relationships
 
 | Tool | Description |
 |---|---|
 | `add_relationship` | Create a relationship between two issues |
+| `remove_relationship` | Remove a relationship from an issue (use the `id` from the relationship object, not the type) |
 
 ### Monitors
 
 | Tool | Description |
 |---|---|
 | `add_monitor` | Add yourself as a monitor of an issue |
+| `remove_monitor` | Remove a user as a monitor of an issue |
 
 ### Tags
 
 | Tool | Description |
 |---|---|
-| `list_tags` | List all available tags |
+| `list_tags` | List all available tags; falls back to the metadata cache when `GET /tags` returns 404 (run `sync_metadata` first to populate) |
 | `attach_tags` | Attach tags to an issue |
 | `detach_tag` | Remove a tag from an issue |
 
@@ -132,10 +139,44 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | Tool | Description |
 |---|---|
 | `list_projects` | List all accessible projects |
-| `get_project_versions` | Get versions of a project |
+| `get_project_versions` | Get versions of a project; optional `obsolete` and `inherit` booleans to include obsolete or parent-inherited versions |
 | `get_project_categories` | Get categories of a project |
 | `get_project_users` | Get users of a project |
 
+### Semantic search *(optional)*
+
+Instead of exact keyword matching, semantic search understands the *meaning* behind a query. Ask in plain language — the search engine finds conceptually related issues even when the wording doesn't match:
+
+- *"login fails after password reset"* — finds issues about authentication edge cases
+- *"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).
+
+Activate with `MANTIS_SEARCH_ENABLED=true`.
+
+| Tool | Description |
+|---|---|
+| `search_issues` | Natural language search over all indexed issues — returns top-N results with cosine similarity score |
+| `rebuild_search_index` | Build or update the search index; `full: true` clears and rebuilds from scratch |
+| `get_search_index_status` | Return the current fill level of the search index: how many issues are indexed vs. total, and the timestamp of the last sync |
+
+#### Which backend to choose?
+
+| | `vectra` *(default)* | `sqlite-vec` |
+|---|---|---|
+| Dependencies | None (pure JS) | Requires native build tools |
+| Install | Included | `npm install sqlite-vec better-sqlite3` |
+| Best for | Up to ~10,000 issues | 10,000+ issues |
+| Performance | Fast enough for most setups | Faster for large corpora |
+
+Start with `vectra`. Switch to `sqlite-vec` if indexing or query times become noticeably slow.
+
+```bash
+npm install sqlite-vec better-sqlite3
+# then set MANTIS_SEARCH_BACKEND=sqlite-vec
+```
+
 ### Metadata & system
 
 | Tool | Description |
@@ -147,7 +188,9 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | `get_current_user` | Retrieve your own user profile |
 | `list_languages` | List available languages |
 | `get_config` | Show server configuration (base URL, cache TTL) |
+| `get_issue_enums` | Return valid ID/name pairs for all issue enum fields (severity, status, priority, resolution, reproducibility) — use before `create_issue` / `update_issue` to look up correct values |
 | `get_mantis_version` | Get MantisBT version and check for updates |
+| `get_mcp_version` | Return the version of this mantisbt-mcp-server instance |
 
 ## HTTP mode
 

package/dist/client.js

@@ -101,6 +101,19 @@ export class MantisClient {
         });
         return this.handleResponse(response);
     }
+    async postFormData(path, formData) {
+        // Note: Content-Type must NOT be set here — fetch sets it automatically
+        // with the correct multipart/form-data boundary.
+        const response = await fetch(this.buildUrl(path), {
+            method: 'POST',
+            headers: {
+                'Authorization': this.apiKey,
+                'Accept': 'application/json',
+            },
+            body: formData,
+        });
+        return this.handleResponse(response);
+    }
     async getVersion() {
         const response = await fetch(this.buildUrl('users/me'), {
             method: 'GET',

package/dist/config.js

@@ -1,6 +1,28 @@
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ---------------------------------------------------------------------------
+// .env.local loader
+// ---------------------------------------------------------------------------
+async function loadDotEnvLocal() {
+    try {
+        const envPath = join(dirname(fileURLToPath(import.meta.url)), '..', '.env.local');
+        const content = await readFile(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const match = line.match(/^([^#=\s][^=]*)=(.*)/);
+            if (match) {
+                const key = match[1].trim();
+                const value = match[2].trim().replace(/^["']|["']$/g, '');
+                if (!process.env[key])
+                    process.env[key] = value;
+            }
+        }
+    }
+    catch {
+        // .env.local not present — use environment variables directly
+    }
+}
 // ---------------------------------------------------------------------------
 // Loader
 // ---------------------------------------------------------------------------
@@ -18,6 +40,7 @@ let cachedConfig = null;
 export async function getConfig() {
     if (cachedConfig)
         return cachedConfig;
+    await loadDotEnvLocal();
     let baseUrl = process.env.MANTIS_BASE_URL ?? '';
     let apiKey = process.env.MANTIS_API_KEY ?? '';
     // If env vars are missing, try ~/.claude/mantis.json as fallback
@@ -44,11 +67,26 @@ export async function getConfig() {
     const cacheTtl = process.env.MANTIS_CACHE_TTL
         ? parseInt(process.env.MANTIS_CACHE_TTL, 10)
         : 3600;
+    const searchEnabled = process.env.MANTIS_SEARCH_ENABLED === 'true';
+    const searchBackendRaw = process.env.MANTIS_SEARCH_BACKEND ?? 'vectra';
+    if (searchBackendRaw !== 'vectra' && searchBackendRaw !== 'sqlite-vec') {
+        process.stderr.write(`[mantisbt-config] Unknown MANTIS_SEARCH_BACKEND="${searchBackendRaw}", falling back to "vectra"\n`);
+    }
+    const searchBackend = searchBackendRaw === 'sqlite-vec' ? 'sqlite-vec' : 'vectra';
+    const searchDir = process.env.MANTIS_SEARCH_DIR ?? join(cacheDir, 'search');
+    const searchModelName = process.env.MANTIS_SEARCH_MODEL ??
+        'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
     cachedConfig = {
         baseUrl: baseUrl.replace(/\/$/, ''), // strip trailing slash
         apiKey,
         cacheDir,
         cacheTtl,
+        search: {
+            enabled: searchEnabled,
+            backend: searchBackend,
+            dir: searchDir,
+            modelName: searchModelName,
+        },
     };
     return cachedConfig;
 }

package/dist/index.js

@@ -50,10 +50,15 @@ async function createMcpServer() {
     registerProjectTools(server, client);
     registerUserTools(server, client);
     registerFilterTools(server, client);
-    registerConfigTools(server, client);
+    registerConfigTools(server, client, cache);
     registerMetadataTools(server, client, cache);
     registerTagTools(server, client);
-    registerVersionTools(server, client, versionHint);
+    registerVersionTools(server, client, versionHint, version);
+    // Optional: Semantic search module
+    if (config.search.enabled) {
+        const { initializeSearchModule } = await import('./search/index.js');
+        await initializeSearchModule(server, client, config.search);
+    }
     return server;
 }
 // ---------------------------------------------------------------------------

package/dist/search/embedder.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Embedder
+// Wraps @huggingface/transformers for local ONNX-based embeddings.
+// Lazy-loaded on first use — no model download at server startup.
+//
+// @huggingface/transformers is an optional dependency. The import is
+// guarded with a try/catch so the server starts without it.
+// ---------------------------------------------------------------------------
+export class Embedder {
+    modelName;
+    pipe = null;
+    constructor(modelName) {
+        this.modelName = modelName;
+    }
+    async load() {
+        if (this.pipe)
+            return this.pipe;
+        process.stderr.write(`[mantisbt-search] Loading embedding model ${this.modelName}...\n`);
+        let transformers;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            transformers = (await import('@huggingface/transformers'));
+        }
+        catch (err) {
+            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 this.pipe;
+    }
+    async embed(text) {
+        const extractor = await this.load();
+        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);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractVector(output) {
+    const data = output.data;
+    return Array.from(data);
+}
+function extractBatchVectors(output, batchSize) {
+    const data = Array.from(output.data);
+    // dims is typically [batchSize, sequenceLen, hiddenSize] or [batchSize, hiddenSize]
+    const vecSize = data.length / batchSize;
+    if (!Number.isInteger(vecSize)) {
+        throw new Error(`Unexpected batch output shape: ${data.length} elements for batch size ${batchSize}`);
+    }
+    const result = [];
+    for (let i = 0; i < batchSize; i++) {
+        result.push(data.slice(i * vecSize, (i + 1) * vecSize));
+    }
+    return result;
+}

package/dist/search/index.js

@@ -0,0 +1,25 @@
+import { createVectorStore } from './store.js';
+import { Embedder } from './embedder.js';
+import { registerSearchTools } from './tools.js';
+import { SearchSyncService } 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);
+    registerSearchTools(server, client, store, embedder);
+    // 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);
+    syncService.sync().catch((err) => {
+        console.error('[mantisbt-search] sync error:', err instanceof Error ? err.message : String(err));
+    });
+}

package/dist/search/store.js

@@ -0,0 +1,138 @@
+import { readFile, writeFile, mkdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// VectraStore
+// ---------------------------------------------------------------------------
+export class VectraStore {
+    dir;
+    vectraDir;
+    lastSyncFile;
+    lastTotalFile;
+    items = new Map();
+    loaded = 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');
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        await mkdir(this.vectraDir, { recursive: true });
+        const indexFile = join(this.vectraDir, 'index.json');
+        try {
+            const raw = await readFile(indexFile, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.items = new Map(parsed.map(item => [item.id, item]));
+        }
+        catch {
+            // No index yet — start empty
+            this.items = new Map();
+        }
+        this.loaded = true;
+    }
+    async persist() {
+        const indexFile = join(this.vectraDir, 'index.json');
+        const data = JSON.stringify([...this.items.values()]);
+        await writeFile(indexFile, data, 'utf-8');
+    }
+    async add(item) {
+        await this.ensureLoaded();
+        this.items.set(item.id, item);
+        await this.persist();
+    }
+    async addBatch(items) {
+        await this.ensureLoaded();
+        for (const item of items) {
+            this.items.set(item.id, item);
+        }
+        await this.persist();
+    }
+    async search(vector, topN) {
+        await this.ensureLoaded();
+        const results = [];
+        for (const item of this.items.values()) {
+            const score = cosineSimilarity(vector, item.vector);
+            results.push({ id: item.id, score });
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, topN);
+    }
+    async delete(id) {
+        await this.ensureLoaded();
+        this.items.delete(id);
+        await this.persist();
+    }
+    async count() {
+        await this.ensureLoaded();
+        return this.items.size;
+    }
+    async clear() {
+        await this.ensureLoaded();
+        this.items.clear();
+        await this.persist();
+    }
+    async getLastSyncedAt() {
+        try {
+            const content = await readFile(this.lastSyncFile, 'utf-8');
+            return content.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async setLastSyncedAt(ts) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.lastSyncFile, ts, 'utf-8');
+    }
+    async resetLastSyncedAt() {
+        try {
+            await unlink(this.lastSyncFile);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    async getLastKnownTotal() {
+        try {
+            const content = await readFile(this.lastTotalFile, 'utf-8');
+            const parsed = parseInt(content.trim(), 10);
+            return isNaN(parsed) ? null : parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    async setLastKnownTotal(total) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.lastTotalFile, String(total), 'utf-8');
+    }
+}
+// ---------------------------------------------------------------------------
+// Cosine similarity helper
+// ---------------------------------------------------------------------------
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createVectorStore(backend, dir) {
+    if (backend === 'sqlite-vec') {
+        throw new Error('sqlite-vec backend requires manual installation: npm install sqlite-vec better-sqlite3');
+    }
+    return new VectraStore(dir);
+}

package/dist/search/sync.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// SearchSyncService
+// ---------------------------------------------------------------------------
+const PAGE_SIZE = 50;
+const EMBED_BATCH_SIZE = 10;
+export class SearchSyncService {
+    client;
+    store;
+    embedder;
+    constructor(client, store, embedder) {
+        this.client = client;
+        this.store = store;
+        this.embedder = embedder;
+    }
+    async sync(projectId) {
+        const lastSyncedAt = await this.store.getLastSyncedAt();
+        const { issues: allIssues, totalFromApi } = await this.fetchAllIssues(lastSyncedAt ?? undefined, projectId);
+        let indexed = 0;
+        let skipped = 0;
+        // Process in batches of EMBED_BATCH_SIZE
+        for (let i = 0; i < allIssues.length; i += EMBED_BATCH_SIZE) {
+            const batch = allIssues.slice(i, i + EMBED_BATCH_SIZE);
+            const toEmbed = [];
+            for (const issue of batch) {
+                if (!issue.summary) {
+                    skipped++;
+                    continue;
+                }
+                const text = `${issue.summary}\n${issue.description ?? ''}`.trim();
+                toEmbed.push({ issue, text });
+            }
+            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,
+                },
+            }));
+            await this.store.addBatch(batchItems);
+            indexed += batchItems.length;
+        }
+        await this.store.setLastSyncedAt(new Date().toISOString());
+        // 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);
+        await this.store.setLastKnownTotal(total);
+        return { indexed, skipped, total };
+    }
+    async fetchAllIssues(updatedAfter, projectId) {
+        const allIssues = [];
+        let totalFromApi = null;
+        let page = 1;
+        while (true) {
+            const params = {
+                page_size: PAGE_SIZE,
+                page,
+                sort: 'updated_at',
+                direction: 'DESC',
+                select: 'id,summary,description,updated_at',
+            };
+            if (projectId !== undefined) {
+                params.project_id = projectId;
+            }
+            if (updatedAfter) {
+                params.updated_after = updatedAfter;
+            }
+            const response = await this.client.get('issues', params);
+            const pageIssues = response.issues ?? [];
+            allIssues.push(...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:
+            // - total_count is provided and reached, or
+            // - page returned fewer items than requested (last page)
+            if (totalFromApi !== null) {
+                if (allIssues.length >= totalFromApi)
+                    break;
+            }
+            else if (pageIssues.length < PAGE_SIZE) {
+                break;
+            }
+            page++;
+        }
+        return { issues: allIssues, totalFromApi };
+    }
+}