@dpesch/mantisbt-mcp-server 1.10.0 → 1.10.2

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test

package/CHANGELOG.md

@@ -7,6 +7,33 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.10.2] – 2026-05-03
+
+### Changed
+- Improved descriptions for `create_issue`, `add_monitor`, `add_note`, `delete_note`, `get_project_users`, and `get_project_versions`: response shapes, prerequisites, and cross-references to related tools (e.g. `find_project_member`, `get_issue_enums`) are now spelled out in each tool description — no behavioural change.
+
+### Fixed
+- HTTP transport (`TRANSPORT=http`): concurrent requests (e.g. MCP Inspector sending `resources/list`, `resources/read`, and `tools/list` in parallel) caused `server.close()` to kill the transport of a still-running request, resulting in `ECONNRESET` on the client side. Fixed by serialising requests through a Promise-based queue — each request waits for the previous transport to be fully closed before connecting its own.
+
+---
+
+## [1.10.1] – 2026-05-02
+
+### Added
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`): runs on push and pull requests to `main`; steps are typecheck, build, and test on Node.js 20.
+
+### Changed
+- Improved descriptions for `upload_file` and `list_issue_files`: both now include return shape, usage guidelines, and cross-references to related tools.
+
+### Fixed
+- `upload_file`: removed Zod `.refine()` calls from `inputSchema`. MCP SDK 1.27.x serialized `ZodEffects` (the type produced by `.refine()`) to an empty `properties: {}` object, making all parameters invisible to clients. Imperative validation in the handler is unchanged — the same constraints are still enforced at runtime.
+
+---
+
 ## [1.10.0] – 2026-04-11
 
 ### Added

package/README.de.md

@@ -119,7 +119,7 @@ npm run build
 
 | Tool | Beschreibung |
 |---|---|
-| `add_monitor` | Sich selbst als Beobachter eines Issues eintragen |
+| `add_monitor` | Einen Benutzer als Beobachter eines Issues eintragen |
 | `remove_monitor` | Benutzer als Beobachter eines Issues austragen |
 
 ### Tags

package/README.md

@@ -119,7 +119,7 @@ npm run build
 
 | Tool | Description |
 |---|---|
-| `add_monitor` | Add yourself as a monitor of an issue |
+| `add_monitor` | Add a user as a monitor of an issue |
 | `remove_monitor` | Remove a user as a monitor of an issue |
 
 ### Tags

package/dist/index.js

@@ -88,6 +88,12 @@ async function runHttp() {
     const startupConfig = await getStartupConfig();
     const server = await createMcpServer();
     const port = startupConfig.httpPort;
+    // Serialize stateless requests: each request waits for the previous transport
+    // to be fully closed before connecting a new one. Without this, concurrent
+    // requests (e.g. from MCP Inspector sending resources/list + resources/read +
+    // tools/list in parallel) would cause server.close() to kill the transport of
+    // a still-running request, leaving those responses never sent.
+    let requestQueue = Promise.resolve();
     const httpServer = createServer(async (req, res) => {
         if (req.method === 'POST' && req.url === '/mcp') {
             if (startupConfig.httpToken) {
@@ -100,28 +106,32 @@ async function runHttp() {
             }
             const chunks = [];
             req.on('data', (chunk) => chunks.push(chunk));
-            req.on('end', async () => {
-                try {
-                    const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-                    const transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: undefined,
-                        enableJsonResponse: true,
-                    });
-                    res.on('close', () => { void transport.close(); });
-                    // Disconnect from any previous transport before connecting the new one.
-                    // The res.on('close') handler above closes the transport asynchronously,
-                    // but the next request may arrive before it fires — causing connect() to
-                    // throw "Already connected". Explicitly closing first avoids that race.
-                    await server.close();
-                    await server.connect(transport);
-                    await transport.handleRequest(req, res, body);
-                }
-                catch {
-                    if (!res.headersSent) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Bad Request' }));
+            req.on('end', () => {
+                const prev = requestQueue;
+                let releaseLock;
+                requestQueue = new Promise(resolve => { releaseLock = resolve; });
+                void prev.then(async () => {
+                    try {
+                        const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                        const transport = new StreamableHTTPServerTransport({
+                            sessionIdGenerator: undefined,
+                            enableJsonResponse: true,
+                        });
+                        await server.connect(transport);
+                        await transport.handleRequest(req, res, body);
                     }
-                }
+                    catch (err) {
+                        console.error('[HTTP handler error]', err instanceof Error ? err.stack : err);
+                        if (!res.headersSent) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'Bad Request' }));
+                        }
+                    }
+                    finally {
+                        await server.close();
+                        releaseLock();
+                    }
+                });
             });
         }
         else if (req.method === 'GET' && req.url === '/health') {

package/dist/tools/files.js

@@ -15,7 +15,9 @@ export function registerFileTools(server, client, uploadDir) {
     // ---------------------------------------------------------------------------
     server.registerTool('list_issue_files', {
         title: 'List Issue File Attachments',
-        description: 'List all file attachments of a MantisBT issue.',
+        description: `List all file attachments of a MantisBT issue. Returns an array of attachment objects, each containing id, filename, size in bytes, content_type, and download_url. Returns an empty array if the issue has no attachments.
+
+Use this tool when you need to inspect or enumerate files attached to an issue. To add a new attachment, use upload_file instead. To retrieve full issue details that include attachments alongside other fields, use get_issue instead.`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
         }),
@@ -42,13 +44,15 @@ export function registerFileTools(server, client, uploadDir) {
     // ---------------------------------------------------------------------------
     server.registerTool('upload_file', {
         title: 'Upload File Attachment',
-        description: `Upload a file as an attachment to a MantisBT issue via multipart/form-data.
+        description: `Upload a file as an attachment to a MantisBT issue. Adds the file to the issue without modifying any issue fields or status. Returns the created attachment metadata on success.
+
+Two input modes — exactly one must be provided:
+- file_path: absolute path to a local file; filename is derived from the path automatically
+- content: Base64-encoded file content; filename must be supplied explicitly via the filename parameter
 
-Two input modes (exactly one must be provided):
-- file_path: absolute path to a local file — filename is derived from the path automatically
-- content: Base64-encoded file content — filename must be supplied explicitly via the filename parameter
+The optional content_type sets the MIME type (e.g. "image/png"); defaults to "application/octet-stream". Use the optional description to annotate the attachment.
 
-The optional content_type parameter sets the MIME type (e.g. "image/png"). If omitted, "application/octet-stream" is used.`,
+Use this tool to attach files such as logs, screenshots, or patches to an existing issue. To list existing attachments, use list_issue_files. To retrieve issue details, use get_issue.`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
             file_path: z.string().min(1).optional().describe('Absolute path to the local file to upload (mutually exclusive with content)'),
@@ -56,12 +60,6 @@ The optional content_type parameter sets the MIME type (e.g. "image/png"). If om
             filename: z.string().min(1).optional().describe('File name for the attachment (required when using content; overrides the derived name when using file_path)'),
             content_type: z.string().optional().describe('MIME type of the file, e.g. "image/png" (default: "application/octet-stream")'),
             description: z.string().optional().describe('Optional description for the attachment'),
-        }).refine(d => !!(d.file_path ?? d.content), {
-            message: 'Either file_path or content must be provided',
-        }).refine(d => !(d.file_path && d.content), {
-            message: 'Only one of file_path or content may be provided',
-        }).refine(d => !d.content || !!d.filename, {
-            message: 'filename is required when using content',
         }),
         annotations: {
             readOnlyHint: false,

package/dist/tools/issues.js

@@ -250,23 +250,34 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('create_issue', {
         title: 'Create Issue',
-        description: 'Create a new MantisBT issue. Returns the created issue including its assigned ID.',
+        description: `Create a new MantisBT issue. Returns the full created issue object including the assigned id, summary, status, priority, severity, category, reporter, created_at, and view_url.
+
+Required fields: summary, description, project_id, category. All other fields are optional with sensible defaults (priority: "normal", severity: "minor").
+
+Recommended workflow:
+1. Call get_project_categories to obtain a valid category name
+2. Optionally call get_project_versions to obtain version names
+3. Optionally call find_project_member to resolve the assignee's username
+
+Both priority and severity accept canonical English names or localized labels from the connected MantisBT instance — call get_issue_enums to see all available values.
+
+For the handler, prefer the username field (resolved server-side) over handler_id when working interactively.`,
         inputSchema: z.object({
-            summary: z.string().min(1).describe('Issue summary/title'),
-            description: z.string().min(1).describe('Detailed issue description. Required — do not create issues without a description. Plain text or Markdown.'),
-            project_id: z.coerce.number().int().positive().describe('Project ID the issue belongs to'),
-            category: z.string().min(1).describe('Category name (use get_project_categories to list available categories)'),
-            priority: z.string().default('normal').describe('Priority: canonical English name (none, low, normal, high, urgent, immediate) or localized label. Default: "normal". Use get_issue_enums to see all available values.'),
-            severity: z.string().default('minor').describe('Severity: canonical English name (feature, trivial, text, tweak, minor, major, crash, block) or localized label. Default: "minor". Use get_issue_enums to see all available values.'),
-            handler_id: z.coerce.number().int().positive().optional().describe('User ID of the person to assign the issue to'),
-            handler: z.string().optional().describe('Username (login name) of the person to assign the issue to. Alternative to handler_id — the server resolves the name to a user ID from the project members. Use get_project_users to see available users.'),
-            version: z.string().optional().describe('Affected product version name (use get_project_versions to list available versions)'),
-            target_version: z.string().optional().describe('Target version name — version in which the issue is planned to be fixed (use get_project_versions to list available versions)'),
-            fixed_in_version: z.string().optional().describe('Version name in which the issue was fixed (use get_project_versions to list available versions)'),
-            steps_to_reproduce: z.string().optional().describe('Steps to reproduce the issue. Plain text or Markdown.'),
-            additional_information: z.string().optional().describe('Additional information about the issue. Plain text or Markdown.'),
-            reproducibility: z.string().optional().describe('Reproducibility: canonical English name or localized label (always, sometimes, random, have not tried, unable to reproduce, N/A). Use get_issue_enums to see all available values.'),
-            view_state: z.enum(['public', 'private']).optional().describe('Visibility of the issue: "public" (default) or "private"'),
+            summary: z.string().min(1).describe('Issue summary/title (required)'),
+            description: z.string().min(1).describe('Detailed issue description (required). Do not create issues without a description. Plain text or Markdown.'),
+            project_id: z.coerce.number().int().positive().describe('Project ID the issue belongs to — use list_projects to discover project IDs'),
+            category: z.string().min(1).describe('Category name (required). Use get_project_categories to list available categories for the project.'),
+            priority: z.string().default('normal').describe('Priority level. Canonical English names: none, low, normal, high, urgent, immediate. Default: "normal". Use get_issue_enums to see localized labels.'),
+            severity: z.string().default('minor').describe('Severity level. Canonical English names: feature, trivial, text, tweak, minor, major, crash, block. Default: "minor". Use get_issue_enums to see localized labels.'),
+            handler_id: z.coerce.number().int().positive().optional().describe('Numeric user ID of the assignee. Alternative to the handler field — use one or the other, not both.'),
+            handler: z.string().optional().describe('MantisBT login name of the assignee. The server resolves the name to a user ID from the project member list. Use find_project_member or get_project_users to look up valid login names.'),
+            version: z.string().optional().describe('Affected product version name. Use get_project_versions to list available version names for the project.'),
+            target_version: z.string().optional().describe('Target fix version — version in which the issue is planned to be resolved. Use get_project_versions to list available version names.'),
+            fixed_in_version: z.string().optional().describe('Version in which the issue was fixed. Use get_project_versions to list available version names.'),
+            steps_to_reproduce: z.string().optional().describe('Step-by-step instructions to reproduce the issue. Plain text or Markdown.'),
+            additional_information: z.string().optional().describe('Additional context or notes about the issue. Plain text or Markdown.'),
+            reproducibility: z.string().optional().describe('How reliably the issue reproduces. Canonical English names: always, sometimes, random, have not tried, unable to reproduce, N/A. Use get_issue_enums to see localized labels.'),
+            view_state: z.enum(['public', 'private']).optional().describe('Visibility of the issue: "public" (visible to all, default) or "private" (restricted to higher-access users).'),
         }),
         annotations: {
             readOnlyHint: false,

package/dist/tools/monitors.js

@@ -12,10 +12,16 @@ export function registerMonitorTools(server, client) {
     // ---------------------------------------------------------------------------
     server.registerTool('add_monitor', {
         title: 'Add Issue Monitor',
-        description: 'Add a user as a monitor (watcher) of a MantisBT issue. Monitors receive email notifications for issue updates.',
+        description: `Add a user as a monitor (watcher) of a MantisBT issue. Monitors receive email notifications whenever the issue is updated. Returns a success confirmation object.
+
+Use add_monitor to subscribe team members to issue updates without assigning them as the handler. To unsubscribe a user, call remove_monitor with the same parameters.
+
+Adding a user who is already a monitor is a no-op — the operation succeeds without creating duplicates.
+
+Prerequisites: obtain issue_id from list_issues or get_issue; use find_project_member or get_project_users to look up valid MantisBT login names.`,
         inputSchema: z.object({
-            issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
-            username: z.string().min(1).describe('Username of the user to add as monitor'),
+            issue_id: z.coerce.number().int().positive().describe('Numeric issue ID — use list_issues or get_issue to obtain issue IDs'),
+            username: z.string().min(1).describe('MantisBT login name (not the display name) of the user to add as monitor. Use find_project_member or get_project_users to discover valid login names for a project.'),
         }),
         annotations: {
             readOnlyHint: false,

package/dist/tools/notes.js

@@ -46,11 +46,17 @@ export function registerNoteTools(server, client) {
     // ---------------------------------------------------------------------------
     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.',
+        description: `Add a note (comment) to an existing MantisBT issue. Returns the created note object including id, created_at, reporter, text, view_state, and a view_url linking directly to the note in the MantisBT web UI.
+
+Full UTF-8 text is supported. Markdown syntax is stored as-is — rendering depends on the MantisBT instance's configured text renderer.
+
+Use view_state="private" to restrict the note to users with reporter-level access or higher; public notes are visible to all users who can view the issue.
+
+Prerequisites: obtain issue_id from list_issues, get_issue, or search_issues.`,
         inputSchema: z.object({
-            issue_id: z.coerce.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)'),
+            issue_id: z.coerce.number().int().positive().describe('Numeric issue ID — use list_issues or get_issue to obtain issue IDs'),
+            text: z.string().min(1).describe('Note text (minimum 1 character). Full UTF-8 including emoji is supported. Markdown is stored as-is.'),
+            view_state: z.enum(['public', 'private']).default('public').describe('Visibility of the note: "public" (visible to all, default) or "private" (visible only to users with sufficient access level).'),
         }),
         annotations: {
             readOnlyHint: false,
@@ -82,10 +88,14 @@ export function registerNoteTools(server, client) {
     // ---------------------------------------------------------------------------
     server.registerTool('delete_note', {
         title: 'Delete Note',
-        description: 'Permanently delete a note from a MantisBT issue. This action is irreversible.',
+        description: `Permanently delete a note from a MantisBT issue. This action is irreversible — deleted notes cannot be recovered.
+
+Returns a plain-text confirmation message on success. Returns an error if the note does not exist or the current user lacks permission to delete it (MantisBT enforces access control: users can typically only delete their own notes unless they have manager-level access or higher).
+
+Prerequisites: obtain note_id from list_notes or from get_issue (notes[].id); obtain issue_id from the same source.`,
         inputSchema: z.object({
-            issue_id: z.coerce.number().int().positive().describe('Numeric issue ID that owns the note'),
-            note_id: z.coerce.number().int().positive().describe('Numeric note ID to delete'),
+            issue_id: z.coerce.number().int().positive().describe('Numeric issue ID that owns the note — use get_issue or list_notes to identify this value'),
+            note_id: z.coerce.number().int().positive().describe('Numeric note ID to delete — obtain from get_issue (notes[].id) or list_notes'),
         }),
         annotations: {
             readOnlyHint: false,

package/dist/tools/projects.js

@@ -40,10 +40,16 @@ export function registerProjectTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_project_users', {
         title: 'Get Project Users',
-        description: 'List all users with access to a specific MantisBT project.',
+        description: `List all users with access to a specific MantisBT project. Returns an array of user objects, each containing id, name (login name), real_name, email, and access_level fields.
+
+Use get_project_users when you need the complete user list for a project — for example, to verify who has access or to build a handler list. For name-based lookup of a single user, prefer find_project_member which supports case-insensitive substring search and is significantly faster on large projects.
+
+Access level IDs: 10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator.
+
+Prerequisites: obtain project_id from list_projects.`,
         inputSchema: z.object({
-            project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            access_level: z.coerce.number().int().optional().describe('Minimum access level filter (e.g. 55 = developer, 90 = manager)'),
+            project_id: z.coerce.number().int().positive().describe('Numeric project ID — use list_projects to discover project IDs'),
+            access_level: z.coerce.number().int().optional().describe('Return only users at or above this access level. Common values: 10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator. Omit to return all users.'),
         }),
         annotations: {
             readOnlyHint: true,
@@ -70,11 +76,17 @@ export function registerProjectTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_project_versions', {
         title: 'Get Project Versions',
-        description: 'List all versions defined for a MantisBT project.',
+        description: `List all versions defined for a MantisBT project. Returns an array of version objects, each containing id, name, released (boolean), obsolete (boolean), and optionally a date field.
+
+Use the returned version names directly when creating or updating issues via create_issue and update_issue (version, target_version, fixed_in_version fields).
+
+By default, obsolete and inherited parent-project versions are excluded. Set obsolete=true to include deprecated versions; set inherit=true to also return versions from parent projects.
+
+Prerequisites: obtain project_id from list_projects.`,
         inputSchema: z.object({
-            project_id: z.coerce.number().int().positive().describe('Numeric project ID'),
-            obsolete: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include obsolete (deprecated) versions (default: false)'),
-            inherit: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include versions inherited from parent projects (default: false)'),
+            project_id: z.coerce.number().int().positive().describe('Numeric project ID — use list_projects to discover project IDs'),
+            obsolete: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include obsolete (deprecated) versions in the response. Default: false. Set to true to see all versions including those no longer actively used.'),
+            inherit: z.preprocess(coerceBool, z.boolean()).default(false).describe('Include versions inherited from parent projects. Default: false. Set to true for sub-projects that share versions with a parent project.'),
         }),
         annotations: {
             readOnlyHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",
@@ -14,7 +14,18 @@
     "url": "https://github.com/dpesch/mantisbt-mcp-server",
     "_note": "GitHub mirror for ecosystem compatibility only — canonical source: https://codeberg.org/dpesch/mantisbt-mcp-server"
   },
-  "keywords": ["mcp", "mcp-server", "mantisbt", "bugtracker", "mantis", "issue-tracker", "bug-tracker", "model-context-protocol", "claude", "claude-code"],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "mantisbt",
+    "bugtracker",
+    "mantis",
+    "issue-tracker",
+    "bug-tracker",
+    "model-context-protocol",
+    "claude",
+    "claude-code"
+  ],
   "main": "dist/index.js",
   "bin": {
     "mantisbt-mcp-server": "dist/index.js"
@@ -35,14 +46,14 @@
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-"zod": "^3.22.4"
+    "zod": "^3.22.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
     "tsx": "^4.0.0",
     "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=18"

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.dpesch/mantisbt-mcp-server",
   "title": "MantisBT MCP Server",
   "description": "MantisBT MCP server – manage issues, notes, files, tags, and relationships. With semantic search.",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.10.0",
+      "version": "1.10.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"