@disco_trooper/apple-notes-mcp 1.0.1 → 1.2.0

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

package/src/notes/tables.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vitest";
+import { parseTable, updateTableCell, findTables } from "./tables.js";
+
+const SAMPLE_TABLE_HTML = `<object><table cellspacing="0" cellpadding="0" style="border-collapse: collapse">
+<tbody>
+<tr><td valign="top" style="border-style: solid"><div><b>Typ</b></div></td><td valign="top" style="border-style: solid"><div><b>Částka</b></div></td></tr>
+<tr><td valign="top" style="border-style: solid"><div>Sociální</div></td><td valign="top" style="border-style: solid"><div>9 154 Kč</div></td></tr>
+<tr><td valign="top" style="border-style: solid"><div>Zdravotní</div></td><td valign="top" style="border-style: solid"><div>3 848 Kč</div></td></tr>
+</tbody>
+</table></object>`;
+
+describe("parseTable", () => {
+  it("should parse table rows and cells", () => {
+    const result = parseTable(SAMPLE_TABLE_HTML);
+    expect(result.rows).toHaveLength(3);
+    expect(result.rows[0]).toEqual(["Typ", "Částka"]);
+    expect(result.rows[1]).toEqual(["Sociální", "9 154 Kč"]);
+    expect(result.rows[2]).toEqual(["Zdravotní", "3 848 Kč"]);
+  });
+
+  it("should preserve bold formatting info", () => {
+    const result = parseTable(SAMPLE_TABLE_HTML);
+    expect(result.formatting[0][0].bold).toBe(true);
+    expect(result.formatting[1][0].bold).toBe(false);
+  });
+
+  it("should return empty for non-table HTML", () => {
+    const result = parseTable("<div>Not a table</div>");
+    expect(result.rows).toHaveLength(0);
+  });
+});
+
+describe("updateTableCell", () => {
+  it("should update cell content", () => {
+    const updated = updateTableCell(SAMPLE_TABLE_HTML, 1, 0, "✅ Sociální");
+    expect(updated).toContain("✅ Sociální");
+  });
+
+  it("should preserve table structure", () => {
+    const updated = updateTableCell(SAMPLE_TABLE_HTML, 1, 0, "✅ Sociální");
+    expect(updated).toContain("<object>");
+    expect(updated).toContain("</table></object>");
+  });
+
+  it("should throw for out of bounds row", () => {
+    expect(() => updateTableCell(SAMPLE_TABLE_HTML, 10, 0, "test")).toThrow("Row 10 out of bounds");
+  });
+
+  it("should throw for out of bounds column", () => {
+    expect(() => updateTableCell(SAMPLE_TABLE_HTML, 0, 10, "test")).toThrow("Column 10 out of bounds");
+  });
+});
+
+describe("findTables", () => {
+  it("should find single table", () => {
+    const tables = findTables(SAMPLE_TABLE_HTML);
+    expect(tables).toHaveLength(1);
+  });
+
+  it("should find multiple tables", () => {
+    const html = `<div>${SAMPLE_TABLE_HTML}</div><p>text</p>${SAMPLE_TABLE_HTML}`;
+    const tables = findTables(html);
+    expect(tables).toHaveLength(2);
+  });
+
+  it("should return empty for no tables", () => {
+    const tables = findTables("<div>No tables here</div>");
+    expect(tables).toHaveLength(0);
+  });
+});

package/src/notes/tables.ts

@@ -0,0 +1,175 @@
+/**
+ * Apple Notes table HTML parsing and editing utilities.
+ *
+ * Apple Notes wraps tables in <object> tags with a specific structure:
+ * <object><table><tbody><tr><td><div>content</div></td>...</tr>...</tbody></table></object>
+ */
+
+export interface CellFormatting {
+  bold: boolean;
+}
+
+export interface TableData {
+  rows: string[][];
+  formatting: CellFormatting[][];
+  raw: string;
+}
+
+/**
+ * Parse Apple Notes table HTML into structured data.
+ */
+export function parseTable(html: string): TableData {
+  const result: TableData = {
+    rows: [],
+    formatting: [],
+    raw: html,
+  };
+
+  // Match table content inside <object>
+  const tableMatch = html.match(/<object[^>]*>[\s\S]*?<table[\s\S]*?<tbody>([\s\S]*?)<\/tbody>[\s\S]*?<\/table>[\s\S]*?<\/object>/i);
+  if (!tableMatch) {
+    return result;
+  }
+
+  const tbodyContent = tableMatch[1];
+
+  // Match all rows
+  const rowRegex = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+  let rowMatch;
+
+  while ((rowMatch = rowRegex.exec(tbodyContent)) !== null) {
+    const rowContent = rowMatch[1];
+    const cells: string[] = [];
+    const cellFormats: CellFormatting[] = [];
+
+    // Match all cells in this row
+    const cellRegex = /<td[^>]*>[\s\S]*?<div[^>]*>([\s\S]*?)<\/div>[\s\S]*?<\/td>/gi;
+    let cellMatch;
+
+    while ((cellMatch = cellRegex.exec(rowContent)) !== null) {
+      const cellContent = cellMatch[1];
+      // Extract text, stripping HTML tags
+      const text = cellContent.replace(/<[^>]+>/g, "").trim();
+      const isBold = /<b>/i.test(cellContent);
+
+      cells.push(text);
+      cellFormats.push({ bold: isBold });
+    }
+
+    if (cells.length > 0) {
+      result.rows.push(cells);
+      result.formatting.push(cellFormats);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Find the HTML of a specific row in a table.
+ */
+function findRowHtml(tableHtml: string, rowIndex: number): { match: RegExpMatchArray; content: string } | null {
+  const rowRegex = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+  let currentRow = 0;
+  let rowMatch;
+
+  while ((rowMatch = rowRegex.exec(tableHtml)) !== null) {
+    if (currentRow === rowIndex) {
+      return { match: rowMatch, content: rowMatch[1] };
+    }
+    currentRow++;
+  }
+  return null;
+}
+
+/**
+ * Escape HTML special characters to prevent injection.
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Update a specific cell within a row's HTML.
+ */
+function updateCellInRow(rowContent: string, columnIndex: number, value: string, isBold: boolean): string {
+  const cellRegex = /(<td[^>]*>[\s\S]*?<div[^>]*>)([\s\S]*?)(<\/div>[\s\S]*?<\/td>)/gi;
+  let currentCol = 0;
+  let result = rowContent;
+  let cellMatch;
+
+  const replacements: Array<{original: string; replacement: string}> = [];
+
+  // Escape HTML to prevent injection
+  const escapedValue = escapeHtml(value);
+
+  while ((cellMatch = cellRegex.exec(rowContent)) !== null) {
+    if (currentCol === columnIndex) {
+      const prefix = cellMatch[1];
+      const suffix = cellMatch[3];
+      const newContent = isBold ? `<b>${escapedValue}</b>` : escapedValue;
+      replacements.push({
+        original: cellMatch[0],
+        replacement: `${prefix}${newContent}${suffix}`
+      });
+    }
+    currentCol++;
+  }
+
+  for (const r of replacements) {
+    result = result.replace(r.original, r.replacement);
+  }
+
+  return result;
+}
+
+/**
+ * Update a specific cell in an Apple Notes table HTML.
+ *
+ * @param html - The table HTML
+ * @param row - Row index (0-based, 0 = header)
+ * @param column - Column index (0-based)
+ * @param value - New cell value
+ * @returns Updated HTML
+ */
+export function updateTableCell(html: string, row: number, column: number, value: string): string {
+  const parsed = parseTable(html);
+
+  if (row >= parsed.rows.length) {
+    throw new Error(`Row ${row} out of bounds (table has ${parsed.rows.length} rows)`);
+  }
+
+  if (column >= parsed.rows[row].length) {
+    throw new Error(`Column ${column} out of bounds (row has ${parsed.rows[row].length} columns)`);
+  }
+
+  const rowData = findRowHtml(html, row);
+  if (!rowData) {
+    throw new Error(`Could not find row ${row} in table HTML`);
+  }
+
+  const isBold = parsed.formatting[row][column].bold;
+  const updatedRowContent = updateCellInRow(rowData.content, column, value, isBold);
+
+  return html.replace(rowData.match[0], `<tr>${updatedRowContent}</tr>`);
+}
+
+/**
+ * Find all tables in note HTML content.
+ * Returns array of table HTML strings.
+ */
+export function findTables(html: string): string[] {
+  const tables: string[] = [];
+  const tableRegex = /<object[^>]*>[\s\S]*?<table[\s\S]*?<\/table>[\s\S]*?<\/object>/gi;
+  let match;
+
+  while ((match = tableRegex.exec(html)) !== null) {
+    tables.push(match[0]);
+  }
+
+  return tables;
+}

package/src/search/index.ts

@@ -37,9 +37,6 @@ export interface SearchOptions {
   include_content?: boolean;
 }
 
-// SearchResult is imported from ../types/index.js
-// RRF_K is imported from ../config/constants.js
-
 /**
  * Calculate RRF score for a result at a given rank.
  * Formula: 1 / (k + rank)
@@ -163,15 +160,16 @@ async function hybridSearch(
   const contentMap = new Map<string, DBSearchResult>();
 
   // Process vector search results
+  // Use id as key to avoid collisions with duplicate titles in different folders
   vectorResults.forEach((item, rank) => {
-    const key = item.title;
+    const key = item.id ?? item.title;
     scoreMap.set(key, (scoreMap.get(key) || 0) + rrfScore(rank));
     contentMap.set(key, item);
   });
 
   // Process FTS results
   ftsResults.forEach((item, rank) => {
-    const key = item.title;
+    const key = item.id ?? item.title;
     scoreMap.set(key, (scoreMap.get(key) || 0) + rrfScore(rank));
     if (!contentMap.has(key)) {
       contentMap.set(key, item);
@@ -257,6 +255,7 @@ export async function searchNotes(
   // Transform to SearchResult format
   const results: SearchResult[] = dbResults.map((r) => {
     const result: SearchResult = {
+      id: r.id,
       title: r.title,
       folder: r.folder,
       preview: generatePreview(r.content),
@@ -276,7 +275,6 @@ export async function searchNotes(
 }
 
 // Re-export types for convenience
-export type { SearchMode as Mode };
 export type { SearchResult } from "../types/index.js";
 
 // Export utility functions for testing

package/src/search/indexer.ts

@@ -13,14 +13,14 @@ import { getAllNotes, getNoteByFolderAndTitle, getNoteByTitle, type NoteInfo } f
 import { createDebugLogger } from "../utils/debug.js";
 import { truncateForEmbedding } from "../utils/text.js";
 import { EMBEDDING_DELAY_MS } from "../config/constants.js";
+import { NoteNotFoundError } from "../errors/index.js";
 
 /**
  * Extract note title from folder/title key.
  * Handles nested folders correctly by taking the last segment.
  */
 export function extractTitleFromKey(key: string): string {
-  const parts = key.split("/");
-  return parts[parts.length - 1];
+  return key.split("/").at(-1) ?? key;
 }
 
 // Debug logging
@@ -98,6 +98,7 @@ export async function fullIndex(): Promise<IndexResult> {
       const vector = await getEmbedding(content);
 
       const record: NoteRecord = {
+        id: noteDetails.id,
         title: noteDetails.title,
         content: noteDetails.content,
         vector,
@@ -234,6 +235,7 @@ export async function incrementalIndex(): Promise<IndexResult> {
       const vector = await getEmbedding(content);
 
       const record: NoteRecord = {
+        id: noteDetails.id,
         title: noteDetails.title,
         content: noteDetails.content,
         vector,
@@ -270,6 +272,12 @@ export async function incrementalIndex(): Promise<IndexResult> {
     }
   }
 
+  // Rebuild FTS index if any changes were made
+  if (toAdd.length > 0 || toUpdate.length > 0 || toDelete.length > 0) {
+    debug("Rebuilding FTS index after incremental changes");
+    await store.rebuildFtsIndex();
+  }
+
   const timeMs = Date.now() - startTime;
   debug(`Incremental index complete: ${timeMs}ms`);
 
@@ -296,7 +304,7 @@ export async function reindexNote(title: string): Promise<void> {
 
   const noteDetails = await getNoteByTitle(title);
   if (!noteDetails) {
-    throw new Error(`Note not found: "${title}"`);
+    throw new NoteNotFoundError(title);
   }
 
   if (!noteDetails.content.trim()) {
@@ -307,6 +315,7 @@ export async function reindexNote(title: string): Promise<void> {
   const vector = await getEmbedding(content);
 
   const record: NoteRecord = {
+    id: noteDetails.id,
     title: noteDetails.title,
     content: noteDetails.content,
     vector,
@@ -319,6 +328,10 @@ export async function reindexNote(title: string): Promise<void> {
   const store = getVectorStore();
   await store.update(record);
 
+  // Rebuild FTS index after single note update
+  debug("Rebuilding FTS index after single note reindex");
+  await store.rebuildFtsIndex();
+
   debug(`Reindexed: ${title}`);
 }
 

package/src/types/index.ts

@@ -7,6 +7,8 @@
  * Contains the full content of the note.
  */
 export interface DBSearchResult {
+  /** Apple Notes unique identifier */
+  id?: string;
   /** Note title */
   title: string;
   /** Folder containing the note */
@@ -24,6 +26,8 @@ export interface DBSearchResult {
  * Contains a preview instead of full content by default.
  */
 export interface SearchResult {
+  /** Apple Notes unique identifier */
+  id?: string;
   /** Note title */
   title: string;
   /** Folder containing the note */

package/src/utils/debug.ts

@@ -10,8 +10,6 @@ const COLORS = {
   dim: "\x1b[2m",
   cyan: "\x1b[36m",
   yellow: "\x1b[33m",
-  red: "\x1b[31m",
-  green: "\x1b[32m",
 } as const;
 
 /**

package/src/utils/text.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { truncateForEmbedding } from "./text.js";
+import { MAX_INPUT_LENGTH } from "../config/constants.js";
+
+describe("truncateForEmbedding", () => {
+  it("should return text unchanged if within limit", () => {
+    const text = "Short text";
+    expect(truncateForEmbedding(text)).toBe(text);
+  });
+
+  it("should truncate text exceeding default limit", () => {
+    const text = "a".repeat(MAX_INPUT_LENGTH + 100);
+    const result = truncateForEmbedding(text);
+    expect(result.length).toBe(MAX_INPUT_LENGTH);
+    expect(result).toBe("a".repeat(MAX_INPUT_LENGTH));
+  });
+
+  it("should use custom maxLength when provided", () => {
+    const text = "Hello World";
+    const result = truncateForEmbedding(text, 5);
+    expect(result).toBe("Hello");
+  });
+
+  it("should handle empty string", () => {
+    expect(truncateForEmbedding("")).toBe("");
+  });
+
+  it("should handle text exactly at limit", () => {
+    const text = "a".repeat(MAX_INPUT_LENGTH);
+    expect(truncateForEmbedding(text)).toBe(text);
+  });
+});

package/CLAUDE.md

@@ -1,56 +0,0 @@
-# CLAUDE.md
-
-## Project Overview
-
-MCP server for Apple Notes with semantic search and CRUD operations.
-
-## Tech Stack
-
-- **Runtime**: Bun
-- **Language**: TypeScript
-- **Database**: LanceDB (vector store)
-- **Embeddings**: HuggingFace Transformers (local) or OpenRouter API
-- **Apple Notes**: JXA (JavaScript for Automation)
-
-## Commands
-
-```bash
-bun run start      # Start MCP server
-bun run setup      # Interactive setup wizard
-bun run dev        # Watch mode
-bun run check      # Type check
-bun run test       # Run tests (uses vitest, NOT bun test)
-```
-
-## Project Structure
-
-```
-src/
-├── index.ts          # MCP server entry (stdio transport)
-├── server.ts         # Smithery-compatible export
-├── setup.ts          # Interactive setup wizard
-├── config/           # Constants and env validation
-├── db/               # LanceDB vector store
-├── embeddings/       # Local and OpenRouter embeddings
-├── notes/            # Apple Notes CRUD via JXA
-├── search/           # Hybrid search and indexing
-└── utils/            # Debug logging, errors, text utils
-```
-
-## Key Patterns
-
-- **Dual embedding support**: Detects `OPENROUTER_API_KEY` to choose provider
-- **Hybrid search**: Combines vector + keyword search with RRF fusion
-- **Incremental indexing**: Only re-embeds changed notes
-- **Folder/title disambiguation**: Use `Folder/Note Title` format for duplicates
-
-## Testing
-
-Always use `bun run test` (vitest), never `bun test` (incompatible bun runner).
-
-## Environment Variables
-
-See README.md for full list. Key ones:
-- `OPENROUTER_API_KEY` - Enables cloud embeddings
-- `READONLY_MODE` - Blocks write operations
-- `DEBUG` - Enables debug logging