@disco_trooper/apple-notes-mcp 1.2.0 → 1.3.0

package/src/index.ts

@@ -1,3 +1,11 @@
+#!/usr/bin/env bun
+import { hasConfig, getEnvPath } from "./config/paths.js";
+import { checkBunRuntime, isTTY } from "./utils/runtime.js";
+import * as dotenv from "dotenv";
+
+// Load config from unified location
+dotenv.config({ path: getEnvPath() });
+
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -5,7 +13,6 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import "dotenv/config";
 
 // Import constants
 import {
@@ -17,17 +24,53 @@ import {
 import { validateEnv } from "./config/env.js";
 
 // Import implementations
-import { getVectorStore } from "./db/lancedb.js";
+import { getVectorStore, getChunkStore } from "./db/lancedb.js";
 import { getNoteByTitle, getAllFolders } from "./notes/read.js";
 import { createNote, updateNote, deleteNote, moveNote, editTable } from "./notes/crud.js";
 import { searchNotes } from "./search/index.js";
 import { indexNotes, reindexNote } from "./search/indexer.js";
+import { fullChunkIndex, hasChunkIndex } from "./search/chunk-indexer.js";
+import { searchChunks } from "./search/chunk-search.js";
+import { listTags, searchByTag, findRelatedNotes } from "./graph/queries.js";
+import { exportGraph } from "./graph/export.js";
 
 // Debug logging and error handling
 import { createDebugLogger } from "./utils/debug.js";
 import { sanitizeErrorMessage } from "./utils/errors.js";
 const debug = createDebugLogger("MCP");
 
+// Runtime and config checks
+checkBunRuntime();
+
+if (!hasConfig()) {
+  if (isTTY()) {
+    // Interactive terminal - run setup wizard
+    console.log("No configuration found. Starting setup wizard...\n");
+    const { spawn } = await import("node:child_process");
+    const setupPath = new URL("./setup.ts", import.meta.url).pathname;
+    const child = spawn("bun", ["run", setupPath], {
+      stdio: "inherit",
+    });
+    child.on("exit", (code) => process.exit(code ?? 0));
+    // Wait for setup to complete
+    await new Promise(() => {}); // Setup will exit the process
+  } else {
+    // Non-interactive (MCP server mode) - show error
+    console.error(`
+╭─────────────────────────────────────────────────────────────╮
+│  apple-notes-mcp: Configuration required                    │
+│                                                             │
+│  Run this command in your terminal first:                   │
+│                                                             │
+│      apple-notes-mcp                                        │
+│                                                             │
+│  The setup wizard will guide you through configuration.     │
+╰─────────────────────────────────────────────────────────────╯
+`);
+    process.exit(1);
+  }
+}
+
 // Tool parameter schemas
 const SearchNotesSchema = z.object({
   query: z.string().min(1, "Query cannot be empty").max(MAX_INPUT_LENGTH),
@@ -82,6 +125,26 @@ const EditTableSchema = z.object({
   })).min(1).max(100),
 });
 
+// Knowledge Graph tool schemas
+const ListTagsSchema = z.object({});
+
+const SearchByTagSchema = z.object({
+  tag: z.string().min(1).max(100),
+  folder: z.string().max(200).optional(),
+  limit: z.number().min(1).max(MAX_SEARCH_LIMIT).default(DEFAULT_SEARCH_LIMIT),
+});
+
+const RelatedNotesSchema = z.object({
+  title: z.string().min(1).max(MAX_TITLE_LENGTH),
+  types: z.array(z.enum(["tag", "link", "similar"])).default(["tag", "link", "similar"]),
+  limit: z.number().min(1).max(50).default(10),
+});
+
+const ExportGraphSchema = z.object({
+  format: z.enum(["json", "graphml"]),
+  folder: z.string().max(200).optional(),
+});
+
 // Create MCP server
 const server = new Server(
   {
@@ -271,6 +334,62 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ["title", "edits"],
         },
       },
+      // Knowledge Graph tools
+      {
+        name: "list-tags",
+        description: "List all tags with occurrence counts",
+        inputSchema: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+      },
+      {
+        name: "search-by-tag",
+        description: "Find notes with a specific tag",
+        inputSchema: {
+          type: "object",
+          properties: {
+            tag: { type: "string", description: "Tag to search for (without #)" },
+            folder: { type: "string", description: "Filter by folder (optional)" },
+            limit: { type: "number", description: "Max results (default: 20)" },
+          },
+          required: ["tag"],
+        },
+      },
+      {
+        name: "related-notes",
+        description: "Find notes related to a source note by tags, links, or semantic similarity",
+        inputSchema: {
+          type: "object",
+          properties: {
+            title: { type: "string", description: "Source note title (use folder/title or id:xxx)" },
+            types: {
+              type: "array",
+              items: { type: "string", enum: ["tag", "link", "similar"] },
+              description: "Relationship types to include (default: all)"
+            },
+            limit: { type: "number", description: "Max results (default: 10)" },
+          },
+          required: ["title"],
+        },
+      },
+      {
+        name: "export-graph",
+        description: "Export knowledge graph to JSON or GraphML format for visualization",
+        inputSchema: {
+          type: "object",
+          properties: {
+            format: {
+              type: "string",
+              enum: ["json", "graphml"],
+              description: "Export format: json (for D3.js, custom viz) or graphml (for Gephi, yEd)"
+            },
+            folder: { type: "string", description: "Filter by folder (optional)" },
+          },
+          required: ["format"],
+        },
+      },
     ],
   };
 });
@@ -285,6 +404,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // Read tools
       case "search-notes": {
         const params = SearchNotesSchema.parse(args);
+
+        // Use chunk-based search if chunk index exists (better for long notes)
+        const useChunkSearch = await hasChunkIndex();
+
+        if (useChunkSearch) {
+          debug("Using chunk-based search");
+          const chunkResults = await searchChunks(params.query, {
+            folder: params.folder,
+            limit: params.limit,
+            mode: params.mode,
+          });
+
+          if (chunkResults.length === 0) {
+            return textResponse("No notes found matching your query.");
+          }
+
+          // Transform chunk results to match expected format
+          const results = chunkResults.map((r) => ({
+            id: r.note_id,
+            title: r.note_title,
+            folder: r.folder,
+            preview: r.matchedChunk.slice(0, 200) + (r.matchedChunk.length > 200 ? "..." : ""),
+            modified: r.modified,
+            score: r.score,
+            matchedChunkIndex: r.matchedChunkIndex,
+          }));
+
+          return textResponse(JSON.stringify(results, null, 2));
+        }
+
+        // Fall back to legacy search if no chunk index
+        debug("Using legacy search (no chunk index)");
         const results = await searchNotes(params.query, {
           folder: params.folder,
           limit: params.limit,
@@ -316,6 +467,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
         }
 
+        // Run chunk indexing for full mode (for semantic search on long notes)
+        if (params.mode === "full") {
+          debug("Running chunk indexing for full mode...");
+          const chunkResult = await fullChunkIndex();
+          message += `\nChunk index: ${chunkResult.totalChunks} chunks from ${chunkResult.totalNotes} notes in ${(chunkResult.timeMs / 1000).toFixed(1)}s`;
+        }
+
         return textResponse(message);
       }
 
@@ -327,8 +485,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case "list-notes": {
         const store = getVectorStore();
-        const count = await store.count();
-        return textResponse(`${count} notes indexed. Run index-notes to update the index.`);
+        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.";
+        }
+
+        return textResponse(message);
       }
 
       case "get-note": {
@@ -363,19 +534,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case "update-note": {
         const params = UpdateNoteSchema.parse(args);
-        await updateNote(params.title, params.content);
+        const result = await updateNote(params.title, params.content);
+
+        // Build location string for messages
+        const location = `${result.folder}/${result.newTitle}`;
+        const renamedMsg = result.titleChanged
+          ? ` (renamed from "${result.originalTitle}")`
+          : "";
 
         if (params.reindex) {
           try {
-            await reindexNote(params.title);
-            return textResponse(`Updated and reindexed note: "${params.title}"`);
+            // Use new title for reindexing (Apple Notes may have renamed it)
+            const reindexTitle = `${result.folder}/${result.newTitle}`;
+            await reindexNote(reindexTitle);
+            return textResponse(`Updated and reindexed note: "${location}"${renamedMsg}`);
           } catch (reindexError) {
             debug("Reindex after update failed:", reindexError);
-            return textResponse(`Updated note: "${params.title}" (reindexing failed, run index-notes to update)`);
+            return textResponse(`Updated note: "${location}"${renamedMsg} (reindexing failed, run index-notes to update)`);
           }
         }
 
-        return textResponse(`Updated note: "${params.title}"`);
+        return textResponse(`Updated note: "${location}"${renamedMsg}`);
       }
 
       case "delete-note": {
@@ -399,6 +578,67 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return textResponse(`Updated ${params.edits.length} cell(s) in table ${params.table_index}`);
       }
 
+      // Knowledge Graph tools
+      case "list-tags": {
+        ListTagsSchema.parse(args);
+        const tags = await listTags();
+
+        if (tags.length === 0) {
+          return textResponse("No tags found. Add #tags to your notes and reindex.");
+        }
+
+        return textResponse(JSON.stringify(tags, null, 2));
+      }
+
+      case "search-by-tag": {
+        const params = SearchByTagSchema.parse(args);
+        const results = await searchByTag(params.tag, {
+          folder: params.folder,
+          limit: params.limit,
+        });
+
+        if (results.length === 0) {
+          return textResponse(`No notes found with tag: #${params.tag}`);
+        }
+
+        return textResponse(JSON.stringify(results, null, 2));
+      }
+
+      case "related-notes": {
+        const params = RelatedNotesSchema.parse(args);
+
+        // Resolve note to get ID
+        const note = await getNoteByTitle(params.title);
+        if (!note) {
+          return errorResponse(`Note not found: "${params.title}"`);
+        }
+
+        const results = await findRelatedNotes(note.id, {
+          types: params.types,
+          limit: params.limit,
+        });
+
+        if (results.length === 0) {
+          return textResponse("No related notes found.");
+        }
+
+        return textResponse(JSON.stringify(results, null, 2));
+      }
+
+      case "export-graph": {
+        const params = ExportGraphSchema.parse(args);
+        const result = await exportGraph({
+          format: params.format,
+          folder: params.folder,
+        });
+
+        if (typeof result === "string") {
+          return textResponse(result);
+        }
+
+        return textResponse(JSON.stringify(result, null, 2));
+      }
+
       default:
         return errorResponse(`Unknown tool: ${name}`);
     }

package/src/notes/crud.test.ts

@@ -111,9 +111,33 @@ 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 () => {

package/src/notes/crud.ts

@@ -115,20 +115,42 @@ 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}"`);
 
   const note = await resolveNoteOrThrow(title);
+  const originalTitle = note.title;
+  const folder = note.folder;
 
   // Convert Markdown to HTML
   const htmlContent = markdownToHtml(content);
@@ -137,7 +159,8 @@ export async function updateNote(title: string, content: string): Promise<void>
 
   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};
@@ -152,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;
+
+  if (titleChanged) {
+    debug(`Note renamed by Apple Notes: "${originalTitle}" -> "${newTitle}"`);
+  } else {
+    debug(`Note updated: "${title}"`);
+  }
 
-  debug(`Note updated: "${title}"`);
+  return {
+    originalTitle,
+    newTitle,
+    folder,
+    titleChanged,
+  };
 }
 
 /**

package/src/notes/read.ts

@@ -40,9 +40,19 @@ export interface NoteDetails extends NoteInfo {
 }
 
 // -----------------------------------------------------------------------------
-// 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
  */
@@ -58,6 +68,21 @@ async function executeJxa<T>(code: string): Promise<T> {
   }
 }
 
+/**
+ * Convert raw JXA note data to NoteDetails with markdown content
+ */
+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,
+  };
+}
+
 // -----------------------------------------------------------------------------
 // Public API
 // -----------------------------------------------------------------------------
@@ -180,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");
@@ -196,27 +214,11 @@ 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: ${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]);
 }
 
 /**
@@ -268,33 +270,15 @@ export async function getNoteById(id: string): Promise<NoteDetails | 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;
+  const note = JSON.parse(result) as RawNoteData | 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,
-  };
+  return toNoteDetails(note);
 }
 
 /**
@@ -357,34 +341,65 @@ 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: ${notes[0].folder}`);
+  return toNoteDetails(notes[0]);
+}
 
-  debug(`Found note in folder: ${note.folder}`);
+/**
+ * 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 note details with content
+ */
+export async function getAllNotesWithContent(): Promise<NoteDetails[]> {
+  debug("Getting all notes with content (single JXA call)...");
 
-  return {
-    id: note.id,
-    title: note.title,
-    folder: note.folder,
-    created: note.created,
-    modified: note.modified,
-    content,
-    htmlContent: note.htmlContent,
-  };
+  const jxaCode = `
+    const app = Application('Notes');
+    app.includeStandardAdditions = true;
+
+    const allNotes = [];
+    const folders = app.folders();
+
+    for (const folder of folders) {
+      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(allNotes);
+  `;
+
+  const result = await executeJxa<string>(jxaCode);
+  const notes = JSON.parse(result) as RawNoteData[];
+
+  debug(`Fetched ${notes.length} notes with content`);
+
+  return notes.map(toNoteDetails);
 }
 
 /**