@dpesch/mantisbt-mcp-server 1.10.1 → 1.10.3

package/CHANGELOG.md

@@ -7,6 +7,30 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [Unreleased]
+
+---
+
+## [1.10.3] – 2026-05-15
+
+### Fixed
+- `upload_file`: file uploads previously used `multipart/form-data` via a now-removed `postFormData` helper. The MantisBT REST API does not accept `multipart/form-data` for file uploads — it expects a JSON body with Base64-encoded content. The tool now sends `POST issues/{id}/files` with a JSON body containing `{ files: [{ name, type, content }] }`. The caller-facing API is unchanged: `file_path` and `content` continue to work as before; the server handles Base64 encoding internally when `file_path` is used.
+
+### Changed
+- `upload_file` tool and parameter descriptions updated: `file_path` is now explicitly marked as the preferred input mode (use whenever the file exists on disk — the server reads and encodes it automatically); `content` is marked as a fallback to be used only when `file_path` is not available (e.g. in-memory data or files not accessible via the server filesystem).
+
+---
+
+## [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

package/README.de.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@dpesch/mantisbt-mcp-server)](https://www.npmjs.com/package/@dpesch/mantisbt-mcp-server)
 [![license](https://img.shields.io/npm/l/@dpesch/mantisbt-mcp-server)](LICENSE)
+[![MCP compatible](https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
 [![MCP Badge](https://lobehub.com/badge/mcp/dpesch-mantisbt-mcp-server)](https://lobehub.com/mcp/dpesch-mantisbt-mcp-server)
 [![MantisBT MCP Server](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server)
 
@@ -106,7 +107,7 @@ npm run build
 | Tool | Beschreibung |
 |---|---|
 | `list_issue_files` | Anhänge eines Issues auflisten |
-| `upload_file` | Datei an ein Issue anhängen – entweder per lokalem `file_path` oder Base64-kodiertem `content` + `filename` |
+| `upload_file` | Datei an ein Issue anhängen – bevorzugt: lokaler `file_path` (der Server liest und kodiert die Datei automatisch); Fallback: Base64-kodiertes `content` + `filename` (nur verwenden, wenn `file_path` nicht verfügbar ist) |
 
 ### Beziehungen
 
@@ -119,7 +120,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

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@dpesch/mantisbt-mcp-server)](https://www.npmjs.com/package/@dpesch/mantisbt-mcp-server)
 [![license](https://img.shields.io/npm/l/@dpesch/mantisbt-mcp-server)](LICENSE)
+[![MCP compatible](https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
 [![MCP Badge](https://lobehub.com/badge/mcp/dpesch-mantisbt-mcp-server)](https://lobehub.com/mcp/dpesch-mantisbt-mcp-server)
 [![MantisBT MCP Server](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/dpesch/mantisbt-mcp-server)
 
@@ -106,7 +107,7 @@ npm run build
 | Tool | Description |
 |---|---|
 | `list_issue_files` | List attachments of an issue |
-| `upload_file` | Upload a file to an issue — either by local `file_path` or Base64-encoded `content` + `filename` |
+| `upload_file` | Upload a file to an issue — preferred: local `file_path` (server reads and encodes automatically); fallback: Base64-encoded `content` + `filename` (use only when `file_path` is not available) |
 
 ### Relationships
 
@@ -119,7 +120,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/client.js

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

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

@@ -46,17 +46,17 @@ Use this tool when you need to inspect or enumerate files attached to an issue.
         title: 'Upload File Attachment',
         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
+Provide exactly one of the two input modes:
+- file_path (preferred): absolute path to a local file — use this whenever the file exists on disk; the server reads and encodes it automatically; filename is derived from the path
+- content: Base64-encoded file content — only use this when the file is not accessible via a path (e.g. in-memory data); 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.
 
 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)'),
-            content: z.string().min(1).optional().describe('Base64-encoded file content (mutually exclusive with file_path)'),
+            file_path: z.string().min(1).optional().describe('Preferred: absolute path to the local file to upload — use this whenever the file exists on disk (mutually exclusive with content)'),
+            content: z.string().min(1).optional().describe('Fallback: Base64-encoded file content — only use when file_path is not available (mutually exclusive with file_path)'),
             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'),
@@ -74,7 +74,7 @@ Use this tool to attach files such as logs, screenshots, or patches to an existi
             if (file_path && content) {
                 return { content: [{ type: 'text', text: 'Error: Only one of file_path or content may be provided' }], isError: true };
             }
-            let fileBuffer;
+            let base64Content;
             let fileName;
             if (file_path) {
                 if (normalizedUploadDir) {
@@ -83,23 +83,22 @@ Use this tool to attach files such as logs, screenshots, or patches to an existi
                         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);
+                const fileBuffer = await readFile(file_path);
+                base64Content = fileBuffer.toString('base64');
                 fileName = filename ?? basename(file_path);
             }
             else {
                 if (!filename) {
                     return { content: [{ type: 'text', text: 'Error: filename is required when using content' }], isError: true };
                 }
-                fileBuffer = Buffer.from(content, 'base64');
+                base64Content = content;
                 fileName = filename;
             }
-            const blob = new Blob([new Uint8Array(fileBuffer)], { type: content_type ?? 'application/octet-stream' });
-            const formData = new FormData();
-            formData.append('file', blob, fileName);
-            if (description) {
-                formData.append('description', description);
-            }
-            const result = await client.postFormData(`issues/${issue_id}/files`, formData);
+            const body = {
+                files: [{ name: fileName, type: content_type ?? 'application/octet-stream', content: base64Content }],
+                ...(description && { description }),
+            };
+            const result = await client.post(`issues/${issue_id}/files`, body);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result ?? { success: true }, null, 2) }],
             };

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/docs/cookbook.de.md

@@ -821,7 +821,7 @@ Hängt eine Datei aus dem lokalen Dateisystem an ein Issue an.
 
 ### Dateiinhalt hochladen (Base64)
 
-Hängt eine Datei an, indem ihr base64-kodierter Inhalt direkt übergeben wird. Verwenden, wenn die Datei nicht auf einem lokal zugänglichen Dateisystem liegt.
+Hängt eine Datei an, indem ihr base64-kodierter Inhalt direkt übergeben wird. Nur als **Fallback** verwenden, wenn die Datei nicht über einen Pfad im Server-Dateisystem erreichbar ist (z.B. im Speicher erzeugte Daten oder Dateien, die nur auf der Client-Seite vorliegen). `file_path` bevorzugen, wenn die Datei auf der Festplatte existiert – der Server liest und kodiert sie automatisch.
 
 **Tool:** `upload_file`
 

package/docs/cookbook.md

@@ -821,7 +821,7 @@ Attaches a file from the local filesystem to an issue.
 
 ### Upload file content (base64)
 
-Attaches a file by passing its base64-encoded content directly. Use this when the file is not on a local filesystem accessible to the server.
+Attaches a file by passing its base64-encoded content directly. Use this **only** as a fallback when the file is not accessible via a path on the server filesystem (e.g. in-memory data or files generated on the client side). Prefer `file_path` whenever the file exists on disk — the server reads and encodes it automatically.
 
 **Tool:** `upload_file`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "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.1",
+  "version": "1.10.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@dpesch/mantisbt-mcp-server",
-      "version": "1.10.1",
+      "version": "1.10.3",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tests/tools/files.test.ts

@@ -99,7 +99,7 @@ describe('upload_file', () => {
     expect(calledUrl).toContain('issues/42/files');
   });
 
-  it('sends a POST request with FormData', async () => {
+  it('sends a POST request with a JSON body', async () => {
     vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
     vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
 
@@ -107,10 +107,12 @@ describe('upload_file', () => {
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
     expect(options.method).toBe('POST');
-    expect(options.body).toBeInstanceOf(FormData);
+    const body = JSON.parse(options.body as string) as { files: Array<{ name: string; type: string; content: string }> };
+    expect(Array.isArray(body.files)).toBe(true);
+    expect(body.files[0]!.name).toBe('test.txt');
   });
 
-  it('does not set Content-Type header (set automatically by fetch)', async () => {
+  it('sets Content-Type header to application/json', async () => {
     vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
     vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
 
@@ -118,18 +120,18 @@ describe('upload_file', () => {
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
     const headers = options.headers as Record<string, string>;
-    expect(headers['Content-Type']).toBeUndefined();
+    expect(headers['Content-Type']).toBe('application/json');
   });
 
-  it('appends description when provided', async () => {
+  it('includes description in JSON body when provided', async () => {
     vi.mocked(readFile).mockResolvedValue(Buffer.from('content') as never);
     vi.mocked(fetch).mockResolvedValue(makeResponse(200, JSON.stringify({ id: 5 })));
 
     await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/test.txt', description: 'My attachment' });
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
-    const formData = options.body as FormData;
-    expect(formData.get('description')).toBe('My attachment');
+    const body = JSON.parse(options.body as string) as { description: string };
+    expect(body.description).toBe('My attachment');
   });
 
   it('returns the API response', async () => {
@@ -170,9 +172,8 @@ describe('upload_file', () => {
     await mockServer.callTool('upload_file', { issue_id: 42, file_path: '/tmp/report.pdf', filename: 'custom-name.pdf' });
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
-    const formData = options.body as FormData;
-    const fileEntry = formData.get('file') as File;
-    expect(fileEntry.name).toBe('custom-name.pdf');
+    const body = JSON.parse(options.body as string) as { files: Array<{ name: string }> };
+    expect(body.files[0]!.name).toBe('custom-name.pdf');
   });
 });
 
@@ -208,9 +209,8 @@ describe('upload_file (Base64)', () => {
     });
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
-    const formData = options.body as FormData;
-    const fileEntry = formData.get('file') as File;
-    expect(fileEntry.name).toBe('export.csv');
+    const body = JSON.parse(options.body as string) as { files: Array<{ name: string }> };
+    expect(body.files[0]!.name).toBe('export.csv');
   });
 
   it('sets the content_type when provided', async () => {
@@ -224,9 +224,8 @@ describe('upload_file (Base64)', () => {
     });
 
     const options = vi.mocked(fetch).mock.calls[0]![1] as RequestInit;
-    const formData = options.body as FormData;
-    const fileEntry = formData.get('file') as File;
-    expect(fileEntry.type).toBe('image/png');
+    const body = JSON.parse(options.body as string) as { files: Array<{ type: string }> };
+    expect(body.files[0]!.type).toBe('image/png');
   });
 
   it('returns isError when neither file_path nor content is provided', async () => {