@dpesch/mantisbt-mcp-server 1.14.1 → 1.16.0

package/dist/client.js

@@ -38,6 +38,10 @@ export function buildIssueViewUrl(baseUrl, issueId) {
 export function buildNoteViewUrl(baseUrl, issueId, noteId) {
     return `${baseUrl}/view.php?id=${issueId}#bugnote${noteId}`;
 }
+/** MantisBT sends download_url for attachments only via SOAP, so the REST tools build it themselves. */
+export function buildAttachmentDownloadUrl(baseUrl, fileId) {
+    return `${baseUrl}/file_download.php?file_id=${fileId}&type=bug`;
+}
 // ---------------------------------------------------------------------------
 // MantisApiError
 // ---------------------------------------------------------------------------

package/dist/coerce.js

@@ -0,0 +1,8 @@
+/**
+ * Turns the strings "true"/"false" into booleans before zod validation. Some
+ * MCP clients send boolean tool arguments as strings. Anything else is passed
+ * through unchanged, so zod still rejects invalid input.
+ *
+ * Use as z.preprocess(coerceBool, z.boolean()…).
+ */
+export const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;

package/dist/config.js

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { normalizeBaseUrl, usesIndexPhpEntryPoint } from './client.js';
+import { parseToolsets } from './toolsets.js';
 // ---------------------------------------------------------------------------
 // .env.local loader
 // ---------------------------------------------------------------------------
@@ -39,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;
@@ -52,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,
@@ -70,6 +71,8 @@ function readNonCredentialConfig() {
             numThreads: searchNumThreads,
         },
         testEnvironment: process.env.MCP_TEST_ENVIRONMENT === 'true',
+        toolsets: parseToolsets(process.env.MANTIS_TOOLSETS),
+        disableDestructive: process.env.MANTIS_DISABLE_DESTRUCTIVE === 'true',
     };
 }
 /**

package/dist/deprecation.js

@@ -0,0 +1,9 @@
+/** Major version in which deprecated tools are removed (see versioning rules in CLAUDE.md). */
+export const REMOVAL_VERSION = '2.0.0';
+/**
+ * First line of the description of a deprecated tool. Keeping the wording in
+ * one place keeps README, CHANGELOG and tests consistent.
+ */
+export function deprecationNote(tool, replacement) {
+    return `Deprecated: use ${replacement} instead — ${tool} will be removed in ${REMOVAL_VERSION}.`;
+}

package/dist/index.js

@@ -10,19 +10,8 @@ import { getConfig, getStartupConfig, assertHttpAuthConfigured } from './config.
 import { MantisClient } from './client.js';
 import { VersionHintService, setGlobalVersionHint } from './version-hint.js';
 import { MetadataCache } from './cache.js';
-import { registerIssueTools } from './tools/issues.js';
-import { registerNoteTools } from './tools/notes.js';
-import { registerFileTools } from './tools/files.js';
-import { registerRelationshipTools } from './tools/relationships.js';
-import { registerMonitorTools } from './tools/monitors.js';
-import { registerProjectTools } from './tools/projects.js';
-import { registerProjectVersionTools } from './tools/project-versions.js';
-import { registerUserTools } from './tools/users.js';
-import { registerFilterTools } from './tools/filters.js';
-import { registerConfigTools } from './tools/config.js';
-import { registerMetadataTools } from './tools/metadata.js';
-import { registerTagTools } from './tools/tags.js';
-import { registerVersionTools } from './tools/version.js';
+import { registerAllTools } from './tools/index.js';
+import { filterToolRegistration } from './toolsets.js';
 import { registerPrompts } from './prompts/index.js';
 import { registerResources } from './resources/index.js';
 // ---------------------------------------------------------------------------
@@ -55,26 +44,26 @@ async function createMcpServer(transport) {
         name: 'mantisbt-mcp-server',
         version,
     });
-    registerIssueTools(server, client, cache);
-    registerNoteTools(server, client);
-    registerFileTools(server, client, startupConfig.uploadDir, transport);
-    registerRelationshipTools(server, client);
-    registerMonitorTools(server, client);
-    registerProjectTools(server, client, cache);
-    registerProjectVersionTools(server, client, cache);
-    registerUserTools(server, client);
-    registerFilterTools(server, client);
-    registerConfigTools(server, client, cache);
-    registerMetadataTools(server, client, cache);
-    registerTagTools(server, client);
-    registerVersionTools(server, client, versionHint, version);
+    // Tools register through a filter for MANTIS_TOOLSETS / MANTIS_DISABLE_DESTRUCTIVE;
+    // prompts and resources use the server directly.
+    const tools = filterToolRegistration(server, startupConfig);
+    // Optional: Semantic search module — needs MANTIS_SEARCH_ENABLED=true and the
+    // "search" tool group (skipping it avoids loading the model and the index).
+    // Initialized first so get_metadata can report the index status.
+    const searchIndexStatus = startupConfig.search.enabled && startupConfig.toolsets.has('search')
+        ? await (await import('./search/index.js')).initializeSearchModule(tools, client, startupConfig.search)
+        : undefined;
+    registerAllTools(tools, {
+        client,
+        cache,
+        versionHint,
+        version,
+        uploadDir: startupConfig.uploadDir,
+        transport,
+        searchIndexStatus,
+    });
     registerPrompts(server);
     registerResources(server, client, cache, startupConfig.testEnvironment);
-    // Optional: Semantic search module
-    if (startupConfig.search.enabled) {
-        const { initializeSearchModule } = await import('./search/index.js');
-        await initializeSearchModule(server, client, startupConfig.search);
-    }
     return server;
 }
 // ---------------------------------------------------------------------------

package/dist/issue-enrich.js

@@ -0,0 +1,23 @@
+import { buildAttachmentDownloadUrl, buildIssueViewUrl, buildNoteViewUrl } from './client.js';
+/**
+ * Adds the links MantisBT's REST API leaves out: view_url for the issue and
+ * each note, download_url for each attachment (REST sends it only via SOAP).
+ * issueId is the fallback when a select projection excluded the id field.
+ */
+export function enrichIssue(issue, baseUrl, issueId) {
+    const id = issue.id ?? issueId;
+    if (id === undefined)
+        return issue;
+    return {
+        ...issue,
+        view_url: buildIssueViewUrl(baseUrl, id),
+        notes: issue.notes?.map(note => ({
+            ...note,
+            view_url: buildNoteViewUrl(baseUrl, id, note.id),
+        })),
+        attachments: issue.attachments?.map(file => ({
+            ...file,
+            download_url: buildAttachmentDownloadUrl(baseUrl, file.id),
+        })),
+    };
+}

package/dist/issue-envelope.js

@@ -0,0 +1,4 @@
+/** The issue from a MantisBT issue response, whichever of the two envelopes it uses. */
+export function firstIssue(response) {
+    return response?.issues?.[0] ?? response?.issue;
+}

package/dist/prompts/index.js

@@ -16,7 +16,7 @@ export function registerPrompts(server) {
         description: 'Guide the creation of a complete bug report in MantisBT. Project, category, summary, and description are required.',
         argsSchema: {
             project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            category: z.string().describe('Issue category (call get_project_categories to list valid values)'),
+            category: z.string().describe('Issue category (call get_project with include: ["categories"] to list valid values)'),
             summary: z.string().describe('Short, descriptive summary of the bug'),
             description: z.string().describe('Detailed description of the bug'),
             steps_to_reproduce: z.string().optional().describe('Step-by-step reproduction instructions'),
@@ -46,7 +46,7 @@ export function registerPrompts(server) {
         if (environment) {
             lines.push(``, `Environment:`, environment);
         }
-        lines.push(``, `Use the create_issue tool to submit this bug report.`, `Call get_issue_enums first if you need to look up valid severity and priority values.`, `Default to severity "minor" and priority "normal" unless the user specifies otherwise.`);
+        lines.push(``, `Use the create_issue tool to submit this bug report.`, `Call get_issue_schema first if you need to look up valid severity and priority values.`, `Default to severity "minor" and priority "normal" unless the user specifies otherwise.`);
         return userMessage(lines.join('\n'));
     });
     // ---------------------------------------------------------------------------
@@ -57,7 +57,7 @@ export function registerPrompts(server) {
         description: 'Guide the creation of a feature request in MantisBT. Project, category, summary, and description are required.',
         argsSchema: {
             project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            category: z.string().describe('Issue category (call get_project_categories to list valid values)'),
+            category: z.string().describe('Issue category (call get_project with include: ["categories"] to list valid values)'),
             summary: z.string().describe('Short description of the requested feature'),
             description: z.string().describe('Detailed description of the feature'),
             use_case: z.string().optional().describe('Business use case or motivation for the feature'),
@@ -75,7 +75,7 @@ export function registerPrompts(server) {
         if (use_case) {
             lines.push(``, `Use case / motivation:`, use_case);
         }
-        lines.push(``, `Use the create_issue tool to submit this feature request.`, `Call get_issue_enums first to look up valid severity values — use severity "feature" and priority "normal" unless the user specifies otherwise.`);
+        lines.push(``, `Use the create_issue tool to submit this feature request.`, `Call get_issue_schema first to look up valid severity values — use severity "feature" and priority "normal" unless the user specifies otherwise.`);
         return userMessage(lines.join('\n'));
     });
     // ---------------------------------------------------------------------------

package/dist/resources/index.js

@@ -1,7 +1,6 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { fetchIssueEnums } from '../tools/config.js';
-import { normalizeProject } from '../tools/metadata.js';
-import { ALL_PROJECTS_PREFIX } from '../constants.js';
+import { normalizeProject, stripAllProjectsPrefix } from '../tools/metadata.js';
 function jsonResource(uri, data) {
     return {
         contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data) }],
@@ -21,7 +20,7 @@ export function registerResources(server, client, cache, testEnvironment = false
     }, async (uri) => jsonResource(uri, await client.get('users/me')));
     server.registerResource('projects', 'mantis://projects', {
         title: 'Projects',
-        description: 'All MantisBT projects accessible to the current API user. Served from local cache when fresh; falls back to live fetch. Refresh via the sync_metadata tool.',
+        description: 'All MantisBT projects accessible to the current API user. Served from local cache when fresh; falls back to live fetch. Refresh via get_metadata with refresh: true.',
         mimeType: 'application/json',
     }, async (uri) => jsonResource(uri, await loadProjects()));
     server.registerResource('project-detail', new ResourceTemplate('mantis://projects/{id}', {
@@ -40,7 +39,7 @@ export function registerResources(server, client, cache, testEnvironment = false
         },
     }), {
         title: 'Project Detail',
-        description: 'Combined project view: fields (status, view_state, access_level, description) plus all associated users, versions, and categories. Served from local cache when fresh; falls back to live API fetch. Refresh via the sync_metadata tool.',
+        description: 'Combined project view: fields (status, view_state, access_level, description) plus all associated users, versions, and categories. Served from local cache when fresh; falls back to live API fetch. Refresh via get_metadata with refresh: true.',
         mimeType: 'application/json',
     }, async (uri, { id }) => {
         const numId = Number(id);
@@ -66,10 +65,7 @@ export function registerResources(server, client, cache, testEnvironment = false
             project = raw ? normalizeProject(raw) : undefined;
             users = usersResult.users ?? [];
             versions = versionsResult.versions ?? [];
-            categories = (raw?.categories ?? []).map((c) => ({
-                ...c,
-                name: c.name.startsWith(ALL_PROJECTS_PREFIX) ? c.name.slice(ALL_PROJECTS_PREFIX.length) : c.name,
-            }));
+            categories = stripAllProjectsPrefix(raw?.categories ?? []);
         }
         if (!project) {
             throw new Error(`Project ${numId} not found`);

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/index.js

@@ -1,21 +1,22 @@
 import { createVectorStore } from './store.js';
 import { Embedder } from './embedder.js';
-import { registerSearchTools } from './tools.js';
+import { registerSearchTools, getSearchIndexStatus } from './tools.js';
 import { SearchSyncService, SyncLockedError } 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, config.numThreads);
     registerSearchTools(server, client, store, embedder, config.dir);
-    // Pre-initialize lastKnownTotal so get_search_index_status shows a value
+    // Pre-initialize lastKnownTotal so the index status (get_metadata) 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);
+    // count() loads the whole index into memory, and this runs before the server
+    // connects — so only do it when there is no stored total yet.
+    if (await store.getLastKnownTotal() === null) {
+        const startupCount = await store.count();
+        if (startupCount > 0)
+            await store.setLastKnownTotal(startupCount);
     }
     // Non-blocking background sync on startup. If another server process (another
     // client session) is already syncing the shared index, this one skips it.
@@ -27,4 +28,5 @@ export async function initializeSearchModule(server, client, config) {
         }
         console.error('[mantisbt-search] sync error:', err instanceof Error ? err.message : String(err));
     });
+    return () => getSearchIndexStatus(store);
 }

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