@dpesch/mantisbt-mcp-server 1.5.2 → 1.5.5

package/CHANGELOG.md

@@ -7,6 +7,36 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.5.5] – 2026-03-18
+
+### Fixed
+- Semantic search index sync: eliminated O(n²) disk write amplification during initial index builds. Previously `addBatch()` wrote the entire `index.json` to disk after every batch, causing n/batch_size complete rewrites for a full rebuild. Now `addBatch()` only updates the in-memory map; a new `flush()` method (atomic write via tmp file + rename) persists to disk. `SearchSyncService.sync()` calls `flush()` as a checkpoint every 100 indexed issues (`CHECKPOINT_INTERVAL=100`), limiting data loss on process kill to at most 100 issues, and performs a final flush after the loop for any remaining items.
+
+---
+
+## [1.5.4] – 2026-03-18
+
+### Fixed
+- `registerFileTools`: the `uploadDir` parameter was typed as required (`string | undefined`) instead of truly optional (`uploadDir?: string`), causing TypeScript errors in callers that omit the argument and breaking the CI typecheck step.
+
+### Changed
+- Added `npm run init` setup script (`scripts/init.mjs`): checks Node.js version (≥ 18), runs `npm install`, installs git hooks from `scripts/hooks/`, and runs a typecheck to verify the setup.
+- Git pre-push hook logic is now version-controlled in `scripts/hooks/pre-push.mjs`; the hook runs `npm run typecheck` before every push to catch type errors locally before they reach CI.
+
+---
+
+## [1.5.3] – 2026-03-17
+
+### Security
+- Removed unused `vectra` dependency. The package was listed in `dependencies` but never imported — `VectraStore` is a self-contained implementation. Removing it eliminates three transitive CVEs in the `openai` → `axios` chain (GHSA-jr5f-v2jv-69x6 SSRF/credential-leakage, GHSA-43fc-jf86-j433 DoS, GHSA-wf5p-g6vw-rhxx CSRF).
+- `upload_file`: new optional `MANTIS_UPLOAD_DIR` environment variable restricts `file_path` uploads to a configured directory. When set, any path that resolves outside the directory (including `../` traversal attempts) is rejected before the file is read. Without the variable the behaviour is unchanged (no restriction). The resolved directory prefix is computed once at server start, not per request.
+- HTTP transport now binds to `127.0.0.1` (localhost only) by default instead of `0.0.0.0` (all interfaces). This prevents unintended exposure on network interfaces when the server is started without explicit network configuration. Set `MCP_HTTP_HOST=0.0.0.0` to restore the previous behaviour (required for Docker and remote access).
+- New optional `MCP_HTTP_TOKEN` environment variable: when set, the `/mcp` endpoint requires an `Authorization: Bearer <token>` header. Requests without a valid token receive HTTP 401. The `/health` endpoint remains public regardless of this setting.
+- New optional `MCP_HTTP_HOST` environment variable: overrides the bind address for HTTP mode (default: `127.0.0.1`).
+- `update_issue`: the `fields` parameter now validates against an explicit allowlist of known MantisBT field names (`summary`, `description`, `steps_to_reproduce`, `additional_information`, `status`, `resolution`, `priority`, `severity`, `reproducibility`, `handler`, `category`, `version`, `fixed_in_version`, `target_version`, `view_state`, `tags`, `custom_fields`); unknown keys are rejected with a validation error. Reference objects (`status`, `handler`, `reproducibility`, `version`, `view_state`, etc.) must now contain at least `id` or `name` — empty objects `{}` are rejected. Previously any key was accepted and forwarded directly to the API.
+
+---
+
 ## [1.5.2] – 2026-03-17
 
 ### Fixed

package/README.de.md

@@ -38,7 +38,7 @@ In `~/.claude/claude_desktop_config.json` (Claude Desktop) oder der lokalen
 ```bash
 git clone https://codeberg.org/dpesch/mantisbt-mcp-server
 cd mantisbt-mcp-server
-npm install
+npm run init
 npm run build
 ```
 
@@ -69,11 +69,14 @@ 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 |
+| `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind-Adresse für HTTP-Modus. **Geändert von `0.0.0.0` auf `127.0.0.1`** — der Server horcht standardmäßig nur auf localhost. Für Docker oder Remote-Zugriff `0.0.0.0` setzen. |
+| `MCP_HTTP_TOKEN` | – | – | Wenn gesetzt, muss jede `/mcp`-Anfrage den Header `Authorization: Bearer <token>` enthalten. `/health` ist immer öffentlich. |
 | `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_UPLOAD_DIR` | – | – | Schränkt `upload_file` auf Dateien in diesem Verzeichnis ein. Wenn gesetzt, wird jeder `file_path` außerhalb des Verzeichnisses abgelehnt (Pfad-Traversal-Versuche via `../` werden blockiert). Ohne diese Variable gilt keine Einschränkung. |
 
 ### Config-Datei (Fallback)
 
@@ -199,14 +202,18 @@ Für den Einsatz als eigenständiger Server (z.B. in Remote-Setups):
 
 ```bash
 MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.js
+
+# Mit Token-Authentifizierung und expliziter Bind-Adresse (erforderlich für Docker/Remote):
+# MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
+#   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
 ```
 
-Healthcheck: `GET http://localhost:3456/health`
+Healthcheck: `GET http://localhost:3456/health` (immer öffentlich, kein Token erforderlich)
 
 ## Entwicklung
 
 ```bash
-npm install          # Abhängigkeiten installieren
+npm run init         # Ersteinrichtung: Abhängigkeiten, Git-Hooks, Typprüfung
 npm run build        # TypeScript → dist/ kompilieren
 npm run typecheck    # Typprüfung ohne Ausgabe
 npm run dev          # Watch-Modus für Entwicklung

package/README.md

@@ -38,7 +38,7 @@ Add to `~/.claude/claude_desktop_config.json` (Claude Desktop) or your local
 ```bash
 git clone https://codeberg.org/dpesch/mantisbt-mcp-server
 cd mantisbt-mcp-server
-npm install
+npm run init
 npm run build
 ```
 
@@ -69,11 +69,14 @@ npm run build
 | `MANTIS_CACHE_TTL` | – | `3600` | Cache lifetime in seconds |
 | `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | – | `3000` | Port for HTTP mode |
+| `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind address for HTTP mode. **Changed from `0.0.0.0` to `127.0.0.1`** — the server now listens on localhost only by default. Set to `0.0.0.0` for Docker or remote access. |
+| `MCP_HTTP_TOKEN` | – | – | When set, the `/mcp` endpoint requires `Authorization: Bearer <token>`. The `/health` endpoint is always public. |
 | `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_UPLOAD_DIR` | – | – | Restrict `upload_file` to files within this directory. When set, any `file_path` outside the directory is rejected (path traversal attempts via `../` are blocked). Without this variable there is no restriction. |
 
 ### Config file (fallback)
 
@@ -199,14 +202,18 @@ For use as a standalone server (e.g. in remote setups):
 
 ```bash
 MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.js
+
+# With token authentication and explicit bind address (required for Docker/remote):
+# MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
+#   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
 ```
 
-Health check: `GET http://localhost:3456/health`
+Health check: `GET http://localhost:3456/health` (always public, no token required)
 
 ## Development
 
 ```bash
-npm install          # Install dependencies
+npm run init         # First-time setup: install deps, git hooks, typecheck
 npm run build        # Compile TypeScript → dist/
 npm run typecheck    # Type check without output
 npm run dev          # Watch mode for development

package/dist/config.js

@@ -77,11 +77,19 @@ export async function getConfig() {
     const searchModelName = process.env.MANTIS_SEARCH_MODEL ??
         'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
     const searchNumThreads = Math.max(1, parseInt(process.env.MANTIS_SEARCH_THREADS ?? '', 10) || 1);
+    const uploadDir = process.env.MANTIS_UPLOAD_DIR;
+    const httpHost = process.env.MCP_HTTP_HOST ?? '127.0.0.1';
+    const httpPort = parseInt(process.env.PORT ?? '3000', 10);
+    const httpToken = process.env.MCP_HTTP_TOKEN;
     cachedConfig = {
         baseUrl: baseUrl.replace(/\/$/, ''), // strip trailing slash
         apiKey,
         cacheDir,
         cacheTtl,
+        uploadDir,
+        httpHost,
+        httpPort,
+        httpToken,
         search: {
             enabled: searchEnabled,
             backend: searchBackend,

package/dist/index.js

@@ -44,7 +44,7 @@ async function createMcpServer() {
     });
     registerIssueTools(server, client, cache);
     registerNoteTools(server, client);
-    registerFileTools(server, client);
+    registerFileTools(server, client, config.uploadDir);
     registerRelationshipTools(server, client);
     registerMonitorTools(server, client);
     registerProjectTools(server, client);
@@ -75,10 +75,19 @@ async function runStdio() {
     process.stdin.once('close', () => process.exit(0));
 }
 async function runHttp() {
+    const config = await getConfig();
     const server = await createMcpServer();
-    const port = parseInt(process.env.PORT ?? '3000', 10);
+    const port = config.httpPort;
     const httpServer = createServer(async (req, res) => {
         if (req.method === 'POST' && req.url === '/mcp') {
+            if (config.httpToken) {
+                const auth = req.headers['authorization'];
+                if (auth !== `Bearer ${config.httpToken}`) {
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Unauthorized' }));
+                    return;
+                }
+            }
             const chunks = [];
             req.on('data', (chunk) => chunks.push(chunk));
             req.on('end', async () => {
@@ -107,8 +116,8 @@ async function runHttp() {
             res.end();
         }
     });
-    httpServer.listen(port, () => {
-        console.error(`MantisBT MCP Server v${version} running on http://localhost:${port}/mcp`);
+    httpServer.listen(port, config.httpHost, () => {
+        console.error(`MantisBT MCP Server v${version} running on http://${config.httpHost}:${port}/mcp`);
     });
 }
 // ---------------------------------------------------------------------------

package/dist/search/store.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir, unlink } from 'node:fs/promises';
+import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 // ---------------------------------------------------------------------------
 // VectraStore
@@ -34,8 +34,10 @@ export class VectraStore {
     }
     async persist() {
         const indexFile = join(this.vectraDir, 'index.json');
+        const tmpFile = indexFile + '.tmp';
         const data = JSON.stringify([...this.items.values()]);
-        await writeFile(indexFile, data, 'utf-8');
+        await writeFile(tmpFile, data, 'utf-8');
+        await rename(tmpFile, indexFile);
     }
     async add(item) {
         await this.ensureLoaded();
@@ -47,6 +49,9 @@ export class VectraStore {
         for (const item of items) {
             this.items.set(item.id, item);
         }
+        // No persist() here — call flush() once after all batches are processed.
+    }
+    async flush() {
         await this.persist();
     }
     async search(vector, topN) {

package/dist/search/sync.js

@@ -3,6 +3,7 @@
 // ---------------------------------------------------------------------------
 const PAGE_SIZE = 50;
 const EMBED_BATCH_SIZE = 10;
+const CHECKPOINT_INTERVAL = 100; // flush to disk every N indexed issues
 export class SearchSyncService {
     client;
     store;
@@ -17,6 +18,7 @@ export class SearchSyncService {
         const { issues: allIssues, totalFromApi } = await this.fetchAllIssues(lastSyncedAt ?? undefined, projectId);
         let indexed = 0;
         let skipped = 0;
+        let indexedSinceCheckpoint = 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);
@@ -43,6 +45,17 @@ export class SearchSyncService {
             }));
             await this.store.addBatch(batchItems);
             indexed += batchItems.length;
+            indexedSinceCheckpoint += batchItems.length;
+            // Checkpoint flush: persist every CHECKPOINT_INTERVAL issues to limit
+            // data loss if the process is killed before the final flush.
+            if (indexedSinceCheckpoint >= CHECKPOINT_INTERVAL) {
+                await this.store.flush();
+                indexedSinceCheckpoint = 0;
+            }
+        }
+        // Final flush for any remaining items not yet written by a checkpoint.
+        if (indexedSinceCheckpoint > 0) {
+            await this.store.flush();
         }
         await this.store.setLastSyncedAt(new Date().toISOString());
         // Persist the best known total for get_search_index_status.

package/dist/tools/files.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
+import { basename, resolve, sep } from 'node:path';
 import { z } from 'zod';
 import { getVersionHint } from '../version-hint.js';
 function errorText(msg) {
@@ -8,7 +8,8 @@ function errorText(msg) {
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
-export function registerFileTools(server, client) {
+export function registerFileTools(server, client, uploadDir) {
+    const normalizedUploadDir = uploadDir ? resolve(uploadDir) + sep : undefined;
     // ---------------------------------------------------------------------------
     // list_issue_files
     // ---------------------------------------------------------------------------
@@ -78,6 +79,12 @@ The optional content_type parameter sets the MIME type (e.g. "image/png"). If om
             let fileBuffer;
             let fileName;
             if (file_path) {
+                if (normalizedUploadDir) {
+                    const normalizedPath = resolve(file_path);
+                    if (!normalizedPath.startsWith(normalizedUploadDir)) {
+                        return { content: [{ type: 'text', text: errorText('file_path is not allowed — access restricted to the designated upload directory') }], isError: true };
+                    }
+                }
                 fileBuffer = await readFile(file_path);
                 fileName = filename ?? basename(file_path);
             }

package/dist/tools/issues.js

@@ -213,6 +213,9 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     // update_issue
     // ---------------------------------------------------------------------------
+    // MantisBT reference shape: at least one of id or name must be provided
+    const ref = z.object({ id: z.number().optional(), name: z.string().optional() })
+        .refine(o => o.id !== undefined || o.name !== undefined, { message: "At least one of 'id' or 'name' must be provided" });
     server.registerTool('update_issue', {
         title: 'Update Issue',
         description: `Update one or more fields of an existing MantisBT issue using a partial PATCH.
@@ -220,19 +223,40 @@ export function registerIssueTools(server, client, cache) {
 The "fields" object accepts any combination of:
 - summary (string)
 - description (string)
+- steps_to_reproduce (string)
+- additional_information (string)
 - status: { name: "new"|"feedback"|"acknowledged"|"confirmed"|"assigned"|"resolved"|"closed" }
 - resolution: { id: 20 }  (20 = fixed/resolved)
 - handler: { id: <user_id> } or { name: "<username>" }
 - priority: { name: "<priority_name>" }
 - severity: { name: "<severity_name>" }
+- reproducibility: { name: "<reproducibility_name>" }
 - category: { name: "<category_name>" }
+- version: { name: "<version_name>" }  (affected version)
 - target_version: { name: "<version_name>" }
 - fixed_in_version: { name: "<version_name>" }
+- view_state: { name: "public"|"private" }
 
 Important: when resolving an issue, always set BOTH status and resolution to avoid leaving resolution as "open".`,
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID to update'),
-            fields: z.record(z.unknown()).describe('Object containing the fields to update (partial update — only provided fields are changed)'),
+            fields: z.object({
+                summary: z.string().optional(),
+                description: z.string().optional(),
+                steps_to_reproduce: z.string().optional(),
+                additional_information: z.string().optional(),
+                status: ref.optional(),
+                resolution: ref.optional(),
+                priority: ref.optional(),
+                severity: ref.optional(),
+                reproducibility: ref.optional(),
+                handler: ref.optional(),
+                category: ref.optional(),
+                version: ref.optional(),
+                target_version: ref.optional(),
+                fixed_in_version: ref.optional(),
+                view_state: ref.optional(),
+            }).strict().describe('Fields to update (partial update — only provided fields are changed; unknown keys are rejected)'),
         }),
         annotations: {
             readOnlyHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.5.2",
+  "version": "1.5.5",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
   "license": "MIT",
@@ -23,13 +23,13 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:record": "tsx scripts/record-fixtures.ts"
+    "test:record": "tsx scripts/record-fixtures.ts",
+    "init": "node scripts/init.mjs"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "vectra": "^0.4.0",
-    "zod": "^3.22.4"
+"zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/scripts/hooks/pre-push.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// pre-push hook — typecheck gate + Codeberg .claude/ filter
+//
+// Typecheck runs for every push (origin and upstream) to catch type errors
+// before they reach CI.
+//
+// Codeberg filter handles multi-commit pushes correctly:
+//   1. Fetches the actual Codeberg tip via ls-remote
+//   2. Finds the local commit whose filtered tree matches that tip (anchor)
+//   3. Filters every commit between anchor and tip in order (oldest first)
+//   4. Builds a proper filtered chain anchored to the actual remote tip
+//   5. Pushes the filtered tip with --force
+//   6. Exits 1 to block git's unfiltered push
+//
+// Branches are processed before tags so the shaMap is available for tags
+// that point to commits already processed as part of the branch.
+//
+// ⚠ IMPORTANT: upstream (Codeberg) is a filtered mirror — push-only.
+// Never run git pull, git fetch + merge, or git rebase against upstream.
+// Filtered commits have different SHAs; pulling them back creates duplicate
+// history. Use origin (Gitolite) as the authoritative source.
+//
+// --force is always required for Codeberg: filtered SHAs structurally diverge
+// from local SHAs, so git rejects main as non-fast-forward before the hook
+// runs unless --force bypasses that check.
+
+import { execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+// Recursion guard — must be first to avoid running typecheck during recursive pushes
+if (process.env._PREPUSH_FILTER_ACTIVE) process.exit(0);
+
+// Run typecheck before every push (catches type errors before they hit CI)
+try {
+  execSync('npm run typecheck', { stdio: 'inherit' });
+} catch {
+  console.error('✗ Typecheck failed — push aborted. Fix type errors first.');
+  process.exit(1);
+}
+
+const [,, , remoteUrl] = process.argv;
+
+// Only intercept Codeberg pushes for the filter step
+if (!remoteUrl?.includes('codeberg.org')) process.exit(0);
+
+console.log('→ Codeberg push detected — filtering .claude/ directory...');
+
+const ZERO_SHA = '0'.repeat(40);
+
+const git = (cmd, opts = {}) => {
+  try {
+    return execSync(`git ${cmd}`, { encoding: 'utf8', ...opts }).trim();
+  } catch (err) {
+    console.error(`✗ git ${cmd}\n${err.stderr || err.message}`);
+    process.exit(1);
+  }
+};
+
+const gitOptional = (cmd, opts = {}) => {
+  try { return execSync(`git ${cmd}`, { encoding: 'utf8', ...opts }).trim(); }
+  catch { return ''; }
+};
+
+const isSha = s => /^[0-9a-f]{40}$/.test(s);
+
+// Remove .claude/ from the root tree of a commit and return the new tree SHA.
+const filterTree = commitSha => {
+  const entries = git(`ls-tree "${commitSha}^{tree}"`);
+  const filtered = entries.split('\n').filter(e => !e.match(/\t\.claude$/)).join('\n');
+  const tree = git('mktree', { input: filtered });
+  if (!isSha(tree)) { console.error(`✗ mktree failed for ${commitSha}`); process.exit(1); }
+  return tree;
+};
+
+// Create a filtered commit object preserving all original metadata.
+const makeFilteredCommit = (commitSha, filteredTree, mappedParents) => {
+  const log = git(`log -1 --format=%an%n%ae%n%aI%n%cn%n%ce%n%cI%n%n%B "${commitSha}"`);
+  const [an, ae, aI, cn, ce, cI, , ...msgLines] = log.split('\n');
+  const commitMsg = msgLines.join('\n').trimEnd();
+  const parentFlags = mappedParents.map(p => `-p ${p}`).join(' ');
+  const env = {
+    ...process.env,
+    GIT_AUTHOR_NAME: an,    GIT_AUTHOR_EMAIL: ae,    GIT_AUTHOR_DATE: aI,
+    GIT_COMMITTER_NAME: cn, GIT_COMMITTER_EMAIL: ce, GIT_COMMITTER_DATE: cI,
+  };
+  const result = git(`commit-tree "${filteredTree}" ${parentFlags}`, { env, input: commitMsg });
+  if (!isSha(result)) { console.error(`✗ commit-tree failed for ${commitSha}`); process.exit(1); }
+  return result;
+};
+
+// Scan ancestors of tipSha (newest first) and return the most recent one whose
+// filtered root tree equals the tree of remoteSha. Returns null if not found.
+const findLocalAnchor = (tipSha, remoteSha, maxDepth = 100) => {
+  const remoteTree = gitOptional(`rev-parse "${remoteSha}^{tree}"`);
+  if (!remoteTree) return null;
+  const candidates = gitOptional(`rev-list --max-count=${maxDepth} "${tipSha}"`);
+  if (!candidates) return null;
+  for (const sha of candidates.split('\n').filter(Boolean)) {
+    if (filterTree(sha) === remoteTree) return sha;
+  }
+  return null;
+};
+
+const rl = createInterface({ input: process.stdin });
+const lines = [];
+rl.on('line', line => { if (line.trim()) lines.push(line.trim()); });
+
+rl.on('close', () => {
+  // Process branches before tags so shaMap is populated when tags are handled.
+  const branches = lines.filter(l => l.split(' ')[2]?.startsWith('refs/heads/'));
+  const others   = lines.filter(l => !l.split(' ')[2]?.startsWith('refs/heads/'));
+
+  // localSha → filteredSha, accumulated across all refs in this push.
+  const shaMap = {};
+  let pushed = 0;
+
+  for (const line of [...branches, ...others]) {
+    const parts = line.split(' ');
+    if (parts.length < 3) { console.error(`✗ Malformed push input: ${line}`); process.exit(1); }
+    const [, localSha, remoteRef] = parts;
+
+    if (localSha === ZERO_SHA) continue; // deletion — skip
+
+    const label = remoteRef.replace('refs/heads/', '').replace('refs/tags/', '');
+
+    // If this commit was already filtered as part of a branch push, reuse it.
+    if (localSha in shaMap) {
+      try {
+        execSync(`git push "${remoteUrl}" "${shaMap[localSha]}:${remoteRef}" --force`,
+          { env: { ...process.env, _PREPUSH_FILTER_ACTIVE: '1' }, stdio: 'inherit' });
+      } catch {
+        console.error(`✗ Push failed for ${label}`); process.exit(1);
+      }
+      console.log(`✓ ${label} pushed to Codeberg (without .claude/)`);
+      pushed++;
+      continue;
+    }
+
+    // Get the actual current SHA on Codeberg for this ref.
+    const lsOut = gitOptional(`ls-remote "${remoteUrl}" "${remoteRef}"`);
+    const actualRemoteSha = lsOut ? lsOut.split(/\s+/)[0] : '';
+
+    if (!actualRemoteSha) {
+      // New ref on Codeberg — filter the tip with no parent.
+      shaMap[localSha] = makeFilteredCommit(localSha, filterTree(localSha), []);
+    } else {
+      // Find the local commit that corresponds to the current Codeberg tip.
+      const localAnchor = findLocalAnchor(localSha, actualRemoteSha);
+
+      if (localAnchor) {
+        shaMap[localAnchor] = actualRemoteSha;
+
+        // Filter all commits between anchor and tip, oldest first.
+        const revList = gitOptional(`rev-list --reverse "${localAnchor}..${localSha}"`);
+        const commits = revList ? revList.split('\n').filter(Boolean) : [];
+
+        for (const sha of commits) {
+          const filteredTree = filterTree(sha);
+          const parents = gitOptional(`log -1 --format=%P "${sha}"`);
+          const parentShas = parents ? parents.split(' ').filter(Boolean) : [];
+          // Map each parent through shaMap; fall back to actualRemoteSha for
+          // parents outside the current range (already on the remote).
+          const mappedParents = parentShas
+            .map(p => shaMap[p] ?? actualRemoteSha)
+            .filter(Boolean);
+          shaMap[sha] = makeFilteredCommit(sha, filteredTree, mappedParents);
+        }
+      } else {
+        // Fallback: anchor not found — filter tip only, rooted at remote tip.
+        console.warn(`  ⚠ Could not find local base for ${label}, filtering tip only`);
+        shaMap[localSha] = makeFilteredCommit(localSha, filterTree(localSha), [actualRemoteSha]);
+      }
+    }
+
+    const filteredTip = shaMap[localSha];
+    if (!filteredTip) {
+      console.error(`✗ Could not compute filtered SHA for ${localSha}`);
+      process.exit(1);
+    }
+
+    try {
+      execSync(`git push "${remoteUrl}" "${filteredTip}:${remoteRef}" --force`,
+        { env: { ...process.env, _PREPUSH_FILTER_ACTIVE: '1' }, stdio: 'inherit' });
+    } catch {
+      console.error(`✗ Push to Codeberg failed for ${label}`); process.exit(1);
+    }
+
+    console.log(`✓ ${label} pushed to Codeberg (without .claude/)`);
+    pushed++;
+  }
+
+  if (pushed === 0) process.exit(0);
+  console.log('→ Filtered push complete. Blocking unfiltered push.');
+  process.exit(1);
+});

package/scripts/init.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Project setup script — run via: npm run init
+//
+// Steps:
+//   1. Check Node.js version (requires >=18)
+//   2. Install dependencies (npm install)
+//   3. Install git hooks from scripts/hooks/ into .git/hooks/
+//   4. Run typecheck to verify the setup
+
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, chmodSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+// Auf Windows .cmd-Dateien via cmd.exe aufrufen — kein shell:true nötig, keine Deprecation-Warnung
+const [npmBin, npmBaseArgs] = process.platform === 'win32'
+  ? ['cmd.exe', ['/c', 'npm']]
+  : ['npm', []];
+
+// ---------------------------------------------------------------------------
+// 1. Node.js version check
+// ---------------------------------------------------------------------------
+
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 18) {
+  console.error(`✗ Node.js >= 18 required, found ${process.version}`);
+  process.exit(1);
+}
+console.log(`✓ Node.js ${process.version}`);
+
+// ---------------------------------------------------------------------------
+// 2. Install dependencies
+// ---------------------------------------------------------------------------
+
+console.log('\n→ Installing dependencies...');
+const install = spawnSync(npmBin, [...npmBaseArgs, 'install'], {
+  stdio: 'inherit',
+  cwd: root,
+});
+if (install.status !== 0) {
+  console.error('✗ npm install failed');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Install git hooks
+// ---------------------------------------------------------------------------
+
+console.log('\n→ Installing git hooks...');
+
+const hooksSourceDir = resolve(root, 'scripts/hooks');
+const gitHooksDir = resolve(root, '.git/hooks');
+
+if (!existsSync(gitHooksDir)) {
+  mkdirSync(gitHooksDir, { recursive: true });
+}
+
+const hooks = ['pre-push'];
+for (const hook of hooks) {
+  const src = resolve(hooksSourceDir, `${hook}.mjs`);
+  const dest = resolve(gitHooksDir, hook);
+
+  if (!existsSync(src)) {
+    console.warn(`  ⚠ Hook source not found, skipping: scripts/hooks/${hook}.mjs`);
+    continue;
+  }
+
+  copyFileSync(src, dest);
+
+  // chmod +x (no-op on Windows — git runs hooks directly via shebang)
+  try {
+    chmodSync(dest, 0o755);
+  } catch {
+    // Silently ignore on platforms that don't support chmod
+  }
+
+  console.log(`  ✓ .git/hooks/${hook} installed`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Typecheck
+// ---------------------------------------------------------------------------
+
+console.log('\n→ Running typecheck...');
+const check = spawnSync(npmBin, [...npmBaseArgs, 'run', 'typecheck'], {
+  stdio: 'inherit',
+  cwd: root,
+});
+if (check.status !== 0) {
+  console.error('✗ Typecheck failed — check type errors above');
+  process.exit(1);
+}
+
+console.log('\n✓ Setup complete. Happy hacking!');

package/tests/config.test.ts

@@ -146,6 +146,75 @@ describe('getConfig() – errors', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// HTTP transport configuration
+// ---------------------------------------------------------------------------
+
+describe('getConfig() – HTTP transport', () => {
+  it('uses 127.0.0.1 as default httpHost', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpHost).toBe('127.0.0.1');
+  });
+
+  it('uses 3000 as default httpPort', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpPort).toBe(3000);
+  });
+
+  it('uses PORT when set', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+    vi.stubEnv('PORT', '8080');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpPort).toBe(8080);
+  });
+
+  it('uses MCP_HTTP_HOST when set', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+    vi.stubEnv('MCP_HTTP_HOST', '0.0.0.0');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpHost).toBe('0.0.0.0');
+  });
+
+  it('leaves httpToken undefined when MCP_HTTP_TOKEN is not set', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpToken).toBeUndefined();
+  });
+
+  it('reads httpToken from MCP_HTTP_TOKEN', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+    vi.stubEnv('MCP_HTTP_TOKEN', 'secret-token');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.httpToken).toBe('secret-token');
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Singleton caching
 // ---------------------------------------------------------------------------

package/tests/helpers/search-mocks.ts

@@ -45,6 +45,7 @@ export function makeMockStore(options?: { lastSyncedAt?: string | null; itemCoun
     resetLastSyncedAt: vi.fn(async () => {}),
     getLastKnownTotal: vi.fn(async () => options?.lastKnownTotal ?? null),
     setLastKnownTotal: vi.fn(async () => {}),
+    flush: vi.fn(async () => {}),
   };
 }
 

package/tests/search/store.test.ts

@@ -146,3 +146,48 @@ describe('VectraStore.resetLastSyncedAt', () => {
     expect(await store.getLastSyncedAt()).toBeNull();
   });
 });
+
+describe('VectraStore.addBatch', () => {
+  it('increases in-memory count without persisting to disk', async () => {
+    await store.addBatch([
+      { id: 1, vector: randomVector(), metadata: { summary: 'A' } },
+      { id: 2, vector: randomVector(), metadata: { summary: 'B' } },
+    ]);
+    expect(await store.count()).toBe(2);
+
+    // A new instance reading the same dir must not see the items yet
+    const store2 = new VectraStore(dir);
+    expect(await store2.count()).toBe(0);
+  });
+
+  it('persists items after flush()', async () => {
+    await store.addBatch([
+      { id: 10, vector: randomVector(), metadata: { summary: 'X' } },
+      { id: 11, vector: randomVector(), metadata: { summary: 'Y' } },
+    ]);
+    await store.flush();
+
+    const store2 = new VectraStore(dir);
+    expect(await store2.count()).toBe(2);
+  });
+
+  it('accumulates items across multiple addBatch calls before flush', async () => {
+    await store.addBatch([{ id: 1, vector: randomVector(), metadata: { summary: 'First' } }]);
+    await store.addBatch([{ id: 2, vector: randomVector(), metadata: { summary: 'Second' } }]);
+    await store.flush();
+
+    const store2 = new VectraStore(dir);
+    expect(await store2.count()).toBe(2);
+  });
+});
+
+describe('VectraStore.flush (atomic write)', () => {
+  it('leaves no .tmp file after a successful flush', async () => {
+    const { readdir } = await import('node:fs/promises');
+    await store.addBatch([{ id: 1, vector: randomVector(), metadata: { summary: 'Test' } }]);
+    await store.flush();
+
+    const files = await readdir(join(dir, 'vectra'));
+    expect(files.some(f => f.endsWith('.tmp'))).toBe(false);
+  });
+});

package/tests/search/sync.test.ts

@@ -144,6 +144,60 @@ describe('SearchSyncService.sync – project_id', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// flush / checkpoint behaviour
+// ---------------------------------------------------------------------------
+
+describe('SearchSyncService.sync – flush and checkpoint', () => {
+  function makeIssues(count: number) {
+    return Array.from({ length: count }, (_, i) => ({
+      id: i + 1,
+      summary: `Issue ${i + 1}`,
+      description: `Description ${i + 1}`,
+      updated_at: '2024-03-10T08:00:00Z',
+    }));
+  }
+
+  it('calls flush exactly once when fewer than 100 issues are indexed', async () => {
+    const store = makeMockStore({ lastSyncedAt: null });
+    vi.mocked(fetch).mockResolvedValue(
+      makeResponse(200, JSON.stringify({ issues: makeIssues(50), total_count: 50 }))
+    );
+
+    const service = new SearchSyncService(client, store, embedder);
+    await service.sync();
+
+    // Only the final flush, no checkpoint
+    expect(store.flush).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls flush exactly once when exactly 100 issues are indexed (checkpoint covers all, no redundant final)', async () => {
+    const store = makeMockStore({ lastSyncedAt: null });
+    vi.mocked(fetch).mockResolvedValue(
+      makeResponse(200, JSON.stringify({ issues: makeIssues(100), total_count: 100 }))
+    );
+
+    const service = new SearchSyncService(client, store, embedder);
+    await service.sync();
+
+    // Checkpoint at 100 covers all items; indexedSinceCheckpoint resets to 0 → no redundant final flush
+    expect(store.flush).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls flush twice when 110 issues are indexed (checkpoint at 100 + final for remaining 10)', async () => {
+    const store = makeMockStore({ lastSyncedAt: null });
+    vi.mocked(fetch).mockResolvedValue(
+      makeResponse(200, JSON.stringify({ issues: makeIssues(110), total_count: 110 }))
+    );
+
+    const service = new SearchSyncService(client, store, embedder);
+    await service.sync();
+
+    // Checkpoint at 100, then final flush for remaining 10
+    expect(store.flush).toHaveBeenCalledTimes(2);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // total_count persistence (regression: MantisBT installations without total_count)
 // ---------------------------------------------------------------------------

package/tests/tools/files.test.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { MantisClient } from '../../src/client.js';
 import { registerFileTools } from '../../src/tools/files.js';
@@ -20,7 +21,7 @@ let client: MantisClient;
 beforeEach(() => {
   mockServer = new MockMcpServer();
   client = new MantisClient('https://mantis.example.com', 'test-token');
-  registerFileTools(mockServer as never, client);
+  registerFileTools(mockServer as never, client, undefined);
   vi.stubGlobal('fetch', vi.fn());
 });
 
@@ -272,3 +273,72 @@ describe('upload_file (Base64)', () => {
     expect(result.content[0]!.text).toContain('Error:');
   });
 });
+
+// ---------------------------------------------------------------------------
+// upload_file – Path Traversal protection (uploadDir)
+// ---------------------------------------------------------------------------
+
+describe('upload_file (uploadDir restriction)', () => {
+  const uploadDir = path.resolve('/tmp/uploads');
+
+  beforeEach(() => {
+    // Override the server registered in the outer beforeEach with one that
+    // has uploadDir set.
+    mockServer = new MockMcpServer();
+    client = new MantisClient('https://mantis.example.com', 'test-token');
+    registerFileTools(mockServer as never, client, uploadDir);
+    vi.stubGlobal('fetch', vi.fn());
+  });
+
+  it('allows file_path inside uploadDir', async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      file_path: path.join(uploadDir, 'report.pdf'),
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(readFile).toHaveBeenCalled();
+  });
+
+  it('blocks file_path outside uploadDir', async () => {
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      file_path: '/etc/passwd',
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('not allowed');
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
+  it('blocks path traversal escaping uploadDir', async () => {
+    const result = await mockServer.callTool('upload_file', {
+      issue_id: 42,
+      file_path: path.join(uploadDir, '..', 'secret.txt'),
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('not allowed');
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
+  it('allows any file_path when uploadDir is undefined (no restriction)', async () => {
+    // This uses the outer beforeEach server (uploadDir = undefined).
+    const unrestrictedServer = new MockMcpServer();
+    registerFileTools(unrestrictedServer as never, client, undefined);
+
+    vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
+
+    const result = await unrestrictedServer.callTool('upload_file', {
+      issue_id: 42,
+      file_path: '/etc/passwd',
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(readFile).toHaveBeenCalledWith('/etc/passwd');
+  });
+});

package/tests/tools/issues.test.ts

@@ -474,3 +474,55 @@ describe('list_issues – recorded fixtures', () => {
     expect(parsed.issues).toHaveLength(resolvedInFixture);
   });
 });
+
+// ---------------------------------------------------------------------------
+// update_issue – fields allowlist
+// ---------------------------------------------------------------------------
+
+describe('update_issue – fields allowlist', () => {
+  it('accepts known string fields (summary, description)', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ issue: { id: 1, summary: 'Updated' } })));
+
+    const result = await mockServer.callTool(
+      'update_issue',
+      { id: 1, fields: { summary: 'Updated', description: 'New desc' } },
+      { validate: true },
+    );
+
+    expect(result.isError).toBeUndefined();
+  });
+
+  it('accepts known object fields (status, resolution, handler)', async () => {
+    vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ issue: { id: 1 } })));
+
+    const result = await mockServer.callTool(
+      'update_issue',
+      { id: 1, fields: { status: { name: 'resolved' }, resolution: { id: 20 }, handler: { id: 5 } } },
+      { validate: true },
+    );
+
+    expect(result.isError).toBeUndefined();
+  });
+
+  it('rejects unknown fields without calling the API', async () => {
+    const result = await mockServer.callTool(
+      'update_issue',
+      { id: 1, fields: { reporter: { id: 99 } } },
+      { validate: true },
+    );
+
+    expect(result.isError).toBe(true);
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it('rejects fields with an unknown key mixed with known keys without calling the API', async () => {
+    const result = await mockServer.callTool(
+      'update_issue',
+      { id: 1, fields: { summary: 'ok', unknown_field: 'bad' } },
+      { validate: true },
+    );
+
+    expect(result.isError).toBe(true);
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+  });
+});