apple-notes-mcp 2.8.31 → 2.8.33

package/README.md

@@ -332,13 +332,42 @@ title line, with no seed line.
   It also refuses Markdown that Notes would rewrite and the server could not
   verify: `_` emphasis (underscores inside a word, as in `snake_case`, and
   inside a link destination, as in `[docs](https://example.com/_next/static)`,
-  are fine), backslash escapes, character references such as `&`, `---` or
-  `===` lines, indented headings or list items, `1)` lists, closing `#`s, and
+  are fine), backslash escapes, character references such as `&`, `===` lines
+  and rule lines other than the `---` divider described below, indented headings or list items, `1)` lists, closing `#`s, and
   formatting inside link labels. Content that needs one of these literally, such
   as a `/_next` path or a literal `\*`, has no Markdown form here: use
   `format: "html"` for that note (or `append-native` with `format: "html"` on an
   existing one), which keeps the characters but not the Heading and Subheading
   styles. Markdown punctuation in `title` is escaped, so the title stays literal.
+- Notes' importer also maps these block constructs to native styles. They are
+  gated separately, and `get-capabilities` reports them as
+  `create-note-markdown-blocks`. Each mapping below was live-verified on
+  macOS 27.2 by reading the created note's stored styles.
+
+  | Markdown | Native result |
+  |----------|---------------|
+  | `- [ ] item` / `- [x] item` | Checklist item, unchecked / checked |
+  | `> text` (consecutive lines form one quote) | Body paragraph with a block quote |
+  | A fence of bare ```` ``` ```` lines (no language) | Monospaced paragraphs; the code text is kept literally |
+  | `---` on its own line, after a blank line | Divider line |
+  | `` `inline code` `` | **Highlighted** text, not monospace |
+
+  Constructs Notes would not render faithfully, or that this server cannot yet
+  verify, are refused before anything is created: `~~~` fences, a language
+  after the opening fence, nested (`>>`) or indented quotes, lists or headings
+  inside a quote, a quote followed directly by text (Markdown would join that
+  text to the quote), `---` directly under text (Markdown would make that text
+  a heading), `***`/`___`/`----` rules, `[X]`, `* [ ]` or `+ [ ]` items, checklist
+  items directly next to ordinary list items, inline code padded with spaces or
+  inside a link label, tables, and `~~strikethrough~~`. The readback checks the
+  block-quote text, the Monospaced text, each checklist item's text and done
+  state, the divider count, and the highlighted text. These mappings apply to
+  the default Shortcut route only; see
+  [Markdown through HTML](#markdown-through-html) for `markdownRoute: "html"`.
+- [`append-native`](#append-native)'s `format: "markdown"` refuses all of the
+  constructs above: its Shortcuts converter is a different one, which renders
+  a quote and a fenced block as plain body text, `- [ ]` as a bullet with
+  literal brackets, and inline code as plain text, and drops `---`.
 - The server finds the new note among the notes added to the default folder
   during the run by verifying each one's visible text, heading levels and links
   by exact-ID readback, and moves it only after exactly one verifies. On any
@@ -366,7 +395,9 @@ 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.
+installed or the note is outside iCloud. Block quotes, fenced code and inline code, which
+the Shortcut route maps natively, are refused on this route, and a `---` line
+stays literal text rather than becoming a divider.
 
 ```json
 {
@@ -1349,6 +1380,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`
@@ -1570,7 +1645,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`
 
@@ -1824,7 +1901,7 @@ Apple Notes stores checklists as a paragraph style (`style_type=103`) inside a g
 **Workarounds:**
 
 1. **Create the note with bulleted list items, then convert manually in Notes.app.** Select the items and press <kbd>⇧⌘L</kbd> (or **Format → Checklist**). This converts the list in place and the resulting checklist will be readable by `get-checklist-state` and annotated by `get-note-markdown`.
-2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript.
+2. **Use the Apple Shortcuts app** to script the checklist creation, since Shortcuts can manipulate Notes content at a higher level than AppleScript. This server does that for you in two ways: [`create-checklist-item`](#create-checklist-item) appends one unchecked item to an existing note, and [`create-note`](#create-note) with `format: "markdown"` turns `- [ ]` / `- [x]` lines into checklist items with that done state through Notes' own Markdown importer, (see [Markdown notes](#markdown-notes)).
 3. **Read-only checklist support is fully implemented** — once a checklist exists (created manually or by another app), `get-checklist-state` and `get-note-markdown` will read its done/undone state correctly (with Full Disk Access).
 
 If you need to *track* todos programmatically and don't strictly need them rendered as Apple Notes checklist UI, plain markdown-style `- [ ] item` / `- [x] item` lines in a `plaintext` note are a reasonable alternative — they are searchable, human-readable, and can be parsed by downstream tooling.

package/build/index.js

@@ -39675,7 +39675,11 @@ function parseRichNote(data, nativeTags = []) {
     const length = varintValue(getField(fields, 1));
     if (length === void 0 || length < 0 || position + length > text.length)
       throw new Error("Invalid Notes run length");
+    const paragraph = embeddedMessage(getField(fields, 2));
     styleRuns.push({
+      paragraphStyle: paragraph ? varintValue(getField(paragraph, 1)) ?? 3 : 3,
+      blockQuote: Boolean(paragraph && varintValue(getField(paragraph, 8))),
+      highlight: Boolean(varintValue(getField(fields, 14))),
       start: position,
       length,
       signature: JSON.stringify(
@@ -39703,7 +39707,6 @@ function parseRichNote(data, nativeTags = []) {
         start: position,
         length
       });
-    const paragraph = embeddedMessage(getField(fields, 2));
     hasChecklist ||= Boolean(paragraph && varintValue(getField(paragraph, 1)) === 103);
     if (paragraph && varintValue(getField(paragraph, 1)) === 103) {
       const checklist = embeddedMessage(getField(paragraph, 5));
@@ -45056,40 +45059,152 @@ function countTaskItems(markdown) {
     return item !== null && TASK_ITEM.test(item[1]);
   }).length;
 }
-function appendMarkdownHtml(markdown, options = {}) {
-  if (markdown.includes("\uE000") || markdown.includes("\uE001"))
+var FENCE = "```";
+var CHECKLIST_ITEM = /^- \[( |x)\] (.+)$/;
+function withoutMarkdownCode(markdown) {
+  let inCode = false;
+  return markdown.replace(/\r\n/g, "\n").split("\n").map((line) => {
+    if (line === FENCE) {
+      inCode = !inCode;
+      return "";
+    }
+    return inCode ? "" : line.replace(/`[^`\n]+`/g, "x");
+  }).join("\n");
+}
+function usesMarkdownBlocks(markdown) {
+  return /`/.test(markdown) || /^>/m.test(markdown) || /^---[ \t]*$/m.test(markdown) || /^- \[[ x]\] /m.test(markdown);
+}
+function renderMarkdown(markdown, options = {}) {
+  const blocks = options.blocks === true;
+  if (blocks ? /[-]/u.test(markdown) : /[]/u.test(markdown))
     throw new Error("Unsupported reserved characters");
   if (Array.from(markdown).some((c) => c.charCodeAt(0) < 32 && !["\n", "\r", "	"].includes(c)))
     throw new Error("Unsupported control characters");
-  if (/[`~|]|^#{4,}\s|^\s*>|^\s*\[.+\]:|!\[|<\/?[a-z]/im.test(markdown))
+  const checked = blocks ? withoutMarkdownCode(markdown) : markdown;
+  if (blocks ? /[`~|]|^#{4,}\s|^[ \t]+>|^>[ \t]*>|^\s*\[.+\]:|!\[|<\/?[a-z]/im.test(checked) : /[`~|]|^#{4,}\s|^\s*>|^\s*\[.+\]:|!\[|<\/?[a-z]/im.test(checked))
     throw new Error(
-      "Markdown append supports paragraphs, headings, flat lists, emphasis and inline links; use semantic HTML for other formatting"
+      blocks ? "Markdown import supports paragraphs, headings, flat lists, checklist items, block quotes, fenced code, dividers, emphasis, inline code and inline links; use semantic HTML for other formatting" : "Markdown append supports paragraphs, headings, flat lists, emphasis and inline links; use semantic HTML for other formatting"
     );
+  const expect = {
+    quotes: [],
+    code: [],
+    checklist: [],
+    dividers: 0,
+    highlights: []
+  };
   const inline = (text) => {
+    const spans = [];
+    let value = text;
+    if (blocks)
+      value = value.replace(/`([^`\n]+)`/g, (_s, code2) => {
+        if (/^\s|\s$/.test(code2)) throw new Error("Inline code cannot start or end with a space");
+        expect.highlights.push(code2);
+        spans.push(`<code>${escape2(code2)}</code>`);
+        return `\uE002${spans.length - 1}\uE003`;
+      });
     const links = [];
-    let value = text.replace(/\[([^\]\n]+)\]\(([^()\s]+)\)/g, (_s, label, url) => {
+    value = value.replace(/\[([^\]\n]+)\]\(([^()\s]+)\)/g, (_s, label, url) => {
       if (!/^(https?:\/\/|notes:\/\/|applenotes:|mailto:)/i.test(url))
         throw new Error("Unsupported Markdown link URL");
+      if (/[]/u.test(label)) throw new Error("Inline code inside a link is unsupported");
       links.push(`<a href="${escape2(url)}">${escape2(label)}</a>`);
       return `\uE000${links.length - 1}\uE001`;
     });
     value = escape2(value).replace(/\*\*([^*\n]+)\*\*/g, "<b>$1</b>").replace(/\*([^*\n]+)\*/g, "<i>$1</i>");
     if (value.includes("[") || value.includes("]") || value.includes("*"))
       throw new Error("Unsupported or unbalanced Markdown inline syntax");
-    return value.replace(/\uE000(\d+)\uE001/g, (_s, i) => links[Number(i)]);
+    return value.replace(/(\d+)/g, (_s, i) => links[Number(i)]).replace(/(\d+)/g, (_s, i) => spans[Number(i)]);
   };
-  let html = "", list;
+  const withoutTags = (html2) => {
+    let text = "", inTag = false;
+    for (const ch of html2) {
+      if (ch === "<") inTag = true;
+      else if (ch === ">" && inTag) inTag = false;
+      else if (!inTag) text += ch;
+    }
+    return text;
+  };
+  const visible = (html2) => withoutTags(html2).replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+  let html = "", list, quote = false, code, previousBlank = true;
   const close = () => {
     if (list) {
-      html += `</${list}>`;
+      html += list === "checklist" ? "</ul>" : `</${list}>`;
       list = void 0;
     }
+    if (quote) {
+      html += "</blockquote>";
+      quote = false;
+    }
   };
   for (const line of markdown.replace(/\r\n/g, "\n").split("\n")) {
+    if (code) {
+      if (line === FENCE) {
+        if (!code.length) throw new Error("Empty fenced code blocks are unsupported");
+        html += `<pre>${escape2(code.join("\n"))}</pre>`;
+        expect.code.push(code.join("\n"));
+        code = void 0;
+        previousBlank = false;
+      } else code.push(line);
+      continue;
+    }
+    const blank = !line.trim();
+    if (blocks) {
+      if (quote && !blank && !line.startsWith(">"))
+        throw new Error("End a block quote with a blank line before other text");
+      if (line.startsWith(FENCE)) {
+        if (line !== FENCE)
+          throw new Error("Fenced code must open and close with a bare ``` line (no language)");
+        close();
+        code = [];
+        continue;
+      }
+      if (line.startsWith(">")) {
+        const text = line.replace(/^> ?/, "");
+        if (!text.trim()) throw new Error("Empty block quote lines are unsupported");
+        if (/^(?:#|[-+*][ \t]|\d+[.)][ \t]|>|```)/.test(text))
+          throw new Error("Block quotes support text and inline formatting only");
+        if (!quote) {
+          close();
+          html += "<blockquote>";
+          quote = true;
+          expect.quotes.push("");
+        }
+        const rendered = inline(text);
+        html += `<div>${rendered}</div>`;
+        expect.quotes[expect.quotes.length - 1] += ` ${visible(rendered)}`;
+        previousBlank = false;
+        continue;
+      }
+      if (/^---[ \t]*$/.test(line)) {
+        if (!previousBlank) throw new Error("Put a blank line before a --- divider");
+        close();
+        html += "<hr>";
+        expect.dividers++;
+        previousBlank = false;
+        continue;
+      }
+      const task = CHECKLIST_ITEM.exec(line);
+      if (task) {
+        if (list && list !== "checklist")
+          throw new Error("Separate checklist items from other list items with a blank line");
+        if (list !== "checklist") {
+          close();
+          list = "checklist";
+          html += '<ul class="checklist">';
+        }
+        const rendered = inline(task[2]);
+        html += `<li>${rendered}</li>`;
+        expect.checklist.push({ text: visible(rendered).trim(), done: task[1] === "x" });
+        previousBlank = false;
+        continue;
+      }
+    }
     if (/^\s{2,}\S/.test(line)) throw new Error("Nested lists and indented code are unsupported");
     const heading = /^(#{1,3})\s+(.+)$/.exec(line), item = /^(?:([-+*])|\d+\.)\s+(.+)$/.exec(line);
     if (item) {
       const kind = item[1] ? "ul" : "ol";
+      if (list === "checklist")
+        throw new Error("Separate checklist items from other list items with a blank line");
       if (list !== kind) {
         close();
         list = kind;
@@ -45097,13 +45212,20 @@ function appendMarkdownHtml(markdown, options = {}) {
       }
       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>`;
+      previousBlank = false;
       continue;
     }
     close();
-    html += heading ? `<h${heading[1].length}>${inline(heading[2])}</h${heading[1].length}>` : line.trim() ? `<div>${inline(line)}</div>` : "<div><br></div>";
+    html += heading ? `<h${heading[1].length}>${inline(heading[2])}</h${heading[1].length}>` : !blank ? `<div>${inline(line)}</div>` : "<div><br></div>";
+    previousBlank = blank;
   }
+  if (code) throw new Error("Unclosed fenced code block");
   close();
-  return html;
+  expect.quotes = expect.quotes.map((q) => q.trim());
+  return { html, expect };
+}
+function appendMarkdownHtml(markdown, options = {}) {
+  return renderMarkdown(markdown, { taskGlyphs: options.taskGlyphs }).html;
 }
 
 // src/utils/noteRevision.ts
@@ -45197,7 +45319,7 @@ var UNMODELED_MARKDOWN = [
   [/^#{1,3}[ \t].*[ \t]#+[ \t]*$/m, "closing # sequences"],
   [/\[[^\]\n]*[*_][^\]\n]*\]\(/m, "formatting inside link labels"]
 ];
-function validateAppendContent(content, format) {
+function validateAppendContent(content, format, options = {}) {
   if (!content || content.length > 1024 * 1024 || content.includes("\0"))
     throw new Error("Invalid append content (limit 1 MiB)");
   if (format === "html") {
@@ -45227,11 +45349,12 @@ function validateAppendContent(content, format) {
     if (/<!--|<!|<\?|<[^>]*$/u.test(content)) throw new Error("Unsupported HTML markup");
   }
   if (format === "markdown") {
-    if (/!\[|<\/?[a-z]|\]\(\s*(?:javascript|data|file):/i.test(content))
+    const checked = options.blocks ? withoutMarkdownCode(content).replace(/^---[ \t]*$/gm, "") : content;
+    if (/!\[|<\/?[a-z]|\]\(\s*(?:javascript|data|file):/i.test(checked))
       throw new Error("Markdown images, raw HTML and local/executable links are unsupported");
-    const withoutLinkDestinations = content.replace(/(\[[^\]\n]+\])\([^()\s]+\)/g, "$1()");
+    const withoutLinkDestinations = checked.replace(/(\[[^\]\n]+\])\([^()\s]+\)/g, "$1()");
     for (const [pattern, name] of UNMODELED_MARKDOWN)
-      if (pattern.test(name === UNDERSCORES_OUTSIDE_A_WORD ? withoutLinkDestinations : content))
+      if (pattern.test(name === UNDERSCORES_OUTSIDE_A_WORD ? withoutLinkDestinations : checked))
         throw new Error(
           `Markdown cannot use ${name}; Notes would change that text, so the result could not be verified`
         );
@@ -45455,10 +45578,42 @@ var literalMarkdown = (text) => text.replace(/[!-/:-@[-`{-~]/g, "\\$&");
 function headingLevels(html) {
   return [...html.matchAll(/<h([1-3])\b[^>]*>([\s\S]*?)<\/h\1>/gi)].filter((match) => comparableVisibleText(match[2])).map((match) => Number(match[1]));
 }
+var DIVIDER_UTI = "com.apple.notes.inlinetextattachment.dividerline";
+function assertMarkdownBlocks(rich, expected) {
+  const tidy = (s) => s.replace(/[\s]+/gu, " ").trim();
+  const runs = rich.styleRuns || [];
+  const styledText = (matches) => {
+    let out = "", previous = false;
+    for (const run of runs) {
+      const hit = matches(run);
+      if (hit) out += (previous ? "" : " ") + rich.text.slice(run.start, run.start + run.length);
+      previous = hit;
+    }
+    return tidy(out);
+  };
+  if (styledText((run) => run.blockQuote === true) !== tidy(expected.quotes.join(" ")))
+    throw new Error("Block quotes not verified");
+  if (styledText((run) => run.paragraphStyle === 4) !== tidy(expected.code.join(" ")))
+    throw new Error("Monospaced code blocks not verified");
+  if (styledText((run) => run.highlight === true) !== tidy(expected.highlights.join(" ")))
+    throw new Error("Inline code highlights not verified");
+  const items = (rich.checklistItems || []).map((item) => ({
+    text: tidy(item.text),
+    done: item.done
+  }));
+  const wanted = expected.checklist.map((item) => ({ text: tidy(item.text), done: item.done }));
+  if (JSON.stringify(items) !== JSON.stringify(wanted))
+    throw new Error("Checklist items or their done state not verified");
+  if ((rich.objects || []).filter((o) => o.type === DIVIDER_UTI).length !== expected.dividers)
+    throw new Error("Dividers not verified");
+}
 function createMarkdownNote(manager, request, run = runBackgroundShortcut) {
   if (/[\r\n\0]/u.test(request.title)) throw new Error("A Markdown note title must be one line");
-  validateAppendContent(request.content, "markdown");
-  const bodyHtml = appendMarkdownHtml(request.content);
+  validateAppendContent(request.content, "markdown", { blocks: true });
+  const { html: bodyHtml, expect: blockExpectations } = renderMarkdown(request.content, {
+    blocks: true
+  });
+  const checkBlocks = usesMarkdownBlocks(request.content);
   if (request.folder) buildFolderReference(request.folder);
   const expectedText = `${request.title} ${comparableVisibleText(bodyHtml)}`.replace(/\s+/gu, " ").trim();
   const expectedLevels = [1, ...headingLevels(bodyHtml)].join();
@@ -45511,6 +45666,7 @@ ${request.content}`
         if (headingLevels(note2.html).join() !== expectedLevels)
           throw new Error("Heading styles not verified");
         assertAppendedHtmlLinks(0, note2.rich.links, bodyHtml);
+        if (checkBlocks) assertMarkdownBlocks(note2.rich, blockExpectations);
         return [{ id: noteId3, account: account2, note: note2 }];
       } catch (error2) {
         failures.push(`${noteId3}: ${reason(error2)}`);
@@ -46748,7 +46904,7 @@ import {
   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,
@@ -46764,7 +46920,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) };
 }
@@ -46853,66 +47009,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(
@@ -47006,7 +47240,8 @@ var VERIFIED_BACKGROUND = /* @__PURE__ */ new Set([
   "set-note-pinned",
   "remove-native-tags",
   "replace-native-tag",
-  "create-note-markdown"
+  "create-note-markdown",
+  "create-note-markdown-blocks"
 ]);
 var LIVE_VALIDATION_BLOCKERS = {};
 var signingRefusal = "Installed Shortcuts refuses to sign this Notes action (unsupported features); no background fallback is enabled";
@@ -47040,6 +47275,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,7 +47392,8 @@ function registerNativeOperations(server2, manager) {
         "remove-native-tags",
         "replace-native-tag",
         "insert-note-link",
-        "create-note-markdown"
+        "create-note-markdown",
+        "create-note-markdown-blocks"
       ];
       let tagBridgeInstalled = false;
       try {
@@ -47165,7 +47405,7 @@ function registerNativeOperations(server2, manager) {
         markdownBridgeInstalled = markdownNoteStatus().installed;
       } catch {
       }
-      const installed = (name) => name === "create-note-markdown" ? markdownBridgeInstalled : bridge.installed;
+      const installed = (name) => name.startsWith("create-note-markdown") ? markdownBridgeInstalled : bridge.installed;
       return {
         bridge,
         nativeTagBridgeInstalled: tagBridgeInstalled,
@@ -47241,13 +47481,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);
@@ -47619,7 +47862,7 @@ registerTool(
     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).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.'
+        'Note body; required unless contentPath is given (pass exactly one). In plaintext and HTML, AppleScript cannot create true Apple Notes checklists \u2014 `<input type="checkbox">`, checklist CSS classes, and markdown `- [ ]` lines do not render as checkable items; create a plain `<ul>` or `- ` list and convert it in Notes.app with \u21E7\u2318L. With format "markdown" (markdownRoute "shortcut"), `- [ ]`/`- [x]` lines, `>` block quotes, ``` fenced code, `---` dividers and `inline code` (which Notes renders as a highlight, not monospace) become native styles (see create-note-markdown-blocks in get-capabilities).'
       ),
       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.`
@@ -47628,7 +47871,7 @@ registerTool(
         "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."
+        "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 \u2014 refusing block quotes, fenced code and inline code, and keeping a `---` line as literal text."
       ),
       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."
@@ -47718,6 +47961,7 @@ registerTool(
           'tags are not supported with format "markdown"; create the note without tags, then add them with add-native-tags using the returned id'
         );
       requireValidated("create-note-markdown");
+      if (usesMarkdownBlocks(content)) requireValidated("create-note-markdown-blocks");
       const result = createMarkdownNote(notesManager, { title, content, folder });
       return successResponse(`Note created from Markdown: "${title}" [id: ${result.id}]`, {
         ...result,

package/package.json

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