@dpesch/mantisbt-mcp-server 1.0.0

package/dist/tools/notes.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+export function registerNoteTools(server, client) {
+    // ---------------------------------------------------------------------------
+    // list_notes
+    // ---------------------------------------------------------------------------
+    server.registerTool('list_notes', {
+        title: 'List Issue Notes',
+        description: 'List all notes (comments) attached to a MantisBT issue.',
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ issue_id }) => {
+        try {
+            const result = await client.get(`issues/${issue_id}`);
+            const notes = result.issues?.[0]?.notes ?? [];
+            return {
+                content: [{ type: 'text', text: JSON.stringify(notes, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // add_note
+    // ---------------------------------------------------------------------------
+    server.registerTool('add_note', {
+        title: 'Add Note to Issue',
+        description: 'Add a note (comment) to an existing MantisBT issue. Full UTF-8 text is supported.',
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+            text: z.string().min(1).describe('Note text (supports full UTF-8, markdown will be stored as-is)'),
+            view_state: z.enum(['public', 'private']).default('public').describe('Visibility of the note (default: public)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, text, view_state }) => {
+        try {
+            const body = {
+                text,
+                view_state: { name: view_state },
+            };
+            const result = await client.post(`issues/${issue_id}/notes`, body);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.note ?? result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // delete_note
+    // ---------------------------------------------------------------------------
+    server.registerTool('delete_note', {
+        title: 'Delete Note',
+        description: 'Permanently delete a note from a MantisBT issue. This action is irreversible.',
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID that owns the note'),
+            note_id: z.number().int().positive().describe('Numeric note ID to delete'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+        },
+    }, async ({ issue_id, note_id }) => {
+        try {
+            await client.delete(`issues/${issue_id}/notes/${note_id}`);
+            return {
+                content: [{ type: 'text', text: `Note #${note_id} deleted from issue #${issue_id}.` }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/projects.js

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+const ALL_PROJECTS_PREFIX = '[All Projects] ';
+export function registerProjectTools(server, client) {
+    // ---------------------------------------------------------------------------
+    // list_projects
+    // ---------------------------------------------------------------------------
+    server.registerTool('list_projects', {
+        title: 'List Projects',
+        description: 'List all MantisBT projects accessible to the current API user.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async () => {
+        try {
+            const result = await client.get('projects');
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.projects ?? result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // get_project_users
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_project_users', {
+        title: 'Get Project Users',
+        description: 'List all users with access to a specific MantisBT project.',
+        inputSchema: z.object({
+            project_id: z.number().int().positive().describe('Numeric project ID'),
+            access_level: z.number().int().optional().describe('Minimum access level filter (e.g. 55 = developer, 90 = manager)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id, access_level }) => {
+        try {
+            const params = {};
+            if (access_level !== undefined)
+                params.access_level = access_level;
+            const result = await client.get(`projects/${project_id}/users`, params);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.users ?? result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // get_project_versions
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_project_versions', {
+        title: 'Get Project Versions',
+        description: 'List all versions defined for a MantisBT project.',
+        inputSchema: z.object({
+            project_id: z.number().int().positive().describe('Numeric project ID'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get(`projects/${project_id}/versions`);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.versions ?? result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // get_project_categories
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_project_categories', {
+        title: 'Get Project Categories',
+        description: `List all categories available for a MantisBT project.
+
+Note: The MantisBT API returns global (cross-project) categories with a "[All Projects] " prefix.
+This tool strips that prefix so the returned names can be used directly when creating issues.`,
+        inputSchema: z.object({
+            project_id: z.number().int().positive().describe('Numeric project ID'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id }) => {
+        try {
+            const result = await client.get(`projects/${project_id}`);
+            const raw = result.projects?.[0]?.categories ?? [];
+            const categories = raw.map((cat) => ({
+                ...cat,
+                name: cat.name.startsWith(ALL_PROJECTS_PREFIX)
+                    ? cat.name.slice(ALL_PROJECTS_PREFIX.length)
+                    : cat.name,
+            }));
+            return {
+                content: [{ type: 'text', text: JSON.stringify(categories, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/relationships.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { RELATIONSHIP_TYPES } from '../constants.js';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+export function registerRelationshipTools(server, client) {
+    // ---------------------------------------------------------------------------
+    // add_relationship
+    // ---------------------------------------------------------------------------
+    server.registerTool('add_relationship', {
+        title: 'Add Issue Relationship',
+        description: `Add a relationship between two MantisBT issues.
+
+Relationship type IDs:
+- ${RELATIONSHIP_TYPES.DUPLICATE_OF} = duplicate_of    — this issue is a duplicate of target
+- ${RELATIONSHIP_TYPES.RELATED_TO}   = related_to      — this issue is related to target
+- ${RELATIONSHIP_TYPES.PARENT_OF}    = parent_of       — this issue depends on target (target must be done first)
+- ${RELATIONSHIP_TYPES.CHILD_OF}     = child_of        — this issue blocks target (target can't proceed until this is done)
+- ${RELATIONSHIP_TYPES.HAS_DUPLICATE} = has_duplicate  — this issue has target as a duplicate
+
+Directionality note: "A child_of B" means A blocks B. "A parent_of B" means A depends on B.
+
+Important: The API only accepts numeric type IDs, not string names.`,
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('The source issue ID (the one the relationship is added to)'),
+            target_id: z.number().int().positive().describe('The target issue ID'),
+            type_id: z.number().int().min(0).max(4).describe(`Relationship type ID: 0=duplicate_of, 1=related_to, 2=parent_of (depends on), 3=child_of (blocks), 4=has_duplicate`),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, target_id, type_id }) => {
+        try {
+            const body = {
+                issue: { id: target_id },
+                type: { id: type_id },
+            };
+            const result = await client.post(`issues/${issue_id}/relationships`, body);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/tags.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+export function registerTagTools(server, client) {
+    // ---------------------------------------------------------------------------
+    // attach_tags
+    // ---------------------------------------------------------------------------
+    server.registerTool('attach_tags', {
+        title: 'Attach Tags to Issue',
+        description: `Attach one or more tags to a MantisBT issue.
+
+Each tag can be specified either by ID or by name. If a tag name is provided
+that does not exist yet, MantisBT will create it automatically (requires
+tag_create_threshold permission, default: REPORTER).
+
+Requires tag_attach_threshold permission (default: REPORTER).`,
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+            tags: z.array(z.object({
+                id: z.number().int().positive().optional().describe('Tag ID'),
+                name: z.string().min(1).optional().describe('Tag name'),
+            }).refine(t => t.id !== undefined || t.name !== undefined, {
+                message: 'Each tag must have at least an id or a name',
+            })).min(1).describe('Tags to attach — each entry needs at least id or name'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+    }, async ({ issue_id, tags }) => {
+        try {
+            await client.post(`issues/${issue_id}/tags`, { tags });
+            return {
+                content: [{ type: 'text', text: `Tags successfully attached to issue #${issue_id}.` }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // detach_tag
+    // ---------------------------------------------------------------------------
+    server.registerTool('detach_tag', {
+        title: 'Detach Tag from Issue',
+        description: `Remove a tag from a MantisBT issue.
+
+Requires tag_detach_own_threshold (default: REPORTER) for own tags,
+or tag_detach_threshold (default: DEVELOPER) for tags attached by others.`,
+        inputSchema: z.object({
+            issue_id: z.number().int().positive().describe('Numeric issue ID'),
+            tag_id: z.number().int().positive().describe('Numeric tag ID to remove'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ issue_id, tag_id }) => {
+        try {
+            await client.delete(`issues/${issue_id}/tags/${tag_id}`);
+            return {
+                content: [{ type: 'text', text: `Tag #${tag_id} successfully removed from issue #${issue_id}.` }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/users.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { getVersionHint } from '../version-hint.js';
+function errorText(msg) {
+    const vh = getVersionHint();
+    vh?.triggerLatestVersionFetch();
+    const hint = vh?.getUpdateHint();
+    return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
+}
+export function registerUserTools(server, client) {
+    // ---------------------------------------------------------------------------
+    // get_current_user
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_current_user', {
+        title: 'Get Current User',
+        description: 'Retrieve the profile of the user associated with the current API key.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async () => {
+        try {
+            const result = await client.get('users/me');
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+}

package/dist/tools/version.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { parseVersion, compareVersions } from '../version-hint.js';
+export function registerVersionTools(server, client, versionHint) {
+    // ---------------------------------------------------------------------------
+    // get_mantis_version
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_mantis_version', {
+        title: 'Get MantisBT Version',
+        description: `Returns the version of the connected MantisBT installation and optionally compares it against the latest official release on GitHub.
+
+The version is read from the X-Mantis-Version response header sent by every API call.
+The GitHub comparison requires an outbound HTTPS request to the GitHub API.`,
+        inputSchema: z.object({
+            check_latest: z.boolean().default(true).describe('Whether to fetch the latest release from GitHub and compare (default: true)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ check_latest }) => {
+        try {
+            const installedRaw = await client.getVersion();
+            const result = { installed_version: installedRaw };
+            if (check_latest) {
+                versionHint.triggerLatestVersionFetch();
+                const latestRaw = await versionHint.waitForLatestVersion(5000);
+                result.latest_version = latestRaw;
+                if (latestRaw === null) {
+                    result.status = 'unknown';
+                    result.github_note = 'Could not fetch latest version from GitHub (timeout or network error).';
+                }
+                else {
+                    const installed = parseVersion(installedRaw);
+                    const latest = parseVersion(latestRaw);
+                    if (installed && latest) {
+                        const cmp = compareVersions(installed, latest);
+                        result.status = cmp === 0
+                            ? 'up-to-date'
+                            : cmp > 0
+                                ? 'newer-than-release'
+                                : 'update-available';
+                    }
+                    else {
+                        result.status = 'unknown';
+                    }
+                }
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Common building blocks
+// ---------------------------------------------------------------------------
+export {};

package/dist/version-hint.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// Version parsing utilities
+// ---------------------------------------------------------------------------
+export function parseVersion(raw) {
+    const match = raw.replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+export function compareVersions(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// VersionHintService
+// ---------------------------------------------------------------------------
+const MANTISBT_TAGS_URL = 'https://api.github.com/repos/mantisbt/mantisbt/tags?per_page=10';
+/**
+ * Reads the installed MantisBT version from API response headers and lazily
+ * fetches the latest release from GitHub. Provides a non-blocking update hint
+ * that can be appended to API error messages.
+ *
+ * Intentionally has no imports from the rest of this project to avoid
+ * circular dependencies.
+ */
+export class VersionHintService {
+    installedVersion = null;
+    latestVersion = null;
+    fetchStarted = false;
+    /** Called by MantisClient after every successful API response. */
+    onSuccessfulResponse(response) {
+        if (!this.installedVersion) {
+            const v = response.headers.get('X-Mantis-Version');
+            if (v)
+                this.installedVersion = v;
+        }
+    }
+    /**
+     * Starts the GitHub fetch exactly once (fire-and-forget).
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    triggerLatestVersionFetch() {
+        if (this.fetchStarted)
+            return;
+        this.fetchStarted = true;
+        void this.doFetch();
+    }
+    async doFetch() {
+        try {
+            const resp = await fetch(MANTISBT_TAGS_URL, {
+                headers: {
+                    'Accept': 'application/vnd.github+json',
+                    'User-Agent': 'mantisbt-mcp-server',
+                },
+            });
+            if (!resp.ok)
+                return;
+            const tags = await resp.json();
+            const tag = tags.find(t => /^release-\d+\.\d+\.\d+$/.test(t.name));
+            this.latestVersion = tag ? tag.name.replace('release-', '') : null;
+        }
+        catch {
+            // Network error — no hint, no crash
+        }
+    }
+    /**
+     * Returns an update hint string if a newer version is known, or null.
+     * Never blocks — returns null while the GitHub fetch is still in flight.
+     */
+    getUpdateHint() {
+        if (!this.installedVersion || !this.latestVersion)
+            return null;
+        const installed = parseVersion(this.installedVersion);
+        const latest = parseVersion(this.latestVersion);
+        if (!installed || !latest)
+            return null;
+        if (compareVersions(installed, latest) < 0) {
+            return (`Note: MantisBT ${this.latestVersion} is available ` +
+                `(installed: ${this.installedVersion}) — updating may resolve this issue.`);
+        }
+        return null;
+    }
+    getInstalledVersion() { return this.installedVersion; }
+    getLatestVersion() { return this.latestVersion; }
+    /**
+     * Waits up to `timeoutMs` for the GitHub fetch to complete.
+     * Used by the get_mantis_version tool where blocking is acceptable.
+     */
+    async waitForLatestVersion(timeoutMs = 5000) {
+        if (this.latestVersion !== null)
+            return this.latestVersion;
+        if (!this.fetchStarted)
+            return null;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (this.latestVersion !== null)
+                return this.latestVersion;
+            await new Promise(r => setTimeout(r, 100));
+        }
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-level singleton (one per server process)
+// ---------------------------------------------------------------------------
+let globalInstance = null;
+export function setGlobalVersionHint(svc) {
+    globalInstance = svc;
+}
+export function getVersionHint() {
+    return globalInstance;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@dpesch/mantisbt-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
+  "author": "Dominik Pesch",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/dpesch/mantisbt-mcp-server"
+  },
+  "keywords": ["mcp", "mantisbt", "bugtracker", "mantis", "model-context-protocol"],
+  "main": "dist/index.js",
+  "bin": {
+    "mantisbt-mcp-server": "dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:record": "tsx scripts/record-fixtures.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}