@dpesch/mantisbt-mcp-server 1.14.1 → 1.15.0

package/dist/tools/issues.js

@@ -1,30 +1,21 @@
 import { z } from 'zod';
-import { buildIssueViewUrl, buildNoteViewUrl } from '../client.js';
+import { coerceBool } from '../coerce.js';
+import { buildIssueViewUrl } from '../client.js';
+import { enrichIssue } from '../issue-enrich.js';
 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 { dateFilterSchema, matchesDateFilter } from '../date-filter.js';
 import { fetchIssueEnumsWithCache } from './config.js';
-import { postNote } from './notes.js';
+import { postNote, noteEditsSchema, prepareNoteEdits, verifyNoteEdits } from './notes.js';
+import { applyMonitorChanges } from './monitors.js';
+import { firstIssue } from '../issue-envelope.js';
+import { deprecationNote } from '../deprecation.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
     const hint = vh?.getUpdateHint();
     return hint ? `Error: ${msg}\n\n${hint}` : `Error: ${msg}`;
 }
-// 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, id),
-        notes: issue.notes?.map(note => ({
-            ...note,
-            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" });
@@ -34,6 +25,55 @@ const customFieldEntry = z.object({
     value: z.coerce.string().describe('Field value as string'),
 });
 const GET_ISSUES_CONCURRENCY = 5;
+const GROUP_BY_FIELDS = ['status', 'handler', 'priority', 'category'];
+// group_by scans every matching issue. MantisBT 2.28 does not cap page_size
+// and returns no total count; 1000 issues per page with a narrow select
+// scanned 7,700 issues in about 1 s. The cap guards against huge instances.
+const GROUP_BY_PAGE_SIZE = 1000;
+const GROUP_BY_MAX_PAGES = 50;
+/**
+ * The client-side filters of list_issues (the MantisBT REST API does not apply
+ * them server-side), shared by the paged listing and group_by.
+ */
+function makeIssueFilter({ status, assigned_to, reporter_id, dateFilter }) {
+    const statusLower = status?.toLowerCase();
+    const statusId = status ? resolveEnumId('status', status) : undefined;
+    // Pre-parse once — avoids repeated new Date() inside the scan loop
+    const updatedAfterMs = dateFilter.updated_after ? new Date(dateFilter.updated_after).getTime() : undefined;
+    const matchesStatus = (issue) => {
+        if (!statusLower)
+            return true;
+        if (!issue.status)
+            return false;
+        if (statusLower === 'open')
+            return (issue.status.id ?? 0) < MANTIS_RESOLVED_STATUS_ID;
+        if (statusId !== undefined)
+            return issue.status.id === statusId;
+        return issue.status.name?.toLowerCase() === statusLower;
+    };
+    /** Fields the filters read — needed in a narrow select. */
+    const fields = [
+        ...(status !== undefined ? ['status'] : []),
+        ...(assigned_to !== undefined ? ['handler'] : []),
+        ...(reporter_id !== undefined ? ['reporter'] : []),
+        ...(dateFilter.updated_after || dateFilter.updated_before ? ['updated_at'] : []),
+        ...(dateFilter.created_after || dateFilter.created_before ? ['created_at'] : []),
+    ];
+    return {
+        /** True when any client-side filter is set (every filter reads a field). */
+        active: fields.length > 0,
+        fields,
+        matches: (issue) => matchesStatus(issue)
+            && (assigned_to === undefined || issue.handler?.id === assigned_to)
+            && (reporter_id === undefined || issue.reporter?.id === reporter_id)
+            && matchesDateFilter(issue, dateFilter),
+        /**
+         * MantisBT returns issues newest-first: once one is at or before
+         * updated_after, every following page is older too.
+         */
+        olderThanUpdatedAfter: (issue) => updatedAfterMs !== undefined && issue.updated_at !== undefined && new Date(issue.updated_at).getTime() <= updatedAfterMs,
+    };
+}
 // 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.
 async function runWithConcurrency(items, concurrency, fn) {
@@ -66,17 +106,95 @@ async function resolveEnum(group, value, client) {
         // localized lookup unavailable — fall through to static error
     }
     const valid = Object.values(MANTIS_CANONICAL_ENUM_NAMES[group]).join(', ');
-    return `Invalid ${group} "${value}". Valid canonical names: ${valid}. Call get_issue_enums to see localized labels.`;
+    return `Invalid ${group} "${value}". Valid canonical names: ${valid}. Call get_issue_schema to see localized labels.`;
 }
 export function registerIssueTools(server, client, cache) {
+    /**
+     * Pages through GET /issues and hands every issue matching the client-side
+     * filter to onMatch (return false to stop). Ends on a short page, or after
+     * the current page once MantisBT's newest-first order shows the rest is
+     * older than updated_after. Returns truncated when maxPages ended the scan
+     * before either happened.
+     */
+    async function scanMatchingIssues(params, filter, pageSize, maxPages, onMatch) {
+        for (let page = 1; page <= maxPages; page++) {
+            const issues = (await client.get('issues', { ...params, page, page_size: pageSize })).issues ?? [];
+            let stopAfterBatch = false;
+            for (const issue of issues) {
+                if (filter.matches(issue)) {
+                    if (onMatch(issue) === false)
+                        return { truncated: false };
+                }
+                else if (filter.olderThanUpdatedAfter(issue)) {
+                    stopAfterBatch = true; // finish the batch — items within it may still be newer
+                }
+            }
+            if (issues.length < pageSize || stopAfterBatch)
+                return { truncated: false };
+        }
+        return { truncated: true };
+    }
+    /**
+     * Counts all matching issues per group (list_issues group_by), fetching only
+     * the fields grouping and filters need.
+     */
+    async function groupIssues(groupBy, params, filter) {
+        const select = [...new Set(['id', groupBy, ...filter.fields])].join(',');
+        const groups = new Map();
+        let total = 0;
+        const { truncated } = await scanMatchingIssues({ ...params, select }, filter, GROUP_BY_PAGE_SIZE, GROUP_BY_MAX_PAGES, issue => {
+            const ref = issue[groupBy];
+            const key = ref?.id ?? null;
+            let group = groups.get(key);
+            if (!group) {
+                group = {
+                    id: key,
+                    name: ref?.name ?? (groupBy === 'handler' ? '(unassigned)' : '(none)'),
+                    ...(ref?.label !== undefined && { label: ref.label }),
+                    count: 0,
+                };
+                groups.set(key, group);
+            }
+            group.count++;
+            total++;
+        });
+        const sorted = [...groups.values()].sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+        return { group_by: groupBy, total, ...(truncated && { truncated: true }), groups: sorted };
+    }
+    /**
+     * Fetches and enriches one issue. The requested ID is passed to enrichIssue
+     * so view_url survives a select without "id".
+     */
+    async function fetchIssue(id, select) {
+        const [result, baseUrl] = await Promise.all([
+            client.get(`issues/${id}`, { select }),
+            client.getBaseUrl(),
+        ]);
+        return enrichIssue(firstIssue(result) ?? result, baseUrl, id);
+    }
+    /**
+     * Fetches several issues in parallel (max GET_ISSUES_CONCURRENCY). Missing or
+     * inaccessible IDs yield null at their position; the call itself never fails.
+     */
+    async function fetchIssuesByIds(ids, select) {
+        const issues = await runWithConcurrency(ids, GET_ISSUES_CONCURRENCY, id => fetchIssue(id, select).catch(() => null));
+        const found = issues.filter(i => i !== null).length;
+        return { issues, requested: ids.length, found, failed: ids.length - found };
+    }
     // ---------------------------------------------------------------------------
     // get_issue
     // ---------------------------------------------------------------------------
     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 (unless "select" is given). Notes are always included — no separate list_notes call needed.',
+        description: `Retrieve one MantisBT issue by "id", or several by "ids" (1–50). Pass exactly one of the two.
+
+With "id": returns the issue with all fields including notes (each with view_url), attachments and relationships, unless "select" is given.
+With "ids": returns { issues, requested, found, failed } — requests run in parallel (max 5 concurrent); missing or inaccessible IDs give null at their position instead of failing the call.
+
+Use "select" to fetch only some fields, e.g. select: "notes" for just the notes or select: "attachments" for just the file attachments of an issue.`,
         inputSchema: z.object({
-            id: z.coerce.number().int().positive().describe('Numeric issue ID'),
+            id: z.coerce.number().int().positive().optional().describe('Numeric issue ID (use either id or ids)'),
+            ids: z.array(z.coerce.number().int().positive()).min(1).max(50).optional().describe('Several issue IDs (1–50) to fetch in one call (use either id or ids)'),
             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: {
@@ -84,14 +202,15 @@ export function registerIssueTools(server, client, cache) {
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ id, select }) => {
+    }, async ({ id, ids, select }) => {
+        if ((id === undefined) === (ids === undefined)) {
+            return { content: [{ type: 'text', text: errorText('Pass exactly one of "id" or "ids".') }], isError: true };
+        }
+        if (ids) {
+            return { content: [{ type: 'text', text: JSON.stringify(await fetchIssuesByIds(ids, select), null, 2) }] };
+        }
         try {
-            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, id), null, 2) }],
-            };
+            return { content: [{ type: 'text', text: JSON.stringify(await fetchIssue(id, select), null, 2) }] };
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -103,7 +222,8 @@ export function registerIssueTools(server, client, cache) {
     // ---------------------------------------------------------------------------
     server.registerTool('get_issues', {
         title: 'Get Multiple Issues',
-        description: 'Retrieve multiple MantisBT issues by their numeric IDs in a single MCP call. ' +
+        description: `${deprecationNote('get_issues', 'get_issue with ids')}\n\n` +
+            'Retrieve multiple MantisBT issues by their numeric IDs in a single MCP call. ' +
             'Requests run in parallel (max 5 concurrent). ' +
             'Missing or inaccessible IDs return null at their array position — ' +
             'the call never fails due to individual missing IDs. ' +
@@ -120,34 +240,15 @@ export function registerIssueTools(server, client, cache) {
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ ids }) => {
-        const [rawResults, baseUrl] = await Promise.all([
-            runWithConcurrency(ids, GET_ISSUES_CONCURRENCY, async (id) => {
-                try {
-                    const result = await client.get(`issues/${id}`);
-                    return result.issues?.[0] ?? result;
-                }
-                catch {
-                    return null;
-                }
-            }),
-            client.getBaseUrl(),
-        ]);
-        const results = rawResults.map(issue => issue !== null ? enrichIssue(issue, baseUrl) : null);
-        const found = results.filter((r) => r !== null).length;
-        return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({ issues: results, requested: ids.length, found, failed: ids.length - found }, null, 2),
-                }],
-        };
-    });
+    }, async ({ ids }) => ({
+        content: [{ type: 'text', text: JSON.stringify(await fetchIssuesByIds(ids), null, 2) }],
+    }));
     // ---------------------------------------------------------------------------
     // list_issues
     // ---------------------------------------------------------------------------
     server.registerTool('list_issues', {
         title: 'List Issues',
-        description: 'List MantisBT issues with optional filtering. Returns a paginated list of issues. Use the "select" parameter to limit returned fields and reduce response size significantly.\n\nNote: "assigned_to", "reporter_id", "status", and date filters are applied client-side (the MantisBT REST API does not support these as server-side filters). When any of these filters are active the tool automatically fetches multiple pages internally until enough matching results are found (up to 500 issues scanned). The "page" and "page_size" parameters refer to the resulting filtered list.\n\nTip for date queries: fetching with select="id,updated_at,created_at" plus a date filter is very compact and efficient.',
+        description: 'List MantisBT issues with optional filtering. Returns a paginated list of issues. Use the "select" parameter to limit returned fields and reduce response size significantly.\n\nNote: "assigned_to", "reporter_id", "status", and date filters are applied client-side (the MantisBT REST API does not support these as server-side filters). When any of these filters are active the tool automatically fetches multiple pages internally until enough matching results are found (up to 500 issues scanned); if that limit ends the search before the page is full, the response contains "truncated": true. The "page" and "page_size" parameters refer to the resulting filtered list.\n\nTip for date queries: fetching with select="id,updated_at,created_at" plus a date filter is very compact and efficient.\n\nFor overviews use "group_by" ("status", "handler", "priority" or "category"): the server counts all matching issues itself and returns { group_by, total, groups: [{ id, name, label?, count }] } instead of an issue list — far fewer tokens than listing issues and counting them. All filters still apply. If the scan stops at its limit (' + (GROUP_BY_PAGE_SIZE * GROUP_BY_MAX_PAGES).toLocaleString('en-US') + ' issues), the response contains "truncated": true.',
         inputSchema: z.object({
             project_id: z.coerce.number().int().positive().optional().describe('Filter by project ID'),
             page: z.coerce.number().int().positive().default(1).describe('Page number (default: 1)'),
@@ -159,6 +260,7 @@ export function registerIssueTools(server, client, cache) {
             direction: z.enum(['ASC', 'DESC']).optional().describe('Sort direction'),
             select: z.string().optional().describe('Comma-separated list of fields to include in the response (server-side projection). Significantly reduces response size. Example: "id,summary,status,priority,handler,updated_at"'),
             status: z.string().optional().describe('Filter issues by status name (e.g. "new", "feedback", "acknowledged", "confirmed", "assigned", "resolved", "closed") or use "open" as shorthand for all statuses with id < 80 (i.e. not yet resolved or closed). Applied client-side after fetching — when combined with pagination, a page may contain fewer results than page_size.'),
+            group_by: z.enum(GROUP_BY_FIELDS).optional().describe('Return counts per group instead of issues: "status", "handler", "priority" or "category". All matching issues are counted (page, page_size and select are ignored).'),
             ...dateFilterSchema,
         }),
         annotations: {
@@ -166,7 +268,7 @@ export function registerIssueTools(server, client, cache) {
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status, updated_after, updated_before, created_after, created_before }) => {
+    }, async ({ project_id, page, page_size, assigned_to, reporter_id, filter_id, sort, direction, select, status, group_by, updated_after, updated_before, created_after, created_before }) => {
         try {
             const baseParams = {
                 project_id,
@@ -178,9 +280,13 @@ export function registerIssueTools(server, client, cache) {
                 select,
             };
             const dateFilter = { updated_after, updated_before, created_after, created_before };
-            const needsClientFilter = status !== undefined || assigned_to !== undefined || reporter_id !== undefined || hasDateFilter(dateFilter);
+            const filter = makeIssueFilter({ status, assigned_to, reporter_id, dateFilter });
+            if (group_by) {
+                const grouped = await groupIssues(group_by, { project_id, assigned_to, reporter_id, filter_id }, filter);
+                return { content: [{ type: 'text', text: JSON.stringify(grouped, null, 2) }] };
+            }
             const baseUrl = await client.getBaseUrl();
-            if (!needsClientFilter) {
+            if (!filter.active) {
                 // No client-side filtering — single API call, pass pagination as-is
                 const result = await client.get('issues', { ...baseParams, page, page_size });
                 const enriched = { ...result, issues: result.issues?.map(i => enrichIssue(i, baseUrl)) };
@@ -194,63 +300,17 @@ export function registerIssueTools(server, client, cache) {
             const MAX_API_PAGES = 10; // hard cap: scan at most 500 issues
             const neededTotal = page * page_size; // need this many matches to serve page N
             const matching = [];
-            let serverPage = 1;
-            let hasMore = true;
-            const statusLower = status?.toLowerCase();
-            const statusId = status ? resolveEnumId('status', status) : undefined;
-            // Pre-parse date thresholds once — avoids repeated new Date() inside the scan loop
-            const updatedAfterMs = updated_after ? new Date(updated_after).getTime() : undefined;
-            while (matching.length < neededTotal && serverPage <= MAX_API_PAGES && hasMore) {
-                const batch = await client.get('issues', {
-                    ...baseParams,
-                    page: serverPage,
-                    page_size: API_PAGE_SIZE,
-                });
-                const issues = batch.issues ?? [];
-                hasMore = issues.length === API_PAGE_SIZE;
-                let stopAfterBatch = false;
-                for (const issue of issues) {
-                    if (statusLower) {
-                        if (!issue.status)
-                            continue;
-                        if (statusLower === 'open') {
-                            if ((issue.status.id ?? 0) >= MANTIS_RESOLVED_STATUS_ID)
-                                continue;
-                        }
-                        else if (statusId !== undefined) {
-                            if (issue.status.id !== statusId)
-                                continue;
-                        }
-                        else if (issue.status.name?.toLowerCase() !== statusLower) {
-                            continue;
-                        }
-                    }
-                    if (assigned_to !== undefined && issue.handler?.id !== assigned_to)
-                        continue;
-                    if (reporter_id !== undefined && issue.reporter?.id !== reporter_id)
-                        continue;
-                    if (!matchesDateFilter(issue, dateFilter)) {
-                        // MantisBT returns results newest-first. Once updated_at drops below
-                        // updated_after, all subsequent pages are guaranteed to be older too.
-                        // Finish the current batch first (items within it may still be newer),
-                        // then stop fetching further pages.
-                        if (updatedAfterMs && issue.updated_at && new Date(issue.updated_at).getTime() <= updatedAfterMs) {
-                            stopAfterBatch = true;
-                        }
-                        continue;
-                    }
-                    matching.push(issue);
-                }
-                if (stopAfterBatch)
-                    break;
-                serverPage++;
-            }
+            const { truncated } = await scanMatchingIssues(baseParams, filter, API_PAGE_SIZE, MAX_API_PAGES, issue => {
+                matching.push(issue);
+                return matching.length < neededTotal;
+            });
             const start = (page - 1) * page_size;
             const pageIssues = matching.slice(start, start + page_size).map(i => enrichIssue(i, baseUrl));
+            // truncated: the scan limit ended the search before enough matches were found.
             return {
                 content: [{
                         type: 'text',
-                        text: JSON.stringify({ issues: pageIssues }, null, 2),
+                        text: JSON.stringify({ issues: pageIssues, ...(truncated && { truncated: true }) }, null, 2),
                     }],
             };
         }
@@ -269,30 +329,30 @@ export function registerIssueTools(server, client, cache) {
 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
+1. Call get_project with include: ["categories"] to obtain a valid category name
+2. Optionally add "versions" to include to obtain version names
+3. Optionally call get_project with member_query 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.
+Both priority and severity accept canonical English names or localized labels from the connected MantisBT instance — call get_issue_schema 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 (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.'),
+            category: z.string().min(1).describe('Category name (required). Use get_project with include: ["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_schema 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_schema 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.'),
+            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 get_project with member_query or include: ["users"] to look up valid login names.'),
+            version: z.string().optional().describe('Affected product version name. Use get_project with include: ["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 with include: ["versions"] to list available version names.'),
+            fixed_in_version: z.string().optional().describe('Version in which the issue was fixed. Use get_project with include: ["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.'),
+            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_schema 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.'),
+            custom_fields: z.array(customFieldEntry).optional().describe('Custom field values: [{field: {id|name}, value: "<string>"}]. Use get_issue_schema or get_metadata to discover available custom fields per project.'),
         }),
         annotations: {
             readOnlyHint: false,
@@ -318,7 +378,7 @@ For the handler, prefer the username field (resolved server-side) over handler_i
             if (!user) {
                 const names = users.map(u => u.name).join(', ');
                 return {
-                    content: [{ type: 'text', text: errorText(`User "${handler}" not found in project ${project_id}. Available users: ${names || 'none (run sync_metadata or check project_id)'}`) }],
+                    content: [{ type: 'text', text: errorText(`User "${handler}" not found in project ${project_id}. Available users: ${names || 'none (run get_metadata with refresh: true or check project_id)'}`) }],
                     isError: true,
                 };
             }
@@ -362,16 +422,14 @@ For the handler, prefer the username field (resolved server-side) over handler_i
             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']
-                : raw;
+            const partial = firstIssue(raw) ?? raw;
             let issue = partial;
             if (!('summary' in partial)) {
                 // Older MantisBT returned only { id: N } — fetch the full issue.
                 // Suppress GET errors: the issue was already created.
                 try {
                     const fetched = await client.get(`issues/${partial.id}`);
-                    issue = fetched.issues?.[0] ?? partial;
+                    issue = firstIssue(fetched) ?? partial;
                 }
                 catch {
                     // unable to fetch details — return minimal object
@@ -390,7 +448,24 @@ 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;
+    /** PATCHes the issue fields (enum names resolved to IDs) and returns the enriched issue. */
+    async function patchIssueFields(id, fields) {
+        const patch = { ...fields };
+        for (const field of ['status', 'priority', 'severity', 'resolution', 'reproducibility']) {
+            const val = fields[field];
+            if (val?.name !== undefined && val.id === undefined) {
+                const resolved = await resolveEnum(field, val.name, client);
+                if (typeof resolved !== 'string')
+                    patch[field] = resolved;
+            }
+        }
+        const [result, baseUrl] = await Promise.all([
+            client.patch(`issues/${id}`, patch),
+            client.getBaseUrl(),
+        ]);
+        const issue = firstIssue(result) ?? result;
+        return enrichIssue(issue, baseUrl, id);
+    }
     server.registerTool('update_issue', {
         title: 'Update Issue',
         description: `Update one or more fields of an existing MantisBT issue using a partial PATCH.
@@ -411,13 +486,20 @@ 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)
+- custom_fields: [{field: {id|name}, value: "<string>"}]  (only the listed custom fields are changed, others stay untouched; use get_issue_schema to discover fields)
+- notes: [{ id: <note_id>, text?: "<new text>", view_state?: "public"|"private" }]  (edits existing notes; note IDs come from get_issue. An omitted view_state keeps the note's current visibility. To add a new note use the "note" parameter or add_note.)
 
 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.`,
+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.
+
+Use "add_monitors" / "remove_monitors" (lists of MantisBT login names) to change who watches the issue — "fields" may be omitted then. The response contains "monitors" with added/removed/not_monitoring and the current monitor list. Adding or removing other users requires the monitor_add_others_bug_threshold / monitor_delete_others_bug_threshold access level.
+
+Steps run in order: fields, monitors, note. Once one step succeeded, a later failure is reported inline ("notes_error" when a note edit was not applied, "monitors_error", "note_error") instead of failing the call — do not retry the steps that went through. Only if every requested step failed is the call an error.`,
         inputSchema: z.object({
             id: z.coerce.number().int().positive().describe('Numeric issue ID to update'),
+            add_monitors: z.array(z.string().min(1)).min(1).optional().describe('MantisBT login names to add as monitors (watchers) of the issue'),
+            remove_monitors: z.array(z.string().min(1)).min(1).optional().describe('MantisBT login names to remove from the monitors of the issue; names that are not monitoring are ignored'),
             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.'),
@@ -447,46 +529,102 @@ Use the optional "note" parameter to append a note in the same call (e.g. the re
                 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)')),
+                notes: noteEditsSchema.optional(),
+            }).strict().optional().describe('Fields to update (partial update — only provided fields are changed; unknown keys are rejected). May be omitted when only add_monitors, remove_monitors or note are given.')),
         }),
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
         },
-    }, async ({ id, fields, dry_run, note, note_view_state }) => {
-        if (dry_run) {
+    }, async ({ id, fields, dry_run, note, note_view_state, add_monitors, remove_monitors }) => {
+        const fieldChanges = fields ?? {};
+        const hasFields = Object.keys(fieldChanges).length > 0;
+        const hasMonitorChanges = add_monitors !== undefined || remove_monitors !== undefined;
+        if (!hasFields && !hasMonitorChanges && note === undefined) {
             return {
-                content: [{ type: 'text', text: JSON.stringify({ dry_run: true, id, would_patch: fields, would_add_note: note ?? null }, null, 2) }],
+                content: [{ type: 'text', text: errorText('Nothing to update — pass fields, add_monitors, remove_monitors or note.') }],
+                isError: true,
+            };
+        }
+        const removing = new Set(remove_monitors?.map(u => u.toLowerCase()));
+        const conflicting = add_monitors?.filter(u => removing.has(u.toLowerCase())) ?? [];
+        if (conflicting.length > 0) {
+            return {
+                content: [{ type: 'text', text: errorText(`${conflicting.join(', ')} appear(s) in both add_monitors and remove_monitors.`) }],
+                isError: true,
             };
         }
         try {
-            const patch = { ...fields };
-            for (const field of ['status', 'priority', 'severity', 'resolution', 'reproducibility']) {
-                const val = fields[field];
-                if (val?.name !== undefined && val.id === undefined) {
-                    const resolved = await resolveEnum(field, val.name, client);
-                    if (typeof resolved !== 'string')
-                        patch[field] = resolved;
+            // Note edits need the current notes first (unknown IDs, missing view_state).
+            const noteEdits = fieldChanges.notes && await prepareNoteEdits(client, id, fieldChanges.notes);
+            const patchFields = noteEdits ? { ...fieldChanges, notes: noteEdits } : fieldChanges;
+            if (dry_run) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                dry_run: true,
+                                id,
+                                would_patch: patchFields,
+                                ...(add_monitors && { would_add_monitors: add_monitors }),
+                                ...(remove_monitors && { would_remove_monitors: remove_monitors }),
+                                would_add_note: note ?? null,
+                            }, null, 2),
+                        }],
+                };
+            }
+            const patched = hasFields ? await patchIssueFields(id, patchFields) : undefined;
+            const response = patched
+                ? { ...patched }
+                : { id, view_url: buildIssueViewUrl(await client.getBaseUrl(), id) };
+            // MantisBT skips note edits it does not apply without an error, so the
+            // response is checked.
+            const noteProblems = noteEdits && patched ? verifyNoteEdits(noteEdits, patched.notes) : [];
+            // As soon as one step succeeded, later failures are reported inline —
+            // otherwise the caller would retry changes that already went through.
+            // Only if every requested step failed is the call an error. The field
+            // step succeeded unless note edits failed and no other field was sent.
+            let succeeded = hasFields
+                && (noteProblems.length === 0 || Object.keys(fieldChanges).some(k => k !== 'notes'));
+            const failures = [];
+            const describeFailure = (what, detail) => {
+                const message = succeeded
+                    ? `Issue #${id} was updated successfully, but ${what} failed: ${detail}`
+                    : `${what.charAt(0).toUpperCase()}${what.slice(1)} failed: ${detail}`;
+                failures.push(message);
+                return message;
+            };
+            if (noteProblems.length > 0) {
+                response['notes_error'] = describeFailure('editing notes', `${noteProblems.join('; ')}.`);
+            }
+            if (hasMonitorChanges) {
+                // The PATCH response already holds the monitor list; MantisBT omits
+                // the key when the issue has no monitors.
+                const knownMonitors = patched ? patched.monitors ?? [] : undefined;
+                const { changes, problems } = await applyMonitorChanges(client, id, add_monitors, remove_monitors, knownMonitors);
+                if (changes)
+                    response['monitors'] = changes;
+                if (problems.length > 0) {
+                    response['monitors_error'] = describeFailure('changing monitors', problems.join(' '));
+                }
+                else {
+                    succeeded = true;
                 }
             }
-            const [result, baseUrl] = await Promise.all([
-                client.patch(`issues/${id}`, patch),
-                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);
+                    succeeded = true;
                 }
                 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.`;
+                    response['note_error'] = describeFailure('adding the note', `${noteMsg}. Retry with add_note.`);
                 }
             }
+            if (!succeeded) {
+                return { content: [{ type: 'text', text: errorText(failures.join(' ')) }], isError: true };
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
             };