@disco_trooper/apple-notes-mcp 1.1.0 → 1.3.0

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,25 +39,20 @@ 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
+// Internal types and helpers
 // -----------------------------------------------------------------------------
 
+/** Raw note data from JXA before markdown conversion */
+interface RawNoteData {
+  id: string;
+  title: string;
+  folder: string;
+  created: string;
+  modified: string;
+  htmlContent: string;
+}
+
 /**
  * Execute JXA code safely with error handling
  */
@@ -98,33 +69,18 @@ async function executeJxa<T>(code: string): Promise<T> {
 }
 
 /**
- * Convert HTML content to Markdown, handling Apple Notes specifics
+ * Convert raw JXA note data to NoteDetails with markdown content
  */
-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();
+function toNoteDetails(raw: RawNoteData): NoteDetails {
+  return {
+    id: raw.id,
+    title: raw.title,
+    folder: raw.folder,
+    created: raw.created,
+    modified: raw.modified,
+    content: htmlToMarkdown(raw.htmlContent),
+    htmlContent: raw.htmlContent,
+  };
 }
 
 // -----------------------------------------------------------------------------
@@ -178,7 +134,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 +142,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;
@@ -242,14 +205,7 @@ export async function getNoteByTitle(
   `;
 
   const result = await executeJxa<string>(jxaCode);
-  const notes = JSON.parse(result) as Array<{
-    id: string;
-    title: string;
-    folder: string;
-    created: string;
-    modified: string;
-    htmlContent: string;
-  }>;
+  const notes = JSON.parse(result) as RawNoteData[];
 
   if (notes.length === 0) {
     debug("Note not found");
@@ -258,27 +214,71 @@ export async function getNoteByTitle(
 
   if (notes.length > 1) {
     debug(`Multiple notes found with title: ${targetTitle}`);
-    // If folder wasn't specified and multiple exist, return the first one
-    // but log a warning
-    debug(
-      "Returning first match. Use folder/title format for disambiguation."
-    );
+    debug("Returning first match. Use folder/title format for disambiguation.");
   }
 
-  const note = notes[0];
-  const content = htmlToMarkdown(note.htmlContent);
+  debug(`Found note in folder: ${notes[0].folder}`);
+  return toNoteDetails(notes[0]);
+}
 
-  debug(`Found note in folder: ${note.folder}`);
+/**
+ * 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}`);
 
-  return {
-    id: note.id,
-    title: note.title,
-    folder: note.folder,
-    created: note.created,
-    modified: note.modified,
-    content,
-    htmlContent: note.htmlContent,
-  };
+  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 RawNoteData | null;
+
+  if (!note) {
+    debug("Note not found by ID");
+    return null;
+  }
+
+  debug(`Found note: ${note.title} in folder: ${note.folder}`);
+  return toNoteDetails(note);
 }
 
 /**
@@ -341,164 +341,96 @@ export async function getNoteByFolderAndTitle(
   `;
 
   const result = await executeJxa<string>(jxaCode);
-  const notes = JSON.parse(result) as Array<{
-    id: string;
-    title: string;
-    folder: string;
-    created: string;
-    modified: string;
-    htmlContent: string;
-  }>;
+  const notes = JSON.parse(result) as RawNoteData[];
 
   if (notes.length === 0) {
     debug("Note not found");
     return null;
   }
 
-  const note = notes[0];
-  const content = htmlToMarkdown(note.htmlContent);
-
-  debug(`Found note in folder: ${note.folder}`);
-
-  return {
-    id: note.id,
-    title: note.title,
-    folder: note.folder,
-    created: note.created,
-    modified: note.modified,
-    content,
-    htmlContent: note.htmlContent,
-  };
+  debug(`Found note in folder: ${notes[0].folder}`);
+  return toNoteDetails(notes[0]);
 }
 
 /**
- * Get all folder names from Apple Notes
+ * Get all notes with full content in a single JXA call.
+ * This is much faster than calling getNoteByFolderAndTitle for each note
+ * because it avoids the JXA process spawn overhead per note.
  *
- * @returns Array of folder names
+ * @returns Array of note details with content
  */
-export async function getAllFolders(): Promise<string[]> {
-  debug("Getting all folders...");
+export async function getAllNotesWithContent(): Promise<NoteDetails[]> {
+  debug("Getting all notes with content (single JXA call)...");
 
   const jxaCode = `
     const app = Application('Notes');
     app.includeStandardAdditions = true;
 
+    const allNotes = [];
     const folders = app.folders();
-    const folderNames = [];
 
     for (const folder of folders) {
-      try {
-        folderNames.push(folder.name());
-      } catch (e) {
-        // Skip folders that can't be accessed
+      const folderName = folder.name();
+      const notes = folder.notes();
+
+      for (let i = 0; i < notes.length; i++) {
+        try {
+          const note = notes[i];
+          const props = note.properties();
+          allNotes.push({
+            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) {
+          // Skip notes that can't be accessed
+        }
       }
     }
 
-    return JSON.stringify(folderNames);
+    return JSON.stringify(allNotes);
   `;
 
   const result = await executeJxa<string>(jxaCode);
-  const folders = JSON.parse(result) as string[];
+  const notes = JSON.parse(result) as RawNoteData[];
 
-  debug(`Found ${folders.length} folders`);
-  return folders;
+  debug(`Fetched ${notes.length} notes with content`);
+
+  return notes.map(toNoteDetails);
 }
 
 /**
- * Resolve a note title input to a unique note
- *
- * Handles:
- * - Exact title match
- * - "folder/title" format for disambiguation
- * - Returns suggestions when multiple matches exist
+ * Get all folder names from Apple Notes
  *
- * @param input - The note title or "folder/title" string
- * @returns Resolution result with success status, note info, or suggestions
+ * @returns Array of folder names
  */
-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";
+export async function getAllFolders(): Promise<string[]> {
+  debug("Getting all folders...");
 
   const jxaCode = `
     const app = Application('Notes');
     app.includeStandardAdditions = true;
 
-    const targetTitle = ${escapedTitle};
-    const targetFolder = ${escapedFolder};
-
-    let foundNotes = [];
     const folders = app.folders();
+    const folderNames = [];
 
     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
-        }
+      try {
+        folderNames.push(folder.name());
+      } catch (e) {
+        // Skip folders that can't be accessed
       }
     }
 
-    return JSON.stringify(foundNotes);
+    return JSON.stringify(folderNames);
   `;
 
   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(", ")}`);
+  const folders = JSON.parse(result) as string[];
 
-  return {
-    success: false,
-    error: `Multiple notes found with title "${targetTitle}". Please specify the folder.`,
-    suggestions,
-  };
+  debug(`Found ${folders.length} folders`);
+  return folders;
 }

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,
+  };
+}