@dpesch/mantisbt-mcp-server 1.10.6 → 1.11.0

package/CHANGELOG.md

@@ -11,6 +11,23 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.11.0] – 2026-07-03
+
+### Added
+
+- `create_issue` and `update_issue` now accept `custom_fields` (`[{field: {id|name}, value}]`) to write custom field values — reading was already supported via `select`.
+- `update_issue` gained an optional `note` parameter (plus `note_view_state`) that appends a note after a successful update — e.g. the reason for a status change in a single call. If the note fails after a successful PATCH, the response contains `note_error` instead of failing the whole call. `dry_run` previews the note as `would_add_note`.
+- `get_issue` now supports the `select` parameter for server-side field projection (same as `list_issues`), significantly reducing response size for large issues.
+
+Feature ideas inspired by [kfnzero/mantis-mcp-server#8](https://github.com/kfnzero/mantis-mcp-server/pull/8).
+
+### Security
+
+- **HTTP transport now requires `MCP_HTTP_TOKEN`.** Starting with `TRANSPORT=http` and no token set previously exposed all tools (including writes like `create_issue`, `delete_issue`, `upload_file`) unauthenticated to any process that could reach the port. The server now refuses to start in HTTP mode without a token. **Behaviour change for HTTP users:** set `MCP_HTTP_TOKEN` to a secret value. The stdio transport (the default) is unaffected.
+- **`upload_file`'s `file_path` is now disabled over the HTTP transport** unless `MANTIS_UPLOAD_DIR` is configured. Over HTTP, `file_path` reads from the *server's* filesystem — a remote client could otherwise exfiltrate arbitrary server-readable files (e.g. SSH keys) as issue attachments. HTTP clients should upload via the `content` (Base64) parameter. The stdio transport keeps unrestricted `file_path` access (the caller is the trusted local agent); set `MANTIS_UPLOAD_DIR` there too if you want to sandbox it.
+
+---
+
 ## [1.10.6] – 2026-06-29
 
 ### Changed

package/README.de.md

@@ -73,13 +73,13 @@ npm run build
 | `TRANSPORT` | – | `stdio` | Transport-Modus: `stdio` oder `http` |
 | `PORT` | – | `3000` | Port für HTTP-Modus |
 | `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind-Adresse für HTTP-Modus. **Geändert von `0.0.0.0` auf `127.0.0.1`** — der Server horcht standardmäßig nur auf localhost. Für Docker oder Remote-Zugriff `0.0.0.0` setzen. |
-| `MCP_HTTP_TOKEN` | – | – | Wenn gesetzt, muss jede `/mcp`-Anfrage den Header `Authorization: Bearer <token>` enthalten. `/health` ist immer öffentlich. |
+| `MCP_HTTP_TOKEN` | ✅ (HTTP-Modus) | – | Bearer-Token für den `/mcp`-Endpunkt (`Authorization: Bearer <token>`). **Pflicht bei `TRANSPORT=http`** — der Server startet im HTTP-Modus ohne diesen Wert nicht, damit Tools nie unauthentifiziert erreichbar sind. Im stdio-Modus ohne Bedeutung. `/health` ist immer öffentlich. |
 | `MANTIS_SEARCH_ENABLED` | – | `false` | Auf `true` setzen, um die semantische Suche zu aktivieren |
 | `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vektorspeicher: `vectra` (reines JS) oder `sqlite-vec` (manuelle Installation erforderlich) |
 | `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Verzeichnis für den Suchindex |
 | `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding-Modell (wird beim ersten Start einmalig heruntergeladen, ~80 MB) |
 | `MANTIS_SEARCH_THREADS` | – | `1` | Anzahl der ONNX-Intra-Op-Threads für das Embedding-Modell. Standard ist 1, um CPU-Sättigung auf Mehrkernsystemen und in WSL zu verhindern. Nur erhöhen, wenn die Indexierungsgeschwindigkeit kritisch ist und der Host ausschließlich für diese Last vorgesehen ist. |
-| `MANTIS_UPLOAD_DIR` | – | – | Schränkt `upload_file` auf Dateien in diesem Verzeichnis ein. Wenn gesetzt, wird jeder `file_path` außerhalb des Verzeichnisses abgelehnt (Pfad-Traversal-Versuche via `../` werden blockiert). Ohne diese Variable gilt keine Einschränkung. |
+| `MANTIS_UPLOAD_DIR` | – | – | Schränkt den `file_path` von `upload_file` auf dieses Verzeichnis ein (Pfad-Traversal via `../` wird blockiert). Im **stdio-Modus** ist `file_path` ohne diese Variable unbeschränkt. Im **HTTP-Modus** liest `file_path` aus dem Dateisystem des Servers und ist deshalb **deaktiviert, sofern diese Variable nicht gesetzt ist** — HTTP-Clients sollten stattdessen den Parameter `content` (Base64) verwenden. |
 
 ## Verfügbare Tools
 
@@ -87,11 +87,11 @@ npm run build
 
 | Tool | Beschreibung |
 |---|---|
-| `get_issue` | Ein Issue anhand seiner ID abrufen |
+| `get_issue` | Ein Issue anhand seiner ID abrufen; optionales `select` zur Feldauswahl reduziert die Antwortgröße |
 | `get_issues` | Mehrere Issues per ID in einem Aufruf abrufen (1–50 IDs); nicht zugängliche IDs liefern `null` an ihrer Position, statt den gesamten Aufruf abzubrechen |
 | `list_issues` | Issues nach Projekt, Status, Autor u.v.m. filtern; optionales `select` für Feldprojektion und `status` für clientseitige Statusfilterung — kanonische englische Statusnamen (z.B. `"new"`, `"resolved"`) werden per ID abgeglichen und funktionieren damit sprachunabhängig auf lokalisierten Installationen |
-| `create_issue` | Neues Issue anlegen; `severity` und `priority` müssen kanonische englische Namen sein (z.B. `minor`, `major`, `normal`, `high`) — `get_issue_enums` aufrufen, um alle gültigen Werte und deren lokalisierte Bezeichnungen zu sehen; optionaler `handler`-Parameter akzeptiert einen Benutzernamen als Alternative zu `handler_id` (wird gegen die Projektmitglieder aufgelöst) |
-| `update_issue` | Bestehendes Issue bearbeiten; Enum-Felder (`status`, `priority`, `severity`, `resolution`, `reproducibility`) akzeptieren kanonische englische Namen, lokalisierte Namen oder numerische IDs — der Server löst Namen automatisch zu IDs auf |
+| `create_issue` | Neues Issue anlegen; `severity` und `priority` müssen kanonische englische Namen sein (z.B. `minor`, `major`, `normal`, `high`) — `get_issue_enums` aufrufen, um alle gültigen Werte und deren lokalisierte Bezeichnungen zu sehen; optionaler `handler`-Parameter akzeptiert einen Benutzernamen als Alternative zu `handler_id` (wird gegen die Projektmitglieder aufgelöst); optionales `custom_fields` zum Setzen benutzerdefinierter Felder |
+| `update_issue` | Bestehendes Issue bearbeiten; Enum-Felder (`status`, `priority`, `severity`, `resolution`, `reproducibility`) akzeptieren kanonische englische Namen, lokalisierte Namen oder numerische IDs — der Server löst Namen automatisch zu IDs auf; unterstützt `custom_fields` sowie einen optionalen `note`-Parameter, der im selben Aufruf eine Notiz anhängt (z.B. die Begründung eines Status-Wechsels) |
 | `delete_issue` | Issue löschen |
 
 ### Notizen
@@ -215,16 +215,19 @@ MCP-Prompt-Templates sind Gesprächseinstiege, die den LLM anweisen, strukturier
 
 ## HTTP-Modus
 
-Für den Einsatz als eigenständiger Server (z.B. in Remote-Setups):
+Für den Einsatz als eigenständiger Server (z.B. in Remote-Setups). `MCP_HTTP_TOKEN` ist im HTTP-Modus **Pflicht** — der Server startet ohne diesen Wert nicht:
 
 ```bash
-MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.js
+MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
+  TRANSPORT=http PORT=3456 node dist/index.js
 
-# Mit Token-Authentifizierung und expliziter Bind-Adresse (erforderlich für Docker/Remote):
+# Mit expliziter Bind-Adresse (erforderlich für Docker/Remote):
 # MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
 #   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
 ```
 
+Jede `/mcp`-Anfrage muss `Authorization: Bearer <token>` senden. Im HTTP-Modus ist der `file_path` von `upload_file` deaktiviert, sofern `MANTIS_UPLOAD_DIR` nicht gesetzt ist — stattdessen den Parameter `content` (Base64) verwenden.
+
 Healthcheck: `GET http://localhost:3456/health` (immer öffentlich, kein Token erforderlich)
 
 ## Dokumentation

package/README.md

@@ -73,13 +73,13 @@ npm run build
 | `TRANSPORT` | – | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | – | `3000` | Port for HTTP mode |
 | `MCP_HTTP_HOST` | – | `127.0.0.1` | Bind address for HTTP mode. **Changed from `0.0.0.0` to `127.0.0.1`** — the server now listens on localhost only by default. Set to `0.0.0.0` for Docker or remote access. |
-| `MCP_HTTP_TOKEN` | – | – | When set, the `/mcp` endpoint requires `Authorization: Bearer <token>`. The `/health` endpoint is always public. |
+| `MCP_HTTP_TOKEN` | ✅ (HTTP mode) | – | Bearer token for the `/mcp` endpoint (`Authorization: Bearer <token>`). **Required when `TRANSPORT=http`** — the server refuses to start in HTTP mode without it, so tools are never exposed unauthenticated. Ignored in stdio mode. The `/health` endpoint is always public. |
 | `MANTIS_SEARCH_ENABLED` | – | `false` | Set to `true` to enable semantic search |
 | `MANTIS_SEARCH_BACKEND` | – | `vectra` | Vector store backend: `vectra` (pure JS) or `sqlite-vec` (requires manual install) |
 | `MANTIS_SEARCH_DIR` | – | `{MANTIS_CACHE_DIR}/search` | Directory for the search index |
 | `MANTIS_SEARCH_MODEL` | – | `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | Embedding model name (downloaded once on first use, ~80 MB) |
 | `MANTIS_SEARCH_THREADS` | – | `1` | Number of ONNX intra-op threads for the embedding model. Default is 1 to prevent CPU saturation on multi-core machines and WSL. Increase only if index rebuild speed matters and the host is dedicated to this workload. |
-| `MANTIS_UPLOAD_DIR` | – | – | Restrict `upload_file` to files within this directory. When set, any `file_path` outside the directory is rejected (path traversal attempts via `../` are blocked). Without this variable there is no restriction. |
+| `MANTIS_UPLOAD_DIR` | – | – | Restrict `upload_file`'s `file_path` to files within this directory (path traversal via `../` is blocked). In **stdio mode** `file_path` is unrestricted unless this is set. In **HTTP mode** `file_path` reads from the server's filesystem, so it is **disabled unless this variable is set** — HTTP clients should upload via the `content` (Base64) parameter instead. |
 
 ## Available tools
 
@@ -87,11 +87,11 @@ npm run build
 
 | Tool | Description |
 |---|---|
-| `get_issue` | Retrieve an issue by its numeric ID |
+| `get_issue` | Retrieve an issue by its numeric ID; optional `select` for field projection to reduce response size |
 | `get_issues` | Retrieve multiple issues by ID in one call (1–50 IDs); missing or inaccessible IDs return `null` at their position instead of failing the call |
 | `list_issues` | Filter issues by project, status, author, and more; optional `select` for field projection and `status` for client-side status filtering — canonical English status names (e.g. `"new"`, `"resolved"`) are matched by ID, making the filter language-independent on localized installations |
-| `create_issue` | Create a new issue; `severity` and `priority` must be canonical English names (e.g. `minor`, `major`, `normal`, `high`) — call `get_issue_enums` to see all valid values and their localized labels; optional `handler` parameter accepts a username as alternative to `handler_id` (resolved against project members) |
-| `update_issue` | Update an existing issue; enum fields (`status`, `priority`, `severity`, `resolution`, `reproducibility`) accept canonical English names, localized names, or numeric IDs — the server resolves names to IDs automatically |
+| `create_issue` | Create a new issue; `severity` and `priority` must be canonical English names (e.g. `minor`, `major`, `normal`, `high`) — call `get_issue_enums` to see all valid values and their localized labels; optional `handler` parameter accepts a username as alternative to `handler_id` (resolved against project members); optional `custom_fields` to set custom field values |
+| `update_issue` | Update an existing issue; enum fields (`status`, `priority`, `severity`, `resolution`, `reproducibility`) accept canonical English names, localized names, or numeric IDs — the server resolves names to IDs automatically; supports `custom_fields` and an optional `note` parameter that appends a note in the same call (e.g. the reason for a status change) |
 | `delete_issue` | Delete an issue |
 
 ### Notes
@@ -215,16 +215,19 @@ MCP prompt templates are conversation starters that instruct the LLM to collect
 
 ## HTTP mode
 
-For use as a standalone server (e.g. in remote setups):
+For use as a standalone server (e.g. in remote setups). `MCP_HTTP_TOKEN` is **required** in HTTP mode — the server refuses to start without it:
 
 ```bash
-MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.js
+MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
+  TRANSPORT=http PORT=3456 node dist/index.js
 
-# With token authentication and explicit bind address (required for Docker/remote):
+# With explicit bind address (required for Docker/remote):
 # MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
 #   TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.js
 ```
 
+Every `/mcp` request must send `Authorization: Bearer <token>`. Over HTTP, `upload_file`'s `file_path` is disabled unless `MANTIS_UPLOAD_DIR` is set — use the `content` (Base64) parameter instead.
+
 Health check: `GET http://localhost:3456/health` (always public, no token required)
 
 ## Documentation

package/dist/config.js

@@ -67,6 +67,19 @@ export async function getStartupConfig() {
     await loadDotEnvLocal();
     return readNonCredentialConfig();
 }
+/**
+ * Enforces authentication for the HTTP transport. Without a token, every tool
+ * (including writes like create_issue, delete_issue and upload_file) would be
+ * reachable unauthenticated by any process that can reach the port. Aborts
+ * startup when the token is missing or blank so HTTP mode is never exposed open.
+ */
+export function assertHttpAuthConfigured(httpToken) {
+    if (httpToken === undefined || httpToken.trim() === '') {
+        throw new Error('HTTP transport requires authentication: set MCP_HTTP_TOKEN to a secret value.\n' +
+            'Without it, all tools would be exposed unauthenticated. ' +
+            'Use the stdio transport (the default) if you do not need HTTP.');
+    }
+}
 // ---------------------------------------------------------------------------
 // Full config (credentials required)
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -6,7 +6,7 @@ import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join, dirname } from 'node:path';
-import { getConfig, getStartupConfig } from './config.js';
+import { getConfig, getStartupConfig, assertHttpAuthConfigured } from './config.js';
 import { MantisClient } from './client.js';
 import { VersionHintService, setGlobalVersionHint } from './version-hint.js';
 import { MetadataCache } from './cache.js';
@@ -34,7 +34,7 @@ const version = packageJson.version;
 // ---------------------------------------------------------------------------
 // Bootstrap
 // ---------------------------------------------------------------------------
-async function createMcpServer() {
+async function createMcpServer(transport) {
     // Use startup config (no credentials required) so the server can connect
     // and respond to tools/list even without MANTIS_BASE_URL / MANTIS_API_KEY.
     // Credentials are resolved lazily on the first actual tool invocation.
@@ -52,7 +52,7 @@ async function createMcpServer() {
     });
     registerIssueTools(server, client, cache);
     registerNoteTools(server, client);
-    registerFileTools(server, client, startupConfig.uploadDir);
+    registerFileTools(server, client, startupConfig.uploadDir, transport);
     registerRelationshipTools(server, client);
     registerMonitorTools(server, client);
     registerProjectTools(server, client, cache);
@@ -75,7 +75,7 @@ async function createMcpServer() {
 // Transport: stdio (default) or HTTP
 // ---------------------------------------------------------------------------
 async function runStdio() {
-    const server = await createMcpServer();
+    const server = await createMcpServer('stdio');
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`MantisBT MCP Server v${version} running (stdio)`);
@@ -86,7 +86,8 @@ async function runStdio() {
 }
 async function runHttp() {
     const startupConfig = await getStartupConfig();
-    const server = await createMcpServer();
+    assertHttpAuthConfigured(startupConfig.httpToken);
+    const server = await createMcpServer('http');
     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
@@ -96,13 +97,12 @@ async function runHttp() {
     let requestQueue = Promise.resolve();
     const httpServer = createServer(async (req, res) => {
         if (req.method === 'POST' && req.url === '/mcp') {
-            if (startupConfig.httpToken) {
-                const auth = req.headers['authorization'];
-                if (auth !== `Bearer ${startupConfig.httpToken}`) {
-                    res.writeHead(401, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Unauthorized' }));
-                    return;
-                }
+            // Token is guaranteed present by assertHttpAuthConfigured() at startup.
+            const auth = req.headers['authorization'];
+            if (auth !== `Bearer ${startupConfig.httpToken}`) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized' }));
+                return;
             }
             const chunks = [];
             req.on('data', (chunk) => chunks.push(chunk));

package/dist/tools/files.js

@@ -8,8 +8,14 @@ function errorText(msg) {
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
-export function registerFileTools(server, client, uploadDir) {
+export function registerFileTools(server, client, uploadDir, transport = 'stdio') {
     const normalizedUploadDir = uploadDir ? resolve(uploadDir) + sep : undefined;
+    // file_path reads from the server's own filesystem. Over stdio the caller is
+    // the trusted local agent (same machine, same user), so any path is fine. Over
+    // HTTP a remote client neither controls nor should reach server-local paths —
+    // it must send Base64 via `content`. Only allow file_path in HTTP mode when an
+    // explicit MANTIS_UPLOAD_DIR sandboxes it.
+    const filePathAllowed = transport === 'stdio' || normalizedUploadDir !== undefined;
     // ---------------------------------------------------------------------------
     // list_issue_files
     // ---------------------------------------------------------------------------
@@ -47,7 +53,7 @@ Use this tool when you need to inspect or enumerate files attached to an issue.
         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.
 
 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
+- 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. Note: file_path reads from the server's filesystem and is disabled over the HTTP transport unless MANTIS_UPLOAD_DIR is configured — HTTP clients should use content instead.
 - 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.
@@ -77,6 +83,9 @@ Use this tool to attach files such as logs, screenshots, or patches to an existi
             let base64Content;
             let fileName;
             if (file_path) {
+                if (!filePathAllowed) {
+                    return { content: [{ type: 'text', text: errorText('file_path is disabled over the HTTP transport. Send the file via the "content" parameter (Base64), or set MANTIS_UPLOAD_DIR to permit server-local paths within that directory.') }], isError: true };
+                }
                 if (normalizedUploadDir) {
                     const normalizedPath = resolve(file_path);
                     if (!normalizedPath.startsWith(normalizedUploadDir)) {

package/dist/tools/issues.js

@@ -4,22 +4,35 @@ import { getVersionHint } from '../version-hint.js';
 import { MANTIS_CANONICAL_ENUM_NAMES, MANTIS_RESOLVED_STATUS_ID, resolveEnumId } from '../constants.js';
 import { dateFilterSchema, matchesDateFilter, hasDateFilter } from '../date-filter.js';
 import { fetchIssueEnumsWithCache } from './config.js';
+import { postNote } from './notes.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
-function enrichIssue(issue, baseUrl) {
+// issueId: fallback when a select projection excluded the id field from the response
+function enrichIssue(issue, baseUrl, issueId) {
+    const id = issue.id ?? issueId;
+    if (id === undefined)
+        return issue;
     return {
         ...issue,
-        view_url: buildIssueViewUrl(baseUrl, issue.id),
+        view_url: buildIssueViewUrl(baseUrl, id),
         notes: issue.notes?.map(note => ({
             ...note,
-            view_url: buildNoteViewUrl(baseUrl, issue.id, note.id),
+            view_url: buildNoteViewUrl(baseUrl, id, note.id),
         })),
     };
 }
+// MantisBT reference shape: at least one of id or name must be provided
+const ref = z.object({ id: z.number().optional(), name: z.string().optional() })
+    .refine(o => o.id !== undefined || o.name !== undefined, { message: "At least one of 'id' or 'name' must be provided" });
+// Custom field entry in MantisBT REST format: { field: {id|name}, value: "<string>" }
+const customFieldEntry = z.object({
+    field: ref.describe('Custom field reference: { id } or { name }'),
+    value: z.coerce.string().describe('Field value as string'),
+});
 const GET_ISSUES_CONCURRENCY = 5;
 // Worker-pool: runs `fn` over all `items` with at most `concurrency` in-flight at once.
 // nextIndex is only incremented inside microtasks, so the ++ is safe without a lock.
@@ -61,22 +74,23 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_issue', {
         title: 'Get Issue',
-        description: 'Retrieve a single MantisBT issue by its numeric ID. Returns all issue fields including notes, attachments, and relationships. Notes are always included — no separate list_notes call needed.',
+        description: 'Retrieve a single MantisBT issue by its numeric ID. Returns all issue fields including notes, attachments, and relationships (unless "select" is given). Notes are always included — no separate list_notes call needed.',
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID'),
+            select: z.string().optional().describe('Comma-separated list of fields to include in the response (server-side projection, same as list_issues). Significantly reduces response size. Example: "id,summary,status,notes"'),
         }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ id }) => {
+    }, async ({ id, select }) => {
         try {
-            const result = await client.get(`issues/${id}`);
+            const result = await client.get(`issues/${id}`, { select });
             const issue = result.issues?.[0] ?? result;
             const baseUrl = await client.getBaseUrl();
             return {
-                content: [{ type: 'text', text: JSON.stringify(enrichIssue(issue, baseUrl), null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(enrichIssue(issue, baseUrl, id), null, 2) }],
             };
         }
         catch (error) {
@@ -278,13 +292,14 @@ For the handler, prefer the username field (resolved server-side) over handler_i
             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).'),
+            custom_fields: z.array(customFieldEntry).optional().describe('Custom field values: [{field: {id|name}, value: "<string>"}]. Use get_issue_fields or get_metadata to discover available custom fields per project.'),
         }),
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
         },
-    }, async ({ summary, description, project_id, category, priority, severity, handler_id, handler, version, target_version, fixed_in_version, steps_to_reproduce, additional_information, reproducibility, view_state }) => {
+    }, async ({ summary, description, project_id, category, priority, severity, handler_id, handler, version, target_version, fixed_in_version, steps_to_reproduce, additional_information, reproducibility, view_state, custom_fields }) => {
         // Resolve handler username to handler_id when only a name is given
         let resolvedHandlerId = handler_id;
         if (resolvedHandlerId === undefined && handler !== undefined) {
@@ -344,6 +359,8 @@ For the handler, prefer the username field (resolved server-side) over handler_i
             }
             if (view_state !== undefined)
                 body.view_state = { name: view_state };
+            if (custom_fields !== undefined)
+                body.custom_fields = custom_fields;
             const raw = await client.post('issues', body);
             const partial = ('issue' in raw && typeof raw['issue'] === 'object' && raw['issue'] !== null)
                 ? raw['issue']
@@ -374,9 +391,6 @@ For the handler, prefer the username field (resolved server-side) over handler_i
     // update_issue
     // ---------------------------------------------------------------------------
     const coerceBool = (val) => val === 'true' ? true : val === 'false' ? false : val;
-    // MantisBT reference shape: at least one of id or name must be provided
-    const ref = z.object({ id: z.number().optional(), name: z.string().optional() })
-        .refine(o => o.id !== undefined || o.name !== undefined, { message: "At least one of 'id' or 'name' must be provided" });
     server.registerTool('update_issue', {
         title: 'Update Issue',
         description: `Update one or more fields of an existing MantisBT issue using a partial PATCH.
@@ -397,11 +411,16 @@ The "fields" object accepts any combination of:
 - target_version: { name: "<version_name>" }
 - fixed_in_version: { name: "<version_name>" }
 - view_state: { name: "public"|"private" }
+- custom_fields: [{field: {id|name}, value: "<string>"}]  (only the listed custom fields are changed, others stay untouched; use get_issue_fields to discover fields)
 
-Important: when resolving an issue, always set BOTH status and resolution to avoid leaving resolution as "open".`,
+Important: when resolving an issue, always set BOTH status and resolution to avoid leaving resolution as "open".
+
+Use the optional "note" parameter to append a note in the same call (e.g. the reason for a status change) — no separate add_note call needed. For a note without field changes use add_note.`,
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID to update'),
             dry_run: z.preprocess(coerceBool, z.boolean().optional()).describe('If true, return the patch payload that would be sent without actually updating the issue. Useful for previewing changes before committing them.'),
+            note: z.string().min(1).optional().describe('Optional note text appended after a successful update (e.g. reason for a status change). Replaces a separate add_note call.'),
+            note_view_state: z.enum(['public', 'private']).default('public').describe('Visibility of the appended note: "public" (default) or "private". Only used when "note" is set.'),
             fields: z.preprocess((v) => {
                 if (typeof v !== 'string')
                     return v;
@@ -427,6 +446,7 @@ Important: when resolving an issue, always set BOTH status and resolution to avo
                 target_version: ref.optional(),
                 fixed_in_version: ref.optional(),
                 view_state: ref.optional(),
+                custom_fields: z.array(customFieldEntry).optional(),
             }).strict().describe('Fields to update (partial update — only provided fields are changed; unknown keys are rejected)')),
         }),
         annotations: {
@@ -434,10 +454,10 @@ Important: when resolving an issue, always set BOTH status and resolution to avo
             destructiveHint: false,
             idempotentHint: false,
         },
-    }, async ({ id, fields, dry_run }) => {
+    }, async ({ id, fields, dry_run, note, note_view_state }) => {
         if (dry_run) {
             return {
-                content: [{ type: 'text', text: JSON.stringify({ dry_run: true, id, would_patch: fields }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({ dry_run: true, id, would_patch: fields, would_add_note: note ?? null }, null, 2) }],
             };
         }
         try {
@@ -455,8 +475,20 @@ Important: when resolving an issue, always set BOTH status and resolution to avo
                 client.getBaseUrl(),
             ]);
             const issue = result.issue ?? result;
+            const response = { ...enrichIssue(issue, baseUrl, id) };
+            if (note !== undefined) {
+                // The PATCH already succeeded — a note failure must not look like a failed
+                // update, or the caller would retry the whole update. Report it inline instead.
+                try {
+                    response['note'] = await postNote(client, id, note, note_view_state);
+                }
+                catch (noteError) {
+                    const noteMsg = noteError instanceof Error ? noteError.message : String(noteError);
+                    response['note_error'] = `Issue #${id} was updated successfully, but adding the note failed: ${noteMsg}. Retry with add_note.`;
+                }
+            }
             return {
-                content: [{ type: 'text', text: JSON.stringify(enrichIssue(issue, baseUrl), null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/notes.js

@@ -7,6 +7,19 @@ function errorText(msg) {
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
+// Shared with update_issue (note parameter) — posts a note and returns it enriched with view_url.
+export async function postNote(client, issueId, text, viewState) {
+    const body = {
+        text,
+        view_state: { name: viewState },
+    };
+    const [result, baseUrl] = await Promise.all([
+        client.post(`issues/${issueId}/notes`, body),
+        client.getBaseUrl(),
+    ]);
+    const note = result.note ?? result;
+    return { ...note, view_url: buildNoteViewUrl(baseUrl, issueId, note.id) };
+}
 export function registerNoteTools(server, client) {
     // ---------------------------------------------------------------------------
     // list_notes
@@ -65,17 +78,9 @@ Prerequisites: obtain issue_id from list_issues, get_issue, or search_issues.`,
         },
     }, async ({ issue_id, text, view_state }) => {
         try {
-            const body = {
-                text,
-                view_state: { name: view_state },
-            };
-            const [result, baseUrl] = await Promise.all([
-                client.post(`issues/${issue_id}/notes`, body),
-                client.getBaseUrl(),
-            ]);
-            const note = result.note ?? result;
+            const note = await postNote(client, issue_id, text, view_state);
             return {
-                content: [{ type: 'text', text: JSON.stringify({ ...note, view_url: buildNoteViewUrl(baseUrl, issue_id, note.id) }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(note, null, 2) }],
             };
         }
         catch (error) {

package/docs/cookbook.de.md

@@ -18,6 +18,8 @@ Tool-orientierte Rezepte für den MantisBT MCP Server — jedes Rezept zeigt gen
   - [Gespeicherten Filter anwenden](#gespeicherten-filter-anwenden)
   - [Issue erstellen](#issue-erstellen)
   - [Issue schließen (Status + Auflösung)](#issue-schließen-status--auflösung)
+  - [Issue auflösen mit Begründungs-Notiz (ein Aufruf)](#issue-auflösen-mit-begründungs-notiz-ein-aufruf)
+  - [Benutzerdefinierte Felder setzen](#benutzerdefinierte-felder-setzen)
   - [Issue neu zuweisen](#issue-neu-zuweisen)
   - [Fix-Version setzen](#fix-version-setzen)
 - [Notizen](#notizen)
@@ -194,6 +196,7 @@ Ruft ein einzelnes Issue anhand seiner numerischen ID ab, inklusive Notizen, Anh
 
 **Parameter:**
 - `id` — numerische Issue-ID
+- `select` — _(optional)_ kommagetrennte Feldliste (server-seitige Projektion); reduziert die Antwortgröße bei großen Issues deutlich, z.B. `"id,summary,status,notes"`
 
 **Request:**
 
@@ -203,6 +206,15 @@ Ruft ein einzelnes Issue anhand seiner numerischen ID ab, inklusive Notizen, Anh
 }
 ```
 
+Kompakte Variante (nur die benötigten Felder):
+
+```json
+{
+  "id": 1042,
+  "select": "id,summary,status,handler"
+}
+```
+
 **Response:**
 
 ```json
@@ -606,6 +618,61 @@ Löst ein Issue auf und schließt es. **Immer beide Felder** `status` und `resol
 
 ---
 
+### Issue auflösen mit Begründungs-Notiz (ein Aufruf)
+
+Ändert den Status und hängt eine Notiz mit der Begründung an — in einem einzigen `update_issue`-Aufruf, kein separates `add_note` nötig.
+
+**Tool:** `update_issue`
+
+**Parameter:**
+- `id` — numerische Issue-ID
+- `fields` — zu ändernde Felder
+- `note` — Notiztext, der nach erfolgreichem Update angehängt wird
+- `note_view_state` — _(optional)_ `"public"` (Standard) oder `"private"`
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "status": { "name": "resolved" },
+    "resolution": { "id": 20 }
+  },
+  "note": "Behoben in Commit abc123 — der Touch-Event-Handler fehlte unter iOS."
+}
+```
+
+**Response:** das aktualisierte Issue plus ein `note`-Objekt mit `view_url`.
+
+> **Hinweis:** Schlägt die Notiz nach erfolgreichem Update fehl, enthält die Antwort `note_error` statt eines Fehlers für den Gesamtaufruf — dann mit `add_note` nachholen. Für eine Notiz ohne Feldänderungen direkt `add_note` verwenden.
+
+---
+
+### Benutzerdefinierte Felder setzen
+
+Schreibt Custom-Field-Werte beim Anlegen oder Aktualisieren. Dasselbe `custom_fields`-Format funktioniert bei `create_issue` und `update_issue` (dort innerhalb von `fields`).
+
+**Tool:** `update_issue`
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "custom_fields": [
+      { "field": { "name": "Kunde" }, "value": "ACME Corp" },
+      { "field": { "id": 3 }, "value": "2026-07-01" }
+    ]
+  }
+}
+```
+
+> **Hinweis:** Nur die aufgeführten Custom Fields werden geändert — alle anderen bleiben unangetastet. Verfügbare Felder pro Projekt mit `get_issue_fields()` oder `get_metadata()` ermitteln. Werte sind immer Strings.
+
+---
+
 ### Issue neu zuweisen
 
 Ändert den Bearbeiter (Handler) eines bestehenden Issues.

package/docs/cookbook.md

@@ -18,6 +18,8 @@ Tool-oriented recipes for the MantisBT MCP server — each recipe shows exactly
   - [Apply a saved filter](#apply-a-saved-filter)
   - [Create an issue](#create-an-issue)
   - [Close an issue (status + resolution)](#close-an-issue-status--resolution)
+  - [Resolve an issue with a reason note (single call)](#resolve-an-issue-with-a-reason-note-single-call)
+  - [Set custom fields](#set-custom-fields)
   - [Reassign an issue](#reassign-an-issue)
   - [Set fix version](#set-fix-version)
 - [Notes](#notes)
@@ -194,6 +196,7 @@ Retrieves a single issue by its numeric ID including notes, attachments, tags, a
 
 **Parameters:**
 - `id` — numeric issue ID
+- `select` — _(optional)_ comma-separated field list (server-side projection); significantly reduces response size for large issues, e.g. `"id,summary,status,notes"`
 
 **Request:**
 
@@ -203,6 +206,15 @@ Retrieves a single issue by its numeric ID including notes, attachments, tags, a
 }
 ```
 
+Compact variant (only the fields you need):
+
+```json
+{
+  "id": 1042,
+  "select": "id,summary,status,handler"
+}
+```
+
 **Response:**
 
 ```json
@@ -606,6 +618,61 @@ Resolves and closes an issue. Always set **both** `status` and `resolution` —
 
 ---
 
+### Resolve an issue with a reason note (single call)
+
+Changes the status and appends a note explaining the change — in one `update_issue` call, no separate `add_note` needed.
+
+**Tool:** `update_issue`
+
+**Parameters:**
+- `id` — numeric issue ID
+- `fields` — fields to change
+- `note` — note text appended after a successful update
+- `note_view_state` — _(optional)_ `"public"` (default) or `"private"`
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "status": { "name": "resolved" },
+    "resolution": { "id": 20 }
+  },
+  "note": "Fixed in commit abc123 — the touch event handler was missing on iOS."
+}
+```
+
+**Response:** the updated issue plus a `note` object with its `view_url`.
+
+> **Note:** If the update succeeds but the note fails, the response contains `note_error` instead of failing the whole call — retry with `add_note`. For a note without field changes use `add_note` directly.
+
+---
+
+### Set custom fields
+
+Writes custom field values on create or update. The same `custom_fields` format works for both `create_issue` and `update_issue` (inside `fields`).
+
+**Tool:** `update_issue`
+
+**Request:**
+
+```json
+{
+  "id": 1042,
+  "fields": {
+    "custom_fields": [
+      { "field": { "name": "Customer" }, "value": "ACME Corp" },
+      { "field": { "id": 3 }, "value": "2026-07-01" }
+    ]
+  }
+}
+```
+
+> **Note:** Only the listed custom fields are changed — others stay untouched. Use `get_issue_fields()` or `get_metadata()` to discover available custom fields per project. Values are always strings.
+
+---
+
 ### Reassign an issue
 
 Changes the handler (assignee) of an existing issue.

package/docs/examples.de.md

@@ -16,6 +16,8 @@ Praktische Beispiele für die Interaktion mit MantisBT über Claude, sobald der
 
 > »Was ist der Status von Issue #1042?«
 
+> »Zeige mir von Issue #1042 nur Titel, Status und Bearbeiter — ohne die vollständige Beschreibung und Notizen.«
+
 > »Zeige mir alle Issues, die jsmith diesen Monat gemeldet hat.«
 
 > »Welche Issues im Webshop-Projekt blockieren das Release 2.4.0?«
@@ -30,6 +32,8 @@ Praktische Beispiele für die Interaktion mit MantisBT über Claude, sobald der
 
 > »Erstelle einen Feature-Request im Frontend-Projekt für einen Dunkelmodus in den Benutzereinstellungen. Niedrige Priorität, kein Fälligkeitsdatum.«
 
+> »Erstelle einen Bug im Backend-Projekt, Kategorie API, Titel 'Token-Refresh gibt 500 zurück bei abgelaufenem Token', und setze das Custom Field 'Kunde' auf 'ACME Corp'.«
+
 ---
 
 ### Issues aktualisieren
@@ -40,6 +44,10 @@ Praktische Beispiele für die Interaktion mit MantisBT über Claude, sobald der
 
 > »Ändere den Schweregrad von #1099 auf 'schwerwiegend' und füge eine Notiz hinzu: auf Produktion reproduziert.«
 
+> »Löse Issue #1042 als behoben auf und füge im selben Schritt eine Notiz hinzu: in Release 2.4.1 auf Produktion ausgerollt.«
+
+> »Setze das Custom Field 'Ticket-Referenz' an Issue #887 auf 'EXT-4421'.«
+
 > »Setze die Fix-Version von Issues #901 und #902 auf 2.4.1.«
 
 ---

package/docs/examples.md

@@ -16,6 +16,8 @@ Practical examples of how to interact with MantisBT through Claude once the MCP
 
 > "What's the status of issue #1042?"
 
+> "Show me only the summary, status, and handler of issue #1042 — skip the full description and notes."
+
 > "Show me all issues reported by jsmith this month."
 
 > "Which issues in the Webshop project are blocking the 2.4.0 release?"
@@ -30,6 +32,8 @@ Practical examples of how to interact with MantisBT through Claude once the MCP
 
 > "Create a feature request in the Frontend project for a dark mode in the user settings. Low priority, no due date."
 
+> "Create a bug in the Backend project, category API, summary 'Token refresh returns 500 on expired token', and set the custom field 'Customer' to 'ACME Corp'."
+
 ---
 
 ### Updating issues
@@ -40,6 +44,10 @@ Practical examples of how to interact with MantisBT through Claude once the MCP
 
 > "Change the severity of #1099 to 'major' and add a note: reproduced on production."
 
+> "Resolve issue #1042 as fixed and add a note in the same step: deployed to production in release 2.4.1."
+
+> "Set the custom field 'Ticket Reference' on issue #887 to 'EXT-4421'."
+
 > "Set the fix version of issues #901 and #902 to 2.4.1."
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpesch/mantisbt-mcp-server",
-  "version": "1.10.6",
+  "version": "1.11.0",
   "mcpName": "io.github.dpesch/mantisbt-mcp-server",
   "description": "MCP server for MantisBT REST API – read and manage bug tracker issues",
   "author": "Dominik Pesch",

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