@dpesch/mantisbt-mcp-server 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -11,6 +11,25 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.16.0] – 2026-11-02
+
+### Added
+
+- Search benchmark `npm run benchmark:search` (`scripts/benchmark-search.ts`): measures recall@10 of `search_issues` on an existing index for exact titles, first sentences, sentences from deep in long descriptions, rare identifiers and — from `BENCHMARK_PARAPHRASES` — hand-written paraphrases, ranked by vectors only and hybrid. Reads the index only; refuses one built with another embedding signature.
+
+### Changed
+
+- Semantic search: `search_issues` now combines the semantic ranking with a keyword ranking (BM25 over summary and description, summary counted twice) by Reciprocal Rank Fusion. Embeddings blur exact terms; a query for an identifier that occurs in at most three issues found its issue among the top 10 in 26 % of the cases, now in 100 % (7,739 issues). Literal queries gain as well — exact titles 97 % → 99.8 %, first sentences 83 % → 99 %, sentences from deep in a long description 58 % → 97 % — while paraphrased queries stay level (38 % → 37 %, 60 queries). `score` is still the semantic similarity, but results are now ordered by the combined ranking, so a keyword match can precede a higher `score`. The keyword index is built in memory on the first search (about 0.1 s and 7 MB for 7,739 issues) and adds about 2 ms per search.
+- Semantic search: a long description is now split into up to 8 chunks of the model's token limit, each embedded together with the summary, and an issue scores by its best chunk. Details deep in a long description become findable (measured without the keyword ranking above): a sentence from the middle of a long description found its issue among the top 10 in 58 % of the cases instead of 13 % (7,739 issues); exact titles 97 % (before 96 %), first sentences 83 % (before 84 %). The index grows to about 1.7 vectors per issue — `index.json` from 67 to 113 MB for 7,739 issues, held in memory by every server process with search enabled. Further chunks are stored in a new optional `chunks` field next to `vector`, so a server of an older version can still read the index.
+
+### Fixed
+
+- Semantic search: `search_issues` often missed issues with a longer description, even when queried with their exact title. The default model is trained on 128 tokens, but the text was embedded with up to 512, so the vectors of long issues collapsed into one another and short issues won almost every query. Text is now cut at the model's training length. On an index of 7,930 issues, an exact-title query found the issue among the top 10 in 95 % of the cases instead of 47 %, a query with the first sentence of the description in 84 % instead of 38 %. Text beyond that limit goes into further chunks (see Changed).
+- Semantic search: the index is rebuilt automatically when it was made with another embedding model or token limit, including the first start after this update. Before, changing `MANTIS_SEARCH_MODEL` kept the old vectors, which cannot be compared with the new ones, until a `rebuild_search_index` with `full: true`. The model and token limit are stored in `embedding_signature.txt` in the search directory. The rebuild runs in the background sync of the first server start and takes about 6 minutes for 7,700 issues with the default of 1 thread (see below); until it is done, `search_issues` finds only the issues indexed so far. It also drops entries of issues that were deleted or are no longer visible, which an incremental sync never removes.
+- Semantic search: `MANTIS_SEARCH_THREADS` had no effect since it was introduced in 1.5.1 — the embedding model always used every CPU core. The thread options were passed in snake_case (`intra_op_num_threads`), which onnxruntime silently ignores; it expects `intraOpNumThreads`. The documented default of 1 thread now applies, as intended against CPU saturation on WSL and multi-core machines. Embedding is about three times slower with 1 thread than with all cores; a full rebuild of 7,700 issues takes about 6 minutes instead of 2.5. With `MANTIS_SEARCH_THREADS=4` the rebuild took 160 s instead of 377 s with 1 thread; 4 is a good value on a machine with 4 or more cores.
+
+---
+
 ## [1.15.0] – 2026-10-31
 
 ### Deprecated

package/README.de.md

@@ -80,8 +80,8 @@ npm run build
 | `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) |
-| `MANTIS_SEARCH_THREADS` | – | `1` | Anzahl der ONNX-Intra-Op-Threads für das Embedding-Modell. Standard ist 1, um CPU-Sättigung auf Mehrkernsystemen und in WSL zu verhindern. Nur erhöhen, wenn die Indexierungsgeschwindigkeit kritisch ist und der Host ausschließlich für diese Last vorgesehen ist. |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding-Modell (wird beim ersten Start einmalig heruntergeladen, ~80 MB). Nach einem Wechsel baut der nächste Sync den Index von selbst neu auf. |
+| `MANTIS_SEARCH_THREADS` | – | `1` | Anzahl der ONNX-Intra-Op-Threads für das Embedding-Modell. Standard ist 1, um CPU-Sättigung auf Mehrkernsystemen und in WSL zu verhindern. Auf Rechnern mit 4 oder mehr Kernen ist `4` ein guter Wert: Ein vollständiger Neuaufbau von 7.700 Issues dauerte damit 160 s statt 377 s mit 1 Thread. Die Einstellung beschleunigt vor allem das Indexieren; eine Suchanfrage ist ein einzelner kurzer Text und profitiert kaum. Wirksam ab 1.16.0 – frühere Versionen haben die Einstellung ignoriert und immer alle Kerne genutzt. |
 | `MANTIS_UPLOAD_DIR` | – | – | Schränkt den `file_path` von `upload_file` auf dieses Verzeichnis ein (Pfad-Traversal via `../` wird blockiert). Im **stdio-Modus** ist `file_path` ohne diese Variable unbeschränkt. Im **HTTP-Modus** liest `file_path` aus dem Dateisystem des Servers und ist deshalb **deaktiviert, sofern diese Variable nicht gesetzt ist** – HTTP-Clients sollten stattdessen den Parameter `content` (Base64) verwenden. |
 | `MANTIS_TOOLSETS` | – | – (alle) | Kommagetrennte Liste der anzubietenden Tool-Gruppen: `issues`, `notes`, `links`, `files`, `projects`, `versions`, `meta`, `search` (Groß-/Kleinschreibung egal). Nicht gesetzt oder leer bedeutet alle Gruppen. Die Gruppe `search` erfordert zusätzlich `MANTIS_SEARCH_ENABLED=true`; ohne die Gruppe wird das Such-Modul gar nicht gestartet. Ein unbekannter Gruppenname stoppt den Server beim Start mit einer Meldung, die die gültigen Namen auflistet. Siehe [Angebotene Tools einschränken](#angebotene-tools-einschränken) und das [Cookbook](docs/cookbook.de.md#nur-bestimmte-tool-gruppen-anbieten). |
 | `MANTIS_DISABLE_DESTRUCTIVE` | – | `false` | Auf `true` setzen, um alle destruktiven Tools auszublenden – `delete_issue`, `delete_note`, `delete_version`, `remove_relationship`, `remove_monitor` – unabhängig von den aktiven Gruppen. Ausgeblendete Tools werden nicht aufgelistet und liefern »Tool … not found«, wenn sie aufgerufen werden. |
@@ -214,19 +214,19 @@ Veraltete Tools gehören immer zur gleichen Gruppe wie ihr Ersatz – eine Grupp
 
 ### 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:
+Die semantische Suche versteht die *Bedeutung* einer Anfrage, nicht nur ihre Stichwörter. 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). 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.
+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. Lange Beschreibungen werden in bis zu 8 Abschnitte geteilt, damit auch Details weiter unten gefunden werden; der Index enthält dadurch etwa 1,7 Vektoren pro Issue (rund 115 MB bei 7.700 Issues), die jeder Serverprozess mit aktivierter Suche im Speicher hält. Die Rangfolge berücksichtigt zusätzlich exakte Stichworttreffer, sodass eine Suche nach einem Bezeichner, Fehlercode oder einer Versionsnummer die Issues findet, die ihn enthalten.
 
 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; optionales `select` (kommagetrennte Feldnamen) reichert jedes Ergebnis mit den angeforderten Issue-Feldern an; optionales `highlight` (boolean, Standard `false`) fügt je Ergebnis ein `highlights`-Feld mit keyword-basierten Ausschnitten aus `summary` und `description` hinzu (Treffer werden in `**fett**` dargestellt) |
+| `search_issues` | Natürlichsprachige Suche über alle indizierten Issues – kombiniert semantische Ähnlichkeit mit Stichwortsuche (BM25), damit auch exakte Begriffe wie Bezeichner oder Fehlercodes gefunden werden; liefert Top-N-Ergebnisse mit der Cosine-Similarity als `score`, sortiert nach der kombinierten Rangfolge; optionales `select` (kommagetrennte Feldnamen) reichert jedes Ergebnis mit den angeforderten Issue-Feldern an; optionales `highlight` (boolean, Standard `false`) fügt je Ergebnis ein `highlights`-Feld mit keyword-basierten Ausschnitten aus `summary` und `description` hinzu (Treffer werden in `**fett**` dargestellt) |
 | `rebuild_search_index` | Suchindex aufbauen oder aktualisieren; `full: true` löscht und baut ihn vollständig neu |
 | `get_search_index_status` | **Veraltet:** stattdessen `get_metadata` (Feld `search_index`) verwenden – wird in 2.0.0 entfernt |
 
@@ -341,6 +341,7 @@ npm test             # Tests ausführen (vitest)
 npm run test:watch   # Tests im Watch-Modus
 npm run test:coverage # Coverage-Report
 npm run benchmark    # Token-Benchmark gegen eine Live-MantisBT-Instanz (siehe Token-Verbrauch oben)
+npm run benchmark:search # Such-Trefferquote auf einem bestehenden Index (MANTIS_SEARCH_DIR), Vektor vs. hybrid
 ```
 
 ## Lizenz

package/README.md

@@ -80,8 +80,8 @@ npm run build
 | `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) |
-| `MANTIS_SEARCH_THREADS` | – | `1` | Number of ONNX intra-op threads for the embedding model. Default is 1 to prevent CPU saturation on multi-core machines and WSL. Increase only if index rebuild speed matters and the host is dedicated to this workload. |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding model name (downloaded once on first use, ~80 MB). After a change the index is rebuilt automatically on the next sync. |
+| `MANTIS_SEARCH_THREADS` | – | `1` | Number of ONNX intra-op threads for the embedding model. Default is 1 to prevent CPU saturation on multi-core machines and WSL. On a machine with 4 or more cores, `4` is a good value: a full rebuild of 7,700 issues took 160 s instead of 377 s with 1 thread. The setting mainly speeds up indexing; a search query is a single short text and hardly benefits. Effective since 1.16.0 — earlier versions ignored this setting and always used every core. |
 | `MANTIS_UPLOAD_DIR` | – | – | Restrict `upload_file`'s `file_path` to files within this directory (path traversal via `../` is blocked). In **stdio mode** `file_path` is unrestricted unless this is set. In **HTTP mode** `file_path` reads from the server's filesystem, so it is **disabled unless this variable is set** — HTTP clients should upload via the `content` (Base64) parameter instead. |
 | `MANTIS_TOOLSETS` | – | – (all) | Comma-separated list of tool groups to offer: `issues`, `notes`, `links`, `files`, `projects`, `versions`, `meta`, `search` (case-insensitive). Unset or empty means all groups. The `search` group additionally requires `MANTIS_SEARCH_ENABLED=true`; without the group the search module is not started at all. An unknown group name stops the server at startup with a message listing the valid names. See [Limit the offered tools](#limit-the-offered-tools) and the [cookbook](docs/cookbook.md#offer-only-some-tool-groups). |
 | `MANTIS_DISABLE_DESTRUCTIVE` | – | `false` | Set to `true` to hide every destructive tool — `delete_issue`, `delete_note`, `delete_version`, `remove_relationship`, `remove_monitor` — regardless of the active groups. Hidden tools are not listed and return "Tool … not found" when called. |
@@ -214,19 +214,19 @@ Deprecated tools always belong to the same group as their replacement — disabl
 
 ### 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:
+Semantic search understands the *meaning* behind a query, not just its keywords. 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). 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).
+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). Long descriptions are split into up to 8 chunks so that details further down are found as well; the index then holds about 1.7 vectors per issue (around 115 MB for 7,700 issues), which every server process with search enabled keeps in memory. The ranking also takes exact keyword matches into account, so a query for an identifier, error code or version number finds the issues that contain it.
 
 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; optional `select` (comma-separated field names) enriches each result with the requested issue fields; optional `highlight` (boolean, default `false`) adds a `highlights` field per result with keyword-matched excerpts from `summary` and `description` (matched terms shown in `**bold**`) |
+| `search_issues` | Natural language search over all indexed issues — combines semantic similarity with keyword matching (BM25), so exact terms such as identifiers or error codes are found as well; returns top-N results with the cosine similarity as `score`, ordered by the combined ranking; optional `select` (comma-separated field names) enriches each result with the requested issue fields; optional `highlight` (boolean, default `false`) adds a `highlights` field per result with keyword-matched excerpts from `summary` and `description` (matched terms shown in `**bold**`) |
 | `rebuild_search_index` | Build or update the search index; `full: true` clears and rebuilds from scratch |
 | `get_search_index_status` | **Deprecated:** use `get_metadata` (field `search_index`) instead — will be removed in 2.0.0 |
 
@@ -341,6 +341,7 @@ npm test             # Run tests (vitest)
 npm run test:watch   # Run tests in watch mode
 npm run test:coverage # Coverage report
 npm run benchmark    # Token benchmark against a live MantisBT (see Token usage above)
+npm run benchmark:search # Search recall on an existing index (MANTIS_SEARCH_DIR), vectors vs. hybrid
 ```
 
 ## License

package/dist/config.js

@@ -40,6 +40,7 @@ async function readDotEnvLocal() {
 // ---------------------------------------------------------------------------
 // Non-credential config (safe to read at startup without credentials)
 // ---------------------------------------------------------------------------
+export const DEFAULT_SEARCH_MODEL = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
 function readNonCredentialConfig() {
     const defaultCacheDir = join(homedir(), '.cache', 'mantisbt-mcp');
     const cacheDir = process.env.MANTIS_CACHE_DIR ?? defaultCacheDir;
@@ -53,8 +54,7 @@ function readNonCredentialConfig() {
     }
     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';
+    const searchModelName = process.env.MANTIS_SEARCH_MODEL ?? DEFAULT_SEARCH_MODEL;
     const searchNumThreads = Math.max(1, parseInt(process.env.MANTIS_SEARCH_THREADS ?? '', 10) || 1);
     return {
         cacheDir,

package/dist/search/embedder.js

@@ -6,18 +6,49 @@
 // @huggingface/transformers is an optional dependency. The import is
 // guarded with a try/catch so the server starts without it.
 // ---------------------------------------------------------------------------
+import { DEFAULT_SEARCH_MODEL } from '../config.js';
+// Sequence length a model was trained on (max_seq_length in its
+// sentence_bert_config.json). transformers.js does not read that file and
+// truncates at the tokenizer's model_max_length instead — 512 for the default
+// model, which is trained on 128. Longer input is out of distribution: the
+// vectors of long issues collapse into one another (#8539). Models not listed
+// keep the tokenizer's limit.
+const MODEL_MAX_TOKENS = {
+    [DEFAULT_SEARCH_MODEL]: 128,
+};
+// Vectors per issue for models with a known token limit: the first covers
+// summary and the start of the description, each further one the next part of
+// the description, prefixed with the summary (#8541). 8 chunks reach about
+// 1,000 description tokens and grow the index by a factor of about 1.7.
+const MAX_CHUNKS = 8;
+// Special tokens the tokenizer adds ([CLS], [SEP]) plus the newline.
+const CHUNK_OVERHEAD_TOKENS = 3;
+const MIN_CHUNK_TOKENS = 32;
+// Characters per token kept before tokenizing: tokens average about 4
+// characters, so this keeps well beyond MAX_CHUNKS windows without tokenizing
+// descriptions of 17,000+ tokens in full.
+const MAX_CHARS_PER_TOKEN = 16;
+// Texts per model call; caps the activation memory of a batch.
+const MODEL_BATCH_SIZE = 32;
 // 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;
+    /** Identifies how vectors are made; a different signature means the index must be rebuilt. */
+    signature;
     pipe = null;
+    maxTokens;
     running = 0;
     idleTimer = null;
     constructor(modelName, numThreads = 1) {
         this.modelName = modelName;
         this.numThreads = numThreads;
+        this.maxTokens = MODEL_MAX_TOKENS[modelName];
+        this.signature = this.maxTokens === undefined
+            ? `${modelName}|max_tokens=default`
+            : `${modelName}|max_tokens=${this.maxTokens}|chunks=${MAX_CHUNKS}`;
     }
     async withPipeline(fn) {
         this.running++;
@@ -54,56 +85,74 @@ export class Embedder {
         process.stderr.write(`[mantisbt-search] Loading embedding model ${this.modelName} (threads: ${this.numThreads})...\n`);
         let transformers;
         try {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-            transformers = (await import('@huggingface/transformers'));
+            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}`);
         }
+        // onnxruntime takes camelCase keys and silently ignores unknown ones
+        // (snake_case had no effect until #8540).
         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
+                intraOpNumThreads: this.numThreads,
+                interOpNumThreads: 1, // Transformer graphs are sequential — no benefit from inter-op parallelism
             },
         });
     }
-    async embed(text) {
-        return this.withPipeline(async (extractor) => {
-            const output = await extractor(text, { pooling: 'mean', normalize: true });
-            return extractVector(output);
+    /** One or more vectors per document; see MAX_CHUNKS. */
+    async embedDocuments(docs) {
+        if (docs.length === 0)
+            return [];
+        return this.withPipeline(async ({ tokenizer }) => {
+            const texts = docs.map(doc => this.chunkTexts(doc, tokenizer));
+            const vectors = await this.embedBatch(texts.flat());
+            let start = 0;
+            return texts.map(chunks => {
+                const own = vectors.slice(start, start + chunks.length);
+                start += chunks.length;
+                return own;
+            });
         });
     }
+    chunkTexts({ summary, description: fullDescription }, tokenizer) {
+        const description = this.maxTokens === undefined
+            ? fullDescription
+            : fullDescription?.slice(0, MAX_CHUNKS * this.maxTokens * MAX_CHARS_PER_TOKEN);
+        const texts = [`${summary}\n${description ?? ''}`.trim()];
+        if (this.maxTokens === undefined || !description)
+            return texts;
+        const encode = (text) => tokenizer.encode(text, { add_special_tokens: false });
+        const window = Math.max(MIN_CHUNK_TOKENS, this.maxTokens - CHUNK_OVERHEAD_TOKENS - encode(summary).length);
+        const tokens = encode(description);
+        // The first text already covers about the first window of the description.
+        for (let start = window; start < tokens.length && texts.length < MAX_CHUNKS; start += window) {
+            const part = tokenizer.decode(tokens.slice(start, start + window), { skip_special_tokens: true });
+            texts.push(`${summary}\n${part}`);
+        }
+        return texts;
+    }
+    async embed(text) {
+        return (await this.embedBatch([text]))[0];
+    }
+    // Same steps as the feature-extraction pipeline with pooling 'mean' and
+    // normalize — but the pipeline offers no way to pass max_length.
     async embedBatch(texts) {
         if (texts.length === 0)
             return [];
-        return this.withPipeline(async (extractor) => {
-            const output = await extractor(texts, { pooling: 'mean', normalize: true });
-            if (Array.isArray(output)) {
-                return output.map(extractVector);
+        return this.withPipeline(async ({ tokenizer, model }) => {
+            // Already loaded by load(), so this resolves from the module cache.
+            const { mean_pooling } = await import('@huggingface/transformers');
+            const vectors = [];
+            for (let i = 0; i < texts.length; i += MODEL_BATCH_SIZE) {
+                const inputs = tokenizer(texts.slice(i, i + MODEL_BATCH_SIZE), { padding: true, truncation: true, max_length: this.maxTokens });
+                const outputs = (await model(inputs));
+                const tokenVectors = outputs['last_hidden_state'] ?? outputs['logits'] ?? outputs['token_embeddings'];
+                if (!tokenVectors)
+                    throw new Error('Embedding model returned no token vectors');
+                vectors.push(...mean_pooling(tokenVectors, inputs.attention_mask).normalize(2, -1).tolist());
             }
-            // Some versions return a single tensor for batch input
-            return extractBatchVectors(output, texts.length);
+            return vectors;
         });
     }
 }
-// ---------------------------------------------------------------------------
-// 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/lexical.js

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// Keyword index (BM25) for hybrid search (#8542)
+//
+// Embeddings capture meaning but blur exact terms: identifiers, error codes,
+// version numbers. search_issues therefore fuses the vector ranking with this
+// keyword ranking. Built in memory from the summaries and descriptions the
+// vector index already stores — no extra API calls.
+// ---------------------------------------------------------------------------
+// Standard BM25 parameters.
+const K1 = 1.2;
+const B = 0.75;
+// A summary term counts twice: titles name what an issue is about.
+const SUMMARY_WEIGHT = 2;
+/** Lowercased words of letters, digits and underscores, at least 2 characters. */
+export function tokenize(text) {
+    return (text.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? []).filter(word => word.length >= 2);
+}
+export class LexicalIndex {
+    // Postings in compressed sparse rows: the documents of term t are
+    // docs[offsets[t] .. offsets[t + 1]], with their term frequencies in tfs.
+    // Typed arrays keep 340,000 postings (7,700 issues) at about 7 MB instead of
+    // 30 MB as one object per posting — in every server process.
+    termIds = new Map();
+    offsets;
+    docs;
+    tfs;
+    ids;
+    lengths;
+    avgLength;
+    constructor(documents) {
+        this.ids = Uint32Array.from(documents, doc => doc.id);
+        this.lengths = new Uint32Array(documents.length);
+        const counts = documents.map((doc, index) => {
+            const terms = new Map();
+            const add = (text, weight) => {
+                for (const term of tokenize(text ?? '')) {
+                    let id = this.termIds.get(term);
+                    if (id === undefined)
+                        this.termIds.set(term, (id = this.termIds.size));
+                    terms.set(id, (terms.get(id) ?? 0) + weight);
+                }
+            };
+            add(doc.summary, SUMMARY_WEIGHT);
+            add(doc.description, 1);
+            for (const tf of terms.values())
+                this.lengths[index] += tf;
+            return terms;
+        });
+        const df = new Uint32Array(this.termIds.size);
+        for (const terms of counts)
+            for (const term of terms.keys())
+                df[term]++;
+        this.offsets = new Uint32Array(df.length + 1);
+        for (let t = 0; t < df.length; t++)
+            this.offsets[t + 1] = this.offsets[t] + df[t];
+        this.docs = new Uint32Array(this.offsets[df.length]);
+        this.tfs = new Uint16Array(this.docs.length);
+        const cursor = this.offsets.slice(0, df.length);
+        counts.forEach((terms, doc) => {
+            for (const [term, tf] of terms) {
+                const at = cursor[term]++;
+                this.docs[at] = doc;
+                this.tfs[at] = Math.min(tf, 0xffff);
+            }
+        });
+        this.avgLength = this.lengths.reduce((sum, length) => sum + length, 0) / (documents.length || 1);
+    }
+    /** BM25 score per document id; documents without a query term are absent. */
+    scores(query) {
+        const byDoc = new Map();
+        const total = this.ids.length;
+        for (const word of new Set(tokenize(query))) {
+            const term = this.termIds.get(word);
+            if (term === undefined)
+                continue;
+            const start = this.offsets[term];
+            const end = this.offsets[term + 1];
+            const idf = Math.log(1 + (total - (end - start) + 0.5) / (end - start + 0.5));
+            for (let at = start; at < end; at++) {
+                const doc = this.docs[at];
+                const tf = this.tfs[at];
+                const norm = K1 * (1 - B + B * this.lengths[doc] / this.avgLength);
+                byDoc.set(doc, (byDoc.get(doc) ?? 0) + idf * tf * (K1 + 1) / (tf + norm));
+            }
+        }
+        return new Map([...byDoc].map(([doc, score]) => [this.ids[doc], score]));
+    }
+}

package/dist/search/store.js

@@ -1,13 +1,20 @@
 import { readFile, writeFile, rename, mkdir, unlink, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { LexicalIndex } from './lexical.js';
 // ---------------------------------------------------------------------------
 // VectraStore
 // ---------------------------------------------------------------------------
+// Reciprocal Rank Fusion constant. Measured on 7,739 issues (#8542): 10 keeps
+// literal queries (titles, sentences, identifiers) at 97–100 % recall@10 and
+// paraphrased ones level with vector-only search; the common 60 lost up to
+// 8 points on literal queries.
+const RRF_K = 10;
 export class VectraStore {
     dir;
     vectraDir;
     lastSyncFile;
     lastTotalFile;
+    signatureFile;
     items = new Map();
     loaded = false;
     // Version of index.json the in-memory items correspond to (null: no file).
@@ -16,11 +23,15 @@ export class VectraStore {
     loadedVersion = null;
     // Unflushed addBatch() changes — never discard them by reloading.
     dirty = false;
+    // Keyword index over the current items, built on the first search with
+    // query text and dropped whenever the items change.
+    lexical = null;
     constructor(dir) {
         this.dir = dir;
         this.vectraDir = join(dir, 'vectra');
         this.lastSyncFile = join(dir, 'last_sync.txt');
         this.lastTotalFile = join(dir, 'last_total.txt');
+        this.signatureFile = join(dir, 'embedding_signature.txt');
     }
     get indexFile() {
         return join(this.vectraDir, 'index.json');
@@ -50,6 +61,7 @@ export class VectraStore {
             // No index yet — start empty
             this.items = new Map();
         }
+        this.lexical = null;
         this.loaded = true;
         this.loadedVersion = version;
     }
@@ -64,6 +76,7 @@ export class VectraStore {
     async add(item) {
         await this.ensureLoaded();
         this.items.set(item.id, item);
+        this.lexical = null;
         await this.persist();
     }
     async addBatch(items) {
@@ -71,21 +84,35 @@ export class VectraStore {
         for (const item of items) {
             this.items.set(item.id, item);
         }
+        this.lexical = null;
         this.dirty = items.length > 0 || this.dirty;
         // No persist() here — call flush() once after all batches are processed.
     }
     async flush() {
         await this.persist();
     }
-    async search(vector, topN) {
+    async search(vector, topN, queryText) {
         await this.ensureLoaded();
         const results = [];
         for (const item of this.items.values()) {
-            const score = cosineSimilarity(vector, item.vector);
+            let score = cosineSimilarity(vector, item.vector);
+            if (item.chunks)
+                for (const chunk of item.chunks)
+                    score = Math.max(score, cosineSimilarity(vector, chunk));
             results.push({ id: item.id, score });
         }
         results.sort((a, b) => b.score - a.score);
-        return results.slice(0, topN);
+        if (!queryText)
+            return results.slice(0, topN);
+        // Reciprocal Rank Fusion of the vector ranking and the keyword ranking.
+        this.lexical ??= new LexicalIndex([...this.items.values()].map(item => ({ id: item.id, ...item.metadata })));
+        const keywordRank = new Map([...this.lexical.scores(queryText)].sort((a, b) => b[1] - a[1]).map(([id], rank) => [id, rank]));
+        const fused = results.map((result, vectorRank) => {
+            const rank = keywordRank.get(result.id);
+            return { result, fused: 1 / (RRF_K + vectorRank) + (rank === undefined ? 0 : 1 / (RRF_K + rank)) };
+        });
+        fused.sort((a, b) => b.fused - a.fused);
+        return fused.slice(0, topN).map(f => f.result);
     }
     async getItem(id) {
         await this.ensureLoaded();
@@ -94,6 +121,7 @@ export class VectraStore {
     async delete(id) {
         await this.ensureLoaded();
         this.items.delete(id);
+        this.lexical = null;
         await this.persist();
     }
     async count() {
@@ -103,6 +131,7 @@ export class VectraStore {
     async clear() {
         await this.ensureLoaded();
         this.items.clear();
+        this.lexical = null;
         await this.persist();
     }
     async getLastSyncedAt() {
@@ -141,6 +170,18 @@ export class VectraStore {
         await mkdir(this.dir, { recursive: true });
         await writeFile(this.lastTotalFile, String(total), 'utf-8');
     }
+    async getEmbeddingSignature() {
+        try {
+            return (await readFile(this.signatureFile, 'utf-8')).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async setEmbeddingSignature(signature) {
+        await mkdir(this.dir, { recursive: true });
+        await writeFile(this.signatureFile, signature, 'utf-8');
+    }
 }
 // ---------------------------------------------------------------------------
 // Cosine similarity helper

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

@@ -46,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
@@ -92,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) {

package/docs/cookbook.de.md

@@ -1584,6 +1584,8 @@ Deabonniert einen Benutzer von Benachrichtigungen zu einem Issue.
 
 Baut den vollständigen Vektor-Suchindex von Grund auf neu auf. Einmalig nach der Aktivierung der semantischen Suche ausführen.
 
+Der Server baut den Index außerdem von selbst neu auf, wenn er mit einem anderen Embedding-Modell oder auf andere Weise erstellt wurde – nach einer Änderung von `MANTIS_SEARCH_MODEL` oder nach einem Update, das die Art der Einbettung ändert. Ein vollständiger Neuaufbau von 7.700 Issues dauerte mit dem Standard von 1 Thread etwa 6 Minuten, mit `MANTIS_SEARCH_THREADS=4` keine 3 Minuten.
+
 **Tool:** `rebuild_search_index`
 
 **Parameter:**
@@ -1614,7 +1616,7 @@ Baut den vollständigen Vektor-Suchindex von Grund auf neu auf. Einmalig nach de
 
 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.
+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. Wurde der Index mit einem anderen Embedding-Modell oder einer anderen Version erstellt, baut der Sync ihn für alle Projekte neu auf, auch mit `project_id`.
 
 **Tool:** `rebuild_search_index`
 
@@ -1682,7 +1684,7 @@ Gibt die Anzahl der indizierten Issues, die Gesamtanzahl der Issues und den Zeit
 
 ### Nach Bedeutung suchen
 
-Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich sind. Gibt Issue-IDs und Relevanz-Scores zurück.
+Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich sind, kombiniert mit einer Stichwortsuche, damit auch exakte Begriffe (Bezeichner, Fehlercodes, Versionsnummern) gefunden werden. Gibt Issue-IDs und Relevanz-Scores zurück. `score` ist die semantische Ähnlichkeit; die Reihenfolge folgt der kombinierten Rangfolge, ein Ergebnis mit exaktem Stichworttreffer kann also vor einem mit höherem `score` stehen.
 
 **Tool:** `search_issues`
 

package/docs/cookbook.md

@@ -1584,6 +1584,8 @@ Unsubscribes a user from notifications for an issue.
 
 Builds the full vector search index from scratch. Run this once after enabling semantic search.
 
+The server also rebuilds the index by itself when it was made with another embedding model or in another way — after `MANTIS_SEARCH_MODEL` was changed, or after an update that changes how issues are embedded. A full rebuild of 7,700 issues took about 6 minutes with the default of 1 thread and less than 3 minutes with `MANTIS_SEARCH_THREADS=4`.
+
 **Tool:** `rebuild_search_index`
 
 **Parameters:**
@@ -1614,7 +1616,7 @@ Builds the full vector search index from scratch. Run this once after enabling s
 
 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.
+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. If the index was made with another embedding model or version, the sync rebuilds it for all projects, even with `project_id`.
 
 **Tool:** `rebuild_search_index`
 
@@ -1682,7 +1684,7 @@ Returns the number of indexed issues, total issue count, and the timestamp of th
 
 ### Search by meaning
 
-Finds issues semantically similar to a natural language query. Returns issue IDs and relevance scores.
+Finds issues semantically similar to a natural language query, combined with keyword matching so that exact terms (identifiers, error codes, version numbers) are found as well. Returns issue IDs and relevance scores. `score` is the semantic similarity; the order follows the combined ranking, so a result with an exact keyword match can come before one with a higher `score`.
 
 **Tool:** `search_issues`
 

package/docs/examples.de.md

@@ -199,6 +199,16 @@ Die semantische Suche versteht die *Bedeutung* deiner Frage – nicht nur einzel
 
 ---
 
+### Exakte Begriffe
+
+Die Suche berücksichtigt auch exakte Stichwörter, daher funktionieren Bezeichner, Fehlercodes und Versionsnummern ebenfalls als Suchanfrage.
+
+> »Welche Issues erwähnen `MANTIS_SEARCH_DIR`?«
+
+> »Finde Issues zum Fehler `ERR_CERT_DATE_INVALID`.«
+
+---
+
 ### Keyword-Highlights
 
 > »Suche nach Login-Fehlern und zeige mir, welche Stelle im Ticket relevant ist.«

package/docs/examples.md

@@ -199,6 +199,16 @@ Semantic search understands the *meaning* of your question — not just keywords
 
 ---
 
+### Exact terms
+
+The search also matches exact keywords, so identifiers, error codes and version numbers work as queries too.
+
+> "Which issues mention `MANTIS_SEARCH_DIR`?"
+
+> "Find issues about the error `ERR_CERT_DATE_INVALID`."
+
+---
+
 ### Keyword highlights
 
 > "Search for login errors and show me which part of each ticket is relevant."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
@@ -42,6 +42,7 @@
     "test:coverage": "vitest run --coverage",
     "test:record": "tsx scripts/record-fixtures.ts",
     "benchmark": "tsx scripts/benchmark-tokens.ts",
+    "benchmark:search": "tsx scripts/benchmark-search.ts",
     "init": "node scripts/init.mjs"
   },
   "dependencies": {

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.15.0",
+  "version": "1.16.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.15.0",
+      "version": "1.16.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"