apple-notes-mcp 2.9.9 → 2.9.11

package/README.md

@@ -261,7 +261,7 @@ Creates a new note in Apple Notes.
 | `account` | string | No | Account name (defaults to Notes.app's default account; matched exactly or by a *unique* prefix — an ambiguous prefix is refused). Must be an account Notes.app already has configured — see [`list-accounts`](#list-accounts) |
 | `format` | string | No | Content format: `"plaintext"` (default), `"html"`, or `"markdown"`. In all formats, the title is automatically prepended as the note's title line. In plaintext mode, newlines become `<br>`, tabs become `<br>`, and backslashes are preserved as HTML entities. `"markdown"` produces real Title/Heading/Subheading styles through a Shortcut; see [Markdown notes](#markdown-notes) |
 | `markdownRoute` | string | No | With `format: "markdown"` only: `"shortcut"` (default) or `"html"`. See [Markdown through HTML](#markdown-through-html) |
-| `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `update-note`, `append-to-note`, `delete-note` and `move-note` |
+| `timeoutSeconds` | number | No | Whole seconds, 1–120, for each Notes.app automation step this call runs; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only. A timed-out write is uncertain, not failed: read the note by id before any retry. Also accepted by `get-note-content`, `update-note`, `append-to-note`, `delete-note` and `move-note` |
 
 **Example (tagged with inline hashtags):**
 ```json
@@ -531,9 +531,12 @@ Retrieves the full content of a specific note.
 | `id` | string | No | Note ID (preferred - more reliable than title) |
 | `title` | string | No | Note title (use `id` instead when available) |
 | `account` | string | No | Account containing the note (defaults to Notes.app's default account; exact or unique-prefix match, ignored if `id` is provided) |
+| `timeoutSeconds` | number | No | Whole seconds, 1–120, for the body read; overrides `APPLE_NOTES_MCP_TIMEOUT_MS` for this call only |
 
 **Note:** Either `id` or `title` must be provided. Using `id` is recommended as it's unique and avoids issues with duplicate titles.
 
+**Large images:** Notes.app returns images inside the body as base64, so a note holding a very large image (tens of MB) can take longer to read than the timeout allows. When the read times out or overflows the output buffer, the error says so and, with Full Disk Access, names the attachments of 5 MB or more. Retry with a larger `timeoutSeconds`; `delete-note` accepts the same argument, and it needs a successful read to verify the note before deleting it.
+
 **Example - Using ID (recommended):**
 ```json
 {
@@ -1854,6 +1857,37 @@ Decodes a note's classic PencilKit drawings (`com.apple.drawing.2` and the older
 
 ---
 
+#### `transcribe-note-audio`
+
+Transcribes a note's voice recordings and audio attachments now, on this Mac, with Apple's Speech framework through the [public native helper](#public-native-helper). Recognition is on-device only: `SpeechAnalyzer` on macOS 26 and later, or `SFSpeechRecognizer` with on-device recognition required on older systems (a locale without on-device support is refused, never sent to a server). The audio files are opened read-only where Notes keeps them.
+
+**Requires:** Full Disk Access for the MCP host process, and the public native helper built once with `apple-notes-mcp setup --public-helper`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Note ID (use `search-notes` to find it first) |
+| `locale` | string | No | BCP-47 language of the speech, such as `"en-US"` (default), `"it-IT"`, or `"fr-FR"` |
+| `attachmentId` | string | No | Only transcribe this audio attachment (an `x-coredata://…/ICAttachment/pN` id) |
+| `includeText` | boolean | No | Include transcript text (default `true`); `false` returns statuses and word counts only |
+| `downloadAssets` | boolean | No | Let macOS download the language's on-device speech model when it is missing (default `false`: the call returns `asset_unavailable` at once) |
+| `maxSeconds` | integer | No | Total time budget for the call, 30 to 3600 seconds (default 900) |
+
+**Returns:** Overall `status` and, per audio attachment, `status`, `durationSeconds`, `wordCount`, `transcript`, and `takes` (a Notes recording can hold several takes; each is transcribed and the texts are joined in stored order). Statuses:
+
+- `ok`: the whole recording was transcribed.
+- `partial`: some text came back, but a take failed or the helper stopped at its deadline (`code: "incomplete"`).
+- `error`: nothing was transcribed; `code` says why (`asset_unavailable` when the audio file is not on this Mac or the language's speech model is not installed, `permission_required`, `unsupported_locale`, `unsupported_audio`, `time_limit`, ...).
+- `indeterminate`: the helper did not answer in time, so the outcome is unknown and a retry may succeed.
+- `none` (overall only): the note has no audio.
+
+Each take gets a deadline of 1.5 times its length plus a minute (at most 30 minutes), shortened to what is left of `maxSeconds`. A take that cannot start before the budget runs out reports `code: "time_limit"`. The helper runs as a separate process without blocking the server, and cancelling the request stops it. On macOS 27 a 16-minute recording took about 22 seconds. Some MCP clients stop waiting for a tool after a fixed time, so transcribe long recordings one at a time with `attachmentId`. Transcripts longer than `APPLE_NOTES_MCP_EXPORT_MAX_BYTES` are shortened and marked `transcriptTruncated`.
+
+**Speech models:** the call never starts a download on its own. When the language's on-device model is not installed, it returns `asset_unavailable` right away. Pass `downloadAssets: true` to let macOS download it (a one-time download); if it is still downloading when the call ends, try again shortly.
+
+**Speech Recognition permission:** the server never shows the Speech Recognition prompt, because nobody may be watching an MCP server to answer it. The helper reads the current authorization first. On older macOS, the `SFSpeechRecognizer` path needs that access, and macOS attributes the grant to the app that launches the MCP server (Claude Desktop, Codex, Terminal, and so on), not to the helper. Without it the call returns `code: "permission_required"`; allow the app under System Settings > Privacy & Security > Speech Recognition. On macOS 26 and later, `SpeechAnalyzer` transcribed files without any grant in testing (authorization stayed "not determined"), so only an explicit refusal (denied or restricted) stops it.
+
+---
+
 #### `add-attachment`
 
 Adds one nonempty local file of at most 64 MiB to an exact note using `id`, the
@@ -2493,13 +2527,13 @@ Every tool that does not read the Notes database works normally without Full Dis
 - `get-note-link` returns an error on macOS 26+; on macOS 12–15 it still works via the AppleScript `note link` fallback
 - `get-note-markdown` returns plain list items without `[x]`/`[ ]` annotations (graceful fallback)
 - `get-sync-status` still answers, but reports no pending uploads and no active sync — treat that as "unknown", not "idle"
-- `get-note-drawings` returns the same Full Disk Access error
+- `get-note-drawings` and `transcribe-note-audio` return the same Full Disk Access error
 
 ---
 
 ## Public native helper
 
-`get-note-drawings` needs Apple's PencilKit framework, which has no AppleScript or command-line interface. For it, the server uses a small Swift helper that links public Apple frameworks only (AppKit and PencilKit). No prebuilt binary ships with the package. Build it once on your Mac:
+`get-note-drawings` needs Apple's PencilKit framework and `transcribe-note-audio` needs the Speech framework; neither has an AppleScript or command-line interface. For them, the server uses a small Swift helper that links public Apple frameworks only (AppKit, PencilKit, AVFoundation, and Speech). No prebuilt binary ships with the package. Build it once on your Mac:
 
 ```bash
 apple-notes-mcp setup --public-helper          # compile, sign, verify, install
@@ -2508,7 +2542,7 @@ apple-notes-mcp setup --public-helper --check  # report the installed state only
 
 Setup compiles `native/public-helper/apple-notes-public-helper.swift` with `xcrun swiftc` (install the Command Line Tools with `xcode-select --install` if it is missing), signs it ad hoc, runs its `hello` handshake, and installs it in `~/Library/Application Support/apple-notes-mcp/public-helper/` next to a manifest recording the SHA-256 of the source and the binary. Before every use the server re-checks both digests: after an upgrade that changes the helper source, or if the binary is replaced, the helper is refused until you run setup again. `APPLE_NOTES_MCP_PUBLIC_HELPER_DIR` overrides the install folder and `APPLE_NOTES_MCP_PUBLIC_HELPER_TIMEOUT_MS` the per-call timeout.
 
-The helper never opens the Notes database and never writes under the Notes group container. The server reads the bytes it needs (read-only) and passes them to the helper on stdin; the helper answers with one JSON object on stdout.
+The helper never opens the Notes database and never writes under the Notes group container. The server reads the bytes it needs (read-only) and passes them to the helper on stdin, or, for transcription, names one audio file that the helper opens for reading; the helper answers with one JSON object on stdout.
 
 ---
 

package/build/index.js

@@ -24465,14 +24465,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join27(output, replacement);
+        return join28(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join27(output, rule.append(self.options));
+          output = join28(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24484,7 +24484,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join27(output, replacement) {
+    function join28(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -42825,15 +42825,27 @@ var AppleNotesManager = class {
    * @returns HTML content of the note, or empty string if not found
    */
   getNoteContentById(id2) {
+    return this.readNoteBodyById(id2).body;
+  }
+  /**
+   * Like {@link getNoteContentById}, but keeps the automation error so a
+   * caller can explain a failed read (for example a timeout on a note whose
+   * body carries a very large inline image, #237) instead of reporting a bare
+   * failure.
+   *
+   * @param id - CoreData URL identifier for the note
+   * @returns The HTML body, or an empty body plus the error that stopped the read
+   */
+  readNoteBodyById(id2) {
     const safeId = sanitizeId(id2);
     const getCommand = `get body of note id "${safeId}"`;
     const script = buildAppLevelScript(getCommand);
     const result = executeAppleScript(script);
     if (!result.success) {
       console.error(`Failed to get content of note with ID "${id2}":`, result.error);
-      return "";
+      return { body: "", error: result.error };
     }
-    return result.output;
+    return { body: result.output };
   }
   /**
    * Retrieves the plain-text content of a note by its exact title.
@@ -49593,6 +49605,37 @@ function readNoteStructure(id2, { dbPath: dbPath2 = NOTES_DB_PATH7, includeText
   };
 }
 
+// src/utils/bodyReadFailure.ts
+var LARGE_ATTACHMENT_BYTES = 5 * 1024 * 1024;
+function classifyBodyReadError(error2) {
+  if (!error2) return "other";
+  if (/ENOBUFS|maxBuffer/i.test(error2)) return "buffer";
+  if (/timed out|timeout|-1712/i.test(error2)) return "timeout";
+  return "other";
+}
+function formatBytes2(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${bytes} bytes`;
+}
+function largeAttachments(attachments, threshold = LARGE_ATTACHMENT_BYTES) {
+  const flat = attachments.flatMap((a) => [a, ...a.children ?? []]);
+  return flat.filter((a) => typeof a.fileSize === "number" && a.fileSize >= threshold).map((a) => ({ name: a.filename || a.title || "attachment", bytes: a.fileSize })).sort((a, b) => b.bytes - a.bytes);
+}
+function describeBodyReadFailure(title, error2, attachments) {
+  const base = `Failed to read content of note "${title}"${error2 ? `: ${error2}` : ""}`;
+  const kind = classifyBodyReadError(error2);
+  if (kind === "other") return base;
+  const large = attachments ? largeAttachments(attachments) : [];
+  const cause = large.length > 0 ? `The note holds ${large.length === 1 ? "a large attachment" : "large attachments"} (${large.map((a) => `${a.name}, ${formatBytes2(a.bytes)}`).join(
+    "; "
+  )}). Notes.app returns images inside the note body as base64, so a large image makes the body too big to read in time.` : "Notes.app returns images inside the note body as base64, so a note with a very large image can take longer to read than the timeout allows.";
+  const remedy = kind === "buffer" ? "Raise APPLE_NOTES_MCP_MAX_BUFFER (bytes) and retry, or remove the attachment in Notes.app." : "Retry with a longer timeoutSeconds (up to 120) or raise APPLE_NOTES_MCP_TIMEOUT_MS. If it still fails, delete or shrink the attachment in Notes.app; delete-note needs a successful read to verify the note first.";
+  return `${base}
+
+${cause} ${remedy}`;
+}
+
 // src/utils/noteLinkInventory.ts
 import { dirname as dirname5 } from "node:path";
 var BODY_BATCH = 100;
@@ -54637,7 +54680,7 @@ function formatShortcutSetup(report) {
 }
 
 // src/services/publicHelper.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawn, spawnSync as spawnSync3 } from "node:child_process";
 import { createHash as createHash5 } from "node:crypto";
 import {
   chmodSync,
@@ -54659,7 +54702,11 @@ var PUBLIC_HELPER_BINARY = "apple-notes-public-helper";
 var PUBLIC_HELPER_SOURCE = "native/public-helper/apple-notes-public-helper.swift";
 var PUBLIC_HELPER_MANIFEST = "manifest.json";
 var PUBLIC_HELPER_SETUP_COMMAND = "apple-notes-mcp setup --public-helper";
-var PUBLIC_HELPER_ACTIONS = /* @__PURE__ */ new Set(["hello", "decode_drawing"]);
+var PUBLIC_HELPER_ACTIONS = /* @__PURE__ */ new Set([
+  "hello",
+  "decode_drawing",
+  "transcribe"
+]);
 var DEFAULT_TIMEOUT_MS2 = 3e4;
 var MAX_OUTPUT_BYTES = 256 * 1024 * 1024;
 var publicManifestSchema = external_exports.object({
@@ -54695,6 +54742,7 @@ function defaultPublicHelperDeps(overrides = {}) {
     exists: existsSync14,
     readFile: (path10) => readFileSync4(path10),
     spawn: spawnSync3,
+    spawnAsync: spawn,
     ...overrides
   };
 }
@@ -54759,10 +54807,14 @@ var UNAVAILABLE_CODES = /* @__PURE__ */ new Set([
   "helper_modified",
   "helper_manifest_invalid"
 ]);
+var ENVELOPE_CODES = {
+  invalid_request: "validation_error",
+  attachment_not_found: "not_found"
+};
 var PublicHelperError = class extends CodedError {
   constructor(code, message) {
     super(message, {
-      code: UNAVAILABLE_CODES.has(code) ? "unsupported" : "operation_failed",
+      code: UNAVAILABLE_CODES.has(code) ? "unsupported" : ENVELOPE_CODES[code] ?? "operation_failed",
       helperCode: code
     });
     this.code = code;
@@ -54778,21 +54830,9 @@ var publicHelloSchema = external_exports.object({
   actions: external_exports.array(external_exports.string())
 }).passthrough();
 function callPublicHelper(action, fields = {}, deps = defaultPublicHelperDeps(), options = {}) {
-  if (!PUBLIC_HELPER_ACTIONS.has(action))
-    throw new PublicHelperError(
-      "unknown_action",
-      `"${action}" is not an action the server sends to the public helper.`
-    );
-  let binaryPath = options.binaryPath;
-  if (!binaryPath) {
-    const install = inspectPublicHelper(deps);
-    if (!install.ready)
-      throw new PublicHelperError(install.reason ?? "helper_not_installed", install.detail ?? "");
-    binaryPath = install.binaryPath;
-  }
-  const timeout = Number.parseInt(deps.env[PUBLIC_HELPER_TIMEOUT_ENV] || "", 10) || options.timeoutMs || DEFAULT_TIMEOUT_MS2;
+  const { binaryPath, timeout, input } = prepareCall(action, fields, deps, options);
   const result = deps.spawn(binaryPath, [], {
-    input: JSON.stringify({ protocol: PUBLIC_HELPER_PROTOCOL, action, ...fields }),
+    input,
     encoding: "utf8",
     timeout,
     killSignal: "SIGKILL",
@@ -54806,24 +54846,100 @@ function callPublicHelper(action, fields = {}, deps = defaultPublicHelperDeps(),
       "helper_unreachable",
       `Could not run the helper: ${result.error.message}`
     );
+  return parseHelperOutput(result.status, String(result.stdout ?? ""));
+}
+async function callPublicHelperAsync(action, fields = {}, deps = defaultPublicHelperDeps(), options = {}) {
+  const { binaryPath, timeout, input } = prepareCall(action, fields, deps, options);
+  const { signal } = options;
+  const aborted2 = () => new PublicHelperError("aborted", "The request was cancelled; the helper was stopped.");
+  if (signal?.aborted) throw aborted2();
+  return new Promise((resolvePromise, reject) => {
+    const child = (deps.spawnAsync ?? spawn)(binaryPath, [], {
+      stdio: ["pipe", "pipe", "ignore"]
+    });
+    const chunks = [];
+    let size = 0;
+    let failure = null;
+    const stop = (error2) => {
+      failure ??= error2;
+      child.kill("SIGKILL");
+    };
+    const timer = setTimeout(
+      () => stop(new PublicHelperError("timeout", `The helper did not answer within ${timeout} ms.`)),
+      timeout
+    );
+    const onAbort = () => stop(aborted2());
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const settle = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    child.stdout?.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_OUTPUT_BYTES)
+        stop(new PublicHelperError("invalid_response", "The helper response is too large."));
+      else chunks.push(chunk);
+    });
+    child.on("error", (error2) => {
+      settle();
+      reject(
+        failure ?? new PublicHelperError("helper_unreachable", `Could not run the helper: ${error2.message}`)
+      );
+    });
+    child.on("close", (status, exitSignal) => {
+      settle();
+      if (failure) return reject(failure);
+      if (status === null && exitSignal)
+        return reject(
+          new PublicHelperError("helper_crashed", `The helper stopped on signal ${exitSignal}.`)
+        );
+      try {
+        resolvePromise(parseHelperOutput(status, Buffer.concat(chunks).toString("utf8")));
+      } catch (error2) {
+        reject(error2);
+      }
+    });
+    child.stdin?.on("error", () => {
+    });
+    child.stdin?.end(input);
+  });
+}
+function prepareCall(action, fields, deps, options) {
+  if (!PUBLIC_HELPER_ACTIONS.has(action))
+    throw new PublicHelperError(
+      "unknown_action",
+      `"${action}" is not an action the server sends to the public helper.`
+    );
+  let binaryPath = options.binaryPath;
+  if (!binaryPath) {
+    const install = inspectPublicHelper(deps);
+    if (!install.ready)
+      throw new PublicHelperError(install.reason ?? "helper_not_installed", install.detail ?? "");
+    binaryPath = install.binaryPath;
+  }
+  const timeout = options.timeoutMs || Number.parseInt(deps.env[PUBLIC_HELPER_TIMEOUT_ENV] || "", 10) || DEFAULT_TIMEOUT_MS2;
+  const input = JSON.stringify({ protocol: PUBLIC_HELPER_PROTOCOL, action, ...fields });
+  return { binaryPath, timeout, input };
+}
+function parseHelperOutput(status, stdout) {
   let parsed;
   try {
-    parsed = JSON.parse(String(result.stdout ?? "").trim());
+    parsed = JSON.parse(stdout.trim());
   } catch {
     throw new PublicHelperError(
       "invalid_response",
-      `The helper exited with status ${result.status} and no JSON response.`
+      `The helper exited with status ${status} and no JSON response.`
     );
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
     throw new PublicHelperError("invalid_response", "The helper response is not a JSON object.");
   const object3 = parsed;
-  if (result.status !== 0 || object3.status !== "ok") {
+  if (status !== 0 || object3.status !== "ok") {
     const error2 = errorSchema.safeParse(object3);
     if (!error2.success)
       throw new PublicHelperError(
         "invalid_response",
-        `The helper failed with an unrecognized response (exit ${result.status}).`
+        `The helper failed with an unrecognized response (exit ${status}).`
       );
     throw new PublicHelperError(error2.data.code, error2.data.message);
   }
@@ -54870,6 +54986,10 @@ function publicHelperCompileArguments(sourcePath, digestPath, plistPath, outputP
     "AppKit",
     "-framework",
     "PencilKit",
+    "-framework",
+    "AVFoundation",
+    "-framework",
+    "Speech",
     "-Xlinker",
     "-sectcreate",
     "-Xlinker",
@@ -55236,6 +55356,313 @@ function formatNoteDrawings(result) {
   return lines.join("\n");
 }
 
+// src/utils/noteAudio.ts
+import { readdirSync as readdirSync4, statSync as statSync4 } from "node:fs";
+import { join as join25 } from "node:path";
+var EXTRA_AUDIO_UTIS = [
+  "public.mp3",
+  "public.aiff-audio",
+  "public.aifc-audio",
+  "com.microsoft.waveform-audio"
+];
+function audioRowsSql(columns, generationColumn) {
+  const generation = generationColumn ? `m.${generationColumn}` : "NULL";
+  const media = (alias) => `json((SELECT json_object('identifier', m.ZIDENTIFIER, 'generation', ${generation}, 'filename', m.ZFILENAME) FROM ZICCLOUDSYNCINGOBJECT m WHERE m.Z_PK = ${alias}.ZMEDIA))`;
+  const live = (alias) => notTombstonedSql(columns, alias);
+  const utis = EXTRA_AUDIO_UTIS.map((u) => `'${u}'`).join(", ");
+  const accountCols = [...columns].filter((c) => /^ZACCOUNT\d*$/.test(c)).sort();
+  const account = accountCols.length ? `SELECT (SELECT acc.ZIDENTIFIER FROM ZICCLOUDSYNCINGOBJECT acc WHERE acc.Z_ENT = ${entity("ICAccount")} AND acc.Z_PK IN (${accountCols.map((c) => `n.${c}`).join(", ")}) LIMIT 1) FROM ZICCLOUDSYNCINGOBJECT n WHERE n.Z_PK = @pk;` : "SELECT NULL;";
+  return [
+    NOTE_STATE_SQL,
+    `SELECT json_group_array(json_object('pk', a.Z_PK, 'identifier', a.ZIDENTIFIER, 'uti', a.ZTYPEUTI, 'duration', a.ZDURATION, 'media', ${media("a")}, 'children', json((SELECT json_group_array(json_object('pk', c.Z_PK, 'identifier', c.ZIDENTIFIER, 'duration', c.ZDURATION, 'media', ${media("c")})) FROM (SELECT * FROM ZICCLOUDSYNCINGOBJECT k WHERE k.ZPARENTATTACHMENT = a.Z_PK AND ${live("k")} ORDER BY k.Z_PK) c)))) FROM (SELECT * FROM ZICCLOUDSYNCINGOBJECT t WHERE t.ZNOTE = @pk AND t.ZPARENTATTACHMENT IS NULL AND ${live("t")} AND (t.ZTYPEUTI LIKE '%audio%' OR t.ZTYPEUTI IN (${utis})) ORDER BY t.Z_PK) a;`,
+    account
+  ].join("\n");
+}
+function accountDirsFor(containerDir, accountIdentifier) {
+  const own = resolveAccountDir(containerDir, accountIdentifier);
+  if (own) return [own];
+  let names;
+  try {
+    names = readdirSync4(join25(containerDir, "Accounts")).sort();
+  } catch {
+    return [];
+  }
+  return names.map((name) => safeComponent(name) ? resolveAccountDir(containerDir, name) : null).filter((dir) => dir !== null);
+}
+function resolveMediaPath(media, accountIdentifier = null, containerDir = NOTES_CONTAINER_DIR) {
+  const id2 = safeComponent(media?.identifier);
+  const filename = safeComponent(media?.filename);
+  if (!id2 || !filename) return null;
+  const generation = safeComponent(media?.generation);
+  for (const dir of accountDirsFor(containerDir, accountIdentifier)) {
+    const base = join25(dir, "Media", id2);
+    const candidates = generation ? [join25(base, generation, filename), join25(base, filename)] : [join25(base, filename)];
+    for (const candidate of candidates) {
+      const real = realInside(candidate, dir);
+      if (real && isFile2(real)) return real;
+    }
+  }
+  return null;
+}
+function isFile2(path10) {
+  try {
+    return statSync4(path10).isFile();
+  } catch {
+    return false;
+  }
+}
+var positive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+function readAudioAssets(noteId3, options = {}) {
+  const { store, pk } = parseNoteId2(noteId3);
+  const dbPath2 = options.dbPath ?? NOTES_DB_PATH7;
+  const columns = readColumns(dbPath2);
+  const missing = ["ZMEDIA", "ZPARENTATTACHMENT", "ZFILENAME"].filter((c) => !columns.has(c));
+  if (missing.length)
+    throw new NoteStoreError(
+      `This macOS version's Notes database lacks ${missing.join(", ")}; audio files cannot be located.`,
+      "schema"
+    );
+  const generation = columns.has("ZGENERATION1") ? "ZGENERATION1" : columns.has("ZGENERATION") ? "ZGENERATION" : null;
+  const [stateLine, rowsLine, accountLine] = queryNoteScoped(
+    audioRowsSql(columns, generation),
+    pk,
+    dbPath2
+  );
+  assertNoteReadable(stateLine, noteId3);
+  const rows = JSON.parse(rowsLine || "[]");
+  const account = accountLine?.trim() || null;
+  const attachmentId = (rowPk) => `x-coredata://${store}/ICAttachment/p${rowPk}`;
+  return rows.map((row) => {
+    const sources = row.children?.length ? row.children : [{ pk: row.pk, identifier: row.identifier, duration: row.duration, media: row.media }];
+    const takes = sources.map((take) => ({
+      attachmentId: attachmentId(take.pk),
+      identifier: take.identifier ?? "",
+      durationSeconds: positive(take.duration),
+      path: resolveMediaPath(take.media, account, options.containerDir)
+    }));
+    const total = takes.reduce((sum, t) => sum + (t.durationSeconds ?? 0), 0);
+    return {
+      pk: row.pk,
+      attachmentId: attachmentId(row.pk),
+      identifier: row.identifier ?? "",
+      typeUti: row.uti,
+      durationSeconds: positive(row.duration) ?? positive(total),
+      takes
+    };
+  });
+}
+function countWords2(text2) {
+  return text2.split(/\s+/u).filter((w) => /[\p{L}\p{N}]/u.test(w)).length;
+}
+
+// src/services/noteTranscription.ts
+var DEFAULT_TRANSCRIPTION_LOCALE = "en-US";
+var LOCALE_PATTERN = /^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8}){0,3}$/;
+var TRANSCRIBE_MAX_SECONDS = { default: 900, min: 30, max: 3600 };
+function takeDeadlineSeconds(durationSeconds) {
+  const duration3 = durationSeconds ?? 600;
+  return Math.min(1800, Math.max(60, Math.ceil(duration3 * 1.5) + 60));
+}
+var KILL_GRACE_MS = 3e4;
+var BUDGET_MARGIN_MS = 1e4;
+var MIN_TAKE_SECONDS = 5;
+var CALL_WIDE_CODES = /* @__PURE__ */ new Set([
+  "permission_required",
+  "asset_unavailable",
+  "unsupported_locale",
+  "speech_unavailable"
+]);
+var helperTranscriptSchema = external_exports.object({
+  status: external_exports.literal("ok"),
+  transcript: external_exports.string(),
+  complete: external_exports.boolean(),
+  stopReason: external_exports.string().optional(),
+  engine: external_exports.string().optional(),
+  durationSeconds: external_exports.number().optional()
+});
+async function transcribeTake(take, ctx) {
+  const base = {
+    attachmentId: take.attachmentId,
+    identifier: take.identifier,
+    status: "error",
+    ...take.durationSeconds !== null ? { durationSeconds: Math.round(take.durationSeconds) } : {}
+  };
+  const failed = (code, message) => ({
+    take: { ...base, code, message },
+    text: ""
+  });
+  if (!take.path)
+    return failed(
+      "asset_unavailable",
+      "The audio file is not on this Mac (it may not have downloaded from iCloud yet)."
+    );
+  if (ctx.callWide) return failed(ctx.callWide.code, ctx.callWide.message);
+  const remainingMs = ctx.deadlineAt - ctx.now();
+  const deadline = Math.min(
+    takeDeadlineSeconds(take.durationSeconds),
+    Math.floor((remainingMs - BUDGET_MARGIN_MS) / 1e3)
+  );
+  if (deadline < MIN_TAKE_SECONDS)
+    return failed(
+      "time_limit",
+      `Not started: the call's ${ctx.maxSeconds}-second limit was reached. Transcribe this recording on its own with attachmentId, or raise maxSeconds.`
+    );
+  let raw;
+  try {
+    raw = await callPublicHelperAsync(
+      "transcribe",
+      {
+        path: take.path,
+        locale: ctx.locale,
+        timeoutSeconds: deadline,
+        downloadAssets: ctx.downloadAssets
+      },
+      ctx.deps,
+      { timeoutMs: Math.min(deadline * 1e3 + KILL_GRACE_MS, remainingMs), signal: ctx.signal }
+    );
+  } catch (error2) {
+    const code = error2 instanceof PublicHelperError ? error2.code : "internal_error";
+    if (code === "aborted") throw error2;
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    if (CALL_WIDE_CODES.has(code)) ctx.callWide = { code, message };
+    return {
+      take: {
+        ...base,
+        // A timeout means the helper was killed mid-run: the outcome is unknown.
+        status: code === "timeout" ? "indeterminate" : "error",
+        code,
+        message
+      },
+      text: ""
+    };
+  }
+  const parsed = helperTranscriptSchema.safeParse(raw);
+  if (!parsed.success) return failed("invalid_response", "Unexpected helper response.");
+  const { transcript, complete, stopReason, engine, durationSeconds } = parsed.data;
+  const text2 = transcript.trim();
+  return {
+    take: {
+      ...base,
+      status: complete ? "ok" : text2 ? "partial" : "indeterminate",
+      ...complete ? {} : { code: "incomplete", message: stopReason ?? "stopped early" },
+      ...durationSeconds !== void 0 ? { durationSeconds } : {},
+      wordCount: countWords2(text2),
+      ...engine ? { engine } : {}
+    },
+    text: text2
+  };
+}
+function combineStatus(parts) {
+  if (parts.length && parts.every((p) => p.status === "ok")) return "ok";
+  if (parts.some((p) => p.hasText)) return "partial";
+  if (parts.some((p) => p.status === "indeterminate")) return "indeterminate";
+  return "error";
+}
+async function transcribeRecording(asset, includeText, ctx) {
+  const outcomes = [];
+  for (const take of asset.takes) outcomes.push(await transcribeTake(take, ctx));
+  const transcript = outcomes.map((o) => o.text).filter(Boolean).join("\n\n");
+  const status = combineStatus(
+    outcomes.map((o) => ({ status: o.take.status, hasText: o.text.length > 0 }))
+  );
+  const firstProblem = outcomes.find((o) => o.take.status !== "ok")?.take;
+  return {
+    attachmentId: asset.attachmentId,
+    identifier: asset.identifier,
+    typeUti: asset.typeUti,
+    status,
+    ...status !== "ok" && firstProblem?.code ? { code: firstProblem.code, message: firstProblem.message } : {},
+    ...asset.durationSeconds !== null ? { durationSeconds: Math.round(asset.durationSeconds) } : {},
+    wordCount: countWords2(transcript),
+    ...includeText ? { transcript } : {},
+    takes: outcomes.map((o) => o.take)
+  };
+}
+async function transcribeNoteAudio(noteId3, options = {}) {
+  const locale = options.locale ?? DEFAULT_TRANSCRIPTION_LOCALE;
+  if (!LOCALE_PATTERN.test(locale))
+    throw new PublicHelperError("invalid_request", `"${locale}" is not a BCP-47 locale.`);
+  const maxSeconds = options.maxSeconds ?? TRANSCRIBE_MAX_SECONDS.default;
+  if (!Number.isInteger(maxSeconds) || maxSeconds < TRANSCRIBE_MAX_SECONDS.min || maxSeconds > TRANSCRIBE_MAX_SECONDS.max)
+    throw new PublicHelperError(
+      "invalid_request",
+      `maxSeconds must be a whole number from ${TRANSCRIBE_MAX_SECONDS.min} to ${TRANSCRIBE_MAX_SECONDS.max}.`
+    );
+  const deps = options.deps ?? defaultPublicHelperDeps();
+  let assets = (options.readAssets ?? ((id2) => readAudioAssets(id2)))(noteId3);
+  if (options.attachmentId) {
+    assets = assets.filter((a) => a.attachmentId === options.attachmentId);
+    if (assets.length === 0)
+      throw new PublicHelperError(
+        "attachment_not_found",
+        `No audio attachment ${options.attachmentId} in note ${noteId3}.`
+      );
+  }
+  const empty = { id: noteId3, locale, recordingCount: 0, recordings: [] };
+  if (assets.length === 0) return { ...empty, status: "none" };
+  const install = inspectPublicHelper(deps);
+  if (!install.ready)
+    throw new PublicHelperError(install.reason ?? "helper_not_installed", install.detail ?? "");
+  const now = options.now ?? Date.now;
+  const ctx = {
+    locale,
+    downloadAssets: options.downloadAssets ?? false,
+    deps,
+    signal: options.signal,
+    now,
+    deadlineAt: now() + maxSeconds * 1e3,
+    maxSeconds,
+    callWide: null
+  };
+  const recordings = [];
+  for (const asset of assets)
+    recordings.push(await transcribeRecording(asset, options.includeText ?? true, ctx));
+  return {
+    ...empty,
+    status: combineStatus(
+      recordings.map((r) => ({ status: r.status, hasText: (r.wordCount ?? 0) > 0 }))
+    ),
+    recordingCount: recordings.length,
+    recordings
+  };
+}
+function fitTranscriptions(result, maxBytes, measure = (r) => Buffer.byteLength(JSON.stringify(r))) {
+  if (measure(result) <= maxBytes) return result;
+  let next = result;
+  for (let share = 0.5; measure(next) > maxBytes && share > 1e-4; share /= 2) {
+    next = {
+      ...result,
+      recordings: result.recordings.map(
+        (r) => r.transcript ? {
+          ...r,
+          transcript: r.transcript.slice(0, Math.floor(r.transcript.length * share)),
+          transcriptTruncated: true
+        } : r
+      )
+    };
+  }
+  return next;
+}
+function formatTranscription(result) {
+  if (result.recordingCount === 0) return `No audio attachments in note ${result.id}.`;
+  const lines = [
+    `${result.recordingCount} audio attachment${result.recordingCount === 1 ? "" : "s"} in note ${result.id} (${result.status}, locale ${result.locale}):`
+  ];
+  result.recordings.forEach((r, i) => {
+    const facts = [
+      `status ${r.status}`,
+      ...r.durationSeconds !== void 0 ? [`${r.durationSeconds} s`] : [],
+      `${r.wordCount ?? 0} words`,
+      ...r.takes.length > 1 ? [`${r.takes.length} takes`] : [],
+      ...r.code ? [`${r.code}: ${r.message}`] : []
+    ];
+    lines.push("", `[${i + 1}] ${r.attachmentId} (${facts.join(", ")})`);
+    if (r.transcript)
+      lines.push(r.transcriptTruncated ? `${r.transcript} [truncated]` : r.transcript);
+  });
+  return lines.join("\n");
+}
+
 // src/services/privateHelperBuild.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
 import {
@@ -55248,14 +55675,14 @@ import {
   writeFileSync as writeFileSync5
 } from "node:fs";
 import { release as release4 } from "node:os";
-import { join as join26 } from "node:path";
+import { join as join27 } from "node:path";
 
 // src/services/privateHelper.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
 import { existsSync as existsSync15, readFileSync as readFileSync5 } from "node:fs";
 import { homedir as homedir20 } from "node:os";
-import { dirname as dirname9, join as join25, resolve as resolve6 } from "node:path";
+import { dirname as dirname9, join as join26, resolve as resolve6 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var PRIVATE_HELPER_PROTOCOL = 1;
 var ENABLE_ENV = "APPLE_NOTES_MCP_ENABLE_PRIVATE";
@@ -55283,7 +55710,7 @@ var manifestSchema = external_exports.object({
 function packageRoot2(fromDir = dirname9(fileURLToPath3(import.meta.url))) {
   let dir = fromDir;
   for (; ; ) {
-    const candidate = join25(dir, "package.json");
+    const candidate = join26(dir, "package.json");
     if (existsSync15(candidate)) {
       try {
         const pkg = JSON.parse(readFileSync5(candidate, "utf8"));
@@ -55300,7 +55727,7 @@ function defaultDeps2(overrides = {}) {
   return {
     env: process.env,
     platform: process.platform,
-    sourcePath: join25(packageRoot2(), HELPER_SOURCE_RELATIVE),
+    sourcePath: join26(packageRoot2(), HELPER_SOURCE_RELATIVE),
     exists: existsSync15,
     readFile: (path10) => readFileSync5(path10),
     spawn: spawnSync4,
@@ -55313,14 +55740,14 @@ function privateHelperEnabled(env = process.env) {
 function helperInstallDir(env = process.env) {
   const override = env[HELPER_DIR_ENV]?.trim();
   if (override) return override;
-  return join25(homedir20(), "Library", "Application Support", "apple-notes-mcp", "private-helper");
+  return join26(homedir20(), "Library", "Application Support", "apple-notes-mcp", "private-helper");
 }
 function sha256Hex2(data) {
   return createHash6("sha256").update(data).digest("hex");
 }
 function inspectInstallation(deps = defaultDeps2()) {
   const installDir = helperInstallDir(deps.env);
-  const binaryPath = join25(installDir, HELPER_BINARY_NAME);
+  const binaryPath = join26(installDir, HELPER_BINARY_NAME);
   const base = {
     installDir,
     binaryPath,
@@ -55338,7 +55765,7 @@ function inspectInstallation(deps = defaultDeps2()) {
   if (!deps.exists(deps.sourcePath))
     return fail("helper_not_installed", `Packaged helper source is missing: ${deps.sourcePath}`);
   base.expectedSourceSha256 = sha256Hex2(deps.readFile(deps.sourcePath));
-  const manifestPath = join25(installDir, MANIFEST_NAME);
+  const manifestPath = join26(installDir, MANIFEST_NAME);
   if (!deps.exists(binaryPath) || !deps.exists(manifestPath))
     return fail(
       "helper_not_installed",
@@ -55653,9 +56080,9 @@ function buildPrivateHelper(checkOnly, deps = defaultBuildDeps()) {
   steps.push({ step: "find compiler", ok: true, detail: compiler });
   const installDir = helperInstallDir(deps.env);
   mkdirSync7(installDir, { recursive: true, mode: 448 });
-  const staging = mkdtempSync6(join26(installDir, ".staging-"));
+  const staging = mkdtempSync6(join27(installDir, ".staging-"));
   try {
-    const stagedBinary = join26(staging, HELPER_BINARY_NAME);
+    const stagedBinary = join27(staging, HELPER_BINARY_NAME);
     const compile = deps.spawn(
       "/usr/bin/xcrun",
       compileArguments(deps.sourcePath, stagedBinary, sourceSha),
@@ -55732,8 +56159,8 @@ function buildPrivateHelper(checkOnly, deps = defaultBuildDeps()) {
       compiler
     };
     chmodSync2(stagedBinary, 448);
-    renameSync2(stagedBinary, join26(installDir, HELPER_BINARY_NAME));
-    writeFileSync5(join26(installDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2) + "\n", {
+    renameSync2(stagedBinary, join27(installDir, HELPER_BINARY_NAME));
+    writeFileSync5(join27(installDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2) + "\n", {
       mode: 384
     });
     steps.push({ step: "install", ok: true, detail: installDir });
@@ -55927,6 +56354,16 @@ function withErrorHandling(handler, errorPrefix) {
     }
   };
 }
+function withAsyncErrorHandling(handler, errorPrefix) {
+  return async (params, extra) => {
+    try {
+      return await handler(params, extra?.signal);
+    } catch (error2) {
+      const message = error2 instanceof Error ? error2.message : "Unknown error";
+      return errorResponse(`${errorPrefix}: ${message}`, error2);
+    }
+  };
+}
 var MAX = {
   TITLE: 2e3,
   CONTENT: 5 * 1024 * 1024,
@@ -56010,11 +56447,25 @@ function readExactNoteSnapshot(id2) {
       error: `Note "${note.title}" is password-protected and cannot be changed. Unlock it in Notes.app first.`
     };
   }
-  const body = notesManager.getNoteContentById(id2);
-  if (!body) return { error: `Failed to read content of note "${note.title}"` };
+  const { body, error: error2 } = notesManager.readNoteBodyById(id2);
+  if (!body) {
+    const reason = bodyReadFailureMessage(id2, note.title, error2);
+    return { error: `${reason}${error2 ? "\n\nNothing was changed." : ""}` };
+  }
   const rich = enrichNoteRead(id2, body);
   return { note, body, rich, contentHash: richContentHash(body, rich) };
 }
+function bodyReadFailureMessage(id2, title, error2) {
+  let attachments;
+  if (classifyBodyReadError(error2) !== "other") {
+    try {
+      attachments = readNoteStructure(id2, { includeText: false }).attachments;
+    } catch {
+      attachments = void 0;
+    }
+  }
+  return describeBodyReadFailure(title, error2, attachments);
+}
 var NOT_DELETED_MESSAGE = "Notes.app accepted the delete, but the note is still in its original folder, so it was not moved to Recently Deleted. Nothing was deleted; read the note again before retrying.";
 function containerUnknownMessage(title) {
   return `Could not read which folder note "${title}" is in, so it may already be in Recently Deleted, where deleting it would remove it permanently. Nothing was deleted. Retry in a moment; if it keeps failing, quit and reopen Notes.app, then retry.`;
@@ -56428,13 +56879,14 @@ ${lines}${footer}`,
 registerTool(
   "get-note-content",
   {
-    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app.",
+    description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app. Notes.app returns images inside the body as base64, so a note with a very large image can time out; the error then names the cause, and a larger timeoutSeconds gives the read more time.",
     inputSchema: {
       id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
         "Account name (defaults to Notes.app's default account; exact or unique-prefix match, ignored if id is provided)"
-      )
+      ),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       id: external_exports.string().optional(),
@@ -56467,9 +56919,9 @@ registerTool(
           `Note "${note2.title}" is password-protected and cannot be read. Unlock it in Notes.app first.`
         );
       }
-      const rawContent2 = notesManager.getNoteContentById(id2);
+      const { body: rawContent2, error: readError2 } = notesManager.readNoteBodyById(id2);
       if (!rawContent2) {
-        return errorResponse(`Failed to read content of note "${note2.title}"`);
+        return errorResponse(bodyReadFailureMessage(id2, note2.title, readError2));
       }
       const rich2 = enrichNoteRead(id2, rawContent2);
       const stripped2 = stripLargeInlineImages(rich2.content);
@@ -56509,9 +56961,9 @@ registerTool(
         `Note "${title}" is password-protected and cannot be read. Unlock it in Notes.app first.`
       );
     }
-    const rawContent = notesManager.getNoteContent(title, account);
+    const { body: rawContent, error: readError } = notesManager.readNoteBodyById(note.id);
     if (!rawContent) {
-      return errorResponse(`Failed to read content of note "${title}"`);
+      return errorResponse(bodyReadFailureMessage(note.id, title, readError));
     }
     const rich = enrichNoteRead(note.id, rawContent);
     const stripped = stripLargeInlineImages(rich.content);
@@ -58948,6 +59400,49 @@ registerTool(
     });
   }, "Error reading drawings")
 );
+registerTool(
+  "transcribe-note-audio",
+  {
+    description: "Use when: you need the words spoken in a note's voice recordings or audio attachments, transcribed now on this Mac, by note id.\nReturns: per audio attachment a status (ok / partial / error / indeterminate), duration, word count, per-take results, and the transcript; overall status ok / partial / error / indeterminate / none.\nDo not use when: you only need the audio file (save-attachment) or a note has no audio.\nNote: read-only; recognition runs entirely on-device (never sent to a server). Needs Full Disk Access and the public native helper built once with `apple-notes-mcp setup --public-helper`. Long recordings take time: pass attachmentId to transcribe one at a time. An indeterminate result means the helper timed out; retrying may succeed. Never prompts: code permission_required means the user must allow the host app under System Settings > Privacy & Security > Speech Recognition. asset_unavailable can mean the language's speech model is not installed; pass downloadAssets: true only if the user agrees to the download.",
+    inputSchema: {
+      id: noteIdInput,
+      locale: external_exports.string().max(35).optional().describe('BCP-47 language of the speech, e.g. "en-US" (default), "it-IT", "fr-FR"'),
+      attachmentId: external_exports.string().max(MAX.ATTACHMENT_ID).optional().describe("Only transcribe this audio attachment (x-coredata ICAttachment id)"),
+      includeText: external_exports.boolean().optional().describe("Include transcript text (default true); false returns statuses and counts only"),
+      downloadAssets: external_exports.boolean().optional().describe(
+        "Let macOS download the language's on-device speech model if it is missing (default false: returns asset_unavailable at once)"
+      ),
+      maxSeconds: external_exports.number().int().min(TRANSCRIBE_MAX_SECONDS.min).max(TRANSCRIBE_MAX_SECONDS.max).optional().describe(
+        `Total time budget for the call in seconds (default ${TRANSCRIBE_MAX_SECONDS.default}); recordings not started in time report code time_limit`
+      )
+    },
+    outputSchema: {
+      id: external_exports.string().optional(),
+      locale: external_exports.string().optional(),
+      status: external_exports.string().optional(),
+      recordingCount: external_exports.number().optional(),
+      recordings: external_exports.array(external_exports.object({}).passthrough()).optional()
+    }
+  },
+  withAsyncErrorHandling(async (params, signal) => {
+    const { id: id2, locale, attachmentId, includeText, downloadAssets, maxSeconds } = params;
+    const result = fitTranscriptions(
+      await transcribeNoteAudio(id2, {
+        locale,
+        attachmentId,
+        includeText,
+        downloadAssets,
+        maxSeconds,
+        signal
+      }),
+      exportMaxResponseBytes()
+    );
+    return successResponse(
+      formatTranscription(result),
+      result
+    );
+  }, "Error transcribing audio")
+);
 registerTool(
   "list-recent-notes",
   {

package/native/public-helper/apple-notes-public-helper.swift

@@ -3,7 +3,8 @@
 // A small command-line helper for apple-notes-mcp that uses PUBLIC Apple
 // frameworks only. It never opens the Notes database and never writes to the
 // Notes group container: the TypeScript server reads the bytes it needs
-// (read-only) and hands them over on stdin.
+// (read-only) and hands them over on stdin, or names an audio file that the
+// helper opens for reading only.
 //
 // Protocol: one JSON object on stdin, one JSON object on stdout.
 //   request:  {"protocol": 1, "action": "<name>", ...fields}
@@ -15,6 +16,7 @@
 //   decode_drawing  PencilKit drawing bytes (base64) -> strokes
 //   encode_drawing  strokes -> PencilKit drawing bytes (base64); used to build
 //                   synthetic test fixtures, never to write to Notes
+//   transcribe      on-device Speech transcription of one audio file
 //
 // Build (done by `apple-notes-mcp setup --public-helper`, which also generates
 // the one-line source-digest file that defines helperSourceSHA256 and the
@@ -23,9 +25,11 @@
 //     -Xlinker -sectcreate -Xlinker __TEXT -Xlinker __info_plist -Xlinker Info.plist \
 //     apple-notes-public-helper.swift source-digest.swift -o apple-notes-public-helper
 
+import AVFoundation
 import AppKit
 import Foundation
 import PencilKit
+import Speech
 
 let protocolVersion = 1
 let maxInputBytes = 96 * 1024 * 1024
@@ -211,11 +215,331 @@ func encodeDrawing(_ request: [String: Any]) throws -> [String: Any] {
     return ["status": "ok", "strokeCount": strokes.count, "dataBase64": data.base64EncodedString()]
 }
 
+// MARK: - Transcription
+//
+// On-device only. On macOS 26 and later, SpeechAnalyzer with SpeechTranscriber
+// runs entirely on the Mac (its language model is a local asset). On older
+// systems, SFSpeechRecognizer is used with requiresOnDeviceRecognition = true,
+// and a locale without on-device support is refused rather than sent to a
+// server. The helper stops at its own deadline and returns what it has with
+// complete = false, so the caller can report a partial transcript.
+
+/// Final transcript segments gathered so far; an actor so the deadline path can read them.
+actor TranscriptCollector {
+    private var segments: [String] = []
+    func add(_ segment: String) { segments.append(segment) }
+    func text() -> String { segments.joined(separator: " ") }
+    func isEmpty() -> Bool { segments.isEmpty }
+}
+
+/// The newest partial result (legacy recognizer), guarded by a lock because the
+/// recognizer calls back on its own queue.
+final class LatestText: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value = ""
+    func set(_ text: String) { lock.withLock { value = text } }
+    func get() -> String { lock.withLock { value } }
+}
+
+enum RaceOutcome {
+    case completed
+    case failed(Error)
+    case timedOut
+}
+
+/// Resumes a continuation exactly once, whichever side of a race finishes first.
+final class RaceGate: @unchecked Sendable {
+    private let lock = NSLock()
+    private var continuation: CheckedContinuation<RaceOutcome, Never>?
+    private var expired = false
+    init(_ continuation: CheckedContinuation<RaceOutcome, Never>) { self.continuation = continuation }
+    /// Called when the deadline passes, before `stop`: whatever `work` reports
+    /// afterwards (usually a cancellation error) is a timeout, not a failure.
+    func expire() { lock.withLock { expired = true } }
+    func resume(_ outcome: RaceOutcome) {
+        let (pending, final): (CheckedContinuation<RaceOutcome, Never>?, RaceOutcome) = lock.withLock {
+            defer { continuation = nil }
+            return (continuation, expired ? .timedOut : outcome)
+        }
+        pending?.resume(returning: final)
+    }
+}
+
+/// Runs `work` against a deadline without waiting for it after the deadline:
+/// some framework calls (asset downloads) ignore cancellation, and the process
+/// exits right after it answers anyway. On timeout, `stop` runs first so a
+/// cooperative `work` can hand back what it has.
+func race(
+    seconds: Double,
+    work: @escaping @Sendable () async throws -> Void,
+    stop: @escaping @Sendable () async -> Void
+) async -> RaceOutcome {
+    await withCheckedContinuation { continuation in
+        let gate = RaceGate(continuation)
+        Task {
+            do {
+                try await work()
+                gate.resume(.completed)
+            } catch {
+                gate.resume(.failed(error))
+            }
+        }
+        Task {
+            try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+            gate.expire()
+            await stop()
+            gate.resume(.timedOut)
+        }
+    }
+}
+
+func authorizationName(_ status: SFSpeechRecognizerAuthorizationStatus) -> String {
+    switch status {
+    case .authorized: return "authorized"
+    case .denied: return "denied"
+    case .restricted: return "restricted"
+    case .notDetermined: return "notDetermined"
+    @unknown default: return "unknown"
+    }
+}
+
+// Speech Recognition access. The helper runs under an MCP server that nobody
+// may be watching, so it never calls SFSpeechRecognizer.requestAuthorization:
+// a system prompt would block the helper until the server killed it. It reads
+// the current status instead and stops with `permission_required` when the
+// engine it is about to use needs a grant that is missing.
+
+/// The failure returned instead of prompting. The grant belongs to the app that
+/// runs the MCP server (Claude, a terminal, ...), which macOS treats as responsible.
+func permissionRequired(_ status: SFSpeechRecognizerAuthorizationStatus) -> HelperFailure {
+    let settings = "System Settings > Privacy & Security > Speech Recognition"
+    let detail: String
+    switch status {
+    case .denied:
+        detail = "Speech Recognition access was denied for the app running this server. Turn it on in \(settings), then try again."
+    case .restricted:
+        detail = "Speech Recognition is restricted on this Mac (for example by a device management profile), so it cannot be used."
+    default:
+        detail = "Speech Recognition access has not been granted to the app running this server, and the server never shows the permission prompt. Allow the app in \(settings), then try again."
+    }
+    return HelperFailure(code: "permission_required", message: detail)
+}
+
+/// Stops before any Speech call when access is missing. The legacy recognizer
+/// needs `.authorized`. SpeechAnalyzer (macOS 26+) runs on-device without a
+/// grant and does not prompt, so there only an explicit refusal (`.denied` or
+/// `.restricted`) stops it; that also covers a future macOS that gates it.
+func checkSpeechAccess(requireGrant: Bool) throws {
+    let status = SFSpeechRecognizer.authorizationStatus()
+    if status == .authorized { return }
+    if requireGrant || status == .denied || status == .restricted {
+        throw permissionRequired(status)
+    }
+}
+
+/// Maps a Speech error to a stable code. Permission is decided from the
+/// explicit authorization status, never from the error's text.
+func speechFailure(_ error: Error, requireGrant: Bool) -> HelperFailure {
+    if let failure = error as? HelperFailure { return failure }
+    do {
+        try checkSpeechAccess(requireGrant: requireGrant)
+    } catch let failure as HelperFailure {
+        return failure
+    } catch {}
+    return HelperFailure(code: "transcription_failed", message: error.localizedDescription)
+}
+
+/// Makes sure the locale's on-device model is installed. A download starts only
+/// when the caller opted in: otherwise a missing model is `asset_unavailable` at once.
+@available(macOS 26, *)
+func ensureSpeechAssets(_ transcriber: SpeechTranscriber, localeID: String, allowDownload: Bool) async throws {
+    switch await AssetInventory.status(forModules: [transcriber]) {
+    case .installed:
+        return
+    case .unsupported:
+        throw HelperFailure(code: "unsupported_locale", message: "No on-device speech model for \(localeID)")
+    case .downloading where !allowDownload:
+        throw HelperFailure(
+            code: "asset_unavailable",
+            message: "macOS is still downloading the on-device speech model for \(localeID); try again shortly"
+        )
+    default:
+        if !allowDownload {
+            throw HelperFailure(
+                code: "asset_unavailable",
+                message: "The on-device speech model for \(localeID) is not installed. Retry with downloadAssets: true to let macOS download it."
+            )
+        }
+    }
+    guard let installation = try await AssetInventory.assetInstallationRequest(supporting: [transcriber]) else {
+        return
+    }
+    let outcome = await race(seconds: 90, work: { try await installation.downloadAndInstall() }, stop: {})
+    switch outcome {
+    case .completed:
+        return
+    case .failed(let error):
+        throw HelperFailure(
+            code: "asset_unavailable",
+            message: "Could not install the on-device speech model for \(localeID): \(error.localizedDescription)"
+        )
+    case .timedOut:
+        throw HelperFailure(
+            code: "asset_unavailable",
+            message: "The on-device speech model for \(localeID) is still downloading; try again shortly"
+        )
+    }
+}
+
+@available(macOS 26, *)
+func transcribeWithAnalyzer(
+    file: AVAudioFile, localeID: String, deadline: Double, allowDownload: Bool
+) async throws -> [String: Any] {
+    try checkSpeechAccess(requireGrant: false)
+    guard SpeechTranscriber.isAvailable else {
+        throw HelperFailure(code: "speech_unavailable", message: "On-device transcription is not available on this Mac")
+    }
+    guard let locale = await SpeechTranscriber.supportedLocale(equivalentTo: Locale(identifier: localeID)) else {
+        throw HelperFailure(code: "unsupported_locale", message: "No on-device transcription for \(localeID)")
+    }
+    let transcriber = SpeechTranscriber(locale: locale, preset: .transcription)
+    try await ensureSpeechAssets(transcriber, localeID: localeID, allowDownload: allowDownload)
+    let analyzer = SpeechAnalyzer(modules: [transcriber])
+    let collector = TranscriptCollector()
+    let reader = Task {
+        for try await result in transcriber.results where result.isFinal {
+            let segment = String(result.text.characters).trimmingCharacters(in: .whitespacesAndNewlines)
+            if !segment.isEmpty { await collector.add(segment) }
+        }
+    }
+    let outcome = await race(
+        seconds: deadline,
+        work: {
+            _ = try await analyzer.analyzeSequence(from: file)
+            try await analyzer.finalizeAndFinishThroughEndOfInput()
+            try await reader.value
+        },
+        stop: {
+            await analyzer.cancelAndFinishNow()
+            reader.cancel()
+        }
+    )
+    var response: [String: Any] = ["status": "ok", "engine": "SpeechAnalyzer", "locale": locale.identifier(.bcp47)]
+    switch outcome {
+    case .completed:
+        response["complete"] = true
+    case .timedOut:
+        response["complete"] = false
+        response["stopReason"] = "deadline"
+    case .failed(let error):
+        await analyzer.cancelAndFinishNow()
+        reader.cancel()
+        let failure = speechFailure(error, requireGrant: false)
+        if await collector.isEmpty() { throw failure }
+        response["complete"] = false
+        response["stopReason"] = failure.message
+    }
+    response["transcript"] = await collector.text()
+    return response
+}
+
+/// Pre-macOS 26 path: SFSpeechRecognizer, forced on-device. It needs a Speech
+/// Recognition grant, which is checked here and never requested.
+func transcribeWithRecognizer(url: URL, localeID: String, deadline: Double) async throws -> [String: Any] {
+    try checkSpeechAccess(requireGrant: true)
+    guard let recognizer = SFSpeechRecognizer(locale: Locale(identifier: localeID)) else {
+        throw HelperFailure(code: "unsupported_locale", message: "No speech recognizer for \(localeID)")
+    }
+    guard recognizer.supportsOnDeviceRecognition else {
+        throw HelperFailure(code: "unsupported_locale", message: "No on-device recognition for \(localeID)")
+    }
+    recognizer.queue = OperationQueue()
+    let request = SFSpeechURLRecognitionRequest(url: url)
+    request.requiresOnDeviceRecognition = true
+    request.shouldReportPartialResults = true
+    let latest = LatestText()
+    final class TaskBox: @unchecked Sendable { var task: SFSpeechRecognitionTask? }
+    let box = TaskBox()
+    let outcome = await race(
+        seconds: deadline,
+        work: {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+                var resumed = false
+                box.task = recognizer.recognitionTask(with: request) { result, error in
+                    if resumed { return }
+                    if let result {
+                        latest.set(result.bestTranscription.formattedString)
+                        if result.isFinal {
+                            resumed = true
+                            continuation.resume()
+                            return
+                        }
+                    }
+                    if let error {
+                        resumed = true
+                        continuation.resume(throwing: error)
+                    }
+                }
+            }
+        },
+        stop: { box.task?.cancel() }
+    )
+    // Partial results replace each other; the newest one is the transcript so far.
+    let transcript = await latest.get()
+    var response: [String: Any] = ["status": "ok", "engine": "SFSpeechRecognizer", "locale": localeID]
+    switch outcome {
+    case .completed:
+        response["complete"] = true
+    case .timedOut:
+        response["complete"] = false
+        response["stopReason"] = "deadline"
+    case .failed(let error):
+        let failure = speechFailure(error, requireGrant: true)
+        if transcript.isEmpty { throw failure }
+        response["complete"] = false
+        response["stopReason"] = failure.message
+    }
+    response["transcript"] = transcript
+    return response
+}
+
+func transcribe(_ request: [String: Any]) async throws -> [String: Any] {
+    guard let path = request["path"] as? String, path.hasPrefix("/") else {
+        throw HelperFailure(code: "invalid_request", message: "path must be an absolute file path")
+    }
+    let localeID = request["locale"] as? String ?? "en-US"
+    let deadline = min(max((request["timeoutSeconds"] as? NSNumber)?.doubleValue ?? 300, 5), 3600)
+    var isDirectory: ObjCBool = false
+    guard FileManager.default.fileExists(atPath: path, isDirectory: &isDirectory), !isDirectory.boolValue else {
+        throw HelperFailure(code: "file_not_found", message: "The audio file does not exist")
+    }
+    let url = URL(fileURLWithPath: path)
+    let file: AVAudioFile
+    do {
+        file = try AVAudioFile(forReading: url)
+    } catch {
+        throw HelperFailure(code: "unsupported_audio", message: "Could not read the audio: \(error.localizedDescription)")
+    }
+    let duration = file.fileFormat.sampleRate > 0 ? Double(file.length) / file.fileFormat.sampleRate : 0
+    var response: [String: Any]
+    if #available(macOS 26, *) {
+        response = try await transcribeWithAnalyzer(
+            file: file, localeID: localeID, deadline: deadline,
+            allowDownload: request["downloadAssets"] as? Bool ?? false
+        )
+    } else {
+        response = try await transcribeWithRecognizer(url: url, localeID: localeID, deadline: deadline)
+    }
+    response["durationSeconds"] = Int(duration.rounded())
+    response["speechAuthorization"] = authorizationName(SFSpeechRecognizer.authorizationStatus())
+    return response
+}
+
 // MARK: - Dispatch
 
-let actions = ["hello", "decode_drawing", "encode_drawing"]
+let actions = ["hello", "decode_drawing", "encode_drawing", "transcribe"]
 
-func handle(_ request: [String: Any]) throws -> [String: Any] {
+func handle(_ request: [String: Any]) async throws -> [String: Any] {
     guard (request["protocol"] as? NSNumber)?.intValue == protocolVersion else {
         throw HelperFailure(code: "protocol_mismatch", message: "expected protocol \(protocolVersion)")
     }
@@ -231,6 +555,8 @@ func handle(_ request: [String: Any]) throws -> [String: Any] {
         return try decodeDrawing(request)
     case "encode_drawing":
         return try encodeDrawing(request)
+    case "transcribe":
+        return try await transcribe(request)
     default:
         throw HelperFailure(code: "unknown_action", message: "unknown action")
     }
@@ -238,7 +564,7 @@ func handle(_ request: [String: Any]) throws -> [String: Any] {
 
 @main
 struct PublicHelper {
-    static func main() {
+    static func main() async {
         let input = FileHandle.standardInput.readDataToEndOfFile()
         if input.count > maxInputBytes {
             fail(HelperFailure(code: "invalid_request", message: "request exceeds \(maxInputBytes) bytes"))
@@ -247,7 +573,7 @@ struct PublicHelper {
             fail(HelperFailure(code: "invalid_request", message: "stdin must be one JSON object"))
         }
         do {
-            finish(try handle(request))
+            finish(try await handle(request))
         } catch let failure as HelperFailure {
             fail(failure)
         } catch {

package/package.json

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