apple-notes-mcp 2.9.28 → 2.9.31

package/README.md

@@ -198,6 +198,24 @@ The server is a standard MCP server over stdio, so any client that can launch a
 
 Read/list/get tools also return **structured JSON** (`structuredContent`) alongside the text, so agents can consume results without parsing prose.
 
+Some clients (Claude Desktop among them) pass the model only a result's text
+and drop `structuredContent`. So every result that has `structuredContent` also
+ends with one more text block holding the same data as a single JSON line:
+
+```
+structuredContent: {"id":"x-coredata://…/ICNote/p123","contentHash":"sha256:…","writable":true,…}
+```
+
+That line carries every token a follow-up call needs: the `contentHash`
+revision token for `expectedContentHash`, new ids, `nativeTags`, `writable`,
+`page.nextOffset`, and an error's `code`, `committed` and `indeterminate`. A
+long value the text above already shows in full, such as the body from
+`get-note-content`, appears as `"[shown in full above]"` instead of twice. If
+the line would still exceed 16 KB, fields larger than 1 KB (usually a list
+already printed above) are left out and named in `_omitted`. Tools whose text
+already is that JSON get no extra block. `structuredContent` itself is
+unchanged.
+
 ### MCP resources & prompts
 
 Resources expose read-only context the client can attach without a tool call:
@@ -238,7 +256,9 @@ When Full Disk Access is granted, list and read tools also return stable identif
 ### Error results
 
 A failed call returns `isError: true` with the same human-readable text as
-before, plus `structuredContent` carrying a stable machine-readable `code`.
+before, plus `structuredContent` carrying a stable machine-readable `code`
+(also repeated in the trailing `structuredContent:` text line, for clients
+that drop `structuredContent`).
 Branch on `code`, not on the prose, which may be reworded.
 
 | `code` | Meaning |
@@ -2409,7 +2429,7 @@ listed under the tool itself:
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Exact note ID: x-coredata id, Notes UUID, or numeric key (see [Identifier forms](#identifier-forms)) |
 | `expectedContentHash` | string | Yes | `contentHash` (`sha256:…`) from a fresh read of the note |
-| `scopeText` | string | Yes | Distinctive phrase already in the note, 12–500 characters, that Notes search can find. Prefer plain words without punctuation, hashtags, or paths |
+| `scopeText` | string | Yes | Distinctive phrase already in the note below its title line, 12–500 characters, that Notes search can find. Prefer plain words without punctuation, hashtags, or paths |
 
 When the Shortcut refuses a request (its Find Notes step did not return
 exactly one note with that exact title and `scopeText`) or stops with its own

package/build/index.js

@@ -48723,6 +48723,12 @@ function describeTransportFailure(error2) {
   if (detail?.refused) return `${named} ${detail.message}`;
   return detail?.code === "ETIMEDOUT" ? `Shortcuts timed out waiting for ${named}. ${shortcutConsentHint(detail.shortcut)}` : `${named} failed: ${String(detail?.stderr || detail?.message || "no output").trim().slice(0, 400)}`;
 }
+function textBelowTitle(text2, title) {
+  const lineEnd = text2.indexOf("\n");
+  const firstLine = lineEnd < 0 ? text2 : text2.slice(0, lineEnd);
+  if (firstLine.trim() !== title.trim()) return text2;
+  return lineEnd < 0 ? "" : text2.slice(lineEnd + 1);
+}
 function mutateBackground(request, operation, data, verify, deps) {
   if (request.scopeText.length < 12 || request.scopeText.length > 500 || /[\r\n\0]/u.test(request.scopeText))
     throw new Error("Use a distinctive existing single-line scope of 12\u2013500 characters");
@@ -48731,6 +48737,11 @@ function mutateBackground(request, operation, data, verify, deps) {
     throw new Error("Note revision changed; read it again");
   if (!before.rich.text.includes(request.scopeText))
     throw new Error("Scope is absent from exact note");
+  if (!textBelowTitle(before.rich.text, before.title).includes(request.scopeText))
+    throw new CodedError(
+      "scopeText appears only in the note's title line. The bridge's Find Notes step matches it against the body below the title, so it would refuse; pass a phrase from below the title. Nothing changed",
+      { code: "validation_error", committed: false, indeterminate: false }
+    );
   const candidates = deps.candidates(before.title, request.scopeText);
   if (candidates.length !== 1 || candidates[0] !== request.id)
     throw new Error("Ambiguous note selection; nothing changed");
@@ -53475,6 +53486,85 @@ function exportWithTemplate(request, deps, chosen, notes, skipped, { output, ass
   return { ...receipt, markdown };
 }
 
+// src/utils/structuredText.ts
+import { isDeepStrictEqual } from "node:util";
+var STRUCTURED_TEXT_PREFIX = "structuredContent: ";
+var SHOWN_ABOVE = "[shown in full above]";
+var MIN_ELIDED_CHARS = 64;
+var MAX_MIRROR_CHARS = 16384;
+var MAX_FIELD_CHARS = 1024;
+function textOf(content) {
+  return content.map(
+    (item) => item && typeof item === "object" && item.type === "text" ? String(item.text ?? "") : ""
+  ).join("\n");
+}
+function elide(value, text2) {
+  if (typeof value === "string") {
+    return value.length >= MIN_ELIDED_CHARS && text2.includes(value) ? SHOWN_ABOVE : value;
+  }
+  if (Array.isArray(value)) return value.map((item) => elide(item, text2));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== void 0) out[key] = elide(item, text2);
+    }
+    return out;
+  }
+  return value;
+}
+function textIsTheJson(content, structured) {
+  const plain = JSON.parse(JSON.stringify(structured));
+  return content.some((item) => {
+    const text2 = item?.text;
+    if (item?.type !== "text" || typeof text2 !== "string") return false;
+    const trimmed = text2.trim();
+    if (!trimmed.startsWith("{")) return false;
+    try {
+      return isDeepStrictEqual(JSON.parse(trimmed), plain);
+    } catch {
+      return false;
+    }
+  });
+}
+function structuredTextLine(structured, text2) {
+  const elided = elide(structured, text2);
+  let json2 = JSON.stringify(elided);
+  if (json2.length > MAX_MIRROR_CHARS) {
+    const kept = {};
+    const omitted = [];
+    for (const [key, value] of Object.entries(elided)) {
+      if (JSON.stringify(value).length > MAX_FIELD_CHARS) omitted.push(key);
+      else kept[key] = value;
+    }
+    json2 = JSON.stringify({ ...kept, _omitted: omitted });
+  }
+  return STRUCTURED_TEXT_PREFIX + json2;
+}
+function withStructuredText(result) {
+  const r = result;
+  if (!r || typeof r !== "object") return result;
+  const structured = r.structuredContent;
+  if (!structured || typeof structured !== "object" || Array.isArray(structured)) return result;
+  const content = Array.isArray(r.content) ? r.content : [];
+  if (textIsTheJson(content, structured)) return result;
+  const line = structuredTextLine(structured, textOf(content));
+  return { ...r, content: [...content, { type: "text", text: line }] };
+}
+function installStructuredText(server2) {
+  const target = server2;
+  const register = target.registerTool;
+  if (typeof register === "function") {
+    target.registerTool = function(name, config2, cb) {
+      const wrapped = typeof cb === "function" ? async (...args) => withStructuredText(await cb(...args)) : cb;
+      return register.call(this, name, config2, wrapped);
+    };
+  }
+  const createError = target.createToolError;
+  if (typeof createError === "function") {
+    target.createToolError = (message) => withStructuredText(createError.call(target, message));
+  }
+}
+
 // src/tools/directOperations.ts
 import { createHash as createHash3 } from "node:crypto";
 import {
@@ -57108,7 +57198,7 @@ var common = {
   id,
   expectedContentHash: revision3,
   scopeText: external_exports.string().min(12).max(500).describe(
-    "Distinctive existing phrase used by Notes search. Prefer plain words without punctuation, hashtags, or paths."
+    "Distinctive existing phrase from below the title line, used by Notes search. Prefer plain words without punctuation, hashtags, or paths."
   )
 };
 var EMPTY_TABLE_ROWS = [
@@ -59292,6 +59382,7 @@ var server = new McpServer({
   description: "MCP server for managing Apple Notes - create, search, update, and organize notes"
 });
 installSdkErrorCodes(server);
+installStructuredText(server);
 var notesManager = new AppleNotesManager();
 registerDirectOperations(server, notesManager);
 registerFolderDelete(server, notesManager);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.9.28",
+  "version": "2.9.31",
   "description": "MCP server for Apple Notes - read, search, create, edit, organize, and export notes on macOS via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",