@disco_trooper/apple-notes-mcp 1.1.0 → 1.3.0

package/src/notes/conversion.ts

@@ -0,0 +1,62 @@
+/**
+ * HTML to Markdown conversion for Apple Notes content.
+ */
+
+import TurndownService from "turndown";
+
+// Initialize Turndown for HTML to Markdown conversion
+const turndownService = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  bulletListMarker: "-",
+});
+
+// Add custom rule to handle Apple Notes attachment placeholders
+turndownService.addRule("attachments", {
+  filter: (node) => {
+    // Apple Notes uses object tags for attachments
+    return node.nodeName === "OBJECT" || node.nodeName === "IMG";
+  },
+  replacement: (_content, node) => {
+    // Turndown uses its own Node type, cast to access attributes
+    const element = node as unknown as {
+      getAttribute: (name: string) => string | null;
+    };
+    const filename =
+      element.getAttribute("data-filename") ||
+      element.getAttribute("alt") ||
+      element.getAttribute("src")?.split("/").pop() ||
+      "unknown";
+    return `[Attachment: ${filename}]`;
+  },
+});
+
+/**
+ * Convert HTML content to Markdown, handling Apple Notes specifics.
+ */
+export function htmlToMarkdown(html: string): string {
+  if (!html) return "";
+
+  // Pre-process: handle Apple Notes specific markup
+  let processed = html;
+
+  // Replace attachment objects with placeholder text before Turndown
+  processed = processed.replace(
+    /<object[^>]*data-filename="([^"]*)"[^>]*>.*?<\/object>/gi,
+    "[Attachment: $1]"
+  );
+
+  // Handle inline images
+  processed = processed.replace(
+    /<img[^>]*(?:alt="([^"]*)")?[^>]*>/gi,
+    (_match, alt) => {
+      const filename = alt || "image";
+      return `[Attachment: ${filename}]`;
+    }
+  );
+
+  // Convert to Markdown
+  const markdown = turndownService.turndown(processed);
+
+  return markdown.trim();
+}

package/src/notes/crud.test.ts

@@ -111,18 +111,45 @@ describe("updateNote", () => {
       success: true,
       note: { id: "123", title: "Test", folder: "Work" },
     });
-    vi.mocked(runJxa).mockResolvedValueOnce("ok");
+    // Mock JXA returning the new title (same as original in this case)
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify({ newTitle: "Test" }));
+
+    const result = await updateNote("Test", "New Content");
+    expect(result).toEqual({
+      originalTitle: "Test",
+      newTitle: "Test",
+      folder: "Work",
+      titleChanged: false,
+    });
+  });
 
-    await expect(updateNote("Test", "New Content")).resolves.toBeUndefined();
+  it("should detect when Apple Notes renames the note", async () => {
+    vi.mocked(resolveNoteTitle).mockResolvedValueOnce({
+      success: true,
+      note: { id: "123", title: "Original Title", folder: "Work" },
+    });
+    // Mock JXA returning a different title (Apple Notes renamed it)
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify({ newTitle: "New Heading" }));
+
+    const result = await updateNote("Original Title", "# New Heading\n\nContent");
+    expect(result).toEqual({
+      originalTitle: "Original Title",
+      newTitle: "New Heading",
+      folder: "Work",
+      titleChanged: true,
+    });
   });
 
   it("should include suggestions in error when multiple notes found", async () => {
     vi.mocked(resolveNoteTitle).mockResolvedValueOnce({
       success: false,
       error: "Multiple notes found",
-      suggestions: ["Work/Note", "Personal/Note"],
+      suggestions: [
+        { id: "id-1", folder: "Work", title: "Note", created: "2026-01-09T10:00:00.000Z" },
+        { id: "id-2", folder: "Personal", title: "Note", created: "2026-01-09T11:00:00.000Z" },
+      ],
     });
-    await expect(updateNote("Note", "Content")).rejects.toThrow("Suggestions: Work/Note, Personal/Note");
+    await expect(updateNote("Note", "Content")).rejects.toThrow("Use ID prefix");
   });
 });
 
@@ -159,9 +186,12 @@ describe("deleteNote", () => {
     vi.mocked(resolveNoteTitle).mockResolvedValueOnce({
       success: false,
       error: "Multiple notes found",
-      suggestions: ["Work/Note", "Personal/Note"],
+      suggestions: [
+        { id: "id-1", folder: "Work", title: "Note", created: "2026-01-09T10:00:00.000Z" },
+        { id: "id-2", folder: "Personal", title: "Note", created: "2026-01-09T11:00:00.000Z" },
+      ],
     });
-    await expect(deleteNote("Note")).rejects.toThrow("Suggestions: Work/Note, Personal/Note");
+    await expect(deleteNote("Note")).rejects.toThrow("Use ID prefix");
   });
 });
 
@@ -198,9 +228,12 @@ describe("moveNote", () => {
     vi.mocked(resolveNoteTitle).mockResolvedValueOnce({
       success: false,
       error: "Multiple notes found",
-      suggestions: ["Work/Note", "Personal/Note"],
+      suggestions: [
+        { id: "id-1", folder: "Work", title: "Note", created: "2026-01-09T10:00:00.000Z" },
+        { id: "id-2", folder: "Personal", title: "Note", created: "2026-01-09T11:00:00.000Z" },
+      ],
     });
-    await expect(moveNote("Note", "Archive")).rejects.toThrow("Suggestions: Work/Note, Personal/Note");
+    await expect(moveNote("Note", "Archive")).rejects.toThrow("Use ID prefix");
   });
 });
 

package/src/notes/crud.ts

@@ -10,6 +10,7 @@ import { marked } from "marked";
 import { resolveNoteTitle } from "./read.js";
 import { createDebugLogger } from "../utils/debug.js";
 import { findTables, updateTableCell } from "./tables.js";
+import { ReadOnlyModeError, NoteNotFoundError, DuplicateNoteError } from "../errors/index.js";
 
 // Debug logging
 const debug = createDebugLogger("CRUD");
@@ -22,25 +23,40 @@ const debug = createDebugLogger("CRUD");
  */
 export function checkReadOnly(): void {
   if (process.env.READONLY_MODE === "true") {
-    throw new Error("Operation disabled in read-only mode");
+    throw new ReadOnlyModeError();
   }
 }
 
 /**
- * Convert Markdown content to HTML for Apple Notes.
+ * Resolve note title and throw if not found.
+ * Consolidates the repeated error handling pattern.
  *
- * @param markdown - Markdown content
- * @returns HTML string
+ * @param title - Note title (supports folder prefix)
+ * @returns The resolved note with id, title, and folder
+ * @throws Error if note not found or duplicates exist without folder prefix
+ */
+async function resolveNoteOrThrow(title: string): Promise<{ id: string; title: string; folder: string }> {
+  const resolved = await resolveNoteTitle(title);
+
+  if (!resolved.success || !resolved.note) {
+    if (resolved.suggestions && resolved.suggestions.length > 0) {
+      throw new DuplicateNoteError(title, resolved.suggestions);
+    }
+    throw new NoteNotFoundError(title);
+  }
+
+  return resolved.note;
+}
+
+/**
+ * Convert Markdown content to HTML for Apple Notes.
  */
 function markdownToHtml(markdown: string): string {
-  // Configure marked for clean HTML output
-  const html = marked.parse(markdown, {
+  return marked.parse(markdown, {
     async: false,
     gfm: true,
     breaks: true,
   }) as string;
-
-  return html;
 }
 
 /**
@@ -99,39 +115,52 @@ export async function createNote(
   debug(`Note created: "${title}"`);
 }
 
+/**
+ * Result of an update operation.
+ * Apple Notes may rename the note based on content (first h1 heading).
+ */
+export interface UpdateResult {
+  /** Original title before update */
+  originalTitle: string;
+  /** Current title after update (may differ if Apple Notes renamed it) */
+  newTitle: string;
+  /** Folder containing the note */
+  folder: string;
+  /** Whether the title changed */
+  titleChanged: boolean;
+}
+
 /**
  * Update an existing note's content.
  *
+ * Note: Apple Notes may automatically rename the note based on the first
+ * heading in the content. The returned UpdateResult contains the actual
+ * title after the update.
+ *
  * @param title - Note title (supports folder prefix: "Work/My Note")
  * @param content - New content (Markdown)
+ * @returns UpdateResult with original and new title
  * @throws Error if READONLY_MODE is enabled
  * @throws Error if note not found or duplicate titles without folder prefix
  */
-export async function updateNote(title: string, content: string): Promise<void> {
+export async function updateNote(title: string, content: string): Promise<UpdateResult> {
   checkReadOnly();
 
   debug(`Updating note: "${title}"`);
 
-  // Resolve the note to get its ID
-  const resolved = await resolveNoteTitle(title);
-
-  if (!resolved.success || !resolved.note) {
-    if (resolved.suggestions && resolved.suggestions.length > 0) {
-      throw new Error(
-        `${resolved.error} Suggestions: ${resolved.suggestions.join(", ")}`
-      );
-    }
-    throw new Error(resolved.error || `Note not found: "${title}"`);
-  }
+  const note = await resolveNoteOrThrow(title);
+  const originalTitle = note.title;
+  const folder = note.folder;
 
   // Convert Markdown to HTML
   const htmlContent = markdownToHtml(content);
-  const escapedNoteId = JSON.stringify(resolved.note.id);
+  const escapedNoteId = JSON.stringify(note.id);
   const escapedContent = JSON.stringify(htmlContent);
 
   debug(`HTML content length: ${htmlContent.length}`);
 
-  await runJxa(`
+  // Update the note and get its new title (Apple Notes may rename it)
+  const result = await runJxa(`
     const app = Application('Notes');
     const noteId = ${escapedNoteId};
     const content = ${escapedContent};
@@ -146,10 +175,25 @@ export async function updateNote(title: string, content: string): Promise<void>
     // Update the body
     note.body = content;
 
-    return "ok";
-  `);
+    // Return the current title (may have changed)
+    return JSON.stringify({ newTitle: note.name() });
+  `) as string;
+
+  const { newTitle } = JSON.parse(result);
+  const titleChanged = newTitle !== originalTitle;
 
-  debug(`Note updated: "${title}"`);
+  if (titleChanged) {
+    debug(`Note renamed by Apple Notes: "${originalTitle}" -> "${newTitle}"`);
+  } else {
+    debug(`Note updated: "${title}"`);
+  }
+
+  return {
+    originalTitle,
+    newTitle,
+    folder,
+    titleChanged,
+  };
 }
 
 /**
@@ -167,19 +211,8 @@ export async function deleteNote(title: string): Promise<void> {
 
   debug(`Deleting note: "${title}"`);
 
-  // Resolve the note to get its ID
-  const resolved = await resolveNoteTitle(title);
-
-  if (!resolved.success || !resolved.note) {
-    if (resolved.suggestions && resolved.suggestions.length > 0) {
-      throw new Error(
-        `${resolved.error} Suggestions: ${resolved.suggestions.join(", ")}`
-      );
-    }
-    throw new Error(resolved.error || `Note not found: "${title}"`);
-  }
-
-  const escapedNoteId = JSON.stringify(resolved.note.id);
+  const note = await resolveNoteOrThrow(title);
+  const escapedNoteId = JSON.stringify(note.id);
 
   await runJxa(`
     const app = Application('Notes');
@@ -214,19 +247,8 @@ export async function moveNote(title: string, folder: string): Promise<void> {
 
   debug(`Moving note: "${title}" to folder: "${folder}"`);
 
-  // Resolve the note to get its ID
-  const resolved = await resolveNoteTitle(title);
-
-  if (!resolved.success || !resolved.note) {
-    if (resolved.suggestions && resolved.suggestions.length > 0) {
-      throw new Error(
-        `${resolved.error} Suggestions: ${resolved.suggestions.join(", ")}`
-      );
-    }
-    throw new Error(resolved.error || `Note not found: "${title}"`);
-  }
-
-  const escapedNoteId = JSON.stringify(resolved.note.id);
+  const note = await resolveNoteOrThrow(title);
+  const escapedNoteId = JSON.stringify(note.id);
   const escapedFolder = JSON.stringify(folder);
 
   await runJxa(`
@@ -279,19 +301,8 @@ export async function editTable(
 
   debug(`Editing table ${tableIndex} in note: "${title}"`);
 
-  // Resolve the note
-  const resolved = await resolveNoteTitle(title);
-  if (!resolved.success || !resolved.note) {
-    if (resolved.suggestions && resolved.suggestions.length > 0) {
-      throw new Error(
-        `${resolved.error} Suggestions: ${resolved.suggestions.join(", ")}`
-      );
-    }
-    throw new Error(resolved.error || `Note not found: "${title}"`);
-  }
-
-  // Get current HTML content
-  const escapedNoteId = JSON.stringify(resolved.note.id);
+  const note = await resolveNoteOrThrow(title);
+  const escapedNoteId = JSON.stringify(note.id);
   const htmlResult = await runJxa(`
     const app = Application('Notes');
     const note = app.notes.byId(${escapedNoteId});

package/src/notes/read.test.ts

@@ -118,14 +118,69 @@ describe("resolveNoteTitle", () => {
 
   it("should return suggestions when multiple matches", async () => {
     const mockNotes = [
-      { id: "123", title: "Note", folder: "Work" },
-      { id: "456", title: "Note", folder: "Personal" },
+      { id: "123", title: "Note", folder: "Work", created: "2026-01-09T10:00:00.000Z" },
+      { id: "456", title: "Note", folder: "Personal", created: "2026-01-09T11:00:00.000Z" },
     ];
     vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
 
     const result = await resolveNoteTitle("Note");
     expect(result.success).toBe(false);
     expect(result.suggestions).toHaveLength(2);
-    expect(result.suggestions).toContain("Work/Note");
+    expect(result.suggestions?.[0].id).toBe("123");
+    expect(result.suggestions?.[0].folder).toBe("Work");
+    expect(result.suggestions?.[1].id).toBe("456");
+  });
+
+  it("should resolve note by ID prefix", async () => {
+    const mockNote = {
+      id: "x-coredata://123",
+      title: "ID Note",
+      folder: "Work",
+      created: "2026-01-09T10:00:00.000Z",
+      modified: "2026-01-09T11:00:00.000Z",
+      htmlContent: "<p>Content</p>",
+    };
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNote));
+
+    const result = await resolveNoteTitle("id:x-coredata://123");
+    expect(result.success).toBe(true);
+    expect(result.note?.id).toBe("x-coredata://123");
+  });
+
+  it("should return error for invalid ID", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce("null");
+
+    const result = await resolveNoteTitle("id:invalid-id");
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("not found");
+  });
+});
+
+describe("getNoteByTitle with ID prefix", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should route id: prefix to ID lookup", async () => {
+    const mockNote = {
+      id: "x-coredata://abc",
+      title: "My Note",
+      folder: "Work",
+      created: "2026-01-09T10:00:00.000Z",
+      modified: "2026-01-09T11:00:00.000Z",
+      htmlContent: "<p>Hello</p>",
+    };
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNote));
+
+    const note = await getNoteByTitle("id:x-coredata://abc");
+    expect(note).not.toBeNull();
+    expect(note?.id).toBe("x-coredata://abc");
+  });
+
+  it("should return null for non-existent ID", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce("null");
+
+    const note = await getNoteByTitle("id:nonexistent");
+    expect(note).toBeNull();
   });
 });