@dpesch/mantisbt-mcp-server 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -11,6 +11,18 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.17.0] – 2026-11-03
+
+### Added
+
+- Search benchmark: an exact-first measure for identifier queries (do all issues that contain the identifier lead the top 10?), a new `compound` query type for identifiers such as `CVE-2026-1234`, and fixed cases from `BENCHMARK_EXACT` that print their ranking.
+
+### Changed
+
+- Semantic search: `search_issues` lists every issue that contains an identifier from the query as a whole — an order number, a CVE, a version, a code name such as `MANTIS_SEARCH_DIR` or `getEmbeddingSignature` — before all issues that do not. The combined ranking found such issues, but put issues in between that were only close by meaning, often short ones (#8545). A query for `CVE-2026-1234` no longer counts an issue with another CVE of 2026 as a near match, and `1.15` does not match `1.15.2`. Identifiers are recognised by their form (underscore, inner capital, letters with digits, five or more digits, or words joined by `-` `.` `:` `/` with a digit), so plain words and short numbers such as "Android 15" keep the combined ranking; an identifier found in more than 20 issues does as well. Measured on 7,742 issues: for a rare identifier, all issues containing it now lead the top 10 in 97 % of the queries instead of 72 %; for a compound identifier such as `7.0.0-1014-azure` in 98 % instead of 11 %, and such a query finds its issue among the top 10 in 98 % instead of 64 %. Titles, sentences and paraphrases stay level or gain slightly. No index rebuild is needed.
+
+---
+
 ## [1.16.0] – 2026-11-02
 
 ### Added

package/README.de.md

@@ -220,13 +220,13 @@ Die semantische Suche versteht die *Bedeutung* einer Anfrage, nicht nur ihre Sti
 - *„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. 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.
+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 – und alle Issues, die eine solche Kennung vollständig enthalten, vor allen anderen auflistet, sofern die Kennung nicht in mehr als 20 Issues vorkommt.
 
 Aktivierung mit `MANTIS_SEARCH_ENABLED=true`.
 
 | Tool | Beschreibung |
 |---|---|
-| `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) |
+| `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; Issues, die eine Kennung aus der Anfrage enthalten (Auftragsnummer, CVE, Version, Code-Bezeichner), stehen vorn; 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,9 +341,11 @@ 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
+npm run benchmark:search # Such-Trefferquote und Exakt-Treffer-Reihenfolge auf einem bestehenden Index (MANTIS_SEARCH_DIR), Vektor vs. hybrid
 ```
 
+`benchmark:search` liest optional handgeschriebene Umschreibungen (`BENCHMARK_PARAPHRASES`) und feste Fälle mit erwarteter Rangfolge (`BENCHMARK_EXACT`); die Dateiformate stehen am Anfang von `scripts/benchmark-search.ts`.
+
 ## Lizenz
 
 MIT – siehe [LICENSE](LICENSE)

package/README.md

@@ -220,13 +220,13 @@ Semantic search understands the *meaning* behind a query, not just its keywords.
 - *"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). 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.
+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 — and lists all issues containing such an identifier as a whole before any others, unless it occurs in more than 20 issues.
 
 Activate with `MANTIS_SEARCH_ENABLED=true`.
 
 | Tool | Description |
 |---|---|
-| `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**`) |
+| `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; issues containing an identifier from the query (order number, CVE, version, code name) come first; 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,9 +341,11 @@ 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
+npm run benchmark:search # Search recall and exact-first order on an existing index (MANTIS_SEARCH_DIR), vectors vs. hybrid
 ```
 
+`benchmark:search` optionally reads hand-written paraphrases (`BENCHMARK_PARAPHRASES`) and fixed cases with an expected ranking (`BENCHMARK_EXACT`); the file formats are described at the top of `scripts/benchmark-search.ts`.
+
 ## License
 
 MIT – see [LICENSE](LICENSE)

package/dist/search/highlight.js

@@ -4,7 +4,7 @@
  * Note: highlights are keyword-based (lexical), not semantic.
  * A result may have no highlighted terms even if it is semantically relevant.
  */
-function escapeRegex(term) {
+export function escapeRegex(term) {
     return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function combinedPattern(terms, flags) {

package/dist/search/lexical.js

@@ -6,6 +6,7 @@
 // keyword ranking. Built in memory from the summaries and descriptions the
 // vector index already stores — no extra API calls.
 // ---------------------------------------------------------------------------
+import { escapeRegex } from './highlight.js';
 // Standard BM25 parameters.
 const K1 = 1.2;
 const B = 0.75;
@@ -15,7 +16,48 @@ const SUMMARY_WEIGHT = 2;
 export function tokenize(text) {
     return (text.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? []).filter(word => word.length >= 2);
 }
+// An identifier (#8545) found in more issues than this is no longer specific
+// enough to put all of them first; the fused ranking decides instead. Keeps
+// common tokens such as UTF-8 from taking over a search. The rare identifiers
+// of the search benchmark occur in at most 8 issues, well below the cap.
+const MAX_EXACT_MATCHES = 20;
+// Words, or words joined by - . : / (CVE-2026-1234, 7.0.0-1014-azure).
+const COMPOUND = /[\p{L}\p{N}_]+(?:[-.:/][\p{L}\p{N}_]+)*/gu;
+function looksLikeIdentifier(word) {
+    return word.includes('_') // MANTIS_SEARCH_DIR, _resizeTimer
+        || /\p{Ll}\p{Lu}/u.test(word) // ScrollViewHelper
+        || (word.length >= 4 && /\p{L}/u.test(word) && /\p{N}/u.test(word)) // host01
+        || /^\p{N}{5,}$/u.test(word); // 202699999
+}
+/**
+ * Identifiers in a search query: order numbers, CVEs, versions, code names.
+ * Plain words, short numbers ("Android 15") and hyphenated words without
+ * digits ("Play-Store-Hinweis") are none.
+ */
+export function identifiers(query) {
+    const found = new Map();
+    for (const match of query.match(COMPOUND) ?? []) {
+        // A compound with a digit is one identifier; otherwise each word counts alone.
+        const candidates = /[-.:/]/.test(match) && /\p{N}/u.test(match)
+            ? [match]
+            : match.split(/[-.:/]/).filter(looksLikeIdentifier);
+        for (const candidate of candidates) {
+            if (!found.has(candidate.toLowerCase()))
+                found.set(candidate.toLowerCase(), candidate);
+        }
+    }
+    return [...found.values()];
+}
+/**
+ * Matches the identifier as a whole: not inside a longer word, and not as the
+ * start or end of a longer number or version (1.15 is not in 1.15.2), while a
+ * word may continue with a hyphen (ScrollViewHelper in ScrollViewHelper-Bridge).
+ */
+export function wholeIdentifier(identifier) {
+    return new RegExp(`(?<![\\p{L}\\p{N}_])(?<!\\p{N}[-.:/])${escapeRegex(identifier)}(?![\\p{L}\\p{N}_])(?![-.:/]\\p{N})`, 'iu');
+}
 export class LexicalIndex {
+    documents;
     // 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
@@ -28,6 +70,7 @@ export class LexicalIndex {
     lengths;
     avgLength;
     constructor(documents) {
+        this.documents = documents;
         this.ids = Uint32Array.from(documents, doc => doc.id);
         this.lengths = new Uint32Array(documents.length);
         const counts = documents.map((doc, index) => {
@@ -85,4 +128,33 @@ export class LexicalIndex {
         }
         return new Map([...byDoc].map(([doc, score]) => [this.ids[doc], score]));
     }
+    /**
+     * Per document id, how many identifiers of the query it contains as a whole
+     * (#8545); documents without one are absent. Candidates come from the
+     * postings of the identifier's rarest word, the text check decides.
+     */
+    exactMatches(query) {
+        const counts = new Map();
+        const frequency = (term) => this.offsets[term + 1] - this.offsets[term];
+        for (const identifier of identifiers(query)) {
+            const terms = tokenize(identifier).map(word => this.termIds.get(word));
+            if (terms.length === 0 || terms.some(term => term === undefined))
+                continue;
+            const rarest = terms.reduce((a, b) => (frequency(a) <= frequency(b) ? a : b));
+            const pattern = wholeIdentifier(identifier);
+            const matches = [];
+            for (let at = this.offsets[rarest]; at < this.offsets[rarest + 1]; at++) {
+                const doc = this.documents[this.docs[at]];
+                if (pattern.test(doc.summary) || pattern.test(doc.description ?? ''))
+                    matches.push(doc.id);
+                if (matches.length > MAX_EXACT_MATCHES)
+                    break;
+            }
+            if (matches.length > MAX_EXACT_MATCHES)
+                continue;
+            for (const id of matches)
+                counts.set(id, (counts.get(id) ?? 0) + 1);
+        }
+        return counts;
+    }
 }

package/dist/search/store.js

@@ -107,11 +107,19 @@ export class VectraStore {
         // 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]));
+        // Issues containing an identifier of the query as a whole come first
+        // (#8545): a search for an order number or a CVE lists all its issues
+        // before any that merely resemble the query.
+        const exact = this.lexical.exactMatches(queryText);
         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)) };
+            return {
+                result,
+                exact: exact.get(result.id) ?? 0,
+                fused: 1 / (RRF_K + vectorRank) + (rank === undefined ? 0 : 1 / (RRF_K + rank)),
+            };
         });
-        fused.sort((a, b) => b.fused - a.fused);
+        fused.sort((a, b) => b.exact - a.exact || b.fused - a.fused);
         return fused.slice(0, topN).map(f => f.result);
     }
     async getItem(id) {

package/dist/search/tools.js

@@ -49,6 +49,8 @@ export function registerSearchTools(server, client, store, embedder, lockDir) {
             '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. ' +
+            'Issues that contain an identifier from the query as a whole (order number, CVE, version, ' +
+            'code name such as MANTIS_SEARCH_DIR) are listed before all others, unless the identifier is common. ' +
             'The search index must be populated first via rebuild_search_index.',
         inputSchema: z.object({
             query: z.string().describe('Natural language search query'),

package/docs/cookbook.de.md

@@ -1684,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, 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.
+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. Issues, die eine Kennung aus der Anfrage vollständig enthalten – eine Auftragsnummer, eine CVE, eine Version, einen Code-Bezeichner wie `MANTIS_SEARCH_DIR` –, stehen vor allen anderen, es sei denn, die Kennung kommt in mehr als 20 Issues vor.
 
 **Tool:** `search_issues`
 
@@ -1712,7 +1712,38 @@ Findet Issues, die einem natürlichsprachigen Suchbegriff semantisch ähnlich si
 ]
 ```
 
-> **Hinweis:** Die semantische Suche gibt die top-N ähnlichsten Issues zurück – vollständige Treffergarantie besteht nicht. Sie eignet sich nicht für Abfragen wie »alle Issues zu Thema X auflisten«.
+> **Hinweis:** Die semantische Suche gibt die top-N ähnlichsten Issues zurück – vollständige Treffergarantie besteht nicht. Sie eignet sich nicht für Abfragen wie »alle Issues zu Thema X auflisten«. Ausnahme ist die Suche nach einer seltenen Kennung: Die Issues, die sie enthalten, stehen vorn (siehe unten), mit ausreichend großem `top_n` werden also alle aufgelistet.
+
+---
+
+### Nach einer Kennung suchen
+
+Eine Suche nach einer Auftragsnummer, einer CVE, einer Version oder einem Code-Bezeichner listet alle Issues, die sie vollständig enthalten, vor allen anderen Ergebnissen. Kennungen werden an ihrer Form erkannt: ein Unterstrich, ein Großbuchstabe mitten im Wort, Buchstaben mit Ziffern, fünf oder mehr Ziffern oder mit `-` `.` `:` `/` verbundene Teile mit einer Ziffer. `1.15` trifft nicht `1.15.2`, und `CVE-2026-1234` trifft nicht `CVE-2026-12345`. Gewöhnliche Wörter und kurze Zahlen behalten die kombinierte Rangfolge, ebenso eine Kennung, die in mehr als 20 Issues vorkommt.
+
+**Tool:** `search_issues`
+
+**Request:**
+
+```json
+{
+  "query": "CVE-2026-1234",
+  "top_n": 5
+}
+```
+
+**Response:**
+
+```json
+[
+  { "id": 2210, "score": 0.58, "view_url": "https://mantis.example.com/view.php?id=2210" },
+  { "id": 2211, "score": 0.47, "view_url": "https://mantis.example.com/view.php?id=2211" },
+  { "id": 2084, "score": 0.65, "view_url": "https://mantis.example.com/view.php?id=2084" },
+  { "id": 1977, "score": 0.63, "view_url": "https://mantis.example.com/view.php?id=1977" },
+  { "id": 2150, "score": 0.61, "view_url": "https://mantis.example.com/view.php?id=2150" }
+]
+```
+
+Die Issues 2210 und 2211 enthalten `CVE-2026-1234` und stehen vorn, obwohl Issue 2084 den höheren `score` hat.
 
 ---
 

package/docs/cookbook.md

@@ -1684,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, 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`.
+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`. Issues that contain an identifier from the query as a whole — an order number, a CVE, a version, a code name such as `MANTIS_SEARCH_DIR` — are listed before all others, unless the identifier occurs in more than 20 issues.
 
 **Tool:** `search_issues`
 
@@ -1712,7 +1712,38 @@ Finds issues semantically similar to a natural language query, combined with key
 ]
 ```
 
-> **Note:** Semantic search returns the top-N most similar issues — it does not guarantee exhaustive recall. It is not suitable for "find all issues about X" census queries.
+> **Note:** Semantic search returns the top-N most similar issues — it does not guarantee exhaustive recall. It is not suitable for "find all issues about X" census queries. The exception is a query for a rare identifier: the issues that contain it come first (see below), so with a large enough `top_n` they are all listed.
+
+---
+
+### Search for an identifier
+
+A query for an order number, a CVE, a version or a code name lists every issue that contains it as a whole before all other results. Identifiers are recognised by their form: an underscore, a capital inside the word, letters with digits, five or more digits, or parts joined by `-` `.` `:` `/` with a digit. `1.15` does not match `1.15.2`, and `CVE-2026-1234` does not match `CVE-2026-12345`. Plain words and short numbers keep the combined ranking, as does an identifier that occurs in more than 20 issues.
+
+**Tool:** `search_issues`
+
+**Request:**
+
+```json
+{
+  "query": "CVE-2026-1234",
+  "top_n": 5
+}
+```
+
+**Response:**
+
+```json
+[
+  { "id": 2210, "score": 0.58, "view_url": "https://mantis.example.com/view.php?id=2210" },
+  { "id": 2211, "score": 0.47, "view_url": "https://mantis.example.com/view.php?id=2211" },
+  { "id": 2084, "score": 0.65, "view_url": "https://mantis.example.com/view.php?id=2084" },
+  { "id": 1977, "score": 0.63, "view_url": "https://mantis.example.com/view.php?id=1977" },
+  { "id": 2150, "score": 0.61, "view_url": "https://mantis.example.com/view.php?id=2150" }
+]
+```
+
+Issues 2210 and 2211 contain `CVE-2026-1234` and come first, although issue 2084 has the higher `score`.
 
 ---
 

package/docs/examples.de.md

@@ -201,10 +201,14 @@ 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.
+Die Suche berücksichtigt auch exakte Stichwörter, daher funktionieren Bezeichner, Fehlercodes und Versionsnummern ebenfalls als Suchanfrage. Issues, die die Kennung enthalten, stehen vorn.
 
 > »Welche Issues erwähnen `MANTIS_SEARCH_DIR`?«
 
+> »Finde alle Issues zu `CVE-2026-1234`.«
+
+Wie Kennungen erkannt werden: [Cookbook – Nach einer Kennung suchen](cookbook.de.md#nach-einer-kennung-suchen).
+
 > »Finde Issues zum Fehler `ERR_CERT_DATE_INVALID`.«
 
 ---

package/docs/examples.md

@@ -201,10 +201,14 @@ 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.
+The search also matches exact keywords, so identifiers, error codes and version numbers work as queries too. Issues that contain the identifier come first.
 
 > "Which issues mention `MANTIS_SEARCH_DIR`?"
 
+> "Find all issues about `CVE-2026-1234`."
+
+How identifiers are recognised: [Cookbook — Search for an identifier](cookbook.md#search-for-an-identifier).
+
 > "Find issues about the error `ERR_CERT_DATE_INVALID`."
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",

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