apple-notes-mcp 2.9.12 → 2.9.14

package/README.md

@@ -257,7 +257,7 @@ Creates a new note in Apple Notes.
 | `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 |
+| `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). A smart folder is refused (see [`move-note`](#move-note)). 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) |
@@ -425,6 +425,7 @@ Searches for notes by title or content.
 | `folder` | string | No | Limit search to a specific folder (supports nested paths like `"Work/Clients"`) |
 | `modifiedSince` | string | No | ISO 8601 date string to filter notes modified on or after this date (e.g., `"2025-01-01"`) |
 | `limit` | number | No | Maximum number of results to return. **Defaults to 50** — a broad query reads several properties per match via AppleScript (~200ms/note), so an unbounded search over hundreds of matches can exceed Notes' 30s timeout and return an error instead of results. Pass a higher value to see more; the applied limit (and whether it truncated the results) is disclosed in the response. |
+| `includeWordCount` | boolean | No | Add `wordCount` to each result (`null` when the note is locked or its body unreadable). A database content search already has the text. Otherwise the bodies are read in one batched read-only database query, never one AppleScript call per note; that needs Full Disk Access and also adds `matchedIn`. Without it, the response carries `wordCountUnavailable` and the results are unchanged. |
 
 **Example - Search titles:**
 ```json
@@ -453,6 +454,17 @@ Searches for notes by title or content.
 
 **Returns:** List of matching notes with titles, folder names, and IDs. Use the returned ID for subsequent operations like `get-note-content`, `update-note`, etc. A content search also returns `source` (`"database"` or `"applescript"`), and `scanTruncated` when the database path left older notes unsearched.
 
+When the note text came from the database (a database content search, or any search with `includeWordCount`), each result also carries `matchedIn`: `["title"]`, `["body"]`, or `["title", "body"]`, saying where the query text occurs. The body is the text after the first line. `matchedIn` is absent for locked notes and for AppleScript searches without `includeWordCount`. The text output appends the same details to each line, for example `· matched in title, body · 245 words`.
+
+**Example - Content search with word counts:**
+```json
+{
+  "query": "budget",
+  "searchContent": true,
+  "includeWordCount": true
+}
+```
+
 ---
 
 #### `query-notes`
@@ -470,6 +482,7 @@ can match titles and bodies together.
 | `limit` | number | No | Maximum notes to return. Defaults to 50, maximum 500. The response reports the total match count. |
 | `scanLimit` | number | No | How many of the most recently modified notes to examine. Defaults to 500, maximum 5000. The response says when older notes were left unscanned. |
 | `includeDeleted` | boolean | No | Also scan notes in Recently Deleted, notes pending deletion, and folderless notes. Defaults to `false`. |
+| `includeWordCount` | boolean | No | Add `wordCount` to each returned note, the same count `words:` filters on (`null` when locked or unreadable). Free when the query already reads bodies; a metadata-only query (for example `pinned`) reads just the returned notes' bodies in one extra read-only query. Defaults to `false`. |
 
 **Syntax:**
 
@@ -514,7 +527,11 @@ Their snippets are always empty.
 
 **Returns:** Matching notes, most recently modified first, each with `id`,
 `title`, `folder`, `account`, `modified`, `created`, and a `snippet` centred on
-the first matched phrase. The ids are the same `x-coredata://…/ICNote/p…` form
+the first matched phrase. Each note also has `matchedIn` when the query has a
+positive text term: `["title"]`, `["body"]`, or both, saying where those terms
+occur (a `title:` term is only looked for in the title, a `body:` term only in
+the body). It is absent for locked or undecodable notes, and an empty list
+means the note matched through a non-text branch such as `pinned OR x`. The ids are the same `x-coredata://…/ICNote/p…` form
 every other tool accepts. `structuredContent` also reports `matched` (total
 matches), `scanned`, `eligible`, `scanTruncated`, `truncated`, and `unreadable`
 (bodies that could not be decoded). A malformed query returns an error naming
@@ -1032,6 +1049,8 @@ such a note for good, do it in Notes.app.
 
 Moves a note to a different folder. The note is relocated in place via Notes.app's native `move`, so its id, creation date, and all embedded attachments (files, images, scans, PDFs, audio) are preserved. The destination folder must already exist — create it first with [`create-folder`](#create-folder).
 
+A smart folder is never a destination: it only gathers notes by its rules, and Notes.app would move the note to Recently Deleted or store a created note where no folder shows it. `create-note`, `create-note-with-attachment`, `move-note`, `batch-move-notes`, and `create-folder` refuse one before writing anything, with `code: "unsupported"`, `committed: false`, and `reason: "smart_folder_destination"`. An ordinary folder that shares a smart folder's name is still found. Detection reads the NoteStore database, so it needs Full Disk Access; without it, destinations resolve as before.
+
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact CoreData note ID returned by a read or search |
@@ -1402,7 +1421,7 @@ Creates a new folder, including a whole nested hierarchy in one call.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `name` | string | Yes | Folder name, or a nested path separated by `/` (e.g. `"Retro Tech/PC/CPUs"`). Every intermediate folder is created; segments that already exist are skipped |
+| `name` | string | Yes | Folder name, or a nested path separated by `/` (e.g. `"Retro Tech/PC/CPUs"`). Every intermediate folder is created; segments that already exist are skipped. A segment that names a smart folder is refused before anything is created |
 | `account` | string | No | Account to create folder in (defaults to Notes.app's default account; exact or unique-prefix match) |
 
 **Example:**
@@ -1590,7 +1609,7 @@ Moves multiple notes to a folder.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `ids` | string[] | Yes | Array of note IDs to move (max 500 per request) |
-| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`). Must already exist — create it with [`create-folder`](#create-folder) |
+| `folder` | string | Yes | Destination folder name or nested path (e.g., `"Work/Clients"`). Must already exist — create it with [`create-folder`](#create-folder). A smart folder is refused for the whole call before any note moves |
 | `account` | string | No | Account containing the folder |
 
 **Returns:** Summary of successes and failures. Each success is reported only

package/build/index.js

@@ -39588,6 +39588,77 @@ function getChecklistItems(noteId3) {
   return { items };
 }
 
+// src/utils/errorCodes.ts
+var CodedError = class extends Error {
+  envelope;
+  constructor(message, envelope) {
+    super(message);
+    this.name = "CodedError";
+    this.envelope = envelope;
+  }
+};
+var RULES = [
+  { code: "timeout_indeterminate", pattern: /timed out|\bETIMEDOUT\b/i },
+  {
+    code: "verification_failed",
+    pattern: /\buncertain\b|may have (?:been|succeeded)|\baccepted (?:the|an) \w+, but|\bnot verified\b|Do not retry automatically|before any retry|read (?:the )?(?:exact )?(?:note|ID)\b[^.]*before retr/i
+  },
+  {
+    code: "revision_conflict",
+    pattern: /changed after it was read|revision changed|(?:pinned|note) state changed|changed during (?:read|preflight)|changed; read (?:it|the note) again|rich text do not match/i
+  },
+  { code: "full_disk_access_missing", pattern: /Full Disk Access/i },
+  {
+    code: "shortcut_not_installed",
+    pattern: /(?:Install|Import) the supplied|no such shortcut|Run apple-notes-mcp setup/i
+  },
+  {
+    code: "not_found",
+    pattern: /not found|does not exist|\bNo \w+ found\b|does not contain any checklist items|Can[’']t get (?:note|folder|account|attachment)|Cannot find note|Scope is absent/i
+  },
+  { code: "ambiguous", pattern: /ambiguous|more than one|exactly once|Duplicate note IDs/i },
+  {
+    code: "notes_unavailable",
+    pattern: /Notes\.app is (?:not responding|busy)|Lost connection to Notes|isn't running/i
+  },
+  {
+    code: "unsupported",
+    pattern: /password-protected|Locked notes|unsupported|not supported|is blocked|blocked because|has not passed live|refuses to sign|No (?:supported )?background|only one where|Real Notes link unavailable/i
+  },
+  {
+    code: "validation_error",
+    pattern: /\bis required\b|required\b|\bInvalid\b|\bmust\b|\bProvide\b|No (?:note IDs|reviewed notes) provided|response limit|Refusing to write|cannot be resolved|at most \d|between \d+ and \d+|supports the (?:end|default)|Use a distinctive|Use create-table|too large|equal cell counts|Folder path is empty/i
+  }
+];
+var NOTHING_WRITTEN = /nothing (?:was )?(?:changed|created|written)|no replacement started|No content was (?:replaced|appended)|Nothing was created/i;
+var WRITE_ACCEPTED = /\baccepted (?:the|an) \w+, but/i;
+function classifyError(message, cause) {
+  if (cause instanceof CodedError) return { ...cause.envelope };
+  const text2 = cause instanceof Error && cause.message && !message.includes(cause.message) ? `${message}
+${cause.message}` : message;
+  const timeoutCause = typeof cause === "object" && cause !== null && cause.code === "ETIMEDOUT";
+  let code = "operation_failed";
+  if (timeoutCause) code = "timeout_indeterminate";
+  else if (isPermissionDenied(text2)) code = "permission_denied";
+  else code = RULES.find((rule) => rule.pattern.test(text2))?.code ?? "operation_failed";
+  const envelope = { code };
+  if (code === "timeout_indeterminate" || code === "verification_failed") {
+    envelope.indeterminate = true;
+    if (WRITE_ACCEPTED.test(text2)) envelope.committed = true;
+  } else if (code === "revision_conflict" || NOTHING_WRITTEN.test(text2)) {
+    envelope.committed = false;
+    envelope.indeterminate = false;
+  }
+  return envelope;
+}
+function errorResult(message, cause) {
+  return {
+    content: [{ type: "text", text: message }],
+    structuredContent: classifyError(message, cause),
+    isError: true
+  };
+}
+
 // src/utils/inlineImages.ts
 var DEFAULT_MAX_INLINE_IMAGE_BYTES = 256 * 1024;
 function maxInlineImageBytes(env = process.env) {
@@ -42358,6 +42429,24 @@ function buildFolderReference(folderPath) {
 }
 var AS_ACCOUNT_REF = "__acctRef";
 var LIVE_FOLDER_NOT_FOUND = "Folder not found";
+var SMART_FOLDER_DESTINATION = "SMART_FOLDER_DESTINATION";
+function readSmartFolderIds(read = readSmartFolders) {
+  return (read().folders ?? []).map((folder) => folder.id).filter((id2) => FOLDER_ID_PATTERN.test(id2));
+}
+function smartFolderDestinationError(folderPath) {
+  return new CodedError(
+    `Refused: "${folderPath}" is a smart folder. Smart folders only gather notes by their rules and cannot hold notes or folders; choose an ordinary folder (list-folders). Nothing was changed`,
+    {
+      code: "unsupported",
+      committed: false,
+      indeterminate: false,
+      reason: "smart_folder_destination"
+    }
+  );
+}
+function throwIfSmartFolderDestination(error2, folderPath) {
+  if (error2?.includes(SMART_FOLDER_DESTINATION)) throw smartFolderDestinationError(folderPath);
+}
 function buildLiveFolderResolution(folderPath, varName, opts = {}) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) throw new Error("Invalid AppleScript variable");
   buildFolderReference(folderPath);
@@ -42366,10 +42455,26 @@ function buildLiveFolderResolution(folderPath, varName, opts = {}) {
   const cid = `${varName}_cid`;
   const any = `${varName}_any`;
   const parent = `${varName}_p`;
-  const notFound = `error "${LIVE_FOLDER_NOT_FOUND}: ${escapePlainStringForAppleScript(folderPath)}" number -1728`;
-  const lines = [];
+  const quotedPath = escapePlainStringForAppleScript(folderPath);
+  const notFound = `error "${LIVE_FOLDER_NOT_FOUND}: ${quotedPath}" number -1728`;
+  const excluded = (opts.excludeFolderIds ?? []).filter((id2) => FOLDER_ID_PATTERN.test(id2));
+  const skipIds = `${varName}_sx`;
+  const skipped = `${varName}_sh`;
+  const candidateTest = excluded.length ? [
+    `    if ${skipIds} contains ${cid} then`,
+    `      set ${skipped} to true`,
+    `    else if exists folder id ${cid} then`
+  ] : [`    if exists folder id ${cid} then`];
+  const unresolved = excluded.length ? [
+    `if ${varName} is missing value then`,
+    `  if ${skipped} then error "${SMART_FOLDER_DESTINATION}: ${quotedPath}" number -1728`,
+    `  ${notFound}`,
+    `end if`
+  ] : [`if ${varName} is missing value then ${notFound}`];
+  const lines = excluded.length ? [`set ${skipIds} to {${excluded.map((id2) => `"${id2}"`).join(", ")}}`] : [];
   parts.forEach((part, i) => {
     const name = escapePlainStringForAppleScript(part);
+    if (excluded.length) lines.push(`set ${skipped} to false`);
     if (i === 0) {
       lines.push(
         `set ${varName} to missing value`,
@@ -42377,7 +42482,7 @@ function buildLiveFolderResolution(folderPath, varName, opts = {}) {
         `repeat with ${c} in (folders of ${AS_ACCOUNT_REF} whose name is "${name}")`,
         `  try`,
         `    set ${cid} to id of ${c}`,
-        `    if exists folder id ${cid} then`,
+        ...candidateTest,
         `      if class of (container of ${c}) is not folder then`,
         `        set ${varName} to folder id ${cid}`,
         `        exit repeat`,
@@ -42397,7 +42502,7 @@ function buildLiveFolderResolution(folderPath, varName, opts = {}) {
         `repeat with ${c} in (folders of ${parent} whose name is "${name}")`,
         `  try`,
         `    set ${cid} to id of ${c}`,
-        `    if exists folder id ${cid} then`,
+        ...candidateTest,
         `      set ${varName} to folder id ${cid}`,
         `      exit repeat`,
         `    end if`,
@@ -42405,7 +42510,7 @@ function buildLiveFolderResolution(folderPath, varName, opts = {}) {
         `end repeat`
       );
     }
-    lines.push(`if ${varName} is missing value then ${notFound}`);
+    lines.push(...unresolved);
   });
   return lines.join("\n");
 }
@@ -42666,7 +42771,9 @@ var AppleNotesManager = class {
     const safeBody = escapeHtmlForAppleScript(`<h1>${htmlTitle}</h1>${bodyContent}`);
     let createCommand;
     if (folder) {
-      createCommand = `${buildLiveFolderResolution(folder, "__folder")}
+      createCommand = `${buildLiveFolderResolution(folder, "__folder", {
+        excludeFolderIds: this.smartFolderIds()
+      })}
       make new note at __folder with properties {body:"${safeBody}"}`;
     } else {
       createCommand = `
@@ -42678,6 +42785,7 @@ var AppleNotesManager = class {
     const result = executeMutationAppleScript(script);
     if (!result.success) {
       throwIfAccountResolutionFailed(result.error);
+      if (folder) throwIfSmartFolderDestination(result.error, folder);
       console.error(`Failed to create note "${title}":`, result.error);
       return null;
     }
@@ -43282,6 +43390,35 @@ var AppleNotesManager = class {
         return (resultList as text)${trashSuffix}
       `;
   }
+  /**
+   * Smart folder ids that a destination folder must never resolve to. Read
+   * fresh on every write (a smart folder can be added at any time); empty
+   * without Full Disk Access. See {@link readSmartFolderIds}.
+   */
+  smartFolderIds() {
+    return readSmartFolderIds();
+  }
+  /**
+   * Read-only preflight: throws the smart-folder refusal when `folderPath`
+   * resolves in `account` only to a smart folder. For write paths that create
+   * something before they reach their own destination check (the Markdown
+   * bridge creates first and moves second). Other failures are left to the
+   * write itself, which reports them as before.
+   *
+   * @param folderPath - Destination folder path (list-folders syntax)
+   * @param account - Account to resolve in (defaults to Notes' default)
+   */
+  assertNotSmartFolderDestination(folderPath, account) {
+    const excludeFolderIds = this.smartFolderIds();
+    if (excludeFolderIds.length === 0) return;
+    const script = buildAccountScopedScript(
+      { account: this.resolveAccount(account) },
+      `${buildLiveFolderResolution(folderPath, "__folder", { excludeFolderIds })}
+      return id of __folder`
+    );
+    const result = executeAppleScript(script);
+    if (!result.success) throwIfSmartFolderDestination(result.error, folderPath);
+  }
   /**
    * Lists every smart folder with its decoded query, read-only.
    *
@@ -43823,37 +43960,40 @@ var AppleNotesManager = class {
       console.error(`Invalid folder name: "${name}"`);
       return null;
     }
+    const smart = { rootOnly: true, excludeFolderIds: this.smartFolderIds() };
     for (let i = 0; i < parts.length; i++) {
       const currentPath = parts.slice(0, i + 1).map((p) => escapeFolderName(p)).join("/");
       const checkScript = buildAccountScopedScript(
         { account: targetAccount },
-        `${buildLiveFolderResolution(currentPath, "__folder", { rootOnly: true })}
+        `${buildLiveFolderResolution(currentPath, "__folder", smart)}
         return id of __folder`
       );
       const checkResult = executeAppleScript(checkScript);
       if (checkResult.success) {
         continue;
       }
+      throwIfSmartFolderDestination(checkResult.error, currentPath);
       const segmentName = escapePlainStringForAppleScript(parts[i]);
       let createCommand;
       if (i === 0) {
         createCommand = `make new folder with properties {name:"${segmentName}"}`;
       } else {
         const parentPath = parts.slice(0, i).map((p) => escapeFolderName(p)).join("/");
-        createCommand = `${buildLiveFolderResolution(parentPath, "__parent", { rootOnly: true })}
+        createCommand = `${buildLiveFolderResolution(parentPath, "__parent", smart)}
         make new folder at __parent with properties {name:"${segmentName}"}`;
       }
       const script = buildAccountScopedScript({ account: targetAccount }, createCommand);
       const result = executeMutationAppleScript(script);
       if (!result.success) {
         throwIfAccountResolutionFailed(result.error);
+        throwIfSmartFolderDestination(result.error, name);
         console.error(`Failed to create folder "${name}":`, result.error);
         return null;
       }
     }
     const idScript = buildAccountScopedScript(
       { account: targetAccount },
-      `${buildLiveFolderResolution(name, "__folder", { rootOnly: true })}
+      `${buildLiveFolderResolution(name, "__folder", smart)}
       return (id of __folder) & ${AS_FIELD_SEP} & (name of it)`
     );
     const idResult = executeAppleScript(idScript);
@@ -43912,7 +44052,9 @@ var AppleNotesManager = class {
   moveNoteById(id2, destinationFolder, account, scope2) {
     const targetAccount = this.resolveAccount(account);
     const safeId = sanitizeNoteId(id2);
-    const destFolderSetup = buildLiveFolderResolution(destinationFolder, "destFolder");
+    const destFolderSetup = buildLiveFolderResolution(destinationFolder, "destFolder", {
+      excludeFolderIds: this.smartFolderIds()
+    });
     const moveCommand = `
       ${buildAccountResolution(targetAccount)}
       ${destFolderSetup}
@@ -43927,6 +44069,7 @@ var AppleNotesManager = class {
     const result = executeMutationAppleScript(script);
     if (!result.success) {
       throwIfAccountResolutionFailed(result.error);
+      throwIfSmartFolderDestination(result.error, destinationFolder);
       console.error(
         `Cannot move note to "${destinationFolder}" (folder may not exist):`,
         result.error
@@ -44821,7 +44964,9 @@ var AppleNotesManager = class {
   batchMoveNotes(ids, folder, account) {
     if (ids.length === 0) return [];
     const targetAccount = this.resolveAccount(account);
-    const destFolderSetup = buildLiveFolderResolution(folder, "destFolder");
+    const destFolderSetup = buildLiveFolderResolution(folder, "destFolder", {
+      excludeFolderIds: this.smartFolderIds()
+    });
     const results = new Array(ids.length);
     const runnable = [];
     ids.forEach((id2, i) => {
@@ -44877,6 +45022,7 @@ var AppleNotesManager = class {
       const res = executeMutationAppleScript(script);
       if (!res.success) {
         throwIfAccountResolutionFailed(res.error);
+        throwIfSmartFolderDestination(res.error, folder);
         for (const r of runnable) {
           results[r.index] = this.createBatchResult(
             ids[r.index],
@@ -46787,13 +46933,6 @@ function describeSearchScope(searchContent, resultCount) {
   return "\n\n\u2139\uFE0F Only note titles were searched, so a term that appears in note bodies would not match. Retry with `searchContent: true` to search bodies instead.";
 }
 
-// src/utils/noteQueryStore.ts
-import { execFileSync as execFileSync14 } from "child_process";
-import * as fs8 from "fs";
-import * as os8 from "os";
-import * as path8 from "path";
-import { gunzipSync as gunzipSync8 } from "zlib";
-
 // src/utils/noteQuery.ts
 var QUERY_LIMITS = {
   /** Maximum number of tokens (terms, operators, parentheses). */
@@ -47225,21 +47364,50 @@ function evaluateNoteQuery(node, note) {
     }
   }
 }
-function positiveTextTerms(node, negated = false) {
+function positiveTextPredicates(node, negated = false) {
   switch (node.type) {
     case "and":
     case "or":
-      return node.children.flatMap((child) => positiveTextTerms(child, negated));
+      return node.children.flatMap((child) => positiveTextPredicates(child, negated));
     case "not":
-      return positiveTextTerms(node.child, !negated);
+      return positiveTextPredicates(node.child, !negated);
     case "text":
-      return negated ? [] : [node.value];
+      return negated ? [] : [{ field: node.field, value: node.value }];
     default:
       return [];
   }
 }
+function positiveTextTerms(node, negated = false) {
+  return positiveTextPredicates(node, negated).map((predicate) => predicate.value);
+}
+function matchLocations(predicates, title, text2) {
+  if (predicates.length === 0) return void 0;
+  if (text2 === null && predicates.some((p) => p.field !== "title")) return void 0;
+  const firstBreak = text2 === null ? -1 : text2.indexOf("\n");
+  const titleLower = normalizeForMatch(title);
+  const firstLineLower = text2 === null ? "" : normalizeForMatch(firstBreak === -1 ? text2 : text2.slice(0, firstBreak));
+  const bodyLower = text2 === null || firstBreak === -1 ? "" : normalizeForMatch(text2.slice(firstBreak + 1));
+  let inTitle = false;
+  let inBody = false;
+  for (const predicate of predicates) {
+    const needle = normalizeForMatch(predicate.value);
+    if (predicate.field !== "body" && !inTitle) {
+      inTitle = titleLower.includes(needle) || firstLineLower.includes(needle);
+    }
+    if (predicate.field !== "title" && !inBody) inBody = bodyLower.includes(needle);
+  }
+  const locations = [];
+  if (inTitle) locations.push("title");
+  if (inBody) locations.push("body");
+  return locations;
+}
 
 // src/utils/noteQueryStore.ts
+import { execFileSync as execFileSync14 } from "child_process";
+import * as fs8 from "fs";
+import * as os8 from "os";
+import * as path8 from "path";
+import { gunzipSync as gunzipSync8 } from "zlib";
 var NOTES_DB_PATH10 = path8.join(
   os8.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
@@ -47321,6 +47489,15 @@ function decodeNoteBody(data) {
     objectIds
   };
 }
+function decodeBodyHex(hex3) {
+  try {
+    return decodeNoteBody(
+      new Uint8Array(gunzipSync8(Buffer.from(hex3, "hex"), { maxOutputLength: 32 * 1024 * 1024 }))
+    );
+  } catch {
+    return null;
+  }
+}
 function countWords(text2) {
   let count = 0;
   for (const word of text2.replace(/\ufffc/gu, " ").split(/\s+/u)) {
@@ -47391,6 +47568,67 @@ function presentColumns2(dbPath2) {
   }
   return cols;
 }
+function readStore(dbPath2, build) {
+  if (!fs8.existsSync(dbPath2)) throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
+  try {
+    return runSqlite6(dbPath2, build(presentColumns2(dbPath2)));
+  } catch (error2) {
+    if (error2 instanceof NoteQueryStoreError) throw error2;
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    if (message.includes("authorization denied") || message.includes("unable to open database")) {
+      throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
+    }
+    console.error(`query-notes: database read failed: ${message}`);
+    throw new NoteQueryStoreError("Failed to read the Notes database.", "query_error");
+  }
+}
+var NOTE_TEXT_BATCH_MAX = QUERY_RESULTS.MAX;
+function buildNoteTextsSql(available, pks) {
+  const missing = ["Z_PK", "Z_ENT"].filter((c) => !available.has(c));
+  if (missing.length) {
+    throw new NoteQueryStoreError(
+      `This macOS version's Notes database lacks columns search enrichment needs (${missing.join(", ")}).`,
+      "schema"
+    );
+  }
+  const keys = [...new Set(pks)];
+  if (keys.length > NOTE_TEXT_BATCH_MAX) {
+    throw new NoteQueryStoreError(
+      `At most ${NOTE_TEXT_BATCH_MAX} notes can be read at once.`,
+      "query_error"
+    );
+  }
+  for (const pk of keys) {
+    if (!Number.isSafeInteger(pk) || pk < 1) {
+      throw new NoteQueryStoreError(`Invalid note key ${String(pk)}`, "query_error");
+    }
+  }
+  const locked = available.has("ZISPASSWORDPROTECTED") ? "COALESCE(n.ZISPASSWORDPROTECTED, 0)" : "0";
+  return [
+    "BEGIN;",
+    "SELECT json_object('k', 'meta', 'uuid', (SELECT Z_UUID FROM Z_METADATA LIMIT 1));",
+    `SELECT json_object('k', 'note', 'pk', n.Z_PK, 'locked', ${locked}, 'data', (SELECT hex(d.ZDATA) FROM ZICNOTEDATA d WHERE d.ZNOTE = n.Z_PK ORDER BY d.Z_PK DESC LIMIT 1)) FROM ZICCLOUDSYNCINGOBJECT n WHERE n.Z_ENT = ${entity2("ICNote")} AND n.Z_PK IN (${keys.length ? keys.join(", ") : "NULL"});`,
+    "COMMIT;"
+  ].join(" ");
+}
+function readNoteTexts(pks, options = {}) {
+  const output = readStore(
+    options.dbPath ?? NOTES_DB_PATH10,
+    (available) => buildNoteTextsSql(available, pks)
+  );
+  let uuid2;
+  const texts = /* @__PURE__ */ new Map();
+  for (const line of output.split("\n")) {
+    if (!line.trim()) continue;
+    const row = JSON.parse(line);
+    if (row.k === "meta") uuid2 = typeof row.uuid === "string" ? row.uuid : void 0;
+    else if (row.k === "note" && typeof row.pk === "number") {
+      const body = row.locked || !row.data ? null : decodeBodyHex(row.data);
+      texts.set(row.pk, body ? body.text : null);
+    }
+  }
+  return { uuid: uuid2, texts };
+}
 var escapeSegment = escapeFolderName;
 function resolveFolders(rows) {
   const byPk = new Map(rows.map((row) => [row.pk, row]));
@@ -47447,23 +47685,10 @@ function runNoteQuery(ast, options = {}) {
   const withBodies = needsContent(ast);
   const withTags = needsTags(ast);
   const dbPath2 = options.dbPath ?? NOTES_DB_PATH10;
-  if (!fs8.existsSync(dbPath2)) throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
-  let output;
-  try {
-    const available = presentColumns2(dbPath2);
-    output = runSqlite6(
-      dbPath2,
-      buildScanSql(available, { scanLimit, includeDeleted, withBodies, withTags })
-    );
-  } catch (error2) {
-    if (error2 instanceof NoteQueryStoreError) throw error2;
-    const message = error2 instanceof Error ? error2.message : String(error2);
-    if (message.includes("authorization denied") || message.includes("unable to open database")) {
-      throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
-    }
-    console.error(`query-notes: database read failed: ${message}`);
-    throw new NoteQueryStoreError("Failed to read the Notes database.", "query_error");
-  }
+  const output = readStore(
+    dbPath2,
+    (available) => buildScanSql(available, { scanLimit, includeDeleted, withBodies, withTags })
+  );
   let uuid2;
   let eligible = 0;
   const folderRows = [];
@@ -47487,6 +47712,8 @@ function runNoteQuery(ast, options = {}) {
   }
   const folders = resolveFolders(folderRows);
   const textTerms = positiveTextTerms(ast);
+  const textPredicates = positiveTextPredicates(ast);
+  const pendingWordCounts = [];
   const hits = [];
   let matched = 0;
   let unreadable = 0;
@@ -47504,15 +47731,7 @@ function runNoteQuery(ast, options = {}) {
         if (withBodies) unreadable++;
         return decoded;
       }
-      try {
-        decoded = decodeNoteBody(
-          new Uint8Array(
-            gunzipSync8(Buffer.from(row.data, "hex"), { maxOutputLength: 32 * 1024 * 1024 })
-          )
-        );
-      } catch {
-        decoded = null;
-      }
+      decoded = decodeBodyHex(row.data);
       if (!decoded) unreadable++;
       return decoded;
     };
@@ -47553,6 +47772,8 @@ function runNoteQuery(ast, options = {}) {
     matched++;
     if (hits.length >= limit) continue;
     const body = locked ? null : decode2();
+    const matchedIn = matchLocations(textPredicates, row.title ?? "", body ? body.text : null);
+    if (options.includeWordCount && !withBodies) pendingWordCounts.push(row.pk);
     hits.push({
       id: `x-coredata://${uuid2}/ICNote/p${row.pk}`,
       title: row.title ?? "",
@@ -47561,7 +47782,16 @@ function runNoteQuery(ast, options = {}) {
       ...note.modified !== void 0 ? { modified: new Date(note.modified).toISOString() } : {},
       ...note.created !== void 0 ? { created: new Date(note.created).toISOString() } : {},
       snippet: locked ? "" : body ? buildSnippet(body.text, textTerms) : (row.snippet ?? "").replace(/\s+/gu, " ").trim(),
-      ...locked ? { locked: true } : {}
+      ...locked ? { locked: true } : {},
+      ...matchedIn ? { matchedIn } : {},
+      ...options.includeWordCount && withBodies ? { wordCount: body ? countWords(body.text) : null } : {}
+    });
+  }
+  if (pendingWordCounts.length) {
+    const { texts } = readNoteTexts(pendingWordCounts, { dbPath: dbPath2 });
+    pendingWordCounts.forEach((pk, index) => {
+      const text2 = texts.get(pk);
+      hits[index].wordCount = typeof text2 === "string" ? countWords(text2) : null;
     });
   }
   return {
@@ -47604,6 +47834,7 @@ function searchContentViaDatabase(options) {
   const result = runNoteQuery(buildSearchContentQuery(options), {
     limit: options.limit,
     scanLimit: QUERY_SCAN.MAX,
+    includeWordCount: options.includeWordCount,
     dbPath: options.dbPath
   });
   const notes = result.notes.map((hit) => ({
@@ -47614,7 +47845,9 @@ function searchContentViaDatabase(options) {
     created: hit.created ? new Date(hit.created) : /* @__PURE__ */ new Date(0),
     modified: hit.modified ? new Date(hit.modified) : /* @__PURE__ */ new Date(0),
     ...hit.folder !== void 0 ? { folder: hit.folder } : {},
-    ...hit.account !== void 0 ? { account: hit.account } : {}
+    ...hit.account !== void 0 ? { account: hit.account } : {},
+    ...hit.matchedIn ? { matchedIn: hit.matchedIn } : {},
+    ...hit.wordCount !== void 0 ? { wordCount: hit.wordCount } : {}
   }));
   return {
     notes,
@@ -47637,6 +47870,55 @@ function contentSearchFailureHint(message, dbUnavailable) {
   const remedy = dbUnavailable === "no_fda" ? " Grant Full Disk Access to the Node binary running this server (run the doctor tool for its path) so search-notes can search note bodies through the Notes database instead, which takes well under a second." : "";
   return `${message} Body search through AppleScript scans every note body before the result limit applies, so a broad term can exceed the time budget on a large library.${remedy} Otherwise narrow the search with \`folder\` or \`modifiedSince\`, or use a more specific term.`;
 }
+var NOTE_ID = /^x-coredata:\/\/([0-9A-Fa-f-]+)\/ICNote\/p(\d{1,15})$/;
+function addWordCountsFromDatabase(notes, query2, options = {}) {
+  const keys = /* @__PURE__ */ new Map();
+  for (const note of notes) {
+    const match = NOTE_ID.exec(note.id ?? "");
+    if (match) keys.set(note, { store: match[1].toUpperCase(), pk: Number(match[2]) });
+  }
+  const pks = [...new Set([...keys.values()].map((key) => key.pk))];
+  let store;
+  const texts = /* @__PURE__ */ new Map();
+  try {
+    for (let start = 0; start < pks.length; start += NOTE_TEXT_BATCH_MAX) {
+      const read = readNoteTexts(pks.slice(start, start + NOTE_TEXT_BATCH_MAX), options);
+      store = read.uuid?.toUpperCase();
+      for (const [pk, text2] of read.texts) texts.set(pk, text2);
+    }
+  } catch (error2) {
+    if (error2 instanceof NoteQueryStoreError) return { notes, unavailable: error2.kind };
+    throw error2;
+  }
+  const predicates = [{ field: "any", value: query2 }];
+  return {
+    notes: notes.map((note) => {
+      const key = keys.get(note);
+      const text2 = key && key.store === store ? texts.get(key.pk) : void 0;
+      if (typeof text2 !== "string") return { ...note, wordCount: null };
+      const matchedIn = matchLocations(predicates, note.title, text2);
+      return {
+        ...note,
+        ...matchedIn?.length ? { matchedIn } : {},
+        wordCount: countWords(text2)
+      };
+    })
+  };
+}
+function describeMatchDetails(hit) {
+  const parts = [];
+  if (hit.matchedIn) {
+    parts.push(
+      hit.matchedIn.length ? `matched in ${hit.matchedIn.join(", ")}` : "no text match (metadata)"
+    );
+  }
+  if (hit.wordCount !== void 0) {
+    parts.push(
+      hit.wordCount === null ? "word count unavailable" : `${hit.wordCount} word${hit.wordCount === 1 ? "" : "s"}`
+    );
+  }
+  return parts.map((part) => ` \xB7 ${part}`).join("");
+}
 
 // src/tools/doctor.ts
 import { spawnSync } from "child_process";
@@ -48358,12 +48640,15 @@ function createMarkdownNote(manager, request, run = runBackgroundShortcut) {
   const segments = (path10) => JSON.stringify(splitFolderPath(path10).map((part) => part.toLocaleLowerCase()));
   if (request.folder) {
     const wanted = segments(request.folder);
-    if (!manager.listAccounts().some(
-      (account) => account.defaultFolder && manager.listFolders(account.name).some((folder) => segments(folder.name) === wanted)
+    const accounts = manager.listAccounts().filter((account) => account.defaultFolder);
+    if (!accounts.some(
+      (account) => manager.listFolders(account.name).some((folder) => segments(folder.name) === wanted)
     ))
       throw new Error(
         `Folder "${request.folder}" does not exist; create it with create-folder first. Nothing was created`
       );
+    for (const account of accounts)
+      manager.assertNotSmartFolderDestination(request.folder, account.name);
   }
   const defaultFolderNotes = () => new Map(
     manager.listAccounts().flatMap(
@@ -49031,77 +49316,6 @@ function withJsonSchema2020_12(transport2) {
   return transport2;
 }
 
-// src/utils/errorCodes.ts
-var CodedError = class extends Error {
-  envelope;
-  constructor(message, envelope) {
-    super(message);
-    this.name = "CodedError";
-    this.envelope = envelope;
-  }
-};
-var RULES = [
-  { code: "timeout_indeterminate", pattern: /timed out|\bETIMEDOUT\b/i },
-  {
-    code: "verification_failed",
-    pattern: /\buncertain\b|may have (?:been|succeeded)|\baccepted (?:the|an) \w+, but|\bnot verified\b|Do not retry automatically|before any retry|read (?:the )?(?:exact )?(?:note|ID)\b[^.]*before retr/i
-  },
-  {
-    code: "revision_conflict",
-    pattern: /changed after it was read|revision changed|(?:pinned|note) state changed|changed during (?:read|preflight)|changed; read (?:it|the note) again|rich text do not match/i
-  },
-  { code: "full_disk_access_missing", pattern: /Full Disk Access/i },
-  {
-    code: "shortcut_not_installed",
-    pattern: /(?:Install|Import) the supplied|no such shortcut|Run apple-notes-mcp setup/i
-  },
-  {
-    code: "not_found",
-    pattern: /not found|does not exist|\bNo \w+ found\b|does not contain any checklist items|Can[’']t get (?:note|folder|account|attachment)|Cannot find note|Scope is absent/i
-  },
-  { code: "ambiguous", pattern: /ambiguous|more than one|exactly once|Duplicate note IDs/i },
-  {
-    code: "notes_unavailable",
-    pattern: /Notes\.app is (?:not responding|busy)|Lost connection to Notes|isn't running/i
-  },
-  {
-    code: "unsupported",
-    pattern: /password-protected|Locked notes|unsupported|not supported|is blocked|blocked because|has not passed live|refuses to sign|No (?:supported )?background|only one where|Real Notes link unavailable/i
-  },
-  {
-    code: "validation_error",
-    pattern: /\bis required\b|required\b|\bInvalid\b|\bmust\b|\bProvide\b|No (?:note IDs|reviewed notes) provided|response limit|Refusing to write|cannot be resolved|at most \d|between \d+ and \d+|supports the (?:end|default)|Use a distinctive|Use create-table|too large|equal cell counts|Folder path is empty/i
-  }
-];
-var NOTHING_WRITTEN = /nothing (?:was )?(?:changed|created|written)|no replacement started|No content was (?:replaced|appended)|Nothing was created/i;
-var WRITE_ACCEPTED = /\baccepted (?:the|an) \w+, but/i;
-function classifyError(message, cause) {
-  if (cause instanceof CodedError) return { ...cause.envelope };
-  const text2 = cause instanceof Error && cause.message && !message.includes(cause.message) ? `${message}
-${cause.message}` : message;
-  const timeoutCause = typeof cause === "object" && cause !== null && cause.code === "ETIMEDOUT";
-  let code = "operation_failed";
-  if (timeoutCause) code = "timeout_indeterminate";
-  else if (isPermissionDenied(text2)) code = "permission_denied";
-  else code = RULES.find((rule) => rule.pattern.test(text2))?.code ?? "operation_failed";
-  const envelope = { code };
-  if (code === "timeout_indeterminate" || code === "verification_failed") {
-    envelope.indeterminate = true;
-    if (WRITE_ACCEPTED.test(text2)) envelope.committed = true;
-  } else if (code === "revision_conflict" || NOTHING_WRITTEN.test(text2)) {
-    envelope.committed = false;
-    envelope.indeterminate = false;
-  }
-  return envelope;
-}
-function errorResult(message, cause) {
-  return {
-    content: [{ type: "text", text: message }],
-    structuredContent: classifyError(message, cause),
-    isError: true
-  };
-}
-
 // src/utils/shutdown.ts
 var SHUTDOWN_DRAIN_TIMEOUT_MS = 2e3;
 function createShutdown(stream, exit, timeoutMs = SHUTDOWN_DRAIN_TIMEOUT_MS) {
@@ -49255,7 +49469,7 @@ function selectParagraph(paragraphs, selector) {
     );
   return matches[occurrence - 1];
 }
-var NOTE_ID = /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p([0-9]{1,15})$/i;
+var NOTE_ID2 = /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p([0-9]{1,15})$/i;
 function titleMatchSql(columns) {
   return `SELECT json_object('pk', n.Z_PK, 'folder', n.ZFOLDER) FROM ZICCLOUDSYNCINGOBJECT n LEFT JOIN ZICCLOUDSYNCINGOBJECT f ON f.Z_PK = n.ZFOLDER WHERE n.Z_ENT = ${entity("ICNote")} AND n.ZTITLE1 = CAST(@title AS TEXT) AND ${activeNoteSql(columns, "n", "f")} ORDER BY n.Z_PK;`;
 }
@@ -49266,7 +49480,7 @@ function checkNoteSelector(selector) {
   if (selector.folder !== void 0 && selector.title === void 0)
     throw new ParagraphLinkError("invalid-argument", "folder only narrows a title lookup");
   if (selector.id === void 0) return void 0;
-  const pk = NOTE_ID.exec(selector.id)?.[1];
+  const pk = NOTE_ID2.exec(selector.id)?.[1];
   if (!pk)
     throw new ParagraphLinkError(
       "invalid-argument",
@@ -51577,7 +51791,9 @@ function registerDirectOperations(server2, manager) {
     {
       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"),
+      folder: external_exports.string().max(1e3).optional().describe(
+        "Existing folder or nested path; create it first with create-folder. A smart folder is refused before the note is created"
+      ),
       account: external_exports.string().max(200).optional().describe("Account name; defaults to Notes' default"),
       ...attachmentInput
     },
@@ -56607,7 +56823,7 @@ function registerTool(name, config2, cb) {
 registerTool(
   "create-note",
   {
-    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.",
+    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. A smart folder is refused (code unsupported); it cannot hold notes.",
     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(
@@ -56747,7 +56963,7 @@ registerTool(
 registerTool(
   "search-notes",
   {
-    description: "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id; `source` says whether a body search read the Notes database or fell back to AppleScript.\nDo not use when: you already have a note id (use get-note-content), want every note (use list-notes), or need boolean or metadata filters (use query-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.\nNote: with Full Disk Access, body search reads the Notes database (fast; the most recent 5000 notes, Recently Deleted excluded); without it, it falls back to AppleScript, which scans every body and can time out on broad terms.",
+    description: "Use when: finding notes by a keyword in the title (or body with searchContent=true) and you need their ids.\nReturns: matching notes with title, folder, and id; `source` says whether a body search read the Notes database or fell back to AppleScript. When the note text came from the database, each result has matchedIn (title, body, or both); includeWordCount adds wordCount.\nDo not use when: you already have a note id (use get-note-content), want every note (use list-notes), or need boolean or metadata filters (use query-notes).\nPrefer this first to obtain ids for subsequent read/update/delete/move calls.\nNote: with Full Disk Access, body search reads the Notes database (fast; the most recent 5000 notes, Recently Deleted excluded); without it, it falls back to AppleScript, which scans every body and can time out on broad terms.",
     inputSchema: {
       query: external_exports.string().min(1, "Search query is required").max(MAX.QUERY),
       searchContent: external_exports.boolean().optional().describe(
@@ -56760,112 +56976,132 @@ registerTool(
       ),
       limit: external_exports.number().int().positive().optional().describe(
         "Maximum number of results to return. Defaults to 50 \u2014 a broad query reads several properties per match via AppleScript, so an unbounded search can time out. Pass a higher value to see more; the applied limit is disclosed in the response."
+      ),
+      includeWordCount: external_exports.boolean().optional().describe(
+        "Add wordCount to each result (null when locked or unreadable). A database body search already has the text; otherwise the bodies are read in one batched read-only database query (needs Full Disk Access), which also adds matchedIn"
       )
     },
     outputSchema: {
       notes: external_exports.array(external_exports.object({}).passthrough()).optional(),
       count: external_exports.number().optional(),
       source: external_exports.enum(["database", "applescript"]).optional(),
-      scanTruncated: external_exports.boolean().optional()
+      scanTruncated: external_exports.boolean().optional(),
+      wordCountUnavailable: external_exports.string().optional()
     }
   },
-  withErrorHandling(({ query: query2, searchContent = false, account, folder, modifiedSince, limit }) => {
-    const effectiveLimit = resolveSearchLimit(limit);
-    const limitWasDefault = limit === void 0;
-    let source;
-    let dbScan;
-    let dbUnavailable;
-    const runSearch = () => {
-      if (searchContent) {
+  withErrorHandling(
+    ({ query: query2, searchContent = false, account, folder, modifiedSince, limit, includeWordCount }) => {
+      const effectiveLimit = resolveSearchLimit(limit);
+      const limitWasDefault = limit === void 0;
+      let source;
+      let dbScan;
+      let dbUnavailable;
+      const runSearch = () => {
+        if (searchContent) {
+          try {
+            const db = searchContentViaDatabase({
+              query: query2,
+              account: notesManager.searchAccountScope(account),
+              folder,
+              modifiedSince,
+              limit: effectiveLimit,
+              includeWordCount
+            });
+            source = "database";
+            dbScan = db.scan;
+            return db.notes;
+          } catch (error2) {
+            if (!(error2 instanceof NoteQueryStoreError)) throw error2;
+            dbUnavailable = error2.kind;
+          }
+          source = "applescript";
+        }
         try {
-          const db = searchContentViaDatabase({
-            query: query2,
-            account: notesManager.searchAccountScope(account),
+          return notesManager.searchNotes(
+            query2,
+            searchContent,
+            account,
             folder,
             modifiedSince,
-            limit: effectiveLimit
-          });
-          source = "database";
-          dbScan = db.scan;
-          return db.notes;
+            effectiveLimit
+          );
         } catch (error2) {
-          if (!(error2 instanceof NoteQueryStoreError)) throw error2;
-          dbUnavailable = error2.kind;
+          if (!searchContent || !(error2 instanceof Error)) throw error2;
+          throw new Error(contentSearchFailureHint(error2.message, dbUnavailable));
         }
-        source = "applescript";
+      };
+      const {
+        result: found,
+        syncBefore,
+        syncInterference
+      } = withSyncAwarenessSync("search-notes", runSearch);
+      let notes = found;
+      let wordCountUnavailable;
+      if (includeWordCount && source !== "database" && found.length > 0) {
+        const enriched = addWordCountsFromDatabase(found, query2);
+        notes = enriched.notes;
+        wordCountUnavailable = enriched.unavailable;
+      }
+      const wordCountFields = wordCountUnavailable ? { wordCountUnavailable } : {};
+      const wordCountNote = wordCountUnavailable ? `
+
+\u2139\uFE0F Word counts were not added: ${wordCountUnavailable === "no_fda" ? "they are read from the Notes database, which needs Full Disk Access (run the doctor tool)" : "the Notes database could not be read"}.` : "";
+      const searchType = searchContent ? source === "database" ? "content via the Notes database" : "content" : "titles";
+      const sourceFields = source ? { source } : {};
+      const scanFields = dbScan ? { scanTruncated: dbScan.scanTruncated } : {};
+      const scanNote = describeContentScan(dbScan);
+      const folderInfo = folder ? ` in folder "${folder}"` : "";
+      const dateInfo = modifiedSince ? ` modified since ${modifiedSince}` : "";
+      const { info: limitInfo, truncationNote } = describeSearchLimit(
+        effectiveLimit,
+        limitWasDefault,
+        notes.length
+      );
+      const syncWarnings = [];
+      if (syncBefore.syncDetected) {
+        syncWarnings.push(`\u26A0\uFE0F iCloud sync was active during search.`);
       }
-      try {
-        return notesManager.searchNotes(
-          query2,
-          searchContent,
-          account,
-          folder,
-          modifiedSince,
-          effectiveLimit
-        );
-      } catch (error2) {
-        if (!searchContent || !(error2 instanceof Error)) throw error2;
-        throw new Error(contentSearchFailureHint(error2.message, dbUnavailable));
+      if (syncInterference) {
+        syncWarnings.push(`\u26A0\uFE0F Sync activity detected - results may be incomplete.`);
       }
-    };
-    const {
-      result: notes,
-      syncBefore,
-      syncInterference
-    } = withSyncAwarenessSync("search-notes", runSearch);
-    const searchType = searchContent ? source === "database" ? "content via the Notes database" : "content" : "titles";
-    const sourceFields = source ? { source } : {};
-    const scanFields = dbScan ? { scanTruncated: dbScan.scanTruncated } : {};
-    const scanNote = describeContentScan(dbScan);
-    const folderInfo = folder ? ` in folder "${folder}"` : "";
-    const dateInfo = modifiedSince ? ` modified since ${modifiedSince}` : "";
-    const { info: limitInfo, truncationNote } = describeSearchLimit(
-      effectiveLimit,
-      limitWasDefault,
-      notes.length
-    );
-    const syncWarnings = [];
-    if (syncBefore.syncDetected) {
-      syncWarnings.push(`\u26A0\uFE0F iCloud sync was active during search.`);
-    }
-    if (syncInterference) {
-      syncWarnings.push(`\u26A0\uFE0F Sync activity detected - results may be incomplete.`);
-    }
-    const syncNote = syncWarnings.length > 0 ? `
+      const syncNote = syncWarnings.length > 0 ? `
 
 ${syncWarnings.join(" ")}` : "";
-    if (notes.length === 0) {
-      const scopeHint = describeSearchScope(searchContent, notes.length);
+      if (notes.length === 0) {
+        const scopeHint = describeSearchScope(searchContent, notes.length);
+        return successResponse(
+          `No notes found matching "${query2}" in ${searchType}${folderInfo}${dateInfo}${scopeHint}${scanNote}${syncNote}`,
+          { notes: [], count: 0, ...sourceFields, ...scanFields }
+        );
+      }
+      const noteList = notes.map((n) => {
+        const idSuffix = `${n.id ? ` [id: ${n.id}]` : ""}${describeMatchDetails(n)}`;
+        if (n.folder === "Recently Deleted") {
+          return `  - ${n.title} [DELETED]${idSuffix}`;
+        } else if (n.folder) {
+          return `  - ${n.title} (${n.folder})${idSuffix}`;
+        }
+        return `  - ${n.title}${idSuffix}`;
+      }).join("\n");
       return successResponse(
-        `No notes found matching "${query2}" in ${searchType}${folderInfo}${dateInfo}${scopeHint}${scanNote}${syncNote}`,
-        { notes: [], count: 0, ...sourceFields, ...scanFields }
+        `Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):
+${noteList}${truncationNote}${scanNote}${wordCountNote}${syncNote}`,
+        {
+          notes: withStableIdentifiers(notes, "ICNote"),
+          count: notes.length,
+          ...sourceFields,
+          ...scanFields,
+          ...wordCountFields
+        }
       );
-    }
-    const noteList = notes.map((n) => {
-      const idSuffix = n.id ? ` [id: ${n.id}]` : "";
-      if (n.folder === "Recently Deleted") {
-        return `  - ${n.title} [DELETED]${idSuffix}`;
-      } else if (n.folder) {
-        return `  - ${n.title} (${n.folder})${idSuffix}`;
-      }
-      return `  - ${n.title}${idSuffix}`;
-    }).join("\n");
-    return successResponse(
-      `Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):
-${noteList}${truncationNote}${scanNote}${syncNote}`,
-      {
-        notes: withStableIdentifiers(notes, "ICNote"),
-        count: notes.length,
-        ...sourceFields,
-        ...scanFields
-      }
-    );
-  }, "Error searching notes")
+    },
+    "Error searching notes"
+  )
 );
 registerTool(
   "query-notes",
   {
-    description: 'Use when: finding notes with a boolean expression over text and metadata \u2014 e.g. `folder:Work has:checklist -checklist:done`, `(title:invoice OR tag:finance) modified:>=2026-07-01`, `pinned words:>250`. Reads the Notes database directly, so it is fast and can match title OR body in one call.\nSyntax: bare words and "quoted phrases" match title or body (case-insensitive substring); fields title:, body:, text:, folder:, account:, tag: (values may be quoted, e.g. folder:"Work Projects"); facets has:link|attachment|checklist|drawing|image|video|audio|pdf|table|scan|tag; checklist:open|done; flags pinned, locked, shared (or is:pinned); words:>250 and created:/modified: with =, >, >=, <, <= and YYYY-MM-DD local dates. AND is implicit; OR, NOT, leading -, and parentheses are supported; operators are case-insensitive and a quoted "and" searches the literal word.\nReturns: matching notes (most recently modified first) with id, title, folder, account, modified date, and snippet, plus scan/match counts. Ids work with get-note-content and every other id-based tool.\nDo not use when: Full Disk Access is unavailable (use search-notes). Scans the most recent scanLimit notes (default 500); raise it for older notes.\nSafety: read-only; never writes the database. Excludes Recently Deleted and folderless notes unless includeDeleted is true. Locked notes match on title and metadata only; body predicates never match them.',
+    description: 'Use when: finding notes with a boolean expression over text and metadata \u2014 e.g. `folder:Work has:checklist -checklist:done`, `(title:invoice OR tag:finance) modified:>=2026-07-01`, `pinned words:>250`. Reads the Notes database directly, so it is fast and can match title OR body in one call.\nSyntax: bare words and "quoted phrases" match title or body (case-insensitive substring); fields title:, body:, text:, folder:, account:, tag: (values may be quoted, e.g. folder:"Work Projects"); facets has:link|attachment|checklist|drawing|image|video|audio|pdf|table|scan|tag; checklist:open|done; flags pinned, locked, shared (or is:pinned); words:>250 and created:/modified: with =, >, >=, <, <= and YYYY-MM-DD local dates. AND is implicit; OR, NOT, leading -, and parentheses are supported; operators are case-insensitive and a quoted "and" searches the literal word.\nReturns: matching notes (most recently modified first) with id, title, folder, account, modified date, snippet, and matchedIn (where the positive text terms occur: title, body, or both; absent when the body is unreadable or the query has no text term), plus scan/match counts; includeWordCount adds wordCount. Ids work with get-note-content and every other id-based tool.\nDo not use when: Full Disk Access is unavailable (use search-notes). Scans the most recent scanLimit notes (default 500); raise it for older notes.\nSafety: read-only; never writes the database. Excludes Recently Deleted and folderless notes unless includeDeleted is true. Locked notes match on title and metadata only; body predicates never match them.',
     inputSchema: {
       query: external_exports.string().min(1, "A query expression is required").max(MAX.QUERY).describe(
         'Boolean query expression, e.g. `folder:"Work Projects" has:checklist -checklist:done`'
@@ -56878,6 +57114,9 @@ registerTool(
       ),
       includeDeleted: external_exports.boolean().optional().describe(
         "Also scan notes in Recently Deleted, notes pending deletion, and folderless notes (default false)"
+      ),
+      includeWordCount: external_exports.boolean().optional().describe(
+        "Add wordCount to each returned note (the count words: filters on; null when locked or unreadable). Free when the query reads bodies; a metadata-only query reads just the returned notes' bodies in one extra query (default false)"
       )
     },
     outputSchema: {
@@ -56894,10 +57133,10 @@ registerTool(
     },
     annotations: { readOnlyHint: true }
   },
-  withErrorHandling(({ query: query2, limit, scanLimit, includeDeleted }) => {
+  withErrorHandling(({ query: query2, limit, scanLimit, includeDeleted, includeWordCount }) => {
     let result;
     try {
-      result = queryNotes(query2, { limit, scanLimit, includeDeleted });
+      result = queryNotes(query2, { limit, scanLimit, includeDeleted, includeWordCount });
     } catch (error2) {
       if (error2 instanceof NoteQueryError || error2 instanceof NoteQueryStoreError) {
         return errorResponse(
@@ -56928,7 +57167,7 @@ ${notes.join("\n")}` : "";
       const where = [n.account, n.folder].filter(Boolean).join(" / ");
       const snippet = n.snippet ? `
       ${n.snippet}` : "";
-      return `  - ${n.title}${where ? ` (${where})` : ""}${n.locked ? " [locked]" : ""} [id: ${n.id}]${snippet}`;
+      return `  - ${n.title}${where ? ` (${where})` : ""}${n.locked ? " [locked]" : ""} [id: ${n.id}]${describeMatchDetails(n)}${snippet}`;
     }).join("\n");
     return successResponse(
       `Found ${result.matched} matching notes (${scope2}):
@@ -58099,7 +58338,7 @@ registerTool(
 registerTool(
   "move-note",
   {
-    description: "Use when: moving one exact note to a different folder by id.\nReturns: confirmation and exact-ID readback.\nDo not use when: you only have a title or want to move many notes (batch-move-notes).\nNote: Notes.app's native move preserves the note id, creation date, body, and attachments. The destination folder must already exist. Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds (which also covers the destination) are re-checked inside the move AppleScript.",
+    description: "Use when: moving one exact note to a different folder by id.\nReturns: confirmation and exact-ID readback.\nDo not use when: you only have a title or want to move many notes (batch-move-notes).\nNote: Notes.app's native move preserves the note id, creation date, body, and attachments. The destination folder must already exist and cannot be a smart folder (refused with code unsupported before the move). Optional ifFolderId, ifAncestorFolderId, and forbiddenAncestorFolderIds (which also covers the destination) are re-checked inside the move AppleScript.",
     inputSchema: {
       id: noteIdInput,
       folder: external_exports.string().min(1, "Destination folder is required").max(MAX.FOLDER),
@@ -58341,7 +58580,7 @@ ${lines.join("\n")}${fullyDecoded ? "" : '\n\nSome rules were not recognized; se
 registerTool(
   "create-folder",
   {
-    description: "Use when: creating a folder, including nested paths like 'Work/Clients' (intermediate folders are created, existing ones skipped).\nReturns: confirmation.\nDo not use when: creating a note (create-note).",
+    description: "Use when: creating a folder, including nested paths like 'Work/Clients' (intermediate folders are created, existing ones skipped).\nReturns: confirmation.\nNote: a path segment that names a smart folder is refused (code unsupported) before anything is created; smart folders cannot hold folders.\nDo not use when: creating a note (create-note).",
     inputSchema: {
       name: external_exports.string().min(1, "Folder name is required").max(MAX.FOLDER).describe(
         'Folder name or nested path separated by "/". E.g., "Retro Tech/PC/CPUs" creates all intermediate folders. Existing segments are skipped.'
@@ -58782,7 +59021,7 @@ registerTool(
 registerTool(
   "batch-move-notes",
   {
-    description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts after destination-folder verification.\nDo not use when: moving a single note (move-note).\nSafety: each moved note's actual container ID is compared with the destination folder ID before success is reported. The destination folder must already exist (create-folder).",
+    description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts after destination-folder verification.\nDo not use when: moving a single note (move-note).\nSafety: each moved note's actual container ID is compared with the destination folder ID before success is reported. The destination folder must already exist (create-folder); a smart folder is refused for the whole call (code unsupported) before any note moves.",
     inputSchema: {
       ids: noteIdArrayInput.describe(
         `Array of note IDs to move (max ${MAX.BATCH_IDS} per request)`

package/package.json

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