@dpesch/mantisbt-mcp-server 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.2.0] – 2026-03-16
+
+### Added
+- New tool `remove_relationship`: removes a relationship from an issue. The `relationship_id` is the numeric `id` field on the relationship object returned by `get_issue` (not the type id).
+- New tool `remove_monitor`: removes a user as a monitor of an issue by username.
+- New tool `upload_file`: uploads a file to an issue via multipart/form-data. Supports two input modes: a local `file_path` (filename derived from path) or Base64-encoded `content` with an explicit `filename`. Optional parameters: `filename` (overrides derived name), `content_type` (default: `application/octet-stream`), `description`.
+- New optional semantic search module (`MANTIS_SEARCH_ENABLED=true`): indexes all MantisBT issues as local vector embeddings using `@huggingface/transformers` (ONNX, no external API required). Two new tools:
+  - `search_issues` — natural language search over all indexed issues, returns top-N results by cosine similarity score.
+  - `rebuild_search_index` — build or incrementally update the search index; `full: true` clears and rebuilds from scratch.
+  - Vector store: `vectra` (pure JS, default) or `sqlite-vec` (optional, requires manual installation).
+  - Incremental sync on every server start via `updated_at` timestamp.
+  - Configuration: `MANTIS_SEARCH_ENABLED`, `MANTIS_SEARCH_BACKEND`, `MANTIS_SEARCH_DIR`, `MANTIS_SEARCH_MODEL`.
+
+### Fixed
+- `list_issues` recorded-fixture tests were fragile: status filter counts are now derived dynamically from the fixture instead of hardcoded assumptions.
+
+---
+
 ## [1.1.0] – 2026-03-15
 
 ### Added

package/README.de.md

@@ -69,6 +69,10 @@ npm run build
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache-Lebensdauer in Sekunden |
 | `TRANSPORT` | – | `stdio` | Transport-Modus: `stdio` oder `http` |
 | `PORT` | – | `3000` | Port für HTTP-Modus |
+| `MANTIS_SEARCH_ENABLED` | – | `false` | Auf `true` setzen, um die semantische Suche zu aktivieren |
+| `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vektorspeicher: `vectra` (reines JS) oder `sqlite-vec` (manuelle Installation erforderlich) |
+| `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Verzeichnis für den Suchindex |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding-Modell (wird beim ersten Start einmalig heruntergeladen, ~80 MB) |
 
 ### Config-Datei (Fallback)
 
@@ -106,18 +110,21 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | Tool | Beschreibung |
 |---|---|
 | `list_issue_files` | Anhänge eines Issues auflisten |
+| `upload_file` | Datei an ein Issue anhängen – entweder per lokalem `file_path` oder Base64-kodiertem `content` + `filename` |
 
 ### Beziehungen
 
 | Tool | Beschreibung |
 |---|---|
 | `add_relationship` | Beziehung zwischen zwei Issues erstellen |
+| `remove_relationship` | Beziehung von einem Issue entfernen (die `id` aus dem Beziehungsobjekt verwenden, nicht die type-ID) |
 
 ### Beobachter
 
 | Tool | Beschreibung |
 |---|---|
 | `add_monitor` | Sich selbst als Beobachter eines Issues eintragen |
+| `remove_monitor` | Benutzer als Beobachter eines Issues austragen |
 
 ### Tags
 
@@ -136,6 +143,21 @@ Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgel
 | `get_project_categories` | Kategorien eines Projekts abrufen |
 | `get_project_users` | Benutzer eines Projekts abrufen |
 
+### Semantische Suche *(optional)*
+
+Aktivierung mit `MANTIS_SEARCH_ENABLED=true`. Beim ersten Start wird das Embedding-Modell (~80 MB) heruntergeladen und lokal gecacht. Alle Issues werden danach bei jedem Serverstart inkrementell indexiert.
+
+| Tool | Beschreibung |
+|---|---|
+| `search_issues` | Natürlichsprachige Suche über alle indizierten Issues – liefert Top-N-Ergebnisse mit Cosine-Similarity-Score |
+| `rebuild_search_index` | Suchindex aufbauen oder aktualisieren; `full: true` löscht und baut ihn vollständig neu |
+
+**`sqlite-vec`-Backend** (optional, schneller bei großen Instanzen):
+```bash
+npm install sqlite-vec better-sqlite3
+# dann MANTIS_SEARCH_BACKEND=sqlite-vec setzen
+```
+
 ### Metadaten & System
 
 | Tool | Beschreibung |

package/README.md

@@ -69,6 +69,10 @@ npm run build
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache lifetime in seconds |
 | `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | – | `3000` | Port for HTTP mode |
+| `MANTIS_SEARCH_ENABLED` | – | `false` | Set to `true` to enable semantic search |
+| `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vector store backend: `vectra` (pure JS) or `sqlite-vec` (requires manual install) |
+| `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Directory for the search index |
+| `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding model name (downloaded once on first use, ~80 MB) |
 
 ### Config file (fallback)
 
@@ -106,18 +110,21 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | Tool | Description |
 |---|---|
 | `list_issue_files` | List attachments of an issue |
+| `upload_file` | Upload a file to an issue — either by local `file_path` or Base64-encoded `content` + `filename` |
 
 ### Relationships
 
 | Tool | Description |
 |---|---|
 | `add_relationship` | Create a relationship between two issues |
+| `remove_relationship` | Remove a relationship from an issue (use the `id` from the relationship object, not the type) |
 
 ### Monitors
 
 | Tool | Description |
 |---|---|
 | `add_monitor` | Add yourself as a monitor of an issue |
+| `remove_monitor` | Remove a user as a monitor of an issue |
 
 ### Tags
 
@@ -136,6 +143,21 @@ If no environment variables are set, `~/.claude/mantis.json` is read:
 | `get_project_categories` | Get categories of a project |
 | `get_project_users` | Get users of a project |
 
+### Semantic search *(optional)*
+
+Activate with `MANTIS_SEARCH_ENABLED=true`. On first start the embedding model (~80 MB) is downloaded and cached locally. All issues are then indexed incrementally on each server start.
+
+| Tool | Description |
+|---|---|
+| `search_issues` | Natural language search over all indexed issues — returns top-N results with cosine similarity score |
+| `rebuild_search_index` | Build or update the search index; `full: true` clears and rebuilds from scratch |
+
+**`sqlite-vec` backend** (optional, faster for large instances):
+```bash
+npm install sqlite-vec better-sqlite3
+# then set MANTIS_SEARCH_BACKEND=sqlite-vec
+```
+
 ### Metadata & system
 
 | Tool | Description |

package/dist/client.js

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

package/dist/config.js

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

package/dist/index.js

@@ -54,6 +54,11 @@ async function createMcpServer() {
     registerMetadataTools(server, client, cache);
     registerTagTools(server, client);
     registerVersionTools(server, client, versionHint);
+    // Optional: Semantic search module
+    if (config.search.enabled) {
+        const { initializeSearchModule } = await import('./search/index.js');
+        await initializeSearchModule(server, client, config.search);
+    }
     return server;
 }
 // ---------------------------------------------------------------------------

package/dist/search/embedder.js

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

package/dist/search/index.js

@@ -0,0 +1,19 @@
+import { createVectorStore } from './store.js';
+import { Embedder } from './embedder.js';
+import { registerSearchTools } from './tools.js';
+import { SearchSyncService } from './sync.js';
+// ---------------------------------------------------------------------------
+// initializeSearchModule
+// ---------------------------------------------------------------------------
+export async function initializeSearchModule(server, client, config) {
+    if (!config.enabled)
+        return;
+    const store = createVectorStore(config.backend, config.dir);
+    const embedder = new Embedder(config.modelName);
+    registerSearchTools(server, client, store, embedder);
+    // Non-blocking background sync on startup
+    const syncService = new SearchSyncService(client, store, embedder);
+    syncService.sync().catch((err) => {
+        console.error('[mantisbt-search] sync error:', err instanceof Error ? err.message : String(err));
+    });
+}

package/dist/search/store.js

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

package/dist/search/sync.js

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

package/dist/search/tools.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { SearchSyncService } from './sync.js';
+// ---------------------------------------------------------------------------
+// registerSearchTools
+// ---------------------------------------------------------------------------
+export function registerSearchTools(server, client, store, embedder) {
+    // ---------------------------------------------------------------------------
+    // search_issues
+    // ---------------------------------------------------------------------------
+    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.',
+        inputSchema: z.object({
+            query: z.string().describe('Natural language search query'),
+            top_n: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .default(10)
+                .describe('Number of results to return (default: 10, max: 50)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ query, top_n }) => {
+        try {
+            const count = await store.count();
+            if (count === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Search index is empty. Run rebuild_search_index first.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const queryVector = await embedder.embed(query);
+            const results = await store.search(queryVector, top_n);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // rebuild_search_index
+    // ---------------------------------------------------------------------------
+    server.registerTool('rebuild_search_index', {
+        title: 'Rebuild Semantic Search Index',
+        description: 'Build or update the semantic search index for MantisBT issues. ' +
+            'Use full: true to clear the existing index and rebuild from scratch.',
+        inputSchema: z.object({
+            project_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Optional: only index issues from this project'),
+            full: z
+                .boolean()
+                .default(false)
+                .describe('If true, clears the existing index and rebuilds from scratch'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id, full }) => {
+        try {
+            if (full) {
+                await store.clear();
+                await store.resetLastSyncedAt();
+            }
+            const startMs = Date.now();
+            const syncService = new SearchSyncService(client, store, embedder);
+            const { indexed, skipped } = await syncService.sync(project_id);
+            const duration_ms = Date.now() - startMs;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ indexed, skipped, duration_ms }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}