apple-notes-mcp 2.8.30 → 2.8.32

package/README.md

@@ -254,11 +254,14 @@ Creates a new note in Apple Notes.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `title` | string | Yes | The title of the note. Automatically prepended as `<h1>` — do NOT include the title in `content` |
-| `content` | string | Yes | The body content of the note (do not repeat the title here) |
+| `content` | string | One of `content`/`contentPath` | The body content of the note (do not repeat the title here) |
+| `contentPath` | string | One of `content`/`contentPath` | Absolute path of a local UTF-8 file to use as the body instead of `content`. Allowed in the same places [`save-attachment`](#save-attachment) may write (home, temp, `/Volumes`); symbolic links, non-regular files, invalid UTF-8 and files over 1 MiB are refused before anything is written. A leading byte-order mark is dropped |
 | `tags` | string[] | No | Returned-only metadata — **NOT written to Notes.app**. Apple Notes tags can't be set via AppleScript, so values passed here are echoed back in the response but do not appear on the created note. Use inline `#hashtags` in `content` instead (Notes.app turns those into real tags). Refused with `format: "markdown"` |
 | `folder` | string | No | Folder to create the note in. Supports nested paths like `"Work/Clients"`. **The folder must already exist** — create it first with [`create-folder`](#create-folder). Defaults to account root |
 | `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` |
 
 **Example (tagged with inline hashtags):**
 ```json
@@ -345,6 +348,35 @@ title line, with no seed line.
   as `create-note-markdown`. The Create Markdown Note Shortcut is optional and
   needed only for this format (macOS 26+); install and approve it as described in
   [`shortcuts/README.md`](shortcuts/README.md).
+- A first line that is exactly `# <title>` (same case and spacing as `title`) is
+  removed together with one blank line after it, because the title is supplied
+  separately; the response then carries `strippedDuplicateTitle: true`. A
+  different first heading stays in the body. This applies to both Markdown
+  routes, and Markdown that holds only that heading is refused.
+
+##### Markdown through HTML
+
+`markdownRoute: "html"` imports the same bounded Markdown subset without the
+Shortcut: the server converts it to HTML and creates the note through AppleScript,
+like `format: "html"`. It works in any account, accepts `tags`, and needs no
+Shortcut, but headings get the plain bold styling described in the known
+limitation above rather than real Heading and Subheading styles.
+
+On this route, bullet task items (`- [ ] item`, `- [x] item`) become ordinary
+list rows that start with a visible `☐` or `☑` character, and the response
+reports how many as `taskItemsRendered`. They are text, not native checkable
+checklist items. Use this route as the glyph fallback when the Shortcut is not
+installed or the note is outside iCloud.
+
+```json
+{
+  "title": "Weekly Review",
+  "contentPath": "/Users/me/Documents/weekly-review.md",
+  "format": "markdown",
+  "markdownRoute": "html",
+  "folder": "Work"
+}
+```
 
 **Returns:** Confirmation message with note title and ID. Save the ID for subsequent operations like `update-note`, `delete-note`, etc.
 
@@ -737,7 +769,10 @@ was read, deletion is also rejected.
 }
 ```
 
-**Returns:** Confirmation message, or error if note not found.
+**Returns:** Confirmation message, or error if note not found. The delete and a
+check of the note's original folder run in one AppleScript: if Notes.app accepts
+the delete but the note is still listed in that folder, the call reports that
+nothing was deleted instead of claiming success.
 
 **⚠️ Safety:** Irreversible from the agent's side — requires explicit user confirmation before calling. Prefer `search-notes` / `list-notes` first to confirm the exact id(s) being deleted.
 
@@ -776,7 +811,7 @@ Appends or prepends content to an existing note without replacing it. Always rea
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
 | `expectedContentHash` | string | Yes | `contentHash` from the exact note version being extended |
 | `content` | string | Yes | Text to append to the note body |
-| `position` | string | No | `"after"` (default) appends to the end; `"before"` prepends to the start |
+| `position` | string | No | `"after"` (default) appends to the end; `"before"` inserts directly below the note's title line, so the title stays first |
 | `separator` | string | No | String placed between existing content and new content (default: two newlines → `<div><br></div>` in HTML) |
 | `format` | string | No | Format of the content being appended: `"plaintext"` (default) or `"html"` |
 
@@ -1314,6 +1349,50 @@ latest `expectedContentHash`, and an absolute `path`. The server never retries
 the insertion. It verifies that existing rich content survived and compares the
 fetched attachment bytes with the source before reporting success.
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Exact CoreData note ID |
+| `expectedContentHash` | string | Yes | `contentHash` from the note version being extended |
+| `path` | string | Yes | Absolute path of the local file; symbolic links are refused |
+| `filename` | string | No | Name the attachment gets in Notes instead of the source file's name. One path component that keeps the source file's extension, with no slash, colon, backslash, control character, leading dot or surrounding spaces. Notes names a file attachment after the file it receives, so the server gives its private temporary copy this name |
+
+**Returns:** `attachmentId`, `bytes`, the `name` Notes reports, and the new
+`contentHash`. With `filename`, `filenameVerified` says whether Notes reports
+that exact name. A mismatch is a warning (`filenameWarning`), not a failure,
+because the attachment and its bytes are already verified.
+
+---
+
+#### `create-note-with-attachment`
+
+Creates a note and attaches one local file to it in a single call. It checks the
+file and `filename` before creating anything, creates the note through Notes.app
+the way [`create-note`](#create-note) does in plaintext, then attaches with the
+same verification as [`add-attachment`](#add-attachment).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | One-line note title |
+| `content` | string | No | Plain-text body placed above the attachment |
+| `folder` | string | No | Existing folder or nested path; create it first with [`create-folder`](#create-folder) |
+| `account` | string | No | Account name; defaults to Notes.app's default account |
+| `path` | string | Yes | Absolute path of the local file (at most 64 MiB) |
+| `filename` | string | No | Attachment name override, as in `add-attachment` |
+
+```json
+{
+  "title": "Signed lease",
+  "folder": "Home",
+  "path": "/Users/me/Downloads/scan-0042.pdf",
+  "filename": "Lease 2026.pdf"
+}
+```
+
+**Returns:** the new note's `id` with `noteCreated: true` and the
+`add-attachment` result. If the attachment step fails after the note exists,
+the error names the new note's id: attach to it with `add-attachment` instead of
+calling this tool again, which would create a second note.
+
 ---
 
 #### `list-attachments`
@@ -1535,7 +1614,9 @@ the note before retrying, and retry only the items that are not present.
 #### `create-table`
 
 Appends a native table from rectangular string rows and verifies every decoded
-cell. It never substitutes a text table.
+cell. It never substitutes a text table. Omit `rows` for an empty 2 × 2 table,
+the size Notes itself inserts from Format > Table; its four empty cells are
+verified the same way.
 
 #### `set-note-pinned`
 
@@ -1693,7 +1774,7 @@ All configuration is optional — the server works out of the box. Override beha
 | `APPLE_NOTES_MCP_MAX_ATTACHMENT_BYTES` | `26214400` (25 MB) | Max size of an attachment that [`fetch-attachment`](#fetch-attachment) will base64-encode inline. Larger attachments are rejected with an error pointing at [`save-attachment`](#save-attachment) (which streams to disk and has no such limit). Raise it to fetch bigger attachments inline; lower it to cap memory. |
 | `APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES` | `262144` (256 KB) | Per-image cap on the base64 payload kept inline in a [`get-note-content`](#get-note-content) response. Inline images over the cap are replaced with placeholders (with a warning appended) so an image-heavy note cannot exceed the MCP client's message limit and drop the connection; export the real files with [`save-attachment`](#save-attachment) or [`fetch-attachment`](#fetch-attachment). Raise it to keep bigger images inline. |
 | `APPLE_NOTES_MCP_CONFIG_FILE` | `~/Library/Application Support/apple-notes-mcp/config.json` | Path to the JSON config file (see below). |
-| `APPLE_NOTES_MCP_TIMEOUT_MS` | `30000` (30 s) | Total AppleScript operation timeout, including retry attempts and delays. Raise it if full-library operations (large searches, exports) time out on a big Notes library. Per-call `timeoutMs` options still win. |
+| `APPLE_NOTES_MCP_TIMEOUT_MS` | `30000` (30 s) | Total AppleScript operation timeout, including retry attempts and delays. Raise it if full-library operations (large searches, exports) time out on a big Notes library. Per-call `timeoutMs` options still win, and a write tool's `timeoutSeconds` argument overrides it for that call. |
 | `APPLE_NOTES_MCP_EXPORT_MAX_BYTES` | `8388608` (8 MB) | Largest response `export-notes-json` sends; a page closes early to stay under it. The default sits below the 10 MB per-message limit of MCP SDK stdio clients, which drop the connection on anything larger. Raise it only if your MCP client accepts bigger messages. |
 | `APPLE_NOTES_MCP_BLOCKS_MAX_BYTES` | `4194304` (4 MB) | Largest block payload one [`get-note-blocks`](#get-note-blocks) page returns; the page closes early to stay under it, and a single oversized paragraph comes back with `textOmitted: true`. |
 | `APPLE_NOTES_MCP_MAX_RETRIES` | `2` | Maximum attempts for a read-only AppleScript call that fails with a **transient** error (Notes.app busy / not responding / lost connection). `2` means one retry; set `1` to fail fast with no retries. Retries share the single `APPLE_NOTES_MCP_TIMEOUT_MS` budget rather than each getting a fresh one, and a retry is skipped when under a second of that budget remains — so this is a ceiling, not a guarantee. In particular a call that exhausts the budget with a **timeout** has no time left to retry by construction. Mutating operations run once because a timeout can occur after Notes.app applied the change. Non-transient errors (e.g. "note not found") never retry. |

package/build/index.js

@@ -417,11 +417,11 @@ var require_codegen = __commonJS({
         const rhs = this.rhs === void 0 ? "" : ` = ${this.rhs}`;
         return `${varKind} ${this.name}${rhs};` + _n;
       }
-      optimizeNames(names, constants2) {
+      optimizeNames(names, constants3) {
         if (!names[this.name.str])
           return;
         if (this.rhs)
-          this.rhs = optimizeExpr(this.rhs, names, constants2);
+          this.rhs = optimizeExpr(this.rhs, names, constants3);
         return this;
       }
       get names() {
@@ -438,10 +438,10 @@ var require_codegen = __commonJS({
       render({ _n }) {
         return `${this.lhs} = ${this.rhs};` + _n;
       }
-      optimizeNames(names, constants2) {
+      optimizeNames(names, constants3) {
         if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
           return;
-        this.rhs = optimizeExpr(this.rhs, names, constants2);
+        this.rhs = optimizeExpr(this.rhs, names, constants3);
         return this;
       }
       get names() {
@@ -502,8 +502,8 @@ var require_codegen = __commonJS({
       optimizeNodes() {
         return `${this.code}` ? this : void 0;
       }
-      optimizeNames(names, constants2) {
-        this.code = optimizeExpr(this.code, names, constants2);
+      optimizeNames(names, constants3) {
+        this.code = optimizeExpr(this.code, names, constants3);
         return this;
       }
       get names() {
@@ -532,12 +532,12 @@ var require_codegen = __commonJS({
         }
         return nodes.length > 0 ? this : void 0;
       }
-      optimizeNames(names, constants2) {
+      optimizeNames(names, constants3) {
         const { nodes } = this;
         let i = nodes.length;
         while (i--) {
           const n = nodes[i];
-          if (n.optimizeNames(names, constants2))
+          if (n.optimizeNames(names, constants3))
             continue;
           subtractNames(names, n.names);
           nodes.splice(i, 1);
@@ -590,12 +590,12 @@ var require_codegen = __commonJS({
           return void 0;
         return this;
       }
-      optimizeNames(names, constants2) {
+      optimizeNames(names, constants3) {
         var _a;
-        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
-        if (!(super.optimizeNames(names, constants2) || this.else))
+        this.else = (_a = this.else) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants3);
+        if (!(super.optimizeNames(names, constants3) || this.else))
           return;
-        this.condition = optimizeExpr(this.condition, names, constants2);
+        this.condition = optimizeExpr(this.condition, names, constants3);
         return this;
       }
       get names() {
@@ -618,10 +618,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.iteration})` + super.render(opts);
       }
-      optimizeNames(names, constants2) {
-        if (!super.optimizeNames(names, constants2))
+      optimizeNames(names, constants3) {
+        if (!super.optimizeNames(names, constants3))
           return;
-        this.iteration = optimizeExpr(this.iteration, names, constants2);
+        this.iteration = optimizeExpr(this.iteration, names, constants3);
         return this;
       }
       get names() {
@@ -657,10 +657,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
       }
-      optimizeNames(names, constants2) {
-        if (!super.optimizeNames(names, constants2))
+      optimizeNames(names, constants3) {
+        if (!super.optimizeNames(names, constants3))
           return;
-        this.iterable = optimizeExpr(this.iterable, names, constants2);
+        this.iterable = optimizeExpr(this.iterable, names, constants3);
         return this;
       }
       get names() {
@@ -702,11 +702,11 @@ var require_codegen = __commonJS({
         (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNodes();
         return this;
       }
-      optimizeNames(names, constants2) {
+      optimizeNames(names, constants3) {
         var _a, _b;
-        super.optimizeNames(names, constants2);
-        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants2);
-        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants2);
+        super.optimizeNames(names, constants3);
+        (_a = this.catch) === null || _a === void 0 ? void 0 : _a.optimizeNames(names, constants3);
+        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants3);
         return this;
       }
       get names() {
@@ -1007,7 +1007,7 @@ var require_codegen = __commonJS({
     function addExprNames(names, from) {
       return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
     }
-    function optimizeExpr(expr, names, constants2) {
+    function optimizeExpr(expr, names, constants3) {
       if (expr instanceof code_1.Name)
         return replaceName(expr);
       if (!canOptimize(expr))
@@ -1022,14 +1022,14 @@ var require_codegen = __commonJS({
         return items;
       }, []));
       function replaceName(n) {
-        const c = constants2[n.str];
+        const c = constants3[n.str];
         if (c === void 0 || names[n.str] !== 1)
           return n;
         delete names[n.str];
         return c;
       }
       function canOptimize(e) {
-        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants2[c.str] !== void 0);
+        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants3[c.str] !== void 0);
       }
     }
     function subtractNames(names, from) {
@@ -7422,7 +7422,7 @@ var require_DOMException = __commonJS({
       "INVALID_NODE_TYPE_ERR (24): the supplied node is invalid or has an invalid ancestor for this operation",
       "DATA_CLONE_ERR (25): the object can not be cloned."
     ];
-    var constants2 = {
+    var constants3 = {
       INDEX_SIZE_ERR,
       DOMSTRING_SIZE_ERR: 2,
       // historical
@@ -7461,8 +7461,8 @@ var require_DOMException = __commonJS({
       this.name = names[code];
     }
     DOMException.prototype.__proto__ = Error.prototype;
-    for (c in constants2) {
-      v = { value: constants2[c] };
+    for (c in constants3) {
+      v = { value: constants3[c] };
       Object.defineProperty(DOMException, c, v);
       Object.defineProperty(DOMException.prototype, c, v);
     }
@@ -9872,9 +9872,9 @@ var require_select = __commonJS({
     var makeSubject = function() {
       var target;
       function subject(el) {
-        var node = el.ownerDocument, scope = node.getElementsByTagName(subject.lname), i = scope.length;
+        var node = el.ownerDocument, scope2 = node.getElementsByTagName(subject.lname), i = scope2.length;
         while (i--) {
-          if (subject.test(scope[i]) && target === el) {
+          if (subject.test(scope2[i]) && target === el) {
             target = null;
             return true;
           }
@@ -9902,16 +9902,16 @@ var require_select = __commonJS({
       };
     };
     var find = function(sel, node) {
-      var results = [], test = compile(sel), scope = node.getElementsByTagName(test.qname), i = 0, el;
-      while (el = scope[i++]) {
+      var results = [], test = compile(sel), scope2 = node.getElementsByTagName(test.qname), i = 0, el;
+      while (el = scope2[i++]) {
         if (test(el)) results.push(el);
       }
       if (test.sel) {
         while (test.sel) {
           test = compile(test.sel);
-          scope = node.getElementsByTagName(test.qname);
+          scope2 = node.getElementsByTagName(test.qname);
           i = 0;
-          while (el = scope[i++]) {
+          while (el = scope2[i++]) {
             if (test(el) && indexOf.call(results, el) === -1) {
               results.push(el);
             }
@@ -38990,6 +38990,22 @@ var NODE_RUNTIME_TCC_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp/blo
 var AUTOMATION_PERMISSION_GUIDE_URL = "https://github.com/sweetrb/apple-notes-mcp#permission-denied";
 var AUTOMATION_REMEDIATION = `Grant automation access in System Settings > Privacy & Security > Automation to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it \u2014 run the doctor tool to verify. See: ${AUTOMATION_PERMISSION_GUIDE_URL}`;
 
+// src/utils/callTimeout.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var CALL_TIMEOUT_SECONDS = { min: 1, max: 120 };
+var scope = new AsyncLocalStorage();
+function runWithCallTimeout(seconds, fn) {
+  if (seconds === void 0) return fn();
+  if (!Number.isInteger(seconds) || seconds < CALL_TIMEOUT_SECONDS.min || seconds > CALL_TIMEOUT_SECONDS.max)
+    throw new Error(
+      `timeoutSeconds must be a whole number from ${CALL_TIMEOUT_SECONDS.min} to ${CALL_TIMEOUT_SECONDS.max}`
+    );
+  return scope.run(seconds * 1e3, fn);
+}
+function callTimeoutMs() {
+  return scope.getStore();
+}
+
 // src/utils/applescript.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
@@ -39146,7 +39162,7 @@ function parseErrorMessage(errorOutput) {
   return coreError.trim() || "Unknown AppleScript error";
 }
 function executeAppleScript(script, options = {}) {
-  const timeoutMs = options.timeoutMs ?? envPositiveNumber("APPLE_NOTES_MCP_TIMEOUT_MS") ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? callTimeoutMs() ?? envPositiveNumber("APPLE_NOTES_MCP_TIMEOUT_MS") ?? DEFAULT_TIMEOUT_MS;
   const maxRetries = options.maxRetries ?? envPositiveNumber("APPLE_NOTES_MCP_MAX_RETRIES") ?? DEFAULT_MAX_RETRIES;
   const retryDelayMs = options.retryDelayMs ?? envPositiveNumber("APPLE_NOTES_MCP_RETRY_DELAY_MS") ?? DEFAULT_RETRY_DELAY_MS;
   if (!script || !script.trim()) {
@@ -40837,10 +40853,14 @@ function readSmartFolders(dbPath2 = NOTES_DB_PATH3) {
 
 // src/utils/attachmentFs.ts
 import {
+  closeSync,
+  constants,
   existsSync as existsSync3,
+  fstatSync,
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  openSync,
   readFileSync,
   realpathSync,
   rmSync,
@@ -40964,6 +40984,48 @@ function fileSize(p) {
 function makeTempDir() {
   return mkdtempSync(resolve(tmpdir(), "apple-notes-att-"));
 }
+function readAllowedTextFile(p, maxBytes, roots = allowedSaveRoots()) {
+  if (!p || !p.trim()) throw new Error("A content file path is required.");
+  if (!isAbsolute(p)) throw new Error(`Content file path must be absolute: "${p}"`);
+  const abs = resolve(p);
+  if (!isWithinRoots(abs, roots))
+    throw new Error(`Refusing to read outside allowed locations (home, temp, /Volumes): "${abs}"`);
+  let canonical;
+  try {
+    canonical = canonicalize(abs);
+  } catch {
+    throw new Error(`Content file does not exist or cannot be resolved: "${abs}"`);
+  }
+  if (!isWithinRoots(canonical, canonicalRoots(roots)))
+    throw new Error(
+      `Refusing to read outside allowed locations (home, temp, /Volumes): "${abs}" resolves to "${canonical}".`
+    );
+  let descriptor;
+  try {
+    descriptor = openSync(abs, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (error2) {
+    if (error2.code === "ELOOP")
+      throw new Error(`Refusing to read the symbolic link "${abs}".`);
+    throw error2;
+  }
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile()) throw new Error(`Content file is not a regular file: "${abs}"`);
+    if (stat.size === 0) throw new Error(`Content file is empty: "${abs}"`);
+    if (stat.size > maxBytes)
+      throw new Error(`Content file is ${stat.size} bytes, over the ${maxBytes}-byte limit.`);
+    const bytes = readFileSync(descriptor);
+    if (bytes.length !== stat.size)
+      throw new Error("Content file changed while it was being read; try again");
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/^\uFEFF/, "");
+    } catch {
+      throw new Error(`Content file is not valid UTF-8 text: "${abs}"`);
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}
 function cleanupTempDir(dir) {
   try {
     if (existsSync3(dir)) rmSync(dir, { recursive: true, force: true });
@@ -41182,10 +41244,10 @@ function buildAccountResolution(account) {
     if ${AS_ACCOUNT_REF} is missing value then error "${ACCOUNT_RESOLUTION_ERROR} Account \\"${safeAccount}\\" not found"
   `;
 }
-function buildAccountScopedScript(scope, command) {
+function buildAccountScopedScript(scope2, command) {
   return `
     tell application "Notes"
-      ${buildAccountResolution(scope.account)}
+      ${buildAccountResolution(scope2.account)}
       tell ${AS_ACCOUNT_REF}
         ${command}
       end tell
@@ -41765,11 +41827,20 @@ var AppleNotesManager = class {
     const safeExpectedBody = escapeHtmlForAppleScript(expectedBody);
     const script = buildAppLevelScript(`
       set noteRef to note id "${safeId}"
+      set originalFolder to missing value
+      try
+        set originalFolder to container of noteRef
+      end try
       set currentBody to body of noteRef
       considering case
         if currentBody is not "${safeExpectedBody}" and currentBody is not "${safeExpectedBody}" & linefeed then return "SAFETY_CONFLICT"
         delete noteRef
       end considering
+      if originalFolder is not missing value then
+        try
+          if (id of notes of originalFolder) contains "${safeId}" then return "SAFETY_NOT_DELETED"
+        end try
+      end if
       return "SAFETY_DELETED"
     `);
     const result = executeMutationAppleScript(script);
@@ -41779,6 +41850,7 @@ var AppleNotesManager = class {
     }
     const status = result.output.trim();
     if (status === "SAFETY_CONFLICT") return { status: "conflict" };
+    if (status === "SAFETY_NOT_DELETED") return { status: "not-deleted" };
     return status === "SAFETY_DELETED" ? { status: "deleted" } : { status: "failed" };
   }
   /**
@@ -44969,7 +45041,22 @@ import { join as join12 } from "node:path";
 
 // src/utils/appendMarkdown.ts
 var escape2 = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-function appendMarkdownHtml(markdown) {
+var TASK_GLYPHS = { open: "\u2610", done: "\u2611" };
+var TASK_ITEM = /^\[([ xX])\][ \t]+(\S.*)$/;
+function stripDuplicateTitleHeading(markdown, title) {
+  const normalized2 = markdown.replace(/^\uFEFF/, "");
+  const lines = normalized2.split(/\r?\n/);
+  if (lines[0] !== `# ${title}`) return { content: markdown, stripped: false };
+  const rest = lines.slice(lines.length > 1 && lines[1] === "" ? 2 : 1);
+  return { content: rest.join("\n"), stripped: true };
+}
+function countTaskItems(markdown) {
+  return markdown.replace(/\r\n/g, "\n").split("\n").filter((line) => {
+    const item = /^[-+*]\s+(.+)$/.exec(line);
+    return item !== null && TASK_ITEM.test(item[1]);
+  }).length;
+}
+function appendMarkdownHtml(markdown, options = {}) {
   if (markdown.includes("\uE000") || markdown.includes("\uE001"))
     throw new Error("Unsupported reserved characters");
   if (Array.from(markdown).some((c) => c.charCodeAt(0) < 32 && !["\n", "\r", "	"].includes(c)))
@@ -45008,7 +45095,8 @@ function appendMarkdownHtml(markdown) {
         list = kind;
         html += `<${kind}>`;
       }
-      html += `<li>${inline(item[2])}</li>`;
+      const task = options.taskGlyphs && item[1] ? TASK_ITEM.exec(item[2]) : null;
+      html += task ? `<li>${task[1] === " " ? TASK_GLYPHS.open : TASK_GLYPHS.done} ${inline(task[2])}</li>` : `<li>${inline(item[2])}</li>`;
       continue;
     }
     close();
@@ -45178,7 +45266,7 @@ function runBackgroundShortcut(input, status = backgroundStatus()) {
     try {
       execFileSync11("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
         encoding: "utf8",
-        timeout: 6e4,
+        timeout: callTimeoutMs() ?? 6e4,
         maxBuffer: 1024 * 1024,
         stdio: ["ignore", "pipe", "pipe"]
       });
@@ -45193,9 +45281,9 @@ function backgroundDependencies(manager) {
   return {
     read: (id2) => readBackgroundSnapshot(manager, id2),
     run: runBackgroundShortcut,
-    candidates: (title, scope) => manager.listAccounts().flatMap(
+    candidates: (title, scope2) => manager.listAccounts().flatMap(
       (account) => manager.searchNotes(title, false, account.name).filter(
-        (note) => note.title === title && !note.passwordProtected && manager.getNotePlaintextById(note.id).includes(scope)
+        (note) => note.title === title && !note.passwordProtected && manager.getNotePlaintextById(note.id).includes(scope2)
       ).map((note) => note.id)
     )
   };
@@ -46650,17 +46738,17 @@ function insertLink(request, deps) {
 // src/tools/directOperations.ts
 import { createHash as createHash2 } from "node:crypto";
 import {
-  closeSync,
-  constants,
-  fstatSync,
+  closeSync as closeSync2,
+  constants as constants2,
+  fstatSync as fstatSync2,
   mkdtempSync as mkdtempSync4,
-  openSync,
+  openSync as openSync2,
   readFileSync as readFileSync3,
   rmSync as rmSync4,
   writeFileSync as writeFileSync3
 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename, isAbsolute as isAbsolute2, join as join15 } from "node:path";
+import { basename, extname, isAbsolute as isAbsolute2, join as join15 } from "node:path";
 var noteId = exactIdInput(
   "ICNote",
   /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i,
@@ -46676,7 +46764,7 @@ function readSnapshot(manager, id2) {
   if (!body) throw new Error("Note content is unavailable");
   const enriched = enrichNoteRead(id2, body);
   const rich = readRichNote(id2);
-  if (!enriched.complete || enriched.revision !== rich.revision)
+  if (enriched.revision !== rich.revision)
     throw new Error("Native metadata changed during read; read the note again");
   return { id: id2, title: note.title, body, rich, hash: richContentHash(body, enriched) };
 }
@@ -46705,9 +46793,9 @@ function assertExistingContentPreserved(before, after) {
 }
 function localAttachment(path7) {
   if (!isAbsolute2(path7)) throw new Error("An absolute local file path is required");
-  const descriptor = openSync(path7, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const descriptor = openSync2(path7, constants2.O_RDONLY | constants2.O_NOFOLLOW);
   try {
-    const stat = fstatSync(descriptor);
+    const stat = fstatSync2(descriptor);
     if (!stat.isFile() || stat.size === 0 || stat.size > 64 * 1024 * 1024)
       throw new Error("Attachment must be a nonempty regular file of at most 64 MiB");
     const bytes = readFileSync3(descriptor);
@@ -46715,7 +46803,7 @@ function localAttachment(path7) {
       throw new Error("Attachment changed while it was being read; try again");
     return bytes;
   } finally {
-    closeSync(descriptor);
+    closeSync2(descriptor);
   }
 }
 function registerDirectOperations(server2, manager) {
@@ -46765,66 +46853,144 @@ function registerDirectOperations(server2, manager) {
       ...manager.renameFolderById(args.id, args.expectedName, args.expectedParentId, args.newName)
     })
   );
+  const attachmentInput = {
+    path: external_exports.string().min(1).max(4096).describe("Absolute path of the local file to attach"),
+    filename: external_exports.string().min(1).max(255).optional().describe(
+      "Name the attachment gets in Notes instead of the source file's name. One path component with the source file's extension; no slash, colon, or control characters, and no leading dot."
+    )
+  };
   tool(
     "add-attachment",
-    "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes.",
-    { id: noteId, expectedContentHash: revision, path: external_exports.string().min(1).max(4096) },
-    ({ id: id2, expectedContentHash, path: path7 }) => {
-      const before = readSnapshot(manager, id2);
-      if (before.hash !== expectedContentHash) throw new Error("Note revision changed");
-      const bytes = localAttachment(path7);
-      const beforeAttachments = manager.listAttachmentsById(id2);
-      const directory = mkdtempSync4(join15(tmpdir4(), "notes-attachment-add-"));
-      const temporaryFile = join15(directory, basename(path7));
+    "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, attachment name, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes.",
+    { id: noteId, expectedContentHash: revision, ...attachmentInput },
+    (args) => attachFile(manager, args)
+  );
+  tool(
+    "create-note-with-attachment",
+    "Use when: creating a new note that holds one local file, in one call.\nReturns: the new note id plus the add-attachment result (attachment id, bytes, name, content hash).\nDo not use when: the note already exists (add-attachment).\nSafety: checks the file and filename before creating anything, creates the note through Notes.app like create-note, then attaches with the same byte verification as add-attachment. If the attachment step fails after the note exists, the error names the new note's id; attach to it with add-attachment instead of creating another note.",
+    {
+      title: external_exports.string().min(1).max(2e3).refine((s) => !/[\r\n\0]/u.test(s), "One-line title"),
+      content: external_exports.string().min(1).max(1024 * 1024).optional().describe("Optional plain-text body placed above the attachment"),
+      folder: external_exports.string().max(1e3).optional().describe("Existing folder or nested path; create it first with create-folder"),
+      account: external_exports.string().max(200).optional().describe("Account name; defaults to Notes' default"),
+      ...attachmentInput
+    },
+    (args) => {
+      const name = attachmentName(args.path, args.filename);
+      localAttachment(args.path);
+      const note = manager.createNote(
+        args.title,
+        args.content ?? "",
+        [],
+        args.folder,
+        args.account,
+        "plaintext"
+      );
+      if (!note)
+        throw new Error(
+          `Failed to create note "${args.title}". Check that the folder and account exist (list-folders, list-accounts); nothing was attached`
+        );
+      const handOff = `Note ${note.id} was created; attach to it with add-attachment instead of creating another note`;
+      let snapshot;
+      try {
+        snapshot = readSnapshot(manager, note.id);
+      } catch (error2) {
+        throw new Error(`${handOff}. The new note could not be read back: ${String(error2)}`);
+      }
       try {
-        writeFileSync3(temporaryFile, bytes, { mode: 384 });
-        if (readSnapshot(manager, id2).hash !== before.hash)
-          throw new Error("Note revision changed");
-        let returnedId;
-        let transportUncertain = false;
-        try {
-          returnedId = manager.addAttachmentById(id2, before.body, temporaryFile);
-        } catch {
-          transportUncertain = true;
-        }
-        const after = readSnapshot(manager, id2);
-        assertExistingContentPreserved(before, after);
-        const readInserted = () => [
-          ...new Map(manager.listAttachmentsById(id2).map((item) => [item.id, item])).values()
-        ].filter((item) => !beforeAttachments.some((existing) => existing.id === item.id));
-        let inserted = readInserted();
-        for (let attempt = 0; attempt < 4 && (inserted.length !== 1 || returnedId && returnedId !== inserted[0].id); attempt++) {
-          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
-          inserted = readInserted();
-        }
-        const persistentReturnedId = returnedId && /\/ICAttachment\/p\d+$/.test(returnedId);
-        if (inserted.length !== 1 || persistentReturnedId && returnedId !== inserted[0].id)
-          throw new Error(
-            "Attachment insertion outcome uncertain; read the exact note before retrying"
-          );
-        const attachmentId = inserted[0].id;
-        const fetched = manager.getAttachmentBase64ById(id2, attachmentId);
-        const actual = typeof fetched.base64 === "string" ? Buffer.from(fetched.base64, "base64") : null;
-        if (!actual || createHash2("sha256").update(actual).digest("hex") !== createHash2("sha256").update(bytes).digest("hex"))
-          throw new Error(
-            "Attachment bytes were not verified; read the exact note before retrying"
-          );
         return {
-          ok: true,
-          id: id2,
-          attachmentId,
-          contentHash: after.hash,
-          bytes: bytes.length,
-          ...transportUncertain ? {
-            transportWarning: "Transport was uncertain; exact bytes and prior content were verified"
-          } : {}
+          ...attachFile(manager, {
+            id: note.id,
+            expectedContentHash: snapshot.hash,
+            path: args.path,
+            filename: name
+          }),
+          title: args.title,
+          folder: args.folder,
+          noteCreated: true
         };
-      } finally {
-        rmSync4(directory, { recursive: true, force: true });
+      } catch (error2) {
+        throw new Error(`${handOff}. ${error2 instanceof Error ? error2.message : String(error2)}`);
       }
     }
   );
 }
+function attachmentName(path7, filename) {
+  const source = basename(path7);
+  if (filename === void 0) return source;
+  if (Buffer.byteLength(filename, "utf8") > 255)
+    throw new Error("filename must be at most 255 bytes");
+  if (filename !== filename.trim() || filename === "" || filename.startsWith(".") || /[/:\\\p{Cc}]/u.test(filename))
+    throw new Error(
+      "filename must be one path component with no slash, colon, backslash, control character, leading dot, or surrounding spaces"
+    );
+  if (extname(filename).toLowerCase() !== extname(source).toLowerCase())
+    throw new Error(
+      `filename must keep the source file's extension (${extname(source) || "none"})`
+    );
+  return filename;
+}
+function attachFile(manager, args) {
+  const { id: id2, expectedContentHash, path: path7 } = args;
+  const name = attachmentName(path7, args.filename);
+  const before = readSnapshot(manager, id2);
+  if (before.hash !== expectedContentHash) throw new Error("Note revision changed");
+  const bytes = localAttachment(path7);
+  const beforeAttachments = manager.listAttachmentsById(id2);
+  const directory = mkdtempSync4(join15(tmpdir4(), "notes-attachment-add-"));
+  const temporaryFile = join15(directory, name);
+  try {
+    writeFileSync3(temporaryFile, bytes, { mode: 384 });
+    if (readSnapshot(manager, id2).hash !== before.hash) throw new Error("Note revision changed");
+    let returnedId;
+    let transportUncertain = false;
+    try {
+      returnedId = manager.addAttachmentById(id2, before.body, temporaryFile);
+    } catch {
+      transportUncertain = true;
+    }
+    const after = readSnapshot(manager, id2);
+    assertExistingContentPreserved(before, after);
+    const readInserted = () => [...new Map(manager.listAttachmentsById(id2).map((item) => [item.id, item])).values()].filter(
+      (item) => !beforeAttachments.some((existing) => existing.id === item.id)
+    );
+    let inserted = readInserted();
+    for (let attempt = 0; attempt < 4 && (inserted.length !== 1 || returnedId && returnedId !== inserted[0].id); attempt++) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+      inserted = readInserted();
+    }
+    const persistentReturnedId = returnedId && /\/ICAttachment\/p\d+$/.test(returnedId);
+    if (inserted.length !== 1 || persistentReturnedId && returnedId !== inserted[0].id)
+      throw new Error(
+        "Attachment insertion outcome uncertain; read the exact note before retrying"
+      );
+    const attachmentId = inserted[0].id;
+    const fetched = manager.getAttachmentBase64ById(id2, attachmentId);
+    const actual = typeof fetched.base64 === "string" ? Buffer.from(fetched.base64, "base64") : null;
+    if (!actual || createHash2("sha256").update(actual).digest("hex") !== createHash2("sha256").update(bytes).digest("hex"))
+      throw new Error("Attachment bytes were not verified; read the exact note before retrying");
+    const nameVerified = inserted[0].name === name;
+    return {
+      ok: true,
+      id: id2,
+      attachmentId,
+      contentHash: after.hash,
+      bytes: bytes.length,
+      name: inserted[0].name,
+      ...args.filename === void 0 ? {} : {
+        filenameVerified: nameVerified,
+        ...nameVerified ? {} : {
+          filenameWarning: "The attachment and its bytes were verified, but Notes reports a different name"
+        }
+      },
+      ...transportUncertain ? {
+        transportWarning: "Transport was uncertain; exact bytes and prior content were verified"
+      } : {}
+    };
+  } finally {
+    rmSync4(directory, { recursive: true, force: true });
+  }
+}
 
 // src/tools/nativeTagsBridge.ts
 var noteId2 = exactIdInput(
@@ -46896,9 +47062,9 @@ function registerNativeTagsBridge(server2, manager) {
         { id: id2, expectedContentHash, scopeText, tags, title: initial.title },
         {
           read,
-          candidates: (title, scope) => manager.listAccounts().flatMap(
+          candidates: (title, scope2) => manager.listAccounts().flatMap(
             (account) => manager.searchNotes(title, false, account.name).filter(
-              (note) => !note.passwordProtected && manager.getNotePlaintextById(note.id).toLocaleLowerCase().includes(scope.toLocaleLowerCase())
+              (note) => !note.passwordProtected && manager.getNotePlaintextById(note.id).toLocaleLowerCase().includes(scope2.toLocaleLowerCase())
             ).map((note) => note.id)
           ),
           run: runNativeTagsShortcut
@@ -46952,6 +47118,10 @@ var common = {
     "Distinctive existing phrase used by Notes search. Prefer plain words without punctuation, hashtags, or paths."
   )
 };
+var EMPTY_TABLE_ROWS = [
+  ["", ""],
+  ["", ""]
+];
 var htmlEscape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 var MAX_CHECKLIST_BATCH = 20;
 var byPosition = (items = []) => [...items].sort((a, b) => a.start - b.start);
@@ -47153,13 +47323,16 @@ function registerNativeOperations(server2, manager) {
   );
   tool(
     "create-table",
-    "Use when: appending one native Notes table from a rectangular array of strings.\nReturns: the native table identity and decoded cells after readback.\nDo not use when: a text table is acceptable or the rows are not rectangular.\nSafety: never substitutes text; preserves existing rich content and reports failure unless the native table is verified.",
+    "Use when: appending one native Notes table from a rectangular array of strings, or an empty table when rows is omitted.\nReturns: the native table identity and decoded cells after readback.\nDo not use when: a text table is acceptable or the rows are not rectangular.\nSafety: never substitutes text; preserves existing rich content and reports failure unless the native table is verified.",
     {
       ...common,
-      rows: external_exports.array(external_exports.array(external_exports.string().max(1e4)).min(1).max(100)).min(1).max(1e3)
+      rows: external_exports.array(external_exports.array(external_exports.string().max(1e4)).min(1).max(100)).min(1).max(1e3).optional().describe(
+        "Cell text, row by row. Omit for an empty 2 x 2 table, the size Notes itself inserts."
+      )
     },
-    (args) => {
+    (input) => {
       requireValidated("create-table");
+      const args = { ...input, rows: input.rows ?? EMPTY_TABLE_ROWS };
       if (args.rows.some((row) => row.length !== args.rows[0].length))
         throw new Error("Table rows must have equal cell counts");
       const before = readRichNote(args.id);
@@ -47437,7 +47610,11 @@ function errorResponse(message, cause) {
 function withErrorHandling(handler, errorPrefix) {
   return async (params) => {
     try {
-      return handler(params);
+      const seconds = params.timeoutSeconds;
+      return runWithCallTimeout(
+        typeof seconds === "number" ? seconds : void 0,
+        () => handler(params)
+      );
     } catch (error2) {
       const message = error2 instanceof Error ? error2.message : "Unknown error";
       return errorResponse(`${errorPrefix}: ${message}`, error2);
@@ -47457,6 +47634,7 @@ var MAX = {
   TAGS: 100,
   BATCH_IDS: 500
 };
+var MAX_CONTENT_FILE_BYTES = 1024 * 1024;
 var noteTitleSchema = {
   title: external_exports.string().min(1, "Note title is required").max(MAX.TITLE),
   account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
@@ -47485,6 +47663,9 @@ function noteIdentifiers(id2) {
 var expectedContentHashInput = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/, "expectedContentHash must come from get-note-content").describe(
   "Revision token returned by get-note-content for this exact ID. The mutation stops if the note changed since that read."
 );
+var timeoutSecondsInput = external_exports.number().int().min(CALL_TIMEOUT_SECONDS.min).max(CALL_TIMEOUT_SECONDS.max).optional().describe(
+  `Per-call timeout in seconds (${CALL_TIMEOUT_SECONDS.min}-${CALL_TIMEOUT_SECONDS.max}) for each Notes.app automation step this call runs, overriding APPLE_NOTES_MCP_TIMEOUT_MS. A timed-out write is uncertain, not failed: read the note by id before any retry.`
+);
 function readExactNoteSnapshot(id2) {
   const note = notesManager.getNoteById(id2);
   if (!note) return { error: `Note with ID "${id2}" not found` };
@@ -47498,6 +47679,7 @@ function readExactNoteSnapshot(id2) {
   const rich = enrichNoteRead(id2, body);
   return { note, body, rich, contentHash: richContentHash(body, rich) };
 }
+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 revisionConflictMessage(title) {
   return `Note "${title}" changed after it was read. Read it again and review the newer version before retrying.`;
 }
@@ -47521,11 +47703,17 @@ registerTool(
     description: "Use when: the user wants to create a brand-new Apple Note.\nReturns: the new note's title and id \u2014 reuse the id for follow-up reads/edits.\nDo not use when: editing an existing note (use update-note).\nNote: the title is prepended as an <h1>; true Apple Notes checklists cannot be created via AppleScript (see the content field). A 'folder' must already exist \u2014 create-folder first (it is idempotent), since this tool does not create it.",
     inputSchema: {
       title: external_exports.string().min(1, "Title is required").max(MAX.TITLE),
-      content: external_exports.string().min(1, "Content is required").max(MAX.CONTENT).describe(
-        'Note body. AppleScript cannot create true Apple Notes checklists \u2014 `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items. To produce a checklist, create the note with a plain `<ul>` or `- ` list and convert it in Notes.app with \u21E7\u2318L.'
+      content: external_exports.string().min(1, "Content is required").max(MAX.CONTENT).optional().describe(
+        'Note body; required unless contentPath is given (pass exactly one). AppleScript cannot create true Apple Notes checklists \u2014 `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items. To produce a checklist, create the note with a plain `<ul>` or `- ` list and convert it in Notes.app with \u21E7\u2318L.'
+      ),
+      contentPath: external_exports.string().min(1).max(MAX.SAVE_PATH).optional().describe(
+        `Absolute path of a local UTF-8 file to use as the body instead of content (pass exactly one). The same locations save-attachment may write to are allowed (home, temp, /Volumes); symbolic links and non-regular files are refused. Limit ${MAX_CONTENT_FILE_BYTES} bytes.`
       ),
       format: external_exports.enum(["plaintext", "html", "markdown"]).optional().default("plaintext").describe(
-        "Content format: 'plaintext' (default), 'html' for rich formatting, or 'markdown' for real Title/Heading/Subheading styles through the Create Markdown Note Shortcut (iCloud only; see get-capabilities)"
+        "Content format: 'plaintext' (default), 'html' for rich formatting, or 'markdown'. Markdown whose first line is exactly `# <title>` (same case and spacing) has that line and one blank line after it removed, since the title is supplied separately."
+      ),
+      markdownRoute: external_exports.enum(["shortcut", "html"]).optional().default("shortcut").describe(
+        "How format 'markdown' is imported. 'shortcut' (default) uses the Create Markdown Note Shortcut for real Title/Heading/Subheading styles (iCloud only, no tags; see get-capabilities). 'html' is the fallback when that Shortcut is not installed or the note is outside iCloud: it converts the same bounded Markdown subset to HTML and creates the note through AppleScript in any account, rendering `- [ ]` / `- [x]` task items as ordinary list rows that start with a visible \u2610 / \u2611 character \u2014 not native, checkable checklist items."
       ),
       tags: external_exports.array(external_exports.string().max(MAX.TAG)).max(MAX.TAGS).optional().describe(
         "Returned-only metadata \u2014 NOT written to Notes.app. Apple Notes tags can't be set via AppleScript, so any values passed here are echoed back in the response but do not appear on the created note. Use #hashtags in the body for searchable text; this does not create native tag objects. Native tags need the Notes Shortcuts action. Refused with format 'markdown': add tags afterwards with add-native-tags."
@@ -47535,7 +47723,8 @@ registerTool(
       ),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
         "Account name (defaults to the account Notes.app itself reports as default). Matched exactly, or by a unique prefix; an ambiguous prefix is refused. Must be an account Notes.app already has configured \u2014 see list-accounts."
-      )
+      ),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -47544,10 +47733,66 @@ registerTool(
       folder: external_exports.string().optional(),
       account: external_exports.string().optional(),
       contentHash: external_exports.string().optional(),
-      verified: external_exports.boolean().optional()
+      verified: external_exports.boolean().optional(),
+      strippedDuplicateTitle: external_exports.boolean().optional(),
+      taskItemsRendered: external_exports.number().optional()
     }
   },
-  withErrorHandling(({ title, content, format = "plaintext", tags = [], folder, account }) => {
+  withErrorHandling((params) => {
+    const {
+      title,
+      contentPath,
+      format = "plaintext",
+      markdownRoute = "shortcut",
+      tags = [],
+      folder,
+      account
+    } = params;
+    if (params.content === void 0 === (contentPath === void 0))
+      return errorResponse("Provide exactly one of content or contentPath");
+    let content = params.content ?? readAllowedTextFile(contentPath, MAX_CONTENT_FILE_BYTES);
+    if (format !== "markdown" && markdownRoute !== "shortcut")
+      return errorResponse('markdownRoute applies to format "markdown" only');
+    let strippedDuplicateTitle = false;
+    if (format === "markdown") {
+      const stripped = stripDuplicateTitleHeading(content, title);
+      strippedDuplicateTitle = stripped.stripped;
+      content = stripped.content;
+      if (!content.trim())
+        return errorResponse(
+          "The Markdown holds only the title heading; add body content, or use format 'plaintext' for a title-only note"
+        );
+    }
+    const titleNote = strippedDuplicateTitle ? { strippedDuplicateTitle: true } : {};
+    if (format === "markdown" && markdownRoute === "html") {
+      const taskItemsRendered = countTaskItems(content);
+      const html = appendMarkdownHtml(content, { taskGlyphs: true });
+      const note2 = notesManager.createNote(title, html, tags, folder, account, "html");
+      if (!note2)
+        return errorResponse(
+          `Failed to create note "${title}". Check that the folder and account exist (list-folders, list-accounts) and that this server has Automation access (run the doctor tool).`
+        );
+      const createdBody2 = notesManager.getNoteContentById(note2.id);
+      if (!notesManager.getNoteById(note2.id) || !createdBody2)
+        return errorResponse(
+          `A note may have been created, but its exact ID could not be verified. Do not retry automatically. Returned ID: ${note2.id}`
+        );
+      const glyphNote = taskItemsRendered ? ` ${taskItemsRendered} task item(s) were rendered as visible \u2610 / \u2611 text, not native checklist items.` : "";
+      return successResponse(
+        `Note created from Markdown: "${note2.title}" [id: ${note2.id}]${glyphNote}`,
+        {
+          ok: true,
+          id: note2.id,
+          title: note2.title,
+          folder,
+          account,
+          contentHash: richContentHash(createdBody2, enrichNoteRead(note2.id, createdBody2)),
+          verified: true,
+          taskItemsRendered,
+          ...titleNote
+        }
+      );
+    }
     if (format === "markdown") {
       if (account)
         return errorResponse(
@@ -47559,7 +47804,10 @@ registerTool(
         );
       requireValidated("create-note-markdown");
       const result = createMarkdownNote(notesManager, { title, content, folder });
-      return successResponse(`Note created from Markdown: "${title}" [id: ${result.id}]`, result);
+      return successResponse(`Note created from Markdown: "${title}" [id: ${result.id}]`, {
+        ...result,
+        ...titleNote
+      });
     }
     const note = notesManager.createNote(title, content, tags, folder, account, format);
     if (!note) {
@@ -47705,7 +47953,7 @@ registerTool(
       }
       throw error2;
     }
-    const scope = `scanned ${result.scanned} of ${result.eligible} notes` + (result.scanTruncated ? `, the most recent ${result.scanLimit}; pass a higher scanLimit to include older notes` : "");
+    const scope2 = `scanned ${result.scanned} of ${result.eligible} notes` + (result.scanTruncated ? `, the most recent ${result.scanLimit}; pass a higher scanLimit to include older notes` : "");
     const notes = [];
     if (result.truncated) {
       notes.push(
@@ -47721,7 +47969,7 @@ registerTool(
 
 ${notes.join("\n")}` : "";
     if (result.count === 0) {
-      return successResponse(`No notes matched (${scope}).${footer}`, { ...result });
+      return successResponse(`No notes matched (${scope2}).${footer}`, { ...result });
     }
     const lines = result.notes.map((n) => {
       const where = [n.account, n.folder].filter(Boolean).join(" / ");
@@ -47730,7 +47978,7 @@ ${notes.join("\n")}` : "";
       return `  - ${n.title}${where ? ` (${where})` : ""}${n.locked ? " [locked]" : ""} [id: ${n.id}]${snippet}`;
     }).join("\n");
     return successResponse(
-      `Found ${result.matched} matching notes (${scope}):
+      `Found ${result.matched} matching notes (${scope2}):
 ${lines}${footer}`,
       { ...result }
     );
@@ -48277,7 +48525,8 @@ registerTool(
       newContent: external_exports.string().min(1, "New content is required").max(MAX.CONTENT).describe(
         "New note body. AppleScript cannot produce true Apple Notes checklists; checkbox inputs and `- [ ]` markdown do not render as checkable items. Use a plain list and convert in Notes.app with \u21E7\u2318L."
       ),
-      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Content format: 'plaintext' (default) or 'html' for rich formatting")
+      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Content format: 'plaintext' (default) or 'html' for rich formatting"),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -48488,10 +48737,11 @@ registerTool(
       content: external_exports.string().min(1, "Content to append is required").max(MAX.CONTENT).describe("Text to append to the note body"),
       scopeText: external_exports.string().min(12).max(500).optional().describe("Existing unique phrase required for native append to protected notes"),
       position: external_exports.enum(["after", "before"]).optional().default("after").describe(
-        "Where to insert: 'after' appends to the end (default), 'before' prepends to the start"
+        "Where to insert: 'after' appends to the end (default); 'before' inserts directly below the note's title line, so the title stays first"
       ),
       separator: external_exports.string().max(20).optional().default("\n\n").describe("String placed between existing content and new content (default: two newlines)"),
-      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Format of the content being appended: 'plaintext' (default) or 'html'")
+      format: external_exports.enum(["plaintext", "html"]).optional().default("plaintext").describe("Format of the content being appended: 'plaintext' (default) or 'html'"),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -48580,7 +48830,8 @@ registerTool(
     description: "Use when: moving one exact note to Recently Deleted after reading and reviewing it.\nReturns: confirmation with the exact id.\nDo not use when: you only have a title or the note changed since review.\nSafety: requires id and expectedContentHash from get-note-content. The body comparison and delete happen in one AppleScript, so a newer edit is preserved.",
     inputSchema: {
       id: noteIdInput,
-      expectedContentHash: expectedContentHashInput
+      expectedContentHash: expectedContentHashInput,
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -48600,6 +48851,9 @@ registerTool(
     if (result.status === "conflict") {
       return errorResponse(revisionConflictMessage(snapshot.note.title));
     }
+    if (result.status === "not-deleted") {
+      return errorResponse(NOT_DELETED_MESSAGE);
+    }
     if (result.status !== "deleted") {
       return errorResponse(
         `The delete result for note "${snapshot.note.title}" is uncertain. Inspect exact ID ${id2} before retrying.`
@@ -48625,7 +48879,8 @@ registerTool(
     inputSchema: {
       id: noteIdInput,
       folder: external_exports.string().min(1, "Destination folder is required").max(MAX.FOLDER),
-      account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note/folder")
+      account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note/folder"),
+      timeoutSeconds: timeoutSecondsInput
     },
     outputSchema: {
       ok: external_exports.boolean().optional(),
@@ -49188,6 +49443,8 @@ registerTool(
       if (result.status === "conflict") {
         return { id: id2, success: false, error: revisionConflictMessage(snapshot.note.title) };
       }
+      if (result.status === "not-deleted")
+        return { id: id2, success: false, error: NOT_DELETED_MESSAGE };
       return { id: id2, success: false, error: "Delete result uncertain; inspect this exact ID" };
     });
     const succeeded = results.filter((r) => r.success).length;

package/package.json

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