@dpesch/mantisbt-mcp-server 1.0.0

package/.env.local

@@ -0,0 +1,2 @@
+MANTIS_BASE_URL=https://mantis.dev.11com7.de
+MANTIS_API_KEY=3vhKDwxVavmCzRUR7Cp0Lk7F8E4dha6n

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.0.0] – 2026-03-15
+
+First stable release.
+
+### Added
+
+**Issues**
+- `get_issue` — retrieve an issue by numeric ID
+- `list_issues` — filter issues by project, status, author, page, and page size
+- `create_issue` — create a new issue
+- `update_issue` — update an existing issue
+- `delete_issue` — delete an issue
+
+**Notes**
+- `list_notes` — list notes of an issue
+- `add_note` — add a note to an issue
+- `delete_note` — delete a note
+
+**Attachments**
+- `list_issue_files` — list attachments of an issue
+
+**Relationships**
+- `add_relationship` — create a relationship between two issues
+
+**Monitors**
+- `add_monitor` — add yourself as a monitor of an issue
+
+**Tags**
+- `list_tags` — list all available tags
+- `attach_tags` — attach tags to an issue
+- `detach_tag` — remove a tag from an issue
+
+**Projects**
+- `list_projects` — list all accessible projects
+- `get_project_versions` — get versions of a project
+- `get_project_categories` — get categories of a project
+- `get_project_users` — get users of a project
+
+**Metadata & System**
+- `get_metadata` — retrieve cached metadata (projects, users, versions, categories)
+- `sync_metadata` — refresh the metadata cache
+- `list_filters` — list saved filters
+- `get_current_user` — retrieve your own user profile
+- `list_languages` — list available languages
+- `get_config` — show server configuration (base URL, cache TTL)
+- `get_mantis_version` — get MantisBT version and check for updates on GitHub
+
+**Infrastructure**
+- stdio and HTTP transport (Streamable HTTP)
+- Metadata cache with configurable TTL (default: 1 hour)
+- Config file fallback (`~/.claude/mantis.json`)
+- `VersionHintService`: appends update hint to API error messages
+- Vitest test suite with 73 unit and fixture-based tests
+- MIT license, `CONTRIBUTING.md`, `README.md`
+
+### Fixed
+- `get_project_categories` was calling `/projects/{id}/categories` (does not exist in MantisBT) — corrected to `GET projects/{id}` with extraction of `.projects[0].categories`
+
+[1.0.0]: https://codeberg.org/dpesch/mantisbt-mcp-server/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominik Pesch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.de.md

@@ -0,0 +1,177 @@
+# MantisBT MCP Server
+
+Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) Server, der die [MantisBT REST API](https://documenter.getpostman.com/view/29959/mantis-bug-tracker-rest-api) in Claude Code und andere MCP-fähige Clients integriert. Issues lesen, erstellen und bearbeiten – direkt aus dem Editor heraus.
+
+## Voraussetzungen
+
+- Node.js ≥ 18
+- MantisBT-Installation mit aktivierter REST-API (ab Version 2.23)
+- MantisBT API-Token (unter *Mein Konto → API-Token* erstellen)
+
+## Installation
+
+**Via npx (empfohlen):**
+
+In `~/.claude/claude_desktop_config.json` (Claude Desktop) oder der lokalen
+`claude_desktop_config.json` (Claude Code) eintragen:
+
+```json
+{
+  "mcpServers": {
+    "mantisbt": {
+      "command": "npx",
+      "args": ["-y", "@dpesch/mantisbt-mcp-server"],
+      "env": {
+        "MANTIS_BASE_URL": "https://deine-mantis-instanz.example.com/api/rest",
+        "MANTIS_API_KEY": "dein-api-token"
+      }
+    }
+  }
+}
+```
+
+**Lokaler Build:**
+
+```bash
+git clone https://codeberg.org/dpesch/mantisbt-mcp-server
+cd mantisbt-mcp-server
+npm install
+npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "mantisbt": {
+      "command": "node",
+      "args": ["/pfad/zum/mantisbt-mcp-server/dist/index.js"],
+      "env": {
+        "MANTIS_BASE_URL": "https://deine-mantis-instanz.example.com/api/rest",
+        "MANTIS_API_KEY": "dein-api-token"
+      }
+    }
+  }
+}
+```
+
+## Konfiguration
+
+### Umgebungsvariablen
+
+| Variable | Pflicht | Standard | Beschreibung |
+|---|---|---|---|
+| `MANTIS_BASE_URL` | ✅ | – | Basis-URL der MantisBT REST API |
+| `MANTIS_API_KEY` | ✅ | – | API-Token für die Authentifizierung |
+| `MANTIS_CACHE_DIR` | – | `~/.cache/mantisbt-mcp` | Verzeichnis für den Metadaten-Cache |
+| `MANTIS_CACHE_TTL` | – | `3600` | Cache-Lebensdauer in Sekunden |
+| `TRANSPORT` | – | `stdio` | Transport-Modus: `stdio` oder `http` |
+| `PORT` | – | `3000` | Port für HTTP-Modus |
+
+### Config-Datei (Fallback)
+
+Falls keine Umgebungsvariablen gesetzt sind, wird `~/.claude/mantis.json` ausgelesen:
+
+```json
+{
+  "base_url": "https://deine-mantis-instanz.example.com/api/rest",
+  "api_key": "dein-api-token"
+}
+```
+
+## Verfügbare Tools
+
+### Issues
+
+| Tool | Beschreibung |
+|---|---|
+| `get_issue` | Ein Issue anhand seiner ID abrufen |
+| `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern |
+| `create_issue` | Neues Issue anlegen |
+| `update_issue` | Bestehendes Issue bearbeiten |
+| `delete_issue` | Issue löschen |
+
+### Notizen
+
+| Tool | Beschreibung |
+|---|---|
+| `list_notes` | Alle Notizen eines Issues auflisten |
+| `add_note` | Notiz zu einem Issue hinzufügen |
+| `delete_note` | Notiz löschen |
+
+### Anhänge
+
+| Tool | Beschreibung |
+|---|---|
+| `list_issue_files` | Anhänge eines Issues auflisten |
+
+### Beziehungen
+
+| Tool | Beschreibung |
+|---|---|
+| `add_relationship` | Beziehung zwischen zwei Issues erstellen |
+
+### Beobachter
+
+| Tool | Beschreibung |
+|---|---|
+| `add_monitor` | Sich selbst als Beobachter eines Issues eintragen |
+
+### Tags
+
+| Tool | Beschreibung |
+|---|---|
+| `list_tags` | Alle verfügbaren Tags auflisten |
+| `attach_tags` | Tags an ein Issue hängen |
+| `detach_tag` | Tag von einem Issue entfernen |
+
+### Projekte
+
+| Tool | Beschreibung |
+|---|---|
+| `list_projects` | Alle zugänglichen Projekte auflisten |
+| `get_project_versions` | Versionen eines Projekts abrufen |
+| `get_project_categories` | Kategorien eines Projekts abrufen |
+| `get_project_users` | Benutzer eines Projekts abrufen |
+
+### Metadaten & System
+
+| Tool | Beschreibung |
+|---|---|
+| `get_metadata` | Gecachte Metadaten abrufen (Projekte, Benutzer, Versionen, Kategorien) |
+| `sync_metadata` | Metadaten-Cache neu befüllen |
+| `list_filters` | Gespeicherte Filter auflisten |
+| `get_current_user` | Eigenes Benutzerprofil abrufen |
+| `list_languages` | Verfügbare Sprachen auflisten |
+| `get_config` | Server-Konfiguration (Basis-URL, Cache-TTL) anzeigen |
+| `get_mantis_version` | MantisBT-Version abrufen und auf Updates prüfen |
+
+## HTTP-Modus
+
+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
+```
+
+Healthcheck: `GET http://localhost:3456/health`
+
+## Entwicklung
+
+```bash
+npm install          # Abhängigkeiten installieren
+npm run build        # TypeScript → dist/ kompilieren
+npm run typecheck    # Typprüfung ohne Ausgabe
+npm run dev          # Watch-Modus für Entwicklung
+npm test             # Tests ausführen (vitest)
+npm run test:watch   # Tests im Watch-Modus
+npm run test:coverage # Coverage-Report
+```
+
+## Lizenz
+
+MIT – siehe [LICENSE](LICENSE)
+
+## Mitwirken
+
+Beiträge willkommen! Bitte [CONTRIBUTING.md](CONTRIBUTING.md) lesen.
+Repository: [codeberg.org/dpesch/mantisbt-mcp-server](https://codeberg.org/dpesch/mantisbt-mcp-server)

package/README.md

@@ -0,0 +1,177 @@
+# MantisBT MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that integrates the [MantisBT REST API](https://documenter.getpostman.com/view/29959/mantis-bug-tracker-rest-api) into Claude Code and other MCP-capable clients. Read, create, and update issues directly from your editor.
+
+## Requirements
+
+- Node.js ≥ 18
+- MantisBT installation with REST API enabled (version 2.23+)
+- MantisBT API token (create under *My Account → API Tokens*)
+
+## Installation
+
+**Via npx (recommended):**
+
+Add to `~/.claude/claude_desktop_config.json` (Claude Desktop) or your local
+`claude_desktop_config.json` (Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "mantisbt": {
+      "command": "npx",
+      "args": ["-y", "@dpesch/mantisbt-mcp-server"],
+      "env": {
+        "MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
+        "MANTIS_API_KEY": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+**Local build:**
+
+```bash
+git clone https://codeberg.org/dpesch/mantisbt-mcp-server
+cd mantisbt-mcp-server
+npm install
+npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "mantisbt": {
+      "command": "node",
+      "args": ["/path/to/mantisbt-mcp-server/dist/index.js"],
+      "env": {
+        "MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
+        "MANTIS_API_KEY": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `MANTIS_BASE_URL` | ✅ | – | Base URL of the MantisBT REST API |
+| `MANTIS_API_KEY` | ✅ | – | API token for authentication |
+| `MANTIS_CACHE_DIR` | – | `~/.cache/mantisbt-mcp` | Directory for the metadata cache |
+| `MANTIS_CACHE_TTL` | – | `3600` | Cache lifetime in seconds |
+| `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
+| `PORT` | – | `3000` | Port for HTTP mode |
+
+### Config file (fallback)
+
+If no environment variables are set, `~/.claude/mantis.json` is read:
+
+```json
+{
+  "base_url": "https://your-mantis.example.com/api/rest",
+  "api_key": "your-api-token"
+}
+```
+
+## Available tools
+
+### Issues
+
+| Tool | Description |
+|---|---|
+| `get_issue` | Retrieve an issue by its numeric ID |
+| `list_issues` | Filter issues by project, status, author, and more |
+| `create_issue` | Create a new issue |
+| `update_issue` | Update an existing issue |
+| `delete_issue` | Delete an issue |
+
+### Notes
+
+| Tool | Description |
+|---|---|
+| `list_notes` | List all notes of an issue |
+| `add_note` | Add a note to an issue |
+| `delete_note` | Delete a note |
+
+### Attachments
+
+| Tool | Description |
+|---|---|
+| `list_issue_files` | List attachments of an issue |
+
+### Relationships
+
+| Tool | Description |
+|---|---|
+| `add_relationship` | Create a relationship between two issues |
+
+### Monitors
+
+| Tool | Description |
+|---|---|
+| `add_monitor` | Add yourself as a monitor of an issue |
+
+### Tags
+
+| Tool | Description |
+|---|---|
+| `list_tags` | List all available tags |
+| `attach_tags` | Attach tags to an issue |
+| `detach_tag` | Remove a tag from an issue |
+
+### Projects
+
+| Tool | Description |
+|---|---|
+| `list_projects` | List all accessible projects |
+| `get_project_versions` | Get versions of a project |
+| `get_project_categories` | Get categories of a project |
+| `get_project_users` | Get users of a project |
+
+### Metadata & system
+
+| Tool | Description |
+|---|---|
+| `get_metadata` | Retrieve cached metadata (projects, users, versions, categories) |
+| `sync_metadata` | Refresh the metadata cache |
+| `list_filters` | List saved filters |
+| `get_current_user` | Retrieve your own user profile |
+| `list_languages` | List available languages |
+| `get_config` | Show server configuration (base URL, cache TTL) |
+| `get_mantis_version` | Get MantisBT version and check for updates |
+
+## HTTP mode
+
+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
+```
+
+Health check: `GET http://localhost:3456/health`
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/
+npm run typecheck    # Type check without output
+npm run dev          # Watch mode for development
+npm test             # Run tests (vitest)
+npm run test:watch   # Run tests in watch mode
+npm run test:coverage # Coverage report
+```
+
+## License
+
+MIT – see [LICENSE](LICENSE)
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).
+Repository: [codeberg.org/dpesch/mantisbt-mcp-server](https://codeberg.org/dpesch/mantisbt-mcp-server)

package/dist/cache.js

@@ -0,0 +1,52 @@
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// MetadataCache
+// ---------------------------------------------------------------------------
+export class MetadataCache {
+    filePath;
+    ttlSeconds;
+    cacheDir;
+    constructor(cacheDir, ttlSeconds) {
+        this.cacheDir = cacheDir;
+        this.filePath = join(cacheDir, 'metadata.json');
+        this.ttlSeconds = ttlSeconds;
+    }
+    async isValid() {
+        try {
+            const raw = await readFile(this.filePath, 'utf-8');
+            const file = JSON.parse(raw);
+            const ageSeconds = (Date.now() - file.timestamp) / 1000;
+            return ageSeconds < this.ttlSeconds;
+        }
+        catch {
+            return false;
+        }
+    }
+    async load() {
+        try {
+            const raw = await readFile(this.filePath, 'utf-8');
+            const file = JSON.parse(raw);
+            return file.data;
+        }
+        catch {
+            return null;
+        }
+    }
+    async save(data) {
+        await mkdir(this.cacheDir, { recursive: true });
+        const file = {
+            timestamp: Date.now(),
+            data,
+        };
+        await writeFile(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+    }
+    async invalidate() {
+        try {
+            await unlink(this.filePath);
+        }
+        catch {
+            // Already gone — that is fine
+        }
+    }
+}

package/dist/client.js

@@ -0,0 +1,114 @@
+// ---------------------------------------------------------------------------
+// MantisApiError
+// ---------------------------------------------------------------------------
+export class MantisApiError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(`MantisBT API error ${statusCode}: ${message}`);
+        this.statusCode = statusCode;
+        this.name = 'MantisApiError';
+    }
+}
+export class MantisClient {
+    baseUrl;
+    apiKey;
+    responseObserver;
+    constructor(baseUrl, apiKey, responseObserver) {
+        // Ensure base URL ends without trailing slash; we always append /api/rest/
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
+        this.responseObserver = responseObserver;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    buildUrl(path, params) {
+        const url = new URL(`${this.baseUrl}/api/rest/${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    headers() {
+        return {
+            'Authorization': this.apiKey,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+        };
+    }
+    async handleResponse(response) {
+        if (response.ok) {
+            this.responseObserver?.(response);
+            // Some DELETE endpoints return 204 No Content
+            if (response.status === 204) {
+                return undefined;
+            }
+            const text = await response.text();
+            if (!text)
+                return undefined;
+            return JSON.parse(text);
+        }
+        let message = response.statusText;
+        try {
+            const body = await response.text();
+            if (body) {
+                const parsed = JSON.parse(body);
+                if (parsed.message)
+                    message = parsed.message;
+                else
+                    message = body;
+            }
+        }
+        catch {
+            // ignore parse errors — keep statusText as message
+        }
+        throw new MantisApiError(response.status, message);
+    }
+    // ---------------------------------------------------------------------------
+    // Public API methods
+    // ---------------------------------------------------------------------------
+    async get(path, params) {
+        const response = await fetch(this.buildUrl(path, params), {
+            method: 'GET',
+            headers: this.headers(),
+        });
+        return this.handleResponse(response);
+    }
+    async post(path, body) {
+        const response = await fetch(this.buildUrl(path), {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        return this.handleResponse(response);
+    }
+    async patch(path, body) {
+        const response = await fetch(this.buildUrl(path), {
+            method: 'PATCH',
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        return this.handleResponse(response);
+    }
+    async delete(path) {
+        const response = await fetch(this.buildUrl(path), {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        return this.handleResponse(response);
+    }
+    async getVersion() {
+        const response = await fetch(this.buildUrl('users/me'), {
+            method: 'GET',
+            headers: this.headers(),
+        });
+        if (!response.ok) {
+            throw new MantisApiError(response.status, response.statusText);
+        }
+        return response.headers.get('X-Mantis-Version') ?? 'unknown';
+    }
+}

package/dist/config.js

@@ -0,0 +1,54 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+async function readMantisJson() {
+    const filePath = join(homedir(), '.claude', 'mantis.json');
+    try {
+        const raw = await readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+let cachedConfig = null;
+export async function getConfig() {
+    if (cachedConfig)
+        return cachedConfig;
+    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
+    if (!baseUrl || !apiKey) {
+        const json = await readMantisJson();
+        if (json) {
+            if (!baseUrl && json.base_url)
+                baseUrl = json.base_url;
+            if (!apiKey && json.api_key)
+                apiKey = json.api_key;
+        }
+    }
+    const missing = [];
+    if (!baseUrl)
+        missing.push('MANTIS_BASE_URL');
+    if (!apiKey)
+        missing.push('MANTIS_API_KEY');
+    if (missing.length > 0) {
+        throw new Error(`Missing required MantisBT configuration: ${missing.join(', ')}.\n` +
+            `Set the environment variables or provide ~/.claude/mantis.json with keys "base_url" and "api_key".`);
+    }
+    const defaultCacheDir = join(homedir(), '.cache', 'mantisbt-mcp');
+    const cacheDir = process.env.MANTIS_CACHE_DIR ?? defaultCacheDir;
+    const cacheTtl = process.env.MANTIS_CACHE_TTL
+        ? parseInt(process.env.MANTIS_CACHE_TTL, 10)
+        : 3600;
+    cachedConfig = {
+        baseUrl: baseUrl.replace(/\/$/, ''), // strip trailing slash
+        apiKey,
+        cacheDir,
+        cacheTtl,
+    };
+    return cachedConfig;
+}

package/dist/constants.js

@@ -0,0 +1,23 @@
+// ---------------------------------------------------------------------------
+// Relationship type IDs
+// ---------------------------------------------------------------------------
+// Note: the MantisBT REST API only accepts numeric type IDs, not string names.
+export const RELATIONSHIP_TYPES = {
+    DUPLICATE_OF: 0,
+    RELATED_TO: 1,
+    PARENT_OF: 2, // "depends on" — this issue depends on the target
+    CHILD_OF: 3, // "blocks" — this issue blocks the target
+    HAS_DUPLICATE: 4,
+};
+// ---------------------------------------------------------------------------
+// Status names (internal English names used in API calls)
+// ---------------------------------------------------------------------------
+export const STATUS_NAMES = [
+    'new',
+    'feedback',
+    'acknowledged',
+    'confirmed',
+    'assigned',
+    'resolved',
+    'closed',
+];