@disco_trooper/apple-notes-mcp 1.0.0

package/CLAUDE.md

@@ -0,0 +1,56 @@
+# 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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 disco-trooper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# apple-notes-mcp
+
+MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.
+
+## Features
+
+- **Semantic Search** - Find notes by meaning, not keywords
+- **Hybrid Search** - Combine vector and keyword search for better results
+- **Full CRUD** - Create, read, update, delete, and move notes
+- **Incremental Indexing** - Re-embed only changed notes
+- **Dual Embedding Support** - Local HuggingFace or OpenRouter API
+- **Claude Code Integration** - Works with Claude Code CLI
+
+## Requirements
+
+- macOS (uses Apple Notes via JXA)
+- [Bun](https://bun.sh) runtime
+- Apple Notes app with notes
+
+## Installation
+
+```bash
+git clone https://github.com/disco-trooper/apple-notes-mcp.git
+cd apple-notes-mcp
+bun install
+```
+
+## Quick Start
+
+Run the setup wizard:
+
+```bash
+bun run setup
+```
+
+The wizard:
+1. Chooses your embedding provider (local or OpenRouter)
+2. Configures API keys if needed
+3. Sets auto-indexing preferences
+4. Adds to Claude Code configuration
+5. Indexes your notes
+
+## Configuration
+
+Store configuration in `.env`:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPENROUTER_API_KEY` | OpenRouter API key (enables cloud embeddings) | - |
+| `EMBEDDING_MODEL` | Model name (local or OpenRouter) | `Xenova/multilingual-e5-small` |
+| `EMBEDDING_DIMS` | Embedding dimensions | `4096` |
+| `READONLY_MODE` | Block all write operations | `false` |
+| `INDEX_TTL` | Auto-reindex interval in seconds | - |
+| `DEBUG` | Enable debug logging | `false` |
+
+### Embedding Providers
+
+**Local (default)**: Uses HuggingFace Transformers with `Xenova/multilingual-e5-small`. Free, runs locally, ~200MB download.
+
+**OpenRouter**: Uses cloud API. Fast, requires no local resources, needs API key from [openrouter.ai](https://openrouter.ai).
+
+See [docs/models.md](docs/models.md) for model comparison.
+
+## Tools
+
+### Search & Discovery
+
+#### `search-notes`
+Search notes with hybrid vector + fulltext search.
+
+```
+query: "meeting notes from last week"
+folder: "Work"           # optional, filter by folder
+limit: 10                 # default: 20
+mode: "hybrid"            # hybrid, keyword, or semantic
+include_content: false    # include full content vs preview
+```
+
+#### `list-notes`
+Count indexed notes.
+
+#### `list-folders`
+List all Apple Notes folders.
+
+#### `get-note`
+Get a note's full content by title.
+
+```
+title: "My Note"          # or "Work/My Note" for disambiguation
+```
+
+### Indexing
+
+#### `index-notes`
+Index all notes for semantic search.
+
+```
+mode: "incremental"       # incremental (default) or full
+force: false              # force reindex even if TTL hasn't expired
+```
+
+#### `reindex-note`
+Re-index a single note after manual edits.
+
+```
+title: "My Note"
+```
+
+### CRUD Operations
+
+#### `create-note`
+Create a note in Apple Notes.
+
+```
+title: "New Note"
+content: "# Heading\n\nMarkdown content..."
+folder: "Work"            # optional, defaults to Notes
+```
+
+#### `update-note`
+Update an existing note.
+
+```
+title: "My Note"
+content: "Updated markdown content..."
+reindex: true             # re-embed after update (default: true)
+```
+
+#### `delete-note`
+Delete a note (requires confirmation).
+
+```
+title: "My Note"
+confirm: true             # must be true to delete
+```
+
+#### `move-note`
+Move a note to another folder.
+
+```
+title: "My Note"
+folder: "Archive"
+```
+
+## Claude Code Setup
+
+### Automatic (via setup wizard)
+
+Run `bun run setup` and select "Add to Claude Code configuration".
+
+### Manual
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "apple-notes": {
+      "command": "bun",
+      "args": ["run", "/path/to/apple-notes-mcp/src/index.ts"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Usage Examples
+
+After setup, use natural language with Claude:
+
+- "Search my notes for project ideas"
+- "Create a note called 'Meeting Notes' in the Work folder"
+- "What's in my note about vacation plans?"
+- "Move the 'Old Project' note to Archive"
+- "Index my notes" (after adding notes in Apple Notes)
+
+## Troubleshooting
+
+### "Note not found"
+Use full path format `Folder/Note Title` when multiple notes share the same name.
+
+### Slow first search
+Local embeddings download the model on first use (~200MB). Subsequent searches run fast.
+
+### "READONLY_MODE is enabled"
+Set `READONLY_MODE=false` in `.env` to enable write operations.
+
+### Notes missing from search
+Run `index-notes` to update the search index. Use `mode: full` if incremental misses changes.
+
+### JXA errors
+Ensure Apple Notes runs and contains notes. Grant automation permissions when prompted.
+
+## Development
+
+```bash
+# Type check
+bun run check
+
+# Run with debug logging
+DEBUG=true bun run start
+
+# Watch mode
+bun run dev
+```
+
+## Contributing
+
+PRs welcome! Please:
+- Run `bun run check` before submitting
+- Add tests for new functionality
+- Update documentation as needed
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@disco_trooper/apple-notes-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Apple Notes with semantic search and CRUD operations",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/server.ts",
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "setup": "bun run src/setup.ts",
+    "dev": "bun --watch run src/index.ts",
+    "check": "bun run tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@lancedb/lancedb": "^0.13.0",
+    "@huggingface/transformers": "^3.0.0",
+    "turndown": "^7.2.0",
+    "marked": "^15.0.0",
+    "run-jxa": "^3.0.0",
+    "zod": "^3.24.0",
+    "@clack/prompts": "^0.8.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@smithery/cli": "^3.0.3",
+    "@types/bun": "^1.1.0",
+    "@types/turndown": "^5.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.16"
+  },
+  "keywords": [
+    "mcp",
+    "apple-notes",
+    "semantic-search",
+    "rag",
+    "claude"
+  ],
+  "author": "disco-trooper",
+  "license": "MIT",
+  "bin": {
+    "apple-notes-mcp": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/disco-trooper/apple-notes-mcp"
+  }
+}

package/src/config/constants.ts

@@ -0,0 +1,41 @@
+/**
+ * Application constants extracted from magic numbers throughout the codebase.
+ * Centralizes configuration values for easy maintenance and documentation.
+ */
+
+// Search defaults
+export const DEFAULT_SEARCH_LIMIT = 20;
+export const MAX_SEARCH_LIMIT = 100;
+export const PREVIEW_LENGTH = 200;
+
+// Embedding settings
+export const DEFAULT_LOCAL_EMBEDDING_DIMS = 384;
+export const DEFAULT_OPENROUTER_EMBEDDING_DIMS = 4096;
+export const DEFAULT_OPENROUTER_MODEL = "qwen/qwen3-embedding-8b";
+
+// Vector search
+export const DEFAULT_VECTOR_SEARCH_LIMIT = 50;
+export const RRF_K = 60; // Reciprocal Rank Fusion constant
+
+// Timeouts and retries
+export const OPENROUTER_TIMEOUT_MS = 30000;
+
+// Cache settings
+export const EMBEDDING_CACHE_MAX_SIZE = 1000;
+
+// Input processing
+export const MAX_INPUT_LENGTH = 8000;
+export const MAX_TITLE_LENGTH = 500;
+export const ERROR_MESSAGE_MAX_LENGTH = 200;
+
+// Retry and backoff
+export const MAX_RETRIES = 3;
+export const RATE_LIMIT_BACKOFF_BASE_MS = 2000;
+
+// Indexing
+export const EMBEDDING_DELAY_MS = 300;
+
+// Search tuning
+export const HYBRID_SEARCH_MIN_FETCH = 40;
+export const FOLDER_FILTER_MULTIPLIER = 3;
+export const PREVIEW_TRUNCATE_RATIO = 0.7;

package/src/config/env.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// We need to test validateEnv with different env vars
+// The module reads process.env at import time, so we need dynamic imports
+
+describe("validateEnv", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("accepts valid configuration", async () => {
+    process.env.DEBUG = "true";
+    process.env.READONLY_MODE = "false";
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).not.toThrow();
+  });
+
+  it("accepts empty configuration", async () => {
+    // Clear relevant env vars
+    delete process.env.OPENROUTER_API_KEY;
+    delete process.env.DEBUG;
+    delete process.env.READONLY_MODE;
+    delete process.env.EMBEDDING_DIMS;
+    delete process.env.INDEX_TTL;
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).not.toThrow();
+  });
+
+  it("validates OPENROUTER_API_KEY format", async () => {
+    process.env.OPENROUTER_API_KEY = "invalid-key";
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).toThrow();
+  });
+
+  it("accepts valid OPENROUTER_API_KEY", async () => {
+    process.env.OPENROUTER_API_KEY = "sk-or-valid-key-123";
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).not.toThrow();
+  });
+
+  it("validates EMBEDDING_DIMS is numeric", async () => {
+    process.env.EMBEDDING_DIMS = "not-a-number";
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).toThrow();
+  });
+
+  it("validates DEBUG is boolean string", async () => {
+    process.env.DEBUG = "yes";
+    const { validateEnv } = await import("./env.js");
+    expect(() => validateEnv()).toThrow();
+  });
+});

package/src/config/env.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+const EnvSchema = z.object({
+  OPENROUTER_API_KEY: z.string().startsWith("sk-or-").optional(),
+  EMBEDDING_MODEL: z.string().optional(),
+  EMBEDDING_DIMS: z.string().regex(/^\d+$/).optional(),
+  READONLY_MODE: z.enum(["true", "false"]).optional(),
+  INDEX_TTL: z.string().regex(/^\d+$/).optional(),
+  DEBUG: z.enum(["true", "false"]).optional(),
+});
+
+export type Env = z.infer<typeof EnvSchema>;
+
+export function validateEnv(): Env {
+  const result = EnvSchema.safeParse(process.env);
+
+  if (!result.success) {
+    const errors = result.error.errors
+      .map((e) => `  ${e.path.join(".")}: ${e.message}`)
+      .join("\n");
+    throw new Error(`Invalid environment configuration:\n${errors}`);
+  }
+
+  return result.data;
+}

package/src/db/lancedb.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { LanceDBStore } from "./lancedb.js";
+import type { NoteRecord } from "./lancedb.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+describe("LanceDBStore", () => {
+  let store: LanceDBStore;
+  let testDbPath: string;
+
+  beforeEach(() => {
+    testDbPath = path.join("/tmp", `lancedb-test-${Date.now()}`);
+    store = new LanceDBStore(testDbPath);
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testDbPath)) {
+      fs.rmSync(testDbPath, { recursive: true, force: true });
+    }
+  });
+
+  const createTestRecord = (title: string): NoteRecord => ({
+    title,
+    folder: "Test",
+    content: `Content of ${title}`,
+    modified: new Date().toISOString(),
+    created: new Date().toISOString(),
+    indexed_at: new Date().toISOString(),
+    vector: Array(384).fill(0.1),
+  });
+
+  describe("index and getByTitle", () => {
+    it("indexes and retrieves a record", async () => {
+      const record = createTestRecord("Test Note");
+      await store.index([record]);
+      const retrieved = await store.getByTitle("Test Note");
+      expect(retrieved).not.toBeNull();
+      expect(retrieved?.title).toBe("Test Note");
+    });
+
+    it("returns null for non-existent title", async () => {
+      await store.index([createTestRecord("Other")]); // Initialize table
+      const retrieved = await store.getByTitle("Does Not Exist");
+      expect(retrieved).toBeNull();
+    });
+  });
+
+  describe("count", () => {
+    it("returns correct count", async () => {
+      await store.index([createTestRecord("Note 1"), createTestRecord("Note 2")]);
+      expect(await store.count()).toBe(2);
+    });
+
+    it("returns 0 for empty store", async () => {
+      expect(await store.count()).toBe(0);
+    });
+  });
+
+  describe("delete", () => {
+    it("deletes existing record", async () => {
+      await store.index([createTestRecord("Delete Me")]);
+      await store.delete("Delete Me");
+      const retrieved = await store.getByTitle("Delete Me");
+      expect(retrieved).toBeNull();
+    });
+
+    it("does not throw when deleting non-existent record", async () => {
+      await store.index([createTestRecord("Existing")]);
+      await expect(store.delete("Non Existent")).resolves.not.toThrow();
+    });
+  });
+
+  describe("getAll", () => {
+    it("returns all indexed records", async () => {
+      await store.index([
+        createTestRecord("Note 1"),
+        createTestRecord("Note 2"),
+        createTestRecord("Note 3"),
+      ]);
+      const all = await store.getAll();
+      expect(all).toHaveLength(3);
+      const titles = all.map((r) => r.title);
+      expect(titles).toContain("Note 1");
+      expect(titles).toContain("Note 2");
+      expect(titles).toContain("Note 3");
+    });
+  });
+
+  describe("update", () => {
+    it("updates existing record content", async () => {
+      await store.index([createTestRecord("Update Me")]);
+
+      const updatedRecord = createTestRecord("Update Me");
+      updatedRecord.content = "New updated content";
+      await store.update(updatedRecord);
+
+      const retrieved = await store.getByTitle("Update Me");
+      expect(retrieved?.content).toBe("New updated content");
+    });
+
+    it("adds new record if title does not exist", async () => {
+      await store.index([createTestRecord("Existing")]);
+
+      const newRecord = createTestRecord("New Note");
+      await store.update(newRecord);
+
+      const retrieved = await store.getByTitle("New Note");
+      expect(retrieved).not.toBeNull();
+      expect(retrieved?.title).toBe("New Note");
+    });
+  });
+
+  describe("clear", () => {
+    it("removes all records", async () => {
+      await store.index([
+        createTestRecord("Note 1"),
+        createTestRecord("Note 2"),
+      ]);
+      expect(await store.count()).toBe(2);
+
+      await store.clear();
+      expect(await store.count()).toBe(0);
+    });
+  });
+
+  describe("search", () => {
+    it("returns results based on vector similarity", async () => {
+      await store.index([
+        createTestRecord("Note 1"),
+        createTestRecord("Note 2"),
+      ]);
+
+      const queryVector = Array(384).fill(0.1);
+      const results = await store.search(queryVector, 2);
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toHaveProperty("title");
+      expect(results[0]).toHaveProperty("score");
+    });
+  });
+});