@dpesch/mantisbt-mcp-server 1.14.0 → 1.15.0

package/dist/tools/metadata.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
+import { coerceBool } from '../coerce.js';
 import { getVersionHint } from '../version-hint.js';
 import { ALL_PROJECTS_PREFIX } from '../constants.js';
+import { deprecationNote } from '../deprecation.js';
+import { fetchIssueEnumsWithCache } from './config.js';
 // Fields MantisBT strips from issue responses when the array is empty.
 // They are always valid 'select' values even if absent in a sample issue.
 const EMPTY_STRIPPED_FIELDS = [
@@ -89,6 +92,13 @@ function normalizeIdName(o) {
     return { id: o.id, name: o.name, ...(o.label !== undefined && { label: o.label }) };
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
+/** MantisBT prefixes global categories with "[All Projects] "; stripped so the names work in create_issue. */
+export function stripAllProjectsPrefix(categories) {
+    return categories.map(cat => ({
+        ...cat,
+        name: cat.name.startsWith(ALL_PROJECTS_PREFIX) ? cat.name.slice(ALL_PROJECTS_PREFIX.length) : cat.name,
+    }));
+}
 export function normalizeProject(p) {
     return {
         id: p.id,
@@ -123,12 +133,7 @@ async function fetchAndCacheMetadata(client, cache) {
         const rawCategories = projectDetailResult.status === 'fulfilled'
             ? (projectDetailResult.value.projects?.[0]?.categories ?? [])
             : [];
-        const categories = rawCategories.map((cat) => ({
-            ...cat,
-            name: cat.name.startsWith(ALL_PROJECTS_PREFIX)
-                ? cat.name.slice(ALL_PROJECTS_PREFIX.length)
-                : cat.name,
-        }));
+        const categories = stripAllProjectsPrefix(rawCategories);
         byProject[project.id] = { users, versions, categories };
     }));
     // Fetch all tags — try the dedicated endpoint first, fall back to collecting
@@ -150,13 +155,36 @@ async function fetchAndCacheMetadata(client, cache) {
     await cache.save(data);
     return data;
 }
-export function registerMetadataTools(server, client, cache) {
+export function registerMetadataTools(server, client, cache, searchIndexStatus) {
+    /** Metadata from the cache, synced when missing, expired or when refresh is set. */
+    async function loadMetadata(refresh) {
+        const cached = refresh ? null : await cache.loadIfValid();
+        return cached ?? fetchAndCacheMetadata(client, cache);
+    }
+    /**
+     * Valid "select" field names: from the cache, else discovered from a sample
+     * issue plus the fields MantisBT strips when empty, else a static list.
+     */
+    async function loadIssueFields(projectId) {
+        const cached = await cache.loadIssueFields();
+        if (cached)
+            return { fields: cached, source: 'cache' };
+        const result = await client.get('issues', { page: 1, page_size: 1, project_id: projectId });
+        const sample = result.issues?.[0];
+        const fields = sample
+            ? Array.from(new Set([...Object.keys(sample), ...EMPTY_STRIPPED_FIELDS])).sort()
+            : STATIC_ISSUE_FIELDS;
+        await cache.saveIssueFields(fields);
+        return { fields, source: sample ? 'live' : 'static' };
+    }
     // ---------------------------------------------------------------------------
     // sync_metadata
     // ---------------------------------------------------------------------------
     server.registerTool('sync_metadata', {
         title: 'Sync Metadata Cache',
-        description: `Fetch all projects and their associated users, versions, categories, and tags from MantisBT and store them in the local metadata cache.
+        description: `${deprecationNote('sync_metadata', 'get_metadata with refresh: true')}
+
+Fetch all projects and their associated users, versions, categories, and tags from MantisBT and store them in the local metadata cache.
 
 Tags are fetched via the dedicated GET /tags endpoint when available. On installations where that endpoint is missing (MantisBT < 2.26), tags are collected by scanning all issues across all projects.
 
@@ -194,19 +222,33 @@ Use this tool to refresh stale data.`,
     // ---------------------------------------------------------------------------
     server.registerTool('get_metadata', {
         title: 'Get Cached Metadata',
-        description: `Return a compact summary of cached MantisBT metadata: project count, tag count, and per-project counts of users, versions, and categories.
+        description: `Return the cached MantisBT metadata (projects with their users, versions and categories, plus all tags).
 
-If the cache does not exist or has expired (default TTL: 24 hours), it will automatically sync first.
-Use sync_metadata to force a refresh. For full lists use: list_projects (projects), get_project_users / get_project_versions / get_project_categories (per-project data), list_tags (tags).`,
-        inputSchema: z.object({}),
+- detail: "summary" (default) — compact counts: project count, tag count, per-project counts of users, versions and categories, cached_at, ttl_seconds.
+- detail: "full" — the complete raw cache with all lists (large; minified JSON).
+- refresh: true — re-fetch everything from MantisBT before answering (otherwise the cache is used and only synced when missing or expired; default TTL 24 hours).
+
+When semantic search is enabled, the response also contains "search_index": how many issues are indexed vs. the total, and the time of the last sync.
+
+For lists of a single project use get_project with include; for tags use list_tags.`,
+        inputSchema: z.object({
+            detail: z.enum(['summary', 'full']).default('summary').describe('"summary" (default): counts only; "full": the complete raw cache'),
+            refresh: z.preprocess(coerceBool, z.boolean().default(false)).describe('Re-fetch all metadata from MantisBT first (default: false)'),
+        }),
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
         },
-    }, async () => {
+    }, async ({ detail, refresh }) => {
         try {
-            const data = await cache.loadIfValid() ?? await fetchAndCacheMetadata(client, cache);
+            const [data, searchIndex] = await Promise.all([
+                loadMetadata(refresh),
+                searchIndexStatus?.(),
+            ]);
+            if (detail === 'full') {
+                return { content: [{ type: 'text', text: JSON.stringify({ ...data, search_index: searchIndex }) }] };
+            }
             const summary = {
                 projects: data.projects.length,
                 tags: data.tags.length,
@@ -221,6 +263,7 @@ Use sync_metadata to force a refresh. For full lists use: list_projects (project
                 })),
                 cached_at: new Date(data.timestamp).toISOString(),
                 ttl_seconds: cache.getRemainingTtlSeconds(data.timestamp),
+                search_index: searchIndex,
             };
             return {
                 content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
@@ -236,10 +279,12 @@ Use sync_metadata to force a refresh. For full lists use: list_projects (project
     // ---------------------------------------------------------------------------
     server.registerTool('get_metadata_full', {
         title: 'Get Full Cached Metadata',
-        description: `Return the complete raw MantisBT metadata cache: all projects with full fields, and per-project lists of users, versions, categories, plus all tags.
+        description: `${deprecationNote('get_metadata_full', 'get_metadata with detail: "full"')}
+
+Return the complete raw MantisBT metadata cache: all projects with full fields, and per-project lists of users, versions, categories, plus all tags.
 
 If the cache does not exist or has expired (default TTL: 24 hours), it will automatically sync first.
-Use sync_metadata to force a refresh. For a lightweight overview use get_metadata instead.`,
+Use get_metadata with refresh: true to force a refresh.`,
         inputSchema: z.object({}),
         annotations: {
             readOnlyHint: true,
@@ -248,7 +293,7 @@ Use sync_metadata to force a refresh. For a lightweight overview use get_metadat
         },
     }, async () => {
         try {
-            const data = await cache.loadIfValid() ?? await fetchAndCacheMetadata(client, cache);
+            const data = await loadMetadata(false);
             return {
                 content: [{ type: 'text', text: JSON.stringify(data) }],
             };
@@ -263,7 +308,9 @@ Use sync_metadata to force a refresh. For a lightweight overview use get_metadat
     // ---------------------------------------------------------------------------
     server.registerTool('get_issue_fields', {
         title: 'Get Issue Fields',
-        description: `Return all field names that are valid for the "select" parameter of list_issues and get_issue.
+        description: `${deprecationNote('get_issue_fields', 'get_issue_schema')}
+
+Return all field names that are valid for the "select" parameter of list_issues and get_issue.
 
 Fields are discovered by fetching a sample issue from MantisBT (which reflects the server's active configuration — e.g. whether eta, projection, or profile fields are enabled) and merging the result with fields that MantisBT omits when empty (notes, attachments, relationships, etc.). The result is cached with the same TTL as the metadata cache.
 
@@ -278,30 +325,42 @@ Use this tool before constructing a "select" string to ensure you only request f
         },
     }, async ({ project_id }) => {
         try {
-            const cached = await cache.loadIssueFields();
-            if (cached) {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({ fields: cached, source: 'cache' }, null, 2) }],
-                };
-            }
-            const params = {
-                page: 1,
-                page_size: 1,
-                project_id,
+            return {
+                content: [{ type: 'text', text: JSON.stringify(await loadIssueFields(project_id), null, 2) }],
             };
-            const result = await client.get('issues', params);
-            const issues = result.issues ?? [];
-            let fields;
-            if (issues.length === 0) {
-                fields = STATIC_ISSUE_FIELDS;
-            }
-            else {
-                const discovered = Object.keys(issues[0]);
-                fields = Array.from(new Set([...discovered, ...EMPTY_STRIPPED_FIELDS])).sort();
-            }
-            await cache.saveIssueFields(fields);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // get_issue_schema
+    // ---------------------------------------------------------------------------
+    server.registerTool('get_issue_schema', {
+        title: 'Get Issue Schema',
+        description: `Return what is valid for issues on this MantisBT server, in one response:
+
+- fields: all field names valid for the "select" parameter of get_issue, list_issues and search_issues. Discovered from a sample issue (reflects the server's active configuration) plus fields MantisBT omits when empty (notes, attachments, relationships, …); cached with the metadata TTL. fields_source tells where they came from: "cache", "live" or "static".
+- enums: ID, name and (if available) localized label for severity, status, priority, resolution and reproducibility. "name" or "id" is what create_issue / update_issue accept; "canonical_name" appears on localized installations.
+
+Call it before building a "select" string or before setting enum fields.`,
+        inputSchema: z.object({
+            project_id: z.coerce.number().int().positive().optional().describe('Optional project ID to scope the sample issue used for field discovery'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async ({ project_id }) => {
+        try {
+            const [{ fields, source }, enums] = await Promise.all([
+                loadIssueFields(project_id),
+                fetchIssueEnumsWithCache(client),
+            ]);
             return {
-                content: [{ type: 'text', text: JSON.stringify({ fields, source: issues.length > 0 ? 'live' : 'static' }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({ fields, fields_source: source, enums }, null, 2) }],
             };
         }
         catch (error) {

package/dist/tools/monitors.js

@@ -1,27 +1,138 @@
 import { z } from 'zod';
+import { firstIssue } from '../issue-envelope.js';
 import { getVersionHint } from '../version-hint.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}`;
 }
+function jsonResult(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+function errorResult(msg) {
+    return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+}
+// ---------------------------------------------------------------------------
+// Monitor helpers
+// ---------------------------------------------------------------------------
+/** MantisBT omits the "monitors" key when the issue has no monitors. */
+const monitorsOf = (response) => firstIssue(response)?.monitors ?? [];
+/** Lower-cased login names of the given monitors (MantisBT login names are case-insensitive). */
+const loginsOf = (monitors) => new Set(monitors.map(m => m.name.toLowerCase()));
+/**
+ * Adds users as monitors of an issue.
+ *
+ * MantisBT reads only a "users" array; without it, MonitorAddCommand adds the
+ * logged-in user (the API-key owner) instead. The POST response contains the
+ * issue, so the result is checked without an extra request. Adding an existing
+ * monitor is a no-op and counts as added.
+ */
+export async function addMonitors(client, issueId, usernames) {
+    const monitors = monitorsOf(await client.post(`issues/${issueId}/monitors`, {
+        users: usernames.map(name => ({ name })),
+    }));
+    const present = loginsOf(monitors);
+    return {
+        added: usernames.filter(u => present.has(u.toLowerCase())),
+        notAdded: usernames.filter(u => !present.has(u.toLowerCase())),
+        monitors,
+    };
+}
+/**
+ * Removes users from an issue's monitor list.
+ *
+ * MantisBT 2.28 has no DELETE route for monitors. PATCH /issues/{id} replaces
+ * the monitor list as a whole, so the list is sent without the given users.
+ * MantisBT skips monitors the caller may not remove without reporting an
+ * error — those end up in `stillPresent`. Usernames are matched
+ * case-insensitively. No PATCH is sent when none of the users is a monitor.
+ *
+ * `knownMonitors` skips the initial GET when the caller already has the
+ * current monitor list (e.g. from a preceding addMonitors call).
+ */
+export async function removeMonitors(client, issueId, usernames, knownMonitors) {
+    const wanted = new Set(usernames.map(u => u.toLowerCase()));
+    const isWanted = (m) => wanted.has(m.name.toLowerCase());
+    const current = knownMonitors ?? monitorsOf(await client.get(`issues/${issueId}`, { select: 'id,monitors' }));
+    const present = loginsOf(current.filter(isWanted));
+    const notMonitoring = usernames.filter(u => !present.has(u.toLowerCase()));
+    if (present.size === 0) {
+        return { removed: [], notMonitoring, stillPresent: [], monitors: current };
+    }
+    const after = monitorsOf(await client.patch(`issues/${issueId}`, {
+        monitors: current.filter(m => !isWanted(m)).map(m => ({ id: m.id })),
+    }));
+    const kept = loginsOf(after);
+    const requested = usernames.filter(u => present.has(u.toLowerCase()));
+    return {
+        removed: requested.filter(u => !kept.has(u.toLowerCase())),
+        notMonitoring,
+        stillPresent: requested.filter(u => kept.has(u.toLowerCase())),
+        monitors: after,
+    };
+}
+const NOT_ADDED_HINT = 'adding other users requires the monitor_add_others_bug_threshold access level';
+const STILL_PRESENT_HINT = 'removing other users requires the monitor_delete_others_bug_threshold access level';
+/**
+ * Applies a combined add/remove of monitors (update_issue add_monitors /
+ * remove_monitors). Never throws: API errors and changes MantisBT silently
+ * skipped are returned as `problems`. Adds run first; the resulting monitor
+ * list is reused for the removal, so no extra GET is needed. `knownMonitors`
+ * (e.g. from a preceding field PATCH) skips the GET when only removing.
+ */
+export async function applyMonitorChanges(client, issueId, add, remove, knownMonitors) {
+    const changes = { current: [] };
+    const problems = [];
+    try {
+        let known = knownMonitors;
+        if (add) {
+            const result = await addMonitors(client, issueId, add);
+            changes.added = result.added;
+            changes.current = result.monitors.map(m => m.name);
+            known = result.monitors;
+            if (result.notAdded.length > 0) {
+                problems.push(`MantisBT did not add ${result.notAdded.join(', ')} as monitor(s) — ${NOT_ADDED_HINT}.`);
+            }
+        }
+        if (remove) {
+            const result = await removeMonitors(client, issueId, remove, known);
+            changes.removed = result.removed;
+            changes.not_monitoring = result.notMonitoring;
+            changes.current = result.monitors.map(m => m.name);
+            if (result.stillPresent.length > 0) {
+                problems.push(`${result.stillPresent.join(', ')} still monitor(s) the issue — ${STILL_PRESENT_HINT}.`);
+            }
+        }
+        return { changes, problems };
+    }
+    catch (error) {
+        problems.push(error instanceof Error ? error.message : String(error));
+        return { problems };
+    }
+}
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
 export function registerMonitorTools(server, client) {
     // ---------------------------------------------------------------------------
     // add_monitor
     // ---------------------------------------------------------------------------
     server.registerTool('add_monitor', {
         title: 'Add Issue Monitor',
-        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.
+        description: `${deprecationNote('add_monitor', 'update_issue with add_monitors')}
+
+Add a user as a monitor (watcher) of a MantisBT issue. Monitors receive email notifications whenever the issue is updated. Returns { success, monitors } — "monitors" lists the login names now monitoring the issue.
 
-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.
+Use it to subscribe team members to issue updates without assigning them as the handler.
 
 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.`,
+Prerequisites: obtain issue_id from list_issues or get_issue; use get_project with member_query to look up valid MantisBT login names.`,
         inputSchema: z.object({
             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.'),
+            username: z.string().min(1).describe('MantisBT login name (not the display name) of the user to add as monitor. Use get_project with member_query to discover valid login names for a project.'),
         }),
         annotations: {
             readOnlyHint: false,
@@ -30,15 +141,14 @@ Prerequisites: obtain issue_id from list_issues or get_issue; use find_project_m
         },
     }, async ({ issue_id, username }) => {
         try {
-            const body = { name: username };
-            const result = await client.post(`issues/${issue_id}/monitors`, body);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result ?? { success: true }, null, 2) }],
-            };
+            const result = await addMonitors(client, issue_id, [username]);
+            if (result.notAdded.length > 0) {
+                return errorResult(`MantisBT accepted the request, but user "${username}" is not a monitor of issue ${issue_id}.`);
+            }
+            return jsonResult({ success: true, monitors: result.monitors.map(m => m.name) });
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+            return errorResult(error instanceof Error ? error.message : String(error));
         }
     });
     // ---------------------------------------------------------------------------
@@ -46,26 +156,41 @@ Prerequisites: obtain issue_id from list_issues or get_issue; use find_project_m
     // ---------------------------------------------------------------------------
     server.registerTool('remove_monitor', {
         title: 'Remove Issue Monitor',
-        description: 'Remove a user from the monitor list of a MantisBT issue. The user will no longer receive email notifications for updates to this issue.',
+        description: `${deprecationNote('remove_monitor', 'update_issue with remove_monitors')}
+
+Remove a user from the monitor list of a MantisBT issue. The user will no longer receive email notifications for updates to this issue.
+
+Returns { success, removed, monitors } — "monitors" lists the login names still monitoring the issue. If the user was not a monitor, the call succeeds with removed=false and nothing is changed.
+
+Removing another user requires the monitor_delete_others_bug_threshold access level; without it the call returns an error.`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
-            username: z.string().min(1).describe('Username of the monitor to remove'),
+            username: z.string().min(1).describe('MantisBT login name (not the display name) of the monitor to remove'),
         }),
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,
-            idempotentHint: false,
+            idempotentHint: true,
         },
     }, async ({ issue_id, username }) => {
         try {
-            await client.delete(`issues/${issue_id}/monitors/${username}`);
-            return {
-                content: [{ type: 'text', text: JSON.stringify({ success: true }, null, 2) }],
-            };
+            const result = await removeMonitors(client, issue_id, [username]);
+            const monitors = result.monitors.map(m => m.name);
+            if (result.stillPresent.length > 0) {
+                return errorResult(`User "${username}" is still a monitor of issue ${issue_id}. MantisBT silently skipped the removal — ${STILL_PRESENT_HINT}.`);
+            }
+            if (result.removed.length === 0) {
+                return jsonResult({
+                    success: true,
+                    removed: false,
+                    message: `User "${username}" is not a monitor of issue ${issue_id} — nothing changed.`,
+                    monitors,
+                });
+            }
+            return jsonResult({ success: true, removed: true, monitors });
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: errorText(msg) }], isError: true };
+            return errorResult(error instanceof Error ? error.message : String(error));
         }
     });
 }

package/dist/tools/notes.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { buildNoteViewUrl } from '../client.js';
 import { getVersionHint } from '../version-hint.js';
+import { firstIssue } from '../issue-envelope.js';
+import { deprecationNote } from '../deprecation.js';
+import { enrichIssue } from '../issue-enrich.js';
 function errorText(msg) {
     const vh = getVersionHint();
     vh?.triggerLatestVersionFetch();
@@ -20,13 +23,70 @@ export async function postNote(client, issueId, text, viewState) {
     const note = result.note ?? result;
     return { ...note, view_url: buildNoteViewUrl(baseUrl, issueId, note.id) };
 }
+// ---------------------------------------------------------------------------
+// Note edits via PATCH /issues/{id} (update_issue fields.notes)
+// ---------------------------------------------------------------------------
+// Edit of an existing note. Without id MantisBT would create a new note, so
+// id is required here.
+const noteEdit = z.object({
+    id: z.coerce.number().int().positive().describe('ID of the note to edit (from get_issue)'),
+    text: z.string().min(1).optional().describe('New note text'),
+    view_state: z.enum(['public', 'private']).optional().describe('New visibility; omitted = keep the current one'),
+}).strict().refine(e => e.text !== undefined || e.view_state !== undefined, { message: "A note edit needs 'text' or 'view_state'" });
+/** Schema of update_issue fields.notes. */
+export const noteEditsSchema = z.array(noteEdit).min(1).superRefine((edits, ctx) => {
+    const ids = edits.map(e => e.id);
+    const twice = ids.filter((noteId, i) => ids.indexOf(noteId) !== i);
+    if (twice.length > 0)
+        ctx.addIssue({ code: 'custom', message: `Note ${twice.join(', ')} listed more than once` });
+});
+/**
+ * Turns note edits into the PATCH payload. MantisBT has no REST route for
+ * editing a note, but PATCH /issues/{id} edits notes by id. The current notes
+ * are read first: unknown IDs throw before anything is written, and a
+ * missing view_state is filled with the note's current one, so an edit keeps
+ * the note's visibility unless the caller changes it.
+ */
+export async function prepareNoteEdits(client, issueId, edits) {
+    const result = await client.get(`issues/${issueId}`, { select: 'id,notes' });
+    const current = new Map((firstIssue(result)?.notes ?? []).map(n => [n.id, n]));
+    const unknown = edits.filter(e => !current.has(e.id)).map(e => e.id);
+    if (unknown.length > 0) {
+        throw new Error(`Note(s) ${unknown.join(', ')} do not belong to issue ${issueId} or are not visible to you — use get_issue to look up note IDs.`);
+    }
+    return edits.map(({ id, text, view_state }) => ({
+        id,
+        ...(text !== undefined && { text }),
+        view_state: { name: view_state ?? current.get(id).view_state?.name ?? 'public' },
+    }));
+}
+const normalizeText = (text) => text.replace(/\r\n/g, '\n').trim();
+/** Compares the notes in the PATCH response with the edits; returns one message per edit MantisBT did not apply. */
+export function verifyNoteEdits(edits, notes) {
+    const byId = new Map((notes ?? []).map(n => [n.id, n]));
+    return edits.flatMap(edit => {
+        const note = byId.get(edit.id);
+        if (!note)
+            return [`note ${edit.id} is missing from the updated issue`];
+        const problems = [];
+        if (edit.text !== undefined && normalizeText(note.text) !== normalizeText(edit.text)) {
+            problems.push(`the text of note ${edit.id} was not changed`);
+        }
+        if (note.view_state?.name !== edit.view_state.name) {
+            problems.push(`note ${edit.id} is ${note.view_state?.name ?? 'unknown'} instead of ${edit.view_state.name}`);
+        }
+        return problems;
+    });
+}
 export function registerNoteTools(server, client) {
     // ---------------------------------------------------------------------------
     // list_notes
     // ---------------------------------------------------------------------------
     server.registerTool('list_notes', {
         title: 'List Issue Notes',
-        description: 'List all notes (comments) attached to a MantisBT issue. Note: get_issue already includes notes in its response — use list_notes only when you need notes without fetching the full issue.',
+        description: `${deprecationNote('list_notes', 'get_issue with select: "notes"')}
+
+List all notes (comments) attached to a MantisBT issue.`,
         inputSchema: z.object({
             issue_id: z.coerce.number().int().positive().describe('Numeric issue ID'),
         }),
@@ -38,13 +98,11 @@ export function registerNoteTools(server, client) {
     }, async ({ issue_id }) => {
         try {
             const [result, baseUrl] = await Promise.all([
-                client.get(`issues/${issue_id}`),
+                client.get(`issues/${issue_id}`, { select: 'id,notes' }),
                 client.getBaseUrl(),
             ]);
-            const notes = (result.issues?.[0]?.notes ?? []).map(note => ({
-                ...note,
-                view_url: buildNoteViewUrl(baseUrl, issue_id, note.id),
-            }));
+            const issue = firstIssue(result);
+            const notes = (issue && enrichIssue(issue, baseUrl, issue_id).notes) ?? [];
             return {
                 content: [{ type: 'text', text: JSON.stringify(notes, null, 2) }],
             };
@@ -97,10 +155,10 @@ Prerequisites: obtain issue_id from list_issues, get_issue, or search_issues.`,
 
 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.`,
+Prerequisites: obtain note_id from get_issue (notes[].id).`,
         inputSchema: z.object({
-            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'),
+            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 — obtain from get_issue (notes[].id)'),
         }),
         annotations: {
             readOnlyHint: false,