apple-notes-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages Apple Notes through natural language.

Commands

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)
bun run test:watch # Watch mode for tests

Important: Always use bun run test (vitest), never bun test (Bun's test runner is incompatible).

Architecture

Data Flow

User Query → MCP Server → Search Module → Embeddings → LanceDB → Results
                ↓
           Apple Notes ← JXA (JavaScript for Automation)

Entry Point

• src/index.ts - Main MCP server with stdio transport for Claude Code

Core Modules

Search Pipeline (src/search/)

• index.ts - Legacy hybrid search using Reciprocal Rank Fusion (RRF)
• indexer.ts - Full and incremental indexing with indexed_at timestamp tracking
• chunk-indexer.ts - Chunk-based indexing for Parent Document Retriever pattern
• chunk-search.ts - Chunk search with note deduplication (keeps best chunk per note)

Embedding Providers (src/embeddings/)

• Auto-detection: checks OPENROUTER_API_KEY to choose provider
• local.ts - HuggingFace Transformers with Xenova/multilingual-e5-small
• openrouter.ts - Cloud API via OpenRouter

Vector Store (src/db/lancedb.ts)

• Singleton LanceDBStore with FTS index on content
• Storage path: ~/.apple-notes-mcp/data
• Schema: NoteRecord with vector, content, indexed_at fields

Apple Notes Access (src/notes/)

• read.ts - JXA queries via run-jxa
• resolve.ts - Note title disambiguation logic
• conversion.ts - HTML→Markdown via Turndown
• crud.ts - Create, update, delete, move operations (respects READONLY_MODE)
• tables.ts - Table HTML parsing and cell editing