apple-notes-mcp 2.8.23 → 2.8.25

package/README.md

@@ -201,6 +201,35 @@ for the investigation and verification behind each:
 
 This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.
 
+### Error results
+
+A failed call returns `isError: true` with the same human-readable text as
+before, plus `structuredContent` carrying a stable machine-readable `code`.
+Branch on `code`, not on the prose, which may be reworded.
+
+| `code` | Meaning |
+|--------|---------|
+| `not_found` | The note, folder, account, attachment, or checklist does not exist |
+| `ambiguous` | More than one item matched; use an exact id |
+| `permission_denied` | macOS refused Automation access to Notes.app |
+| `full_disk_access_missing` | The Notes database is not readable; grant Full Disk Access |
+| `shortcut_not_installed` | A native-write bridge Shortcut is not installed exactly once |
+| `timeout_indeterminate` | The operation timed out; for a write, the outcome is unknown |
+| `verification_failed` | The write ran, but exact-ID readback did not confirm it |
+| `revision_conflict` | The note changed since it was read |
+| `validation_error` | The request was rejected before anything ran |
+| `unsupported` | Not supported for this note or in this mode, such as a locked note |
+| `notes_unavailable` | Notes.app is not running, busy, or not responding |
+| `operation_failed` | The server could not classify the failure; read the text |
+
+Two optional booleans describe a write's outcome when it is known.
+`indeterminate: true` means the outcome is uncertain: read the target by exact
+id before any retry, and never retry blindly. `committed: true` means the write
+took effect even though its verification failed; `committed: false` means
+nothing was written (for example a `revision_conflict`). An absent flag means
+unknown. Errors the MCP SDK raises itself before a tool runs, such as an
+argument that fails the input schema, carry no `structuredContent`.
+
 ### Note Operations
 
 #### `create-note`
@@ -1221,6 +1250,10 @@ Run a full setup diagnostic: Notes.app reachability, the Automation permission,
 
 **Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`). The Full Disk Access check tells you whether checklist-state features will work — see [Full Disk Access Setup](https://github.com/sweetrb/apple-notes-mcp/blob/main/docs/FULL-DISK-ACCESS.md).
 
+The report ends with the same feature matrix as [`get-capabilities`](#get-capabilities)
+(`structuredContent.runtimeOS` and `structuredContent.features`). It is
+informational: an unavailable optional feature never changes `healthy`.
+
 ---
 
 #### `get-notes-stats`
@@ -1273,6 +1306,30 @@ resolve the same note. Creating a note from Markdown is
 Reports which background operations are implemented, live-verified, installed,
 and currently available, with a specific reason for each unavailable operation.
 
+It also reports `runtimeOS` (`platform`, `macOSVersion` from `sw_vers`,
+`darwinRelease`) and a `features` matrix, one entry per feature group:
+`applescriptCore`, `fullDiskAccessReads`, `shortcutsBridges`,
+`backgroundOperationsBridge`, `nativeTagsBridge`, `markdownNoteBridge`, and the
+placeholders `checklistToggle`, `smartFolders`, `paragraphLinks`, and
+`audioTranscription`, which need a native helper this server does not ship.
+Each entry carries `available`, `osSupported`, `minimumMacOSVersion`,
+`requirements`, `missing`, `unverified`, `tools`, and a machine-readable
+`reason` that is `null` when available and otherwise the first that applies:
+
+| `reason` | Meaning |
+|----------|---------|
+| `unsupported_platform` | Not running on macOS |
+| `not_implemented` | The server has no implementation for this feature yet |
+| `unknown_os_version` | The feature has a macOS floor and `sw_vers` could not be read |
+| `requires_macos_<major>` | macOS is older than `minimumMacOSVersion`, e.g. `requires_macos_26` |
+| `full_disk_access_missing` | The Notes database is not readable by this process |
+| `shortcuts_unavailable` | The `shortcuts` command could not be run |
+| `shortcut_not_installed` | A bridge Shortcut is missing or installed more than once |
+
+The probe never opens Notes.app or runs a Shortcut, so the Automation
+permission for Notes.app appears under `unverified` rather than being guessed;
+`doctor` and `health-check` confirm it by contacting Notes.
+
 #### `append-native`
 
 Appends bounded plaintext, semantic HTML, or Markdown while preserving existing

package/build/index.js

@@ -1105,11 +1105,11 @@ var require_util = __commonJS({
       return false;
     }
     exports.schemaHasRules = schemaHasRules;
-    function schemaHasRulesButRef(schema, RULES) {
+    function schemaHasRulesButRef(schema, RULES2) {
       if (typeof schema == "boolean")
         return !schema;
       for (const key in schema)
-        if (key !== "$ref" && RULES.all[key])
+        if (key !== "$ref" && RULES2.all[key])
           return true;
       return false;
     }
@@ -2503,17 +2503,17 @@ var require_validate = __commonJS({
     }
     function schemaKeywords(it, types, typeErrors, errsCount) {
       const { gen, schema, data, allErrors, opts, self } = it;
-      const { RULES } = self;
-      if (schema.$ref && (opts.ignoreKeywordsWithRef || !(0, util_1.schemaHasRulesButRef)(schema, RULES))) {
-        gen.block(() => keywordCode(it, "$ref", RULES.all.$ref.definition));
+      const { RULES: RULES2 } = self;
+      if (schema.$ref && (opts.ignoreKeywordsWithRef || !(0, util_1.schemaHasRulesButRef)(schema, RULES2))) {
+        gen.block(() => keywordCode(it, "$ref", RULES2.all.$ref.definition));
         return;
       }
       if (!opts.jtd)
         checkStrictTypes(it, types);
       gen.block(() => {
-        for (const group of RULES.rules)
+        for (const group of RULES2.rules)
           groupKeywords(group);
-        groupKeywords(RULES.post);
+        groupKeywords(RULES2.post);
       });
       function groupKeywords(group) {
         if (!(0, applicability_1.shouldUseGroup)(schema, group))
@@ -4600,10 +4600,10 @@ var require_core = __commonJS({
       }
       // Remove keyword
       removeKeyword(keyword) {
-        const { RULES } = this;
-        delete RULES.keywords[keyword];
-        delete RULES.all[keyword];
-        for (const group of RULES.rules) {
+        const { RULES: RULES2 } = this;
+        delete RULES2.keywords[keyword];
+        delete RULES2.all[keyword];
+        for (const group of RULES2.rules) {
           const i = group.rules.findIndex((rule) => rule.keyword === keyword);
           if (i >= 0)
             group.rules.splice(i, 1);
@@ -4771,9 +4771,9 @@ var require_core = __commonJS({
     }
     var KEYWORD_NAME = /^[a-z_$][a-z0-9_$:-]*$/i;
     function checkKeyword(keyword, def) {
-      const { RULES } = this;
+      const { RULES: RULES2 } = this;
       (0, util_1.eachItem)(keyword, (kwd) => {
-        if (RULES.keywords[kwd])
+        if (RULES2.keywords[kwd])
           throw new Error(`Keyword ${kwd} is already defined`);
         if (!KEYWORD_NAME.test(kwd))
           throw new Error(`Keyword ${kwd} has invalid name`);
@@ -4789,13 +4789,13 @@ var require_core = __commonJS({
       const post = definition === null || definition === void 0 ? void 0 : definition.post;
       if (dataType && post)
         throw new Error('keyword with "post" flag cannot have "type"');
-      const { RULES } = this;
-      let ruleGroup = post ? RULES.post : RULES.rules.find(({ type: t }) => t === dataType);
+      const { RULES: RULES2 } = this;
+      let ruleGroup = post ? RULES2.post : RULES2.rules.find(({ type: t }) => t === dataType);
       if (!ruleGroup) {
         ruleGroup = { type: dataType, rules: [] };
-        RULES.rules.push(ruleGroup);
+        RULES2.rules.push(ruleGroup);
       }
-      RULES.keywords[keyword] = true;
+      RULES2.keywords[keyword] = true;
       if (!definition)
         return;
       const rule = {
@@ -4810,7 +4810,7 @@ var require_core = __commonJS({
         addBeforeRule.call(this, ruleGroup, rule, definition.before);
       else
         ruleGroup.rules.push(rule);
-      RULES.all[keyword] = rule;
+      RULES2.all[keyword] = rule;
       (_a = definition.implements) === null || _a === void 0 ? void 0 : _a.forEach((kwd) => this.addKeyword(kwd));
     }
     function addBeforeRule(ruleGroup, rule, before) {
@@ -43598,13 +43598,19 @@ function addNativeTags(request, deps) {
     } : {}
   };
 }
-function nativeTagsStatus(shortcut = process.env.APPLE_NOTES_MCP_TAGS_SHORTCUT || NATIVE_TAGS_SHORTCUT) {
-  const lines = execFileSync7("/usr/bin/shortcuts", ["list", "--show-identifiers"], {
+function listInstalledShortcuts() {
+  return execFileSync7("/usr/bin/shortcuts", ["list", "--show-identifiers"], {
     encoding: "utf8",
     timeout: 15e3,
     maxBuffer: 1024 * 1024,
     stdio: ["ignore", "pipe", "pipe"]
   }).split(/\r?\n/u);
+}
+var nativeTagsShortcutName = () => process.env.APPLE_NOTES_MCP_TAGS_SHORTCUT || NATIVE_TAGS_SHORTCUT;
+function nativeTagsStatus(shortcut = nativeTagsShortcutName()) {
+  return resolveShortcut(listInstalledShortcuts(), shortcut);
+}
+function resolveShortcut(lines, shortcut) {
   const matches = lines.flatMap((line) => {
     const match = /^(.*) \(([0-9A-Fa-f-]{36})\)$/.exec(line);
     return match && (match[1] === shortcut || match[2].toLowerCase() === shortcut.toLowerCase()) ? [{ name: match[1], identifier: match[2] }] : [];
@@ -43721,10 +43727,12 @@ function comparableVisibleText(html) {
 
 // src/services/backgroundNotes.ts
 var BACKGROUND_SHORTCUT = "Apple Notes MCP - Background Operations v5";
-var backgroundStatus = () => nativeTagsStatus(process.env.APPLE_NOTES_MCP_BACKGROUND_SHORTCUT || BACKGROUND_SHORTCUT);
+var backgroundShortcutName = () => process.env.APPLE_NOTES_MCP_BACKGROUND_SHORTCUT || BACKGROUND_SHORTCUT;
+var backgroundStatus = () => nativeTagsStatus(backgroundShortcutName());
 var nativeTagBridgeStatus = () => nativeTagsStatus();
 var MARKDOWN_NOTE_SHORTCUT = "Apple Notes MCP - Create Markdown Note";
-var markdownNoteStatus = () => nativeTagsStatus(process.env.APPLE_NOTES_MCP_MARKDOWN_SHORTCUT || MARKDOWN_NOTE_SHORTCUT);
+var markdownShortcutName = () => process.env.APPLE_NOTES_MCP_MARKDOWN_SHORTCUT || MARKDOWN_NOTE_SHORTCUT;
+var markdownNoteStatus = () => nativeTagsStatus(markdownShortcutName());
 function readBackgroundSnapshot(manager, id2) {
   if (!/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i.test(id2))
     throw new Error("Exact note ID required");
@@ -44145,8 +44153,261 @@ ${request.content}`
   }
 }
 
+// src/services/capabilityMatrix.ts
+import { execFileSync as execFileSync9 } from "node:child_process";
+import { release } from "node:os";
+var MACOS_SHORTCUTS_CLI = "12.0";
+var MACOS_MARKDOWN_IMPORT = "26.0";
+var FEATURES = [
+  {
+    name: "applescriptCore",
+    description: "Create, read, search, update, move, and delete notes and folders through Notes.app's AppleScript interface",
+    tools: [
+      "create-note",
+      "search-notes",
+      "get-note-content",
+      "update-note",
+      "append-to-note",
+      "insert-link",
+      "delete-note",
+      "move-note",
+      "list-notes",
+      "list-folders",
+      "create-folder",
+      "list-accounts"
+    ],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "notes_automation" }]
+  },
+  {
+    name: "fullDiskAccessReads",
+    description: "Read-only reads of the Notes database: query-notes, checklist state, note metadata, note links, native objects, native tags, and sync detail",
+    tools: [
+      "query-notes",
+      "get-checklist-state",
+      "get-note-metadata",
+      "get-note-link",
+      "get-native-objects",
+      "list-native-tags",
+      "get-note-markdown (checklist annotations)",
+      "get-sync-status (pending uploads)"
+    ],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "full_disk_access" }]
+  },
+  {
+    name: "shortcutsBridges",
+    description: "Run the optional native-write Shortcut bridges in the background",
+    tools: [],
+    minimumMacOSVersion: MACOS_SHORTCUTS_CLI,
+    requirements: [{ kind: "shortcuts_cli" }]
+  },
+  {
+    name: "backgroundOperationsBridge",
+    description: "Native background edits through the Background Operations bridge, verified by exact-ID database readback",
+    tools: [
+      "append-native",
+      "create-checklist-item",
+      "create-checklist-items",
+      "create-table",
+      "insert-note-link",
+      "set-note-pinned",
+      "remove-native-tags"
+    ],
+    minimumMacOSVersion: MACOS_SHORTCUTS_CLI,
+    requirements: [
+      { kind: "notes_automation" },
+      { kind: "full_disk_access" },
+      { kind: "shortcuts_cli" },
+      { kind: "shortcut", name: backgroundShortcutName }
+    ]
+  },
+  {
+    name: "nativeTagsBridge",
+    description: "Add real Notes tags through the Native Tags bridge",
+    tools: ["add-native-tags", "replace-native-tag"],
+    minimumMacOSVersion: MACOS_SHORTCUTS_CLI,
+    requirements: [
+      { kind: "notes_automation" },
+      { kind: "full_disk_access" },
+      { kind: "shortcuts_cli" },
+      { kind: "shortcut", name: nativeTagsShortcutName }
+    ]
+  },
+  {
+    name: "markdownNoteBridge",
+    description: "Create a note from Markdown with real Title, Heading, and Subheading styles through the Create Markdown Note bridge",
+    tools: ['create-note (format: "markdown")'],
+    minimumMacOSVersion: MACOS_MARKDOWN_IMPORT,
+    requirements: [
+      { kind: "notes_automation" },
+      { kind: "full_disk_access" },
+      { kind: "shortcuts_cli" },
+      { kind: "shortcut", name: markdownShortcutName }
+    ]
+  },
+  // Placeholders for features that need a native helper this server does not
+  // ship. They always report `not_implemented` so clients can detect them.
+  {
+    name: "checklistToggle",
+    description: "Check or uncheck an existing checklist item in place",
+    tools: [],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "native_helper" }]
+  },
+  {
+    name: "smartFolders",
+    description: "Create or edit Smart Folders and their tag rules",
+    tools: [],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "native_helper" }]
+  },
+  {
+    name: "paragraphLinks",
+    description: "Link to a specific paragraph or heading inside a note",
+    tools: [],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "native_helper" }]
+  },
+  {
+    name: "audioTranscription",
+    description: "Transcribe audio recordings attached to a note",
+    tools: [],
+    minimumMacOSVersion: null,
+    requirements: [{ kind: "native_helper" }]
+  }
+];
+function requirementLabel(requirement) {
+  return requirement.kind === "shortcut" ? `shortcut:${requirement.name()}` : requirement.kind;
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function evaluateFeature(feature, env) {
+  const isMac = env.platform === "darwin";
+  const floor = feature.minimumMacOSVersion;
+  const versionKnown = env.macOSVersion !== null;
+  const osSupported = isMac && (floor === null || versionKnown && compareVersions(env.macOSVersion, floor) >= 0);
+  const missing = [];
+  const unverified = [];
+  const failures = /* @__PURE__ */ new Set();
+  for (const requirement of feature.requirements) {
+    const label = requirementLabel(requirement);
+    switch (requirement.kind) {
+      case "notes_automation":
+        unverified.push(label);
+        break;
+      case "full_disk_access":
+        if (!env.fullDiskAccess) {
+          missing.push(label);
+          failures.add("full_disk_access_missing");
+        }
+        break;
+      case "shortcuts_cli":
+        if (env.shortcutLines === null) {
+          missing.push(label);
+          failures.add("shortcuts_unavailable");
+        }
+        break;
+      case "shortcut":
+        if (env.shortcutLines === null) unverified.push(label);
+        else if (!resolveShortcut(env.shortcutLines, requirement.name()).installed) {
+          missing.push(label);
+          failures.add("shortcut_not_installed");
+        }
+        break;
+      case "native_helper":
+        missing.push(label);
+        failures.add("not_implemented");
+        break;
+    }
+  }
+  let reason = null;
+  if (!isMac) reason = "unsupported_platform";
+  else if (failures.has("not_implemented")) reason = "not_implemented";
+  else if (floor !== null && !versionKnown) reason = "unknown_os_version";
+  else if (!osSupported) reason = `requires_macos_${Number.parseInt(floor, 10)}`;
+  else if (failures.has("full_disk_access_missing")) reason = "full_disk_access_missing";
+  else if (failures.has("shortcuts_unavailable")) reason = "shortcuts_unavailable";
+  else if (failures.has("shortcut_not_installed")) reason = "shortcut_not_installed";
+  return {
+    description: feature.description,
+    tools: feature.tools,
+    available: reason === null,
+    osSupported,
+    minimumMacOSVersion: floor,
+    requirements: feature.requirements.map(requirementLabel),
+    missing,
+    unverified,
+    reason
+  };
+}
+function evaluateFeatures(env, features = FEATURES) {
+  return {
+    runtimeOS: {
+      platform: env.platform,
+      macOSVersion: env.macOSVersion,
+      darwinRelease: env.darwinRelease
+    },
+    features: Object.fromEntries(features.map((f) => [f.name, evaluateFeature(f, env)]))
+  };
+}
+function readMacOSVersion() {
+  if (process.platform !== "darwin") return null;
+  try {
+    const out = execFileSync9("/usr/bin/sw_vers", ["-productVersion"], {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return /^\d+(\.\d+)*$/.test(out) ? out : null;
+  } catch {
+    return null;
+  }
+}
+function probeCapabilityEnvironment() {
+  const platform = process.platform;
+  const isMac = platform === "darwin";
+  let shortcutLines = null;
+  if (isMac) {
+    try {
+      shortcutLines = listInstalledShortcuts();
+    } catch {
+      shortcutLines = null;
+    }
+  }
+  return {
+    platform,
+    macOSVersion: readMacOSVersion(),
+    darwinRelease: release(),
+    fullDiskAccess: isMac && hasFullDiskAccess(),
+    shortcutLines
+  };
+}
+function getCapabilityMatrix(probe = probeCapabilityEnvironment) {
+  return evaluateFeatures(probe());
+}
+function formatCapabilityMatrix(matrix) {
+  const os5 = matrix.runtimeOS;
+  const lines = [
+    `Feature matrix (macOS ${os5.macOSVersion ?? "unknown"}, Darwin ${os5.darwinRelease}):`
+  ];
+  for (const [name, status] of Object.entries(matrix.features)) {
+    lines.push(
+      status.available ? `  \u2713 ${name}: available${status.unverified.length ? ` (unverified: ${status.unverified.join(", ")})` : ""}` : `  \u2717 ${name}: ${status.reason}${status.missing.length ? ` (missing: ${status.missing.join(", ")})` : ""}`
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/tools/doctor.ts
-function runDoctor(manager) {
+function runDoctor(manager, capabilityMatrix = getCapabilityMatrix) {
   const checks = [];
   const hc = manager.healthCheck();
   for (const c of hc.checks) {
@@ -44197,7 +44458,13 @@ function runDoctor(manager) {
   }
   checks.push(checkNodeRuntimeSignature());
   const healthy = !checks.some((c) => c.status === "fail");
-  return { healthy, checks };
+  let matrix;
+  try {
+    matrix = capabilityMatrix();
+  } catch {
+    matrix = void 0;
+  }
+  return matrix ? { healthy, checks, runtimeOS: matrix.runtimeOS, features: matrix.features } : { healthy, checks };
 }
 function markdownBridgeDetail() {
   const purpose = 'needed only for create-note format: "markdown" on macOS 26+';
@@ -44241,6 +44508,8 @@ function formatDoctorReport(r) {
   const icon = (s) => s === "ok" ? "\u2705" : s === "warn" ? "\u26A0\uFE0F " : "\u274C";
   const lines = [`\u{1FA7A} apple-notes-mcp doctor \u2014 ${r.healthy ? "healthy" : "ISSUES FOUND"}`, ""];
   for (const c of r.checks) lines.push(`${icon(c.status)} ${c.name}: ${c.detail}`);
+  if (r.runtimeOS && r.features)
+    lines.push("", formatCapabilityMatrix({ runtimeOS: r.runtimeOS, features: r.features }));
   return lines.join("\n");
 }
 
@@ -44458,6 +44727,77 @@ function withJsonSchema2020_12(transport2) {
   return transport2;
 }
 
+// src/utils/errorCodes.ts
+var CodedError = class extends Error {
+  envelope;
+  constructor(message, envelope) {
+    super(message);
+    this.name = "CodedError";
+    this.envelope = envelope;
+  }
+};
+var RULES = [
+  { code: "timeout_indeterminate", pattern: /timed out|\bETIMEDOUT\b/i },
+  {
+    code: "verification_failed",
+    pattern: /\buncertain\b|may have (?:been|succeeded)|\baccepted (?:the|an) \w+, but|\bnot verified\b|Do not retry automatically|before any retry|read (?:the )?(?:exact )?(?:note|ID)\b[^.]*before retr/i
+  },
+  {
+    code: "revision_conflict",
+    pattern: /changed after it was read|revision changed|(?:pinned|note) state changed|changed during (?:read|preflight)|changed; read (?:it|the note) again|rich text do not match/i
+  },
+  { code: "full_disk_access_missing", pattern: /Full Disk Access/i },
+  {
+    code: "shortcut_not_installed",
+    pattern: /(?:Install|Import) the supplied|no such shortcut|Run apple-notes-mcp setup/i
+  },
+  {
+    code: "not_found",
+    pattern: /not found|does not exist|\bNo \w+ found\b|does not contain any checklist items|Can[’']t get (?:note|folder|account|attachment)|Cannot find note|Scope is absent/i
+  },
+  { code: "ambiguous", pattern: /ambiguous|more than one|exactly once|Duplicate note IDs/i },
+  {
+    code: "notes_unavailable",
+    pattern: /Notes\.app is (?:not responding|busy)|Lost connection to Notes|isn't running/i
+  },
+  {
+    code: "unsupported",
+    pattern: /password-protected|Locked notes|unsupported|not supported|is blocked|blocked because|has not passed live|refuses to sign|No (?:supported )?background|only one where|Real Notes link unavailable/i
+  },
+  {
+    code: "validation_error",
+    pattern: /\bis required\b|required\b|\bInvalid\b|\bmust\b|\bProvide\b|No (?:note IDs|reviewed notes) provided|response limit|Refusing to write|cannot be resolved|at most \d|between \d+ and \d+|supports the (?:end|default)|Use a distinctive|Use create-table|too large|equal cell counts|Folder path is empty/i
+  }
+];
+var NOTHING_WRITTEN = /nothing (?:was )?(?:changed|created|written)|no replacement started|No content was (?:replaced|appended)|Nothing was created/i;
+var WRITE_ACCEPTED = /\baccepted (?:the|an) \w+, but/i;
+function classifyError(message, cause) {
+  if (cause instanceof CodedError) return { ...cause.envelope };
+  const text = cause instanceof Error && cause.message && !message.includes(cause.message) ? `${message}
+${cause.message}` : message;
+  const timeoutCause = typeof cause === "object" && cause !== null && cause.code === "ETIMEDOUT";
+  let code = "operation_failed";
+  if (timeoutCause) code = "timeout_indeterminate";
+  else if (isPermissionDenied(text)) code = "permission_denied";
+  else code = RULES.find((rule) => rule.pattern.test(text))?.code ?? "operation_failed";
+  const envelope = { code };
+  if (code === "timeout_indeterminate" || code === "verification_failed") {
+    envelope.indeterminate = true;
+    if (WRITE_ACCEPTED.test(text)) envelope.committed = true;
+  } else if (code === "revision_conflict" || NOTHING_WRITTEN.test(text)) {
+    envelope.committed = false;
+    envelope.indeterminate = false;
+  }
+  return envelope;
+}
+function errorResult(message, cause) {
+  return {
+    content: [{ type: "text", text: message }],
+    structuredContent: classifyError(message, cause),
+    isError: true
+  };
+}
+
 // src/utils/shutdown.ts
 var SHUTDOWN_DRAIN_TIMEOUT_MS = 2e3;
 function createShutdown(stream, exit, timeoutMs = SHUTDOWN_DRAIN_TIMEOUT_MS) {
@@ -44778,15 +45118,7 @@ function registerDirectOperations(server2, manager) {
             structuredContent: result
           };
         } catch (error2) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: error2 instanceof Error ? error2.message : String(error2)
-              }
-            ],
-            isError: true
-          };
+          return errorResult(error2 instanceof Error ? error2.message : String(error2), error2);
         }
       })
     );
@@ -44893,15 +45225,7 @@ function registerNativeTagsBridge(server2, manager) {
             structuredContent: result
           };
         } catch (error2) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: error2 instanceof Error ? error2.message : String(error2)
-              }
-            ],
-            isError: true
-          };
+          return errorResult(error2 instanceof Error ? error2.message : String(error2), error2);
         }
       })
     );
@@ -45088,22 +45412,14 @@ function registerNativeOperations(server2, manager) {
             structuredContent: result
           };
         } catch (error2) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: error2 instanceof Error ? error2.message : "Operation failed"
-              }
-            ],
-            isError: true
-          };
+          return errorResult(error2 instanceof Error ? error2.message : "Operation failed", error2);
         }
       })
     );
   }
   tool(
     "get-capabilities",
-    "Use when: checking native background-edit support before calling a write tool.\nReturns: bridge installation, implementation, verification, availability, and specific limitations per operation.\nDo not use when: checking only the Native Tags bridge (native-tags-status).\nSafety: read-only; does not open Notes or run a mutation.",
+    "Use when: checking native background-edit support or which feature groups this Mac supports before calling a tool.\nReturns: bridge installation, implementation, verification, availability, and specific limitations per operation; plus runtimeOS and an OS-version-aware features matrix (available, osSupported, minimumMacOSVersion, requirements, missing, unverified, machine reason code) per feature group.\nDo not use when: checking only the Native Tags bridge (native-tags-status).\nSafety: read-only; does not open Notes or run a mutation.",
     {},
     () => {
       let bridge;
@@ -45153,7 +45469,8 @@ function registerNativeOperations(server2, manager) {
             }
           ])
         ),
-        unavailable: UNAVAILABLE
+        unavailable: UNAVAILABLE,
+        ...getCapabilityMatrix()
       };
     },
     true
@@ -45380,7 +45697,7 @@ function registerNativeOperations(server2, manager) {
 // src/setupShortcuts.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { existsSync as existsSync8 } from "node:fs";
-import { release } from "node:os";
+import { release as release2 } from "node:os";
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 var OPTIONAL_BRIDGE_NOTE = "(optional \u2014 needed only for create-note format: markdown, macOS 26+)";
@@ -45405,7 +45722,7 @@ function setupShortcuts(checkOnly, dependencies = {}) {
     return result.status === 0 ? { ok: true } : { ok: false, error: result.stderr || result.error?.message || "open failed" };
   });
   const baseDirectory = dependencies.baseDirectory || resolve2(dirname2(fileURLToPath(import.meta.url)), "../shortcuts");
-  const osRelease = (dependencies.osRelease || release)();
+  const osRelease = (dependencies.osRelease || release2)();
   const darwinMajor = Number.parseInt(osRelease.split(".")[0], 10);
   const items = shortcutFiles.map(({ name, file, optional: optional2 }) => {
     const path5 = resolve2(baseDirectory, file);
@@ -45489,11 +45806,8 @@ function successResponse(message, structured) {
   if (structured) res.structuredContent = structured;
   return res;
 }
-function errorResponse(message) {
-  return {
-    content: [{ type: "text", text: message }],
-    isError: true
-  };
+function errorResponse(message, cause) {
+  return errorResult(message, cause);
 }
 function withErrorHandling(handler, errorPrefix) {
   return async (params) => {
@@ -45501,7 +45815,7 @@ function withErrorHandling(handler, errorPrefix) {
       return handler(params);
     } catch (error2) {
       const message = error2 instanceof Error ? error2.message : "Unknown error";
-      return errorResponse(`${errorPrefix}: ${message}`);
+      return errorResponse(`${errorPrefix}: ${message}`, error2);
     }
   };
 }
@@ -46939,11 +47253,13 @@ ${fdaLine}`, {
 registerTool(
   "doctor",
   {
-    description: "Use when: diagnosing setup problems (Notes.app automation permission, account state, Full Disk Access) with actionable guidance.\nReturns: a detailed report plus structured fields.\nDo not use when: you just need a quick pass/fail (health-check).\nRead-only.",
+    description: "Use when: diagnosing setup problems (Notes.app automation permission, account state, Full Disk Access) with actionable guidance.\nReturns: a detailed report plus structured fields, including runtimeOS and the same OS-version-aware features matrix as get-capabilities.\nDo not use when: you just need a quick pass/fail (health-check).\nRead-only.",
     inputSchema: {},
     outputSchema: {
       healthy: external_exports.boolean().optional(),
-      checks: external_exports.array(external_exports.object({}).passthrough()).optional()
+      checks: external_exports.array(external_exports.object({}).passthrough()).optional(),
+      runtimeOS: external_exports.object({}).passthrough().optional(),
+      features: external_exports.record(external_exports.string(), external_exports.object({}).passthrough()).optional()
     }
   },
   withErrorHandling(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.8.23",
+  "version": "2.8.25",
   "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",