@disco_trooper/apple-notes-mcp 1.7.0 → 1.8.2

package/src/notes/crud.ts

@@ -72,7 +72,7 @@ export async function createNote(
   title: string,
   content: string,
   folder?: string
-): Promise<void> {
+): Promise<CreateResult> {
   checkReadOnly();
 
   debug(`Creating note: "${title}" in folder: "${folder || "Notes"}"`);
@@ -85,7 +85,7 @@ export async function createNote(
 
   debug(`HTML content length: ${htmlContent.length}`);
 
-  await runJxa(`
+  const result = await runJxa(`
     const app = Application('Notes');
     const title = ${escapedTitle};
     const content = ${escapedContent};
@@ -109,10 +109,36 @@ export async function createNote(
     const note = app.Note({name: title, body: content});
     targetFolder.notes.push(note);
 
-    return "ok";
-  `);
+    return JSON.stringify({
+      id: note.id(),
+      title: note.name(),
+      folder: targetFolder.name(),
+    });
+  `) as string;
+
+  const created = JSON.parse(result) as {
+    id: string;
+    title: string;
+    folder: string;
+  };
+
+  debug(`Note created: "${created.folder}/${created.title}"`);
+
+  return {
+    id: created.id,
+    title: created.title,
+    folder: created.folder,
+    requestedTitle: title,
+    titleChanged: created.title !== title,
+  };
+}
 
-  debug(`Note created: "${title}"`);
+export interface CreateResult {
+  id: string;
+  title: string;
+  folder: string;
+  requestedTitle: string;
+  titleChanged: boolean;
 }
 
 /**
@@ -120,6 +146,8 @@ export async function createNote(
  * Apple Notes may rename the note based on content (first h1 heading).
  */
 export interface UpdateResult {
+  /** Note ID */
+  id: string;
   /** Original title before update */
   originalTitle: string;
   /** Current title after update (may differ if Apple Notes renamed it) */
@@ -189,6 +217,7 @@ export async function updateNote(title: string, content: string): Promise<Update
   }
 
   return {
+    id: note.id,
     originalTitle,
     newTitle,
     folder,
@@ -206,7 +235,7 @@ export async function updateNote(title: string, content: string): Promise<Update
  * @throws Error if READONLY_MODE is enabled
  * @throws Error if note not found or duplicate titles without folder prefix
  */
-export async function deleteNote(title: string): Promise<void> {
+export async function deleteNote(title: string): Promise<DeleteResult> {
   checkReadOnly();
 
   debug(`Deleting note: "${title}"`);
@@ -232,6 +261,18 @@ export async function deleteNote(title: string): Promise<void> {
   `);
 
   debug(`Note deleted: "${title}"`);
+
+  return {
+    id: note.id,
+    title: note.title,
+    folder: note.folder,
+  };
+}
+
+export interface DeleteResult {
+  id: string;
+  title: string;
+  folder: string;
 }
 
 /**
@@ -242,7 +283,7 @@ export async function deleteNote(title: string): Promise<void> {
  * @throws Error if READONLY_MODE is enabled
  * @throws Error if note not found or target folder not found
  */
-export async function moveNote(title: string, folder: string): Promise<void> {
+export async function moveNote(title: string, folder: string): Promise<MoveResult> {
   checkReadOnly();
 
   debug(`Moving note: "${title}" to folder: "${folder}"`);
@@ -277,6 +318,20 @@ export async function moveNote(title: string, folder: string): Promise<void> {
   `);
 
   debug(`Note moved: "${title}" -> "${folder}"`);
+
+  return {
+    id: note.id,
+    title: note.title,
+    fromFolder: note.folder,
+    toFolder: folder,
+  };
+}
+
+export interface MoveResult {
+  id: string;
+  title: string;
+  fromFolder: string;
+  toFolder: string;
 }
 
 export interface TableEdit {

package/src/notes/read.test.ts

@@ -6,7 +6,7 @@ vi.mock("run-jxa", () => ({
 }));
 
 import { runJxa } from "run-jxa";
-import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle, listNotes } from "./read.js";
+import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle, listNotes, getNoteMetadataByFolder } from "./read.js";
 
 describe("getAllNotes", () => {
   beforeEach(() => {
@@ -243,8 +243,12 @@ describe("listNotes", () => {
     expect(notes[2].title).toBe("Alpha");
   });
 
-  it("should filter by folder", async () => {
-    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+  it("should filter by folder (uses getNoteMetadataByFolder)", async () => {
+    const workNotes = [
+      { title: "Alpha", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Gamma", folder: "Work", created: "2024-01-02T00:00:00Z", modified: "2024-01-15T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(workNotes));
 
     const notes = await listNotes({ folder: "Work" });
     expect(notes).toHaveLength(2);
@@ -259,7 +263,11 @@ describe("listNotes", () => {
   });
 
   it("should combine folder filter and limit", async () => {
-    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+    const workNotes = [
+      { title: "Alpha", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Gamma", folder: "Work", created: "2024-01-02T00:00:00Z", modified: "2024-01-15T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(workNotes));
 
     const notes = await listNotes({ folder: "Work", limit: 1 });
     expect(notes).toHaveLength(1);
@@ -267,7 +275,7 @@ describe("listNotes", () => {
   });
 
   it("should return empty array when folder has no notes", async () => {
-    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify([]));
 
     const notes = await listNotes({ folder: "NonExistent" });
     expect(notes).toHaveLength(0);
@@ -345,3 +353,129 @@ describe("listNotes", () => {
     expect(notes[2].title).toBe("Recent");
   });
 });
+
+describe("getNoteMetadataByFolder", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return notes from the specified folder", async () => {
+    const folderNotes = [
+      { title: "Note A", folder: "Projects", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+      { title: "Note B", folder: "Projects", created: "2024-01-03T00:00:00Z", modified: "2024-01-04T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(folderNotes));
+
+    const notes = await getNoteMetadataByFolder("Projects");
+    expect(notes).toHaveLength(2);
+    expect(notes[0].title).toBe("Note A");
+    expect(notes[1].folder).toBe("Projects");
+  });
+
+  it("should return empty array when folder has no notes", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify([]));
+
+    const notes = await getNoteMetadataByFolder("Empty");
+    expect(notes).toHaveLength(0);
+  });
+
+  it("should return metadata without content fields", async () => {
+    const folderNotes = [
+      { title: "Note", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(folderNotes));
+
+    const notes = await getNoteMetadataByFolder("Work");
+    expect(notes[0]).toHaveProperty("title");
+    expect(notes[0]).toHaveProperty("folder");
+    expect(notes[0]).toHaveProperty("created");
+    expect(notes[0]).toHaveProperty("modified");
+    expect(notes[0]).not.toHaveProperty("content");
+    expect(notes[0]).not.toHaveProperty("htmlContent");
+    expect(notes[0]).not.toHaveProperty("id");
+  });
+
+  it("should aggregate notes from duplicate folder names", async () => {
+    const duplicateFolderNotes = [
+      { title: "A1", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+      { title: "A2", folder: "Work", created: "2024-01-03T00:00:00Z", modified: "2024-01-04T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(duplicateFolderNotes));
+
+    const notes = await getNoteMetadataByFolder("Work");
+    expect(notes).toHaveLength(2);
+    expect(notes.map((n) => n.title)).toEqual(["A1", "A2"]);
+
+    const jxaCode = vi.mocked(runJxa).mock.calls[0][0] as string;
+    expect(jxaCode).not.toContain("break;");
+  });
+});
+
+describe("listNotes folder optimization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should make only one JXA call when folder is specified", async () => {
+    const folderNotes = [
+      { title: "Note 1", folder: "xx", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(folderNotes));
+
+    await listNotes({ folder: "xx" });
+    expect(runJxa).toHaveBeenCalledTimes(1);
+
+    const jxaCode = vi.mocked(runJxa).mock.calls[0][0] as string;
+    expect(jxaCode).toContain("targetFolder");
+    expect(jxaCode).toContain("toLowerCase");
+  });
+
+  it("should not fetch all notes when folder is specified", async () => {
+    const folderNotes = [
+      { title: "Only One", folder: "Tiny", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(folderNotes));
+
+    const notes = await listNotes({ folder: "Tiny" });
+    expect(notes).toHaveLength(1);
+    expect(notes[0].title).toBe("Only One");
+  });
+
+  it("should use getAllNotes when no folder is specified", async () => {
+    const allNotes = [
+      { title: "A", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+      { title: "B", folder: "Personal", created: "2024-01-03T00:00:00Z", modified: "2024-01-04T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(allNotes));
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(2);
+    expect(runJxa).toHaveBeenCalledTimes(1);
+
+    const jxaCode = vi.mocked(runJxa).mock.calls[0][0] as string;
+    expect(jxaCode).not.toContain("targetFolder");
+  });
+
+  it("should still sort folder-filtered results", async () => {
+    const folderNotes = [
+      { title: "Old", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-05T00:00:00Z" },
+      { title: "New", folder: "Work", created: "2024-01-02T00:00:00Z", modified: "2024-01-15T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(folderNotes));
+
+    const notes = await listNotes({ folder: "Work", sort_by: "modified", order: "desc" });
+    expect(notes[0].title).toBe("New");
+    expect(notes[1].title).toBe("Old");
+  });
+
+  it("should match folder case-insensitively in optimized path", async () => {
+    const workNotes = [
+      { title: "Case Note", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-02T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(workNotes));
+
+    const notes = await listNotes({ folder: "work" });
+    expect(notes).toHaveLength(1);
+    expect(notes[0].folder).toBe("Work");
+  });
+});

package/src/notes/read.ts

@@ -619,9 +619,65 @@ export type { ListNotesOptions } from "../index.js";
 // Import the type for internal use
 import type { ListNotesOptions } from "../index.js";
 
+/**
+ * Get notes metadata from a specific folder (no content).
+ * Much faster than getAllNotes() when only one folder is needed,
+ * because it skips iterating all other folders in JXA.
+ *
+ * @param folderName - The folder name (case-insensitive matching)
+ * @returns Array of note metadata from the specified folder
+ */
+export async function getNoteMetadataByFolder(folderName: string): Promise<NoteInfo[]> {
+  debug(`Getting note metadata for folder: ${folderName}`);
+
+  const escapedFolder = JSON.stringify(folderName);
+
+  const jxaCode = `
+    const app = Application('Notes');
+    app.includeStandardAdditions = true;
+
+    const targetFolder = ${escapedFolder}.toLowerCase();
+    const result = [];
+    const folders = app.folders();
+
+    for (const folder of folders) {
+      const folderName = folder.name();
+      if (folderName.toLowerCase() !== targetFolder) continue;
+
+      const notes = folder.notes();
+
+      for (const note of notes) {
+        try {
+          const props = note.properties();
+          result.push({
+            title: props.name || '',
+            folder: folderName,
+            created: props.creationDate ? props.creationDate.toISOString() : '',
+            modified: props.modificationDate ? props.modificationDate.toISOString() : ''
+          });
+        } catch (e) {
+          // Skip notes that can't be accessed
+        }
+      }
+    }
+
+    return JSON.stringify(result);
+  `;
+
+  const result = await executeJxa<string>(jxaCode);
+  const notes = JSON.parse(result) as NoteInfo[];
+
+  debug(`Found ${notes.length} notes in folder: ${folderName}`);
+  return notes;
+}
+
 /**
  * List notes with sorting and filtering.
  *
+ * When a folder filter is provided, only that folder is queried via JXA
+ * instead of fetching all notes first. This is significantly faster for
+ * users with many notes spread across folders.
+ *
  * @param options - Sorting and filtering options
  * @returns Array of note metadata sorted and filtered as specified
  */
@@ -630,12 +686,9 @@ export async function listNotes(options: ListNotesOptions = {}): Promise<NoteInf
 
   debug(`Listing notes: sort_by=${sort_by}, order=${order}, limit=${limit}, folder=${folder}`);
 
-  const allNotes = await getAllNotes();
-
-  // Filter by folder (case-insensitive for better UX)
   const filtered = folder
-    ? allNotes.filter((n) => n.folder.toLowerCase() === folder.toLowerCase())
-    : allNotes;
+    ? await getNoteMetadataByFolder(folder)
+    : await getAllNotes();
 
   filtered.sort((a, b) => {
     let comparison: number;

package/src/search/chunk-indexer.ts

@@ -8,9 +8,18 @@ import { getChunkStore, type ChunkRecord } from "../db/lancedb.js";
 import { getAllNotesWithFallback, type NoteDetails } from "../notes/read.js";
 import { chunkText } from "../utils/chunker.js";
 import { extractMetadata } from "../graph/extract.js";
-import { DEFAULT_CHUNK_SIZE, DEFAULT_CHUNK_OVERLAP } from "../config/constants.js";
+import {
+  DEFAULT_CHUNK_SIZE,
+  DEFAULT_CHUNK_OVERLAP,
+  getEmbeddingBatchSize,
+} from "../config/constants.js";
 import { createDebugLogger } from "../utils/debug.js";
 import { filterContent, shouldIndexContent } from "../utils/content-filter.js";
+import {
+  type IndexRunOptions,
+  type IndexProgressEvent,
+  throwIfCancelled,
+} from "../indexing/contracts.js";
 
 // Debug logging
 const debug = createDebugLogger("CHUNK-INDEXER");
@@ -48,6 +57,29 @@ interface InternalChunkRecord {
   outlinks: string[];
 }
 
+function chunks<T>(array: T[], size: number): T[][] {
+  const result: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    result.push(array.slice(i, i + size));
+  }
+  return result;
+}
+
+function emitProgress(
+  options: IndexRunOptions,
+  stage: IndexProgressEvent["stage"],
+  current: number,
+  total: number,
+  message: string
+): void {
+  options.onProgress?.({
+    stage,
+    current,
+    total,
+    message,
+  });
+}
+
 /**
  * Convert a note into chunk records WITHOUT vectors.
  * Vectors are added later during batch embedding generation.
@@ -125,13 +157,17 @@ export function chunkNote(note: NoteDetails): InternalChunkRecord[] {
  *
  * @returns ChunkIndexResult with stats
  */
-export async function fullChunkIndex(): Promise<ChunkIndexResult> {
+export async function fullChunkIndex(options: IndexRunOptions = {}): Promise<ChunkIndexResult> {
   const startTime = Date.now();
+  throwIfCancelled(options.signal);
+  emitProgress(options, "fetch", 0, 1, "Fetching notes for chunk index");
 
   // Phase 1: Fetch all notes with hybrid fallback
   debug("Phase 1: Fetching all notes with fallback...");
   const { notes, skipped: skippedNotes } = await getAllNotesWithFallback();
   debug(`Fetched ${notes.length} notes, skipped ${skippedNotes.length}`);
+  emitProgress(options, "fetch", 1, 1, `Fetched ${notes.length} notes`);
+  throwIfCancelled(options.signal);
 
   if (notes.length === 0) {
     return {
@@ -147,10 +183,13 @@ export async function fullChunkIndex(): Promise<ChunkIndexResult> {
   debug("Phase 2: Chunking all notes...");
   const allChunks: InternalChunkRecord[] = [];
   for (const note of notes) {
+    throwIfCancelled(options.signal);
     const noteChunks = chunkNote(note);
     allChunks.push(...noteChunks);
   }
   debug(`Created ${allChunks.length} chunks from ${notes.length} notes`);
+  emitProgress(options, "prepare", allChunks.length, Math.max(notes.length, 1), "Prepared note chunks");
+  throwIfCancelled(options.signal);
 
   if (allChunks.length === 0) {
     return {
@@ -163,9 +202,32 @@ export async function fullChunkIndex(): Promise<ChunkIndexResult> {
 
   // Phase 3: Generate embeddings in batch
   debug("Phase 3: Generating embeddings...");
-  const chunkTexts: string[] = allChunks.map((chunk) => chunk.content);
-  const vectors = await getEmbeddingBatch(chunkTexts);
+  const chunkBatches = chunks(allChunks, getEmbeddingBatchSize());
+  const vectors: number[][] = [];
+  for (let batchIdx = 0; batchIdx < chunkBatches.length; batchIdx++) {
+    throwIfCancelled(options.signal);
+    emitProgress(
+      options,
+      "embed",
+      batchIdx,
+      chunkBatches.length,
+      `Embedding chunk batch ${batchIdx + 1}/${chunkBatches.length}`
+    );
+
+    const batchTexts = chunkBatches[batchIdx].map((chunk) => chunk.content);
+    const batchVectors = await getEmbeddingBatch(batchTexts);
+    vectors.push(...batchVectors);
+
+    emitProgress(
+      options,
+      "embed",
+      batchIdx + 1,
+      chunkBatches.length,
+      `Embedded chunk batch ${batchIdx + 1}/${chunkBatches.length}`
+    );
+  }
   debug(`Generated ${vectors.length} embeddings`);
+  throwIfCancelled(options.signal);
 
   // Phase 4: Combine chunks with vectors and set indexed_at
   debug("Phase 4: Combining chunks with vectors...");
@@ -179,11 +241,14 @@ export async function fullChunkIndex(): Promise<ChunkIndexResult> {
   // Phase 5: Store in LanceDB
   debug("Phase 5: Storing chunks...");
   const chunkStore = getChunkStore();
+  emitProgress(options, "persist", 0, 1, "Storing chunk vectors");
   await chunkStore.indexChunks(completeChunks);
+  emitProgress(options, "persist", 1, 1, "Stored chunk vectors");
   debug(`Stored ${completeChunks.length} chunks`);
 
   const timeMs = Date.now() - startTime;
   debug(`Chunk indexing completed in ${timeMs}ms`);
+  emitProgress(options, "done", 1, 1, "Chunk index completed");
 
   return {
     totalNotes: notes.length,

package/src/search/indexer.progress.test.ts

@@ -0,0 +1,75 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockStore = {
+  clear: vi.fn(),
+  index: vi.fn(),
+  addRecords: vi.fn(),
+  rebuildFtsIndex: vi.fn(),
+};
+
+vi.mock("../db/lancedb.js", () => ({
+  getVectorStore: vi.fn(() => mockStore),
+}));
+
+vi.mock("../notes/read.js", () => ({
+  getAllNotesWithFallback: vi.fn().mockResolvedValue({
+    notes: [
+      {
+        id: "n1",
+        title: "Note 1",
+        folder: "Work",
+        content: "content",
+        created: "2026-01-01T00:00:00.000Z",
+        modified: "2026-01-01T00:00:00.000Z",
+      },
+    ],
+    skipped: [],
+  }),
+  getNoteByTitle: vi.fn(),
+}));
+
+vi.mock("../embeddings/index.js", () => ({
+  getEmbedding: vi.fn(),
+  getEmbeddingBatch: vi.fn().mockResolvedValue([[0.1, 0.2, 0.3]]),
+}));
+
+vi.mock("../config/constants.js", () => ({
+  getEmbeddingBatchSize: vi.fn(() => 50),
+}));
+
+vi.mock("../graph/extract.js", () => ({
+  extractMetadata: vi.fn(() => ({ tags: [], outlinks: [] })),
+}));
+
+vi.mock("../utils/text.js", () => ({
+  truncateForEmbedding: vi.fn((content: string) => content),
+}));
+
+vi.mock("../utils/debug.js", () => ({
+  createDebugLogger: vi.fn(() => vi.fn()),
+}));
+
+describe("indexer progress/cancel safety", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("does not call clear during full index", async () => {
+    const { fullIndex } = await import("./indexer.js");
+
+    await fullIndex();
+
+    expect(mockStore.clear).not.toHaveBeenCalled();
+    expect(mockStore.index).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws cancellation before indexing when signal is already aborted", async () => {
+    const { fullIndex } = await import("./indexer.js");
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(fullIndex({ signal: controller.signal })).rejects.toThrow("Indexing cancelled");
+    expect(mockStore.clear).not.toHaveBeenCalled();
+    expect(mockStore.index).not.toHaveBeenCalled();
+  });
+});