@disco_trooper/apple-notes-mcp 1.4.0 → 1.5.1

package/README.md

@@ -10,23 +10,19 @@ MCP server for Apple Notes with semantic search and CRUD operations. Claude sear
 
 ## Features
 
-- **Chunk-Based Search** - Long notes split into chunks for accurate matching (NEW!)
-- **Query Caching** - 60x faster repeated searches (NEW!)
-- **Knowledge Graph** - Tags, links, and related notes discovery (NEW!)
+- **Chunk-Based Search** - Long notes split into chunks for accurate matching
+- **Query Caching** - 60x faster repeated searches
+- **Knowledge Graph** - Tags, links, and related notes discovery
 - **Hybrid Search** - Vector + keyword search with Reciprocal Rank Fusion
 - **Semantic Search** - Find notes by meaning, not keywords
 - **Full CRUD** - Create, read, update, delete, and move notes
 - **Incremental Indexing** - Re-embed only changed notes
 - **Dual Embedding** - Local HuggingFace or OpenRouter API
 
-## What's New in 1.4
+## What's New in 1.5
 
-- **Smart Refresh** - Search auto-reindexes changed notes. No manual `index-notes` needed.
-- **Batch Operations** - Delete or move multiple notes by title or folder.
-- **Purge Index** - Clear all indexed data when switching models or fixing corruption.
-- **Parent Document Retriever** - Splits long notes into 500-char chunks with 100-char overlap.
-- **60x faster cached queries** - Query embedding cache eliminates redundant API calls.
-- **4-6x faster indexing** - Parallel processing and batch embeddings.
+- **List Notes with Sorting** - Sort by created, modified, or title; filter by folder; limit results.
+- **Case-Insensitive Folders** - Folder filtering now matches regardless of case.
 
 ## Installation
 
@@ -113,7 +109,19 @@ include_content: false   # include full content vs preview
 ```
 
 #### `list-notes`
-Count indexed notes.
+List notes with sorting and filtering. Without parameters, shows index statistics.
+
+```
+sort_by: "modified"      # created, modified, or title (default: modified)
+order: "desc"            # asc or desc (default: desc)
+limit: 10                # max notes to return (1-100)
+folder: "Work"           # filter by folder (case-insensitive)
+```
+
+**Examples:**
+- Get 5 newest notes: `{ sort_by: "created", order: "desc", limit: 5 }`
+- Recently modified: `{ sort_by: "modified", limit: 10 }`
+- Alphabetical in folder: `{ sort_by: "title", order: "asc", folder: "Projects" }`
 
 #### `list-folders`
 List all Apple Notes folders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@disco_trooper/apple-notes-mcp",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "MCP server for Apple Notes with semantic search and CRUD operations",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -25,7 +25,7 @@ import { validateEnv } from "./config/env.js";
 
 // Import implementations
 import { getVectorStore, getChunkStore } from "./db/lancedb.js";
-import { getNoteByTitle, getAllFolders } from "./notes/read.js";
+import { getNoteByTitle, getAllFolders, listNotes } from "./notes/read.js";
 import { createNote, updateNote, deleteNote, moveNote, editTable, batchDelete, batchMove } from "./notes/crud.js";
 import { searchNotes } from "./search/index.js";
 import { indexNotes, reindexNote } from "./search/indexer.js";
@@ -148,6 +148,17 @@ const PurgeIndexSchema = z.object({
   confirm: z.literal(true),
 });
 
+const ListNotesSchema = z.object({
+  sort_by: z.enum(["created", "modified", "title"]).default("modified"),
+  order: z.enum(["asc", "desc"]).default("desc"),
+  limit: z.number().min(1).max(100).optional(),
+  folder: z.string().max(200).optional(),
+});
+
+/** Exported type for listNotes options - derived from Zod schema (single source of truth)
+ * Using z.input to get the input type (with optionals) rather than z.infer (output with defaults applied) */
+export type ListNotesOptions = z.input<typeof ListNotesSchema>;
+
 // Knowledge Graph tool schemas
 const ListTagsSchema = z.object({});
 
@@ -265,10 +276,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "list-notes",
-        description: "Count how many notes are indexed",
+        description: "List notes from Apple Notes with sorting and filtering. Without parameters, shows index statistics.",
         inputSchema: {
           type: "object",
-          properties: {},
+          properties: {
+            sort_by: {
+              type: "string",
+              enum: ["created", "modified", "title"],
+              description: "Sort by date or title (default: modified)"
+            },
+            order: {
+              type: "string",
+              enum: ["asc", "desc"],
+              description: "Sort order (default: desc)"
+            },
+            limit: {
+              type: "number",
+              description: "Max notes to return (1-100)"
+            },
+            folder: {
+              type: "string",
+              description: "Filter by folder"
+            },
+          },
           required: [],
         },
       },
@@ -581,22 +611,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case "list-notes": {
-        const store = getVectorStore();
-        const noteCount = await store.count();
-
-        let message = `${noteCount} notes indexed.`;
-
-        // Show chunk statistics if chunk index exists
-        const hasChunks = await hasChunkIndex();
-        if (hasChunks) {
-          const chunkStore = getChunkStore();
-          const chunkCount = await chunkStore.count();
-          message += ` ${chunkCount} chunks indexed for semantic search.`;
-        } else {
-          message += " Run index-notes with mode='full' to enable chunk-based search.";
+        const params = ListNotesSchema.parse(args);
+
+        // No parameters provided: show index statistics (backwards compatible)
+        const hasFilteringParams =
+          params.limit !== undefined ||
+          params.folder !== undefined ||
+          (args && ("sort_by" in args || "order" in args));
+
+        if (!hasFilteringParams) {
+          const store = getVectorStore();
+          const noteCount = await store.count();
+          const hasChunks = await hasChunkIndex();
+
+          if (hasChunks) {
+            const chunkStore = getChunkStore();
+            const chunkCount = await chunkStore.count();
+            return textResponse(
+              `${noteCount} notes indexed. ${chunkCount} chunks indexed for semantic search.`
+            );
+          }
+
+          return textResponse(
+            `${noteCount} notes indexed. Run index-notes with mode='full' to enable chunk-based search.`
+          );
         }
 
-        return textResponse(message);
+        const notes = await listNotes(params);
+        return textResponse(JSON.stringify(notes, null, 2));
       }
 
       case "get-note": {

package/src/notes/read.test.ts

@@ -6,7 +6,7 @@ vi.mock("run-jxa", () => ({
 }));
 
 import { runJxa } from "run-jxa";
-import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle } from "./read.js";
+import { getAllNotes, getNoteByTitle, getAllFolders, resolveNoteTitle, listNotes } from "./read.js";
 
 describe("getAllNotes", () => {
   beforeEach(() => {
@@ -184,3 +184,164 @@ describe("getNoteByTitle with ID prefix", () => {
     expect(note).toBeNull();
   });
 });
+
+describe("listNotes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const mockNotes = [
+    { title: "Alpha", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    { title: "Beta", folder: "Personal", created: "2024-01-03T00:00:00Z", modified: "2024-01-05T00:00:00Z" },
+    { title: "Gamma", folder: "Work", created: "2024-01-02T00:00:00Z", modified: "2024-01-15T00:00:00Z" },
+  ];
+
+  it("should return all notes with default sorting (modified desc)", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(3);
+    // Most recently modified first
+    expect(notes[0].title).toBe("Gamma");
+    expect(notes[1].title).toBe("Alpha");
+    expect(notes[2].title).toBe("Beta");
+  });
+
+  it("should sort by created date ascending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "created", order: "asc" });
+    expect(notes[0].title).toBe("Alpha");
+    expect(notes[1].title).toBe("Gamma");
+    expect(notes[2].title).toBe("Beta");
+  });
+
+  it("should sort by created date descending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "created", order: "desc" });
+    expect(notes[0].title).toBe("Beta");
+    expect(notes[1].title).toBe("Gamma");
+    expect(notes[2].title).toBe("Alpha");
+  });
+
+  it("should sort by title alphabetically", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "title", order: "asc" });
+    expect(notes[0].title).toBe("Alpha");
+    expect(notes[1].title).toBe("Beta");
+    expect(notes[2].title).toBe("Gamma");
+  });
+
+  it("should sort by title descending", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ sort_by: "title", order: "desc" });
+    expect(notes[0].title).toBe("Gamma");
+    expect(notes[1].title).toBe("Beta");
+    expect(notes[2].title).toBe("Alpha");
+  });
+
+  it("should filter by folder", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "Work" });
+    expect(notes).toHaveLength(2);
+    expect(notes.every(n => n.folder === "Work")).toBe(true);
+  });
+
+  it("should apply limit", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ limit: 2 });
+    expect(notes).toHaveLength(2);
+  });
+
+  it("should combine folder filter and limit", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "Work", limit: 1 });
+    expect(notes).toHaveLength(1);
+    expect(notes[0].folder).toBe("Work");
+  });
+
+  it("should return empty array when folder has no notes", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mockNotes));
+
+    const notes = await listNotes({ folder: "NonExistent" });
+    expect(notes).toHaveLength(0);
+  });
+
+  it("should handle empty notes array", async () => {
+    vi.mocked(runJxa).mockResolvedValueOnce("[]");
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(0);
+  });
+
+  it("should handle notes with empty date strings without crashing", async () => {
+    const notesWithEmptyDates = [
+      { title: "Valid", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(notesWithEmptyDates));
+
+    const notes = await listNotes();
+    expect(notes).toHaveLength(2);
+    expect(notes[0].title).toBe("Valid");
+    expect(notes[1].title).toBe("Empty");
+  });
+
+  it("should sort notes with empty dates to the end (oldest)", async () => {
+    const notesWithEmptyDates = [
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+      { title: "Valid", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(notesWithEmptyDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "desc" });
+    expect(notes).toHaveLength(2);
+    // Valid note should come first (most recent)
+    expect(notes[0].title).toBe("Valid");
+    // Empty date should be last (treated as oldest)
+    expect(notes[1].title).toBe("Empty");
+  });
+
+  it("should handle mixing valid and empty dates correctly", async () => {
+    const mixedDates = [
+      { title: "Recent", folder: "Work", created: "2024-03-01T00:00:00Z", modified: "2024-03-15T00:00:00Z" },
+      { title: "Empty1", folder: "Work", created: "", modified: "" },
+      { title: "Old", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+      { title: "Empty2", folder: "Work", created: "", modified: "" },
+      { title: "Middle", folder: "Work", created: "2024-02-01T00:00:00Z", modified: "2024-02-15T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mixedDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "desc" });
+    expect(notes).toHaveLength(5);
+    // Order should be: Recent, Middle, Old, Empty1, Empty2
+    expect(notes[0].title).toBe("Recent");
+    expect(notes[1].title).toBe("Middle");
+    expect(notes[2].title).toBe("Old");
+    // Empty dates at the end (treated as epoch)
+    expect(notes[3].title).toBe("Empty1");
+    expect(notes[4].title).toBe("Empty2");
+  });
+
+  it("should sort empty dates to the beginning when sorting ascending", async () => {
+    const mixedDates = [
+      { title: "Recent", folder: "Work", created: "2024-03-01T00:00:00Z", modified: "2024-03-15T00:00:00Z" },
+      { title: "Empty", folder: "Work", created: "", modified: "" },
+      { title: "Old", folder: "Work", created: "2024-01-01T00:00:00Z", modified: "2024-01-10T00:00:00Z" },
+    ];
+    vi.mocked(runJxa).mockResolvedValueOnce(JSON.stringify(mixedDates));
+
+    const notes = await listNotes({ sort_by: "modified", order: "asc" });
+    expect(notes).toHaveLength(3);
+    // Empty date should be first (oldest when ascending)
+    expect(notes[0].title).toBe("Empty");
+    expect(notes[1].title).toBe("Old");
+    expect(notes[2].title).toBe("Recent");
+  });
+});

package/src/notes/read.ts

@@ -434,3 +434,52 @@ export async function getAllFolders(): Promise<string[]> {
   debug(`Found ${folders.length} folders`);
   return folders;
 }
+
+// -----------------------------------------------------------------------------
+// List Notes with Sorting and Filtering
+// -----------------------------------------------------------------------------
+
+// Re-export ListNotesOptions from index.ts (derived from Zod schema - single source of truth)
+export type { ListNotesOptions } from "../index.js";
+
+// Import the type for internal use
+import type { ListNotesOptions } from "../index.js";
+
+/**
+ * List notes with sorting and filtering.
+ *
+ * @param options - Sorting and filtering options
+ * @returns Array of note metadata sorted and filtered as specified
+ */
+export async function listNotes(options: ListNotesOptions = {}): Promise<NoteInfo[]> {
+  const { sort_by = "modified", order = "desc", limit, folder } = options;
+
+  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;
+
+  filtered.sort((a, b) => {
+    let comparison: number;
+
+    if (sort_by === "title") {
+      comparison = a.title.localeCompare(b.title);
+    } else {
+      // Handle empty dates by treating them as epoch (0)
+      const aTime = a[sort_by] ? new Date(a[sort_by]).getTime() : 0;
+      const bTime = b[sort_by] ? new Date(b[sort_by]).getTime() : 0;
+      comparison = aTime - bTime;
+    }
+
+    return order === "desc" ? -comparison : comparison;
+  });
+
+  const result = limit ? filtered.slice(0, limit) : filtered;
+
+  debug(`Returning ${result.length} notes`);
+  return result;
+}