@disco_trooper/apple-notes-mcp 1.1.0 → 1.2.0

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;
 }
 
 /**
@@ -112,21 +128,11 @@ export async function updateNote(title: string, content: string): Promise<void>
 
   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);
 
   // 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}`);
@@ -167,19 +173,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 +209,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 +263,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();
   });
 });

package/src/notes/read.ts

@@ -6,39 +6,15 @@
  */
 
 import { runJxa } from "run-jxa";
-import TurndownService from "turndown";
 import { createDebugLogger } from "../utils/debug.js";
+import { htmlToMarkdown } from "./conversion.js";
+
+// Re-export for backwards compatibility
+export { resolveNoteTitle, type ResolvedNote } from "./resolve.js";
 
 // Debug logging
 const debug = createDebugLogger("NOTES");
 
-// 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}]`;
-  },
-});
-
 // -----------------------------------------------------------------------------
 // Types
 // -----------------------------------------------------------------------------
@@ -63,21 +39,6 @@ export interface NoteDetails extends NoteInfo {
   id: string;
 }
 
-export interface ResolvedNote {
-  /** Whether resolution was successful */
-  success: boolean;
-  /** The matched note (if exactly one match) */
-  note?: {
-    title: string;
-    folder: string;
-    id: string;
-  };
-  /** Error message if resolution failed */
-  error?: string;
-  /** Suggestions when multiple matches found */
-  suggestions?: string[];
-}
-
 // -----------------------------------------------------------------------------
 // Internal JXA helpers
 // -----------------------------------------------------------------------------
@@ -97,36 +58,6 @@ async function executeJxa<T>(code: string): Promise<T> {
   }
 }
 
-/**
- * Convert HTML content to Markdown, handling Apple Notes specifics
- */
-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();
-}
-
 // -----------------------------------------------------------------------------
 // Public API
 // -----------------------------------------------------------------------------
@@ -178,7 +109,7 @@ export async function getAllNotes(): Promise<NoteInfo[]> {
 /**
  * Get a note by its title, with full content
  *
- * @param title - The note title (can be "folder/title" format for disambiguation)
+ * @param title - The note title (can be "folder/title" or "id:xxx" format)
  * @returns Note details with content, or null if not found
  */
 export async function getNoteByTitle(
@@ -186,6 +117,13 @@ export async function getNoteByTitle(
 ): Promise<NoteDetails | null> {
   debug(`Getting note by title: ${title}`);
 
+  // Check for id:xxx format for direct ID lookup
+  if (title.startsWith("id:")) {
+    const noteId = title.slice(3);
+    debug(`ID prefix detected, looking up note by ID: ${noteId}`);
+    return getNoteById(noteId);
+  }
+
   // Check for folder/title format
   let targetFolder: string | null = null;
   let targetTitle = title;
@@ -281,6 +219,84 @@ export async function getNoteByTitle(
   };
 }
 
+/**
+ * Get a note by its Apple Notes ID.
+ * Use this for precise access when title-based lookup is ambiguous.
+ *
+ * @param id - The Apple Notes unique identifier
+ * @returns Note details with content, or null if not found
+ */
+export async function getNoteById(id: string): Promise<NoteDetails | null> {
+  debug(`Getting note by ID: ${id}`);
+
+  const escapedId = JSON.stringify(id);
+
+  const jxaCode = `
+    const app = Application('Notes');
+    app.includeStandardAdditions = true;
+
+    const targetId = ${escapedId};
+
+    try {
+      const note = app.notes.byId(targetId);
+      const props = note.properties();
+
+      // Find the folder this note belongs to
+      let folderName = 'Notes';
+      const folders = app.folders();
+      for (const folder of folders) {
+        const notes = folder.notes();
+        for (let i = 0; i < notes.length; i++) {
+          if (notes[i].id() === targetId) {
+            folderName = folder.name();
+            break;
+          }
+        }
+      }
+
+      return JSON.stringify({
+        id: note.id(),
+        title: props.name || '',
+        folder: folderName,
+        created: props.creationDate ? props.creationDate.toISOString() : '',
+        modified: props.modificationDate ? props.modificationDate.toISOString() : '',
+        htmlContent: note.body()
+      });
+    } catch (e) {
+      return JSON.stringify(null);
+    }
+  `;
+
+  const result = await executeJxa<string>(jxaCode);
+  const note = JSON.parse(result) as {
+    id: string;
+    title: string;
+    folder: string;
+    created: string;
+    modified: string;
+    htmlContent: string;
+  } | null;
+
+  if (!note) {
+    debug("Note not found by ID");
+    return null;
+  }
+
+  const content = htmlToMarkdown(note.htmlContent);
+
+  debug(`Found note: ${note.title} in folder: ${note.folder}`);
+
+  return {
+    id: note.id,
+    title: note.title,
+    folder: note.folder,
+    created: note.created,
+    modified: note.modified,
+    content,
+    htmlContent: note.htmlContent,
+  };
+}
+
 /**
  * Get a note by explicit folder and title (no "/" parsing).
  * Use this when you have folder and title separately to avoid
@@ -403,102 +419,3 @@ export async function getAllFolders(): Promise<string[]> {
   debug(`Found ${folders.length} folders`);
   return folders;
 }
-
-/**
- * Resolve a note title input to a unique note
- *
- * Handles:
- * - Exact title match
- * - "folder/title" format for disambiguation
- * - Returns suggestions when multiple matches exist
- *
- * @param input - The note title or "folder/title" string
- * @returns Resolution result with success status, note info, or suggestions
- */
-export async function resolveNoteTitle(input: string): Promise<ResolvedNote> {
-  debug(`Resolving note title: ${input}`);
-
-  // Check for folder/title format
-  let targetFolder: string | null = null;
-  let targetTitle = input;
-
-  if (input.includes("/")) {
-    const parts = input.split("/");
-    targetFolder = parts.slice(0, -1).join("/");
-    targetTitle = parts[parts.length - 1];
-    debug(`Parsed folder: ${targetFolder}, title: ${targetTitle}`);
-  }
-
-  const escapedTitle = JSON.stringify(targetTitle);
-  const escapedFolder = targetFolder ? JSON.stringify(targetFolder) : "null";
-
-  const jxaCode = `
-    const app = Application('Notes');
-    app.includeStandardAdditions = true;
-
-    const targetTitle = ${escapedTitle};
-    const targetFolder = ${escapedFolder};
-
-    let foundNotes = [];
-    const folders = app.folders();
-
-    for (const folder of folders) {
-      const folderName = folder.name();
-
-      // Skip if folder filter is specified and doesn't match
-      if (targetFolder !== null && folderName !== targetFolder) {
-        continue;
-      }
-
-      const notes = folder.notes.whose({ name: targetTitle });
-
-      for (let i = 0; i < notes.length; i++) {
-        try {
-          const note = notes[i];
-          foundNotes.push({
-            id: note.id(),
-            title: note.name(),
-            folder: folderName
-          });
-        } catch (e) {
-          // Skip notes that can't be accessed
-        }
-      }
-    }
-
-    return JSON.stringify(foundNotes);
-  `;
-
-  const result = await executeJxa<string>(jxaCode);
-  const notes = JSON.parse(result) as Array<{
-    id: string;
-    title: string;
-    folder: string;
-  }>;
-
-  if (notes.length === 0) {
-    debug("No matching notes found");
-    return {
-      success: false,
-      error: `Note not found: "${input}"`,
-    };
-  }
-
-  if (notes.length === 1) {
-    debug(`Resolved to unique note: ${notes[0].folder}/${notes[0].title}`);
-    return {
-      success: true,
-      note: notes[0],
-    };
-  }
-
-  // Multiple matches - return suggestions
-  const suggestions = notes.map((n) => `${n.folder}/${n.title}`);
-  debug(`Multiple matches found: ${suggestions.join(", ")}`);
-
-  return {
-    success: false,
-    error: `Multiple notes found with title "${targetTitle}". Please specify the folder.`,
-    suggestions,
-  };
-}

package/src/notes/resolve.ts

@@ -0,0 +1,174 @@
+/**
+ * Note title resolution and disambiguation.
+ *
+ * Handles resolving user input (title, folder/title, id:xxx) to a specific note.
+ */
+
+import { runJxa } from "run-jxa";
+import { createDebugLogger } from "../utils/debug.js";
+import type { NoteSuggestion } from "../errors/index.js";
+import { getNoteById } from "./read.js";
+
+const debug = createDebugLogger("NOTES");
+
+/**
+ * Result of resolving a note title to a specific note.
+ */
+export interface ResolvedNote {
+  /** Whether resolution was successful */
+  success: boolean;
+  /** The matched note (if exactly one match) */
+  note?: {
+    title: string;
+    folder: string;
+    id: string;
+  };
+  /** Error message if resolution failed */
+  error?: string;
+  /** Rich suggestions when multiple matches found (includes ID and created date) */
+  suggestions?: NoteSuggestion[];
+}
+
+/**
+ * Execute JXA code safely with error handling.
+ */
+async function executeJxa<T>(code: string): Promise<T> {
+  try {
+    const result = await runJxa(code);
+    return result as T;
+  } catch (error) {
+    debug("JXA execution error:", error);
+    throw new Error(
+      `JXA execution failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Resolve a note title input to a unique note.
+ *
+ * Handles:
+ * - "id:xxx" format for direct ID lookup
+ * - Exact title match
+ * - "folder/title" format for disambiguation
+ * - Returns suggestions when multiple matches exist
+ *
+ * @param input - The note title, "folder/title", or "id:xxx" string
+ * @returns Resolution result with success status, note info, or suggestions
+ */
+export async function resolveNoteTitle(input: string): Promise<ResolvedNote> {
+  debug(`Resolving note title: ${input}`);
+
+  // Check for id:xxx format for direct ID lookup
+  if (input.startsWith("id:")) {
+    const noteId = input.slice(3);
+    debug(`ID prefix detected, looking up note by ID: ${noteId}`);
+    const noteDetails = await getNoteById(noteId);
+    if (!noteDetails) {
+      return {
+        success: false,
+        error: `Note not found with ID: "${noteId}"`,
+      };
+    }
+    return {
+      success: true,
+      note: {
+        id: noteDetails.id,
+        title: noteDetails.title,
+        folder: noteDetails.folder,
+      },
+    };
+  }
+
+  // Check for folder/title format
+  let targetFolder: string | null = null;
+  let targetTitle = input;
+
+  if (input.includes("/")) {
+    const parts = input.split("/");
+    targetFolder = parts.slice(0, -1).join("/");
+    targetTitle = parts[parts.length - 1];
+    debug(`Parsed folder: ${targetFolder}, title: ${targetTitle}`);
+  }
+
+  const escapedTitle = JSON.stringify(targetTitle);
+  const escapedFolder = targetFolder ? JSON.stringify(targetFolder) : "null";
+
+  const jxaCode = `
+    const app = Application('Notes');
+    app.includeStandardAdditions = true;
+
+    const targetTitle = ${escapedTitle};
+    const targetFolder = ${escapedFolder};
+
+    let foundNotes = [];
+    const folders = app.folders();
+
+    for (const folder of folders) {
+      const folderName = folder.name();
+
+      // Skip if folder filter is specified and doesn't match
+      if (targetFolder !== null && folderName !== targetFolder) {
+        continue;
+      }
+
+      const notes = folder.notes.whose({ name: targetTitle });
+
+      for (let i = 0; i < notes.length; i++) {
+        try {
+          const note = notes[i];
+          const props = note.properties();
+          foundNotes.push({
+            id: note.id(),
+            title: note.name(),
+            folder: folderName,
+            created: props.creationDate ? props.creationDate.toISOString() : ''
+          });
+        } catch (e) {
+          // Skip notes that can't be accessed
+        }
+      }
+    }
+
+    return JSON.stringify(foundNotes);
+  `;
+
+  const result = await executeJxa<string>(jxaCode);
+  const notes = JSON.parse(result) as Array<{
+    id: string;
+    title: string;
+    folder: string;
+    created: string;
+  }>;
+
+  if (notes.length === 0) {
+    debug("No matching notes found");
+    return {
+      success: false,
+      error: `Note not found: "${input}"`,
+    };
+  }
+
+  if (notes.length === 1) {
+    debug(`Resolved to unique note: ${notes[0].folder}/${notes[0].title}`);
+    return {
+      success: true,
+      note: notes[0],
+    };
+  }
+
+  // Multiple matches - return rich suggestions with ID and created date
+  const suggestions: NoteSuggestion[] = notes.map((n) => ({
+    id: n.id,
+    folder: n.folder,
+    title: n.title,
+    created: n.created,
+  }));
+  debug(`Multiple matches found: ${suggestions.map(s => `${s.folder}/${s.title}`).join(", ")}`);
+
+  return {
+    success: false,
+    error: `Multiple notes found with title "${targetTitle}". Use ID prefix to specify.`,
+    suggestions,
+  };
+}