@disco_trooper/apple-notes-mcp 1.0.0

package/src/setup.ts

@@ -0,0 +1,540 @@
+#!/usr/bin/env bun
+/**
+ * Setup wizard for apple-notes-mcp
+ *
+ * Interactive CLI for configuring:
+ * - Embedding provider (Local HuggingFace / OpenRouter)
+ * - API keys
+ * - Read-only mode
+ * - Auto-indexing settings
+ * - Claude Code integration
+ */
+
+import * as p from "@clack/prompts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+// Paths
+const PROJECT_DIR = path.dirname(new URL(import.meta.url).pathname);
+const ENV_FILE = path.join(PROJECT_DIR, "..", ".env");
+const CLAUDE_CONFIG_PATH = path.join(
+  process.env.HOME || "~",
+  ".claude.json"
+);
+
+interface Config {
+  provider: "local" | "openrouter";
+  openrouterApiKey?: string;
+  embeddingModel?: string;
+  embeddingDims?: number;
+  readonlyMode: boolean;
+  autoIndex: "none" | "on-search" | "ttl";
+  indexTtl?: number;
+  debug: boolean;
+}
+
+/**
+ * Read existing .env file if it exists
+ */
+function readExistingEnv(): Record<string, string> {
+  if (!fs.existsSync(ENV_FILE)) {
+    return {};
+  }
+
+  const content = fs.readFileSync(ENV_FILE, "utf-8");
+  const env: Record<string, string> = {};
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex);
+    let value = trimmed.slice(eqIndex + 1);
+
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    env[key] = value;
+  }
+
+  return env;
+}
+
+/**
+ * Write configuration to .env file
+ */
+function writeEnvFile(config: Config): void {
+  const lines: string[] = [
+    "# apple-notes-mcp configuration",
+    "# Generated by setup wizard",
+    "",
+  ];
+
+  if (config.provider === "openrouter") {
+    lines.push("# Embedding provider: OpenRouter");
+    if (config.openrouterApiKey) {
+      lines.push(`OPENROUTER_API_KEY="${config.openrouterApiKey}"`);
+    }
+    if (config.embeddingModel) {
+      lines.push(`EMBEDDING_MODEL="${config.embeddingModel}"`);
+    }
+    if (config.embeddingDims) {
+      lines.push(`EMBEDDING_DIMS="${config.embeddingDims}"`);
+    }
+  } else {
+    lines.push("# Embedding provider: Local HuggingFace");
+    lines.push("# No OPENROUTER_API_KEY = uses local embeddings");
+  }
+
+  lines.push("");
+
+  if (config.readonlyMode) {
+    lines.push("# Read-only mode (no write operations)");
+    lines.push("READONLY_MODE=true");
+  }
+
+  lines.push("");
+
+  if (config.autoIndex === "ttl" && config.indexTtl) {
+    lines.push("# Auto-index TTL in seconds");
+    lines.push(`INDEX_TTL=${config.indexTtl}`);
+  }
+
+  if (config.debug) {
+    lines.push("");
+    lines.push("# Debug logging");
+    lines.push("DEBUG=true");
+  }
+
+  fs.writeFileSync(ENV_FILE, lines.join("\n") + "\n");
+}
+
+/**
+ * Read Claude Code config if it exists
+ */
+function readClaudeConfig(): Record<string, unknown> | null {
+  if (!fs.existsSync(CLAUDE_CONFIG_PATH)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(CLAUDE_CONFIG_PATH, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    // Config doesn't exist or is invalid JSON
+    if (process.env.DEBUG === "true") {
+      console.error("[SETUP] Could not read Claude config:", error);
+    }
+    return null;
+  }
+}
+
+/**
+ * Add MCP server to Claude Code config
+ */
+function addToClaudeConfig(): boolean {
+  const projectPath = path.resolve(PROJECT_DIR, "..");
+  const serverEntry = {
+    command: "bun",
+    args: ["run", path.join(projectPath, "src", "index.ts")],
+    env: {},
+  };
+
+  let config = readClaudeConfig();
+
+  if (!config) {
+    // Create new config
+    config = {
+      mcpServers: {
+        "apple-notes": serverEntry,
+      },
+    };
+  } else {
+    // Add to existing config
+    const mcpServers = (config.mcpServers || {}) as Record<string, unknown>;
+    mcpServers["apple-notes"] = serverEntry;
+    config.mcpServers = mcpServers;
+  }
+
+  try {
+    fs.writeFileSync(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+    return true;
+  } catch (error) {
+    if (process.env.DEBUG === "true") {
+      console.error("[SETUP] Failed to write Claude config:", error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Generate config snippet for manual setup
+ */
+function getConfigSnippet(): string {
+  const projectPath = path.resolve(PROJECT_DIR, "..");
+  return JSON.stringify(
+    {
+      "apple-notes": {
+        command: "bun",
+        args: ["run", path.join(projectPath, "src", "index.ts")],
+        env: {},
+      },
+    },
+    null,
+    2
+  );
+}
+
+/**
+ * Run indexing with specified mode
+ */
+async function runIndexing(mode: "full" | "incremental"): Promise<{ count: number; timeMs: number; skipped?: number }> {
+  // Dynamic import to avoid loading embeddings before config is set
+  const { indexNotes } = await import("./search/indexer.js");
+  const result = await indexNotes(mode);
+  return {
+    count: result.indexed,
+    timeMs: result.timeMs,
+    skipped: result.breakdown?.skipped,
+  };
+}
+
+/**
+ * Download local model (warm up the pipeline)
+ */
+async function downloadLocalModel(): Promise<void> {
+  const { getLocalEmbedding } = await import("./embeddings/local.js");
+  // Generate a test embedding to trigger model download
+  await getLocalEmbedding("test");
+}
+
+/**
+ * Main setup wizard
+ */
+async function main(): Promise<void> {
+  console.clear();
+
+  p.intro("apple-notes-mcp Setup Wizard");
+
+  // Check existing configuration
+  const existingEnv = readExistingEnv();
+  const hasExistingConfig = Object.keys(existingEnv).length > 0;
+
+  if (hasExistingConfig) {
+    p.note(
+      "Existing configuration found in .env\n" +
+      "Your current settings will be shown as defaults.",
+      "Configuration Detected"
+    );
+  }
+
+  // Provider selection
+  const provider = await p.select({
+    message: "Which embedding provider would you like to use?",
+    options: [
+      {
+        value: "local",
+        label: "Local (HuggingFace)",
+        hint: "Free, runs on your machine, ~200MB model download",
+      },
+      {
+        value: "openrouter",
+        label: "OpenRouter API",
+        hint: "Fast, requires API key, pay-per-use",
+      },
+    ],
+    initialValue: existingEnv.OPENROUTER_API_KEY ? "openrouter" : "local",
+  });
+
+  if (p.isCancel(provider)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  let openrouterApiKey: string | undefined;
+  let embeddingModel: string | undefined;
+  let embeddingDims: number | undefined;
+
+  if (provider === "openrouter") {
+    const apiKey = await p.text({
+      message: "Enter your OpenRouter API key:",
+      placeholder: "sk-or-v1-...",
+      initialValue: existingEnv.OPENROUTER_API_KEY || "",
+      validate: (value) => {
+        if (!value.trim()) return "API key is required";
+        if (!value.startsWith("sk-or-")) return "Invalid API key format (should start with sk-or-)";
+      },
+    });
+
+    if (p.isCancel(apiKey)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    openrouterApiKey = apiKey;
+
+    const useCustomModel = await p.confirm({
+      message: "Use custom embedding model? (default: qwen/qwen3-embedding-8b)",
+      initialValue: false,
+    });
+
+    if (p.isCancel(useCustomModel)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    if (useCustomModel) {
+      const model = await p.text({
+        message: "Enter model name:",
+        placeholder: "qwen/qwen3-embedding-8b",
+        initialValue: existingEnv.EMBEDDING_MODEL || "qwen/qwen3-embedding-8b",
+      });
+
+      if (p.isCancel(model)) {
+        p.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+
+      embeddingModel = model;
+
+      const dims = await p.text({
+        message: "Enter embedding dimensions:",
+        placeholder: "4096",
+        initialValue: existingEnv.EMBEDDING_DIMS || "4096",
+        validate: (value) => {
+          const num = parseInt(value, 10);
+          if (isNaN(num) || num <= 0) return "Must be a positive number";
+        },
+      });
+
+      if (p.isCancel(dims)) {
+        p.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+
+      embeddingDims = parseInt(dims, 10);
+    }
+  }
+
+  // Read-only mode
+  const readonlyMode = await p.confirm({
+    message: "Enable read-only mode? (prevents all write operations to Apple Notes)",
+    initialValue: existingEnv.READONLY_MODE === "true",
+  });
+
+  if (p.isCancel(readonlyMode)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  // Auto-indexing
+  const autoIndex = await p.select({
+    message: "Auto-indexing mode:",
+    options: [
+      {
+        value: "none",
+        label: "Manual only",
+        hint: "Run index-notes manually when needed",
+      },
+      {
+        value: "ttl",
+        label: "Time-based (TTL)",
+        hint: "Auto-reindex after specified time",
+      },
+    ],
+    initialValue: existingEnv.INDEX_TTL ? "ttl" : "none",
+  });
+
+  if (p.isCancel(autoIndex)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  let indexTtl: number | undefined;
+
+  if (autoIndex === "ttl") {
+    const ttl = await p.select({
+      message: "Reindex after:",
+      options: [
+        { value: "3600", label: "1 hour" },
+        { value: "21600", label: "6 hours" },
+        { value: "86400", label: "24 hours" },
+        { value: "604800", label: "1 week" },
+      ],
+      initialValue: existingEnv.INDEX_TTL || "86400",
+    });
+
+    if (p.isCancel(ttl)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    indexTtl = parseInt(ttl, 10);
+  }
+
+  // Debug mode
+  const debug = await p.confirm({
+    message: "Enable debug logging?",
+    initialValue: existingEnv.DEBUG === "true",
+  });
+
+  if (p.isCancel(debug)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  // Build configuration
+  const config: Config = {
+    provider: provider as "local" | "openrouter",
+    openrouterApiKey,
+    embeddingModel,
+    embeddingDims,
+    readonlyMode,
+    autoIndex: autoIndex as "none" | "ttl",
+    indexTtl,
+    debug,
+  };
+
+  // Save configuration
+  const s = p.spinner();
+
+  s.start("Saving configuration...");
+  writeEnvFile(config);
+  s.stop("Configuration saved to .env");
+
+  // Download local model if needed
+  if (provider === "local") {
+    const downloadModel = await p.confirm({
+      message: "Download local embedding model now? (~200MB, recommended)",
+      initialValue: true,
+    });
+
+    if (p.isCancel(downloadModel)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    if (downloadModel) {
+      s.start("Downloading embedding model (this may take a minute)...");
+      try {
+        await downloadLocalModel();
+        s.stop("Model downloaded successfully");
+      } catch (error) {
+        s.stop("Model download failed (will download on first use)");
+        p.log.warn(
+          `Download error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
+
+  // Claude Code integration
+  const addToClaude = await p.confirm({
+    message: "Add to Claude Code configuration (~/.claude.json)?",
+    initialValue: true,
+  });
+
+  if (p.isCancel(addToClaude)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  if (addToClaude) {
+    s.start("Updating Claude Code configuration...");
+    const success = addToClaudeConfig();
+    if (success) {
+      s.stop("Added to ~/.claude.json");
+    } else {
+      s.stop("Failed to update Claude config");
+      p.log.warn("You may need to add the server manually.");
+      p.note(getConfigSnippet(), "Add this to mcpServers in ~/.claude.json");
+    }
+  } else {
+    p.note(getConfigSnippet(), "Add this to mcpServers in ~/.claude.json");
+  }
+
+  // Initial indexing
+  const runIndex = await p.confirm({
+    message: "Index your Apple Notes now?",
+    initialValue: true,
+  });
+
+  if (p.isCancel(runIndex)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  if (runIndex) {
+    // Ask for indexing mode
+    const indexMode = await p.select({
+      message: "Indexing mode:",
+      options: [
+        { value: "incremental", label: "Incremental", hint: "Only new/changed notes (faster)" },
+        { value: "full", label: "Full", hint: "Reindex everything (slower)" },
+      ],
+      initialValue: "incremental",
+    });
+
+    if (p.isCancel(indexMode)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    const mode = indexMode as "full" | "incremental";
+    const indexingMsg = `${mode === "full" ? "Full" : "Incremental"} indexing...`;
+
+    // Don't use spinner in debug mode - it conflicts with debug output
+    if (!debug) {
+      s.start(indexingMsg);
+    } else {
+      p.log.info(indexingMsg);
+    }
+
+    try {
+      // Reload environment with new config
+      const dotenv = await import("dotenv");
+      dotenv.config({ path: ENV_FILE });
+
+      const result = await runIndexing(mode);
+      const skippedInfo = result.skipped ? `, ${result.skipped} unchanged` : "";
+      const doneMsg = `Indexed ${result.count} notes in ${(result.timeMs / 1000).toFixed(1)}s${skippedInfo}`;
+
+      if (!debug) {
+        s.stop(doneMsg);
+      } else {
+        p.log.success(doneMsg);
+      }
+    } catch (error) {
+      if (!debug) {
+        s.stop("Indexing failed");
+      }
+      p.log.error(
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+      p.log.info("You can run indexing later with the index-notes tool.");
+    }
+  }
+
+  // Summary
+  p.note(
+    [
+      `Provider: ${provider === "local" ? "Local HuggingFace" : "OpenRouter"}`,
+      `Read-only: ${readonlyMode ? "Yes" : "No"}`,
+      `Auto-index: ${autoIndex === "ttl" ? `Every ${indexTtl! / 3600}h` : "Manual"}`,
+      `Debug: ${debug ? "Enabled" : "Disabled"}`,
+    ].join("\n"),
+    "Configuration Summary"
+  );
+
+  p.outro("Setup complete! Restart Claude Code to use apple-notes-mcp.");
+}
+
+main().catch((error) => {
+  console.error("Setup failed:", error);
+  process.exit(1);
+});

package/src/types/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared type definitions for Apple Notes MCP.
+ */
+
+/**
+ * Search result returned from the database layer.
+ * Contains the full content of the note.
+ */
+export interface DBSearchResult {
+  /** Note title */
+  title: string;
+  /** Folder containing the note */
+  folder: string;
+  /** Full content of the note */
+  content: string;
+  /** Last modified date (ISO string) */
+  modified: string;
+  /** Relevance score (higher = more relevant) */
+  score: number;
+}
+
+/**
+ * Search result returned to clients.
+ * Contains a preview instead of full content by default.
+ */
+export interface SearchResult {
+  /** Note title */
+  title: string;
+  /** Folder containing the note */
+  folder: string;
+  /** Preview of content (200 chars) or full content if include_content=true */
+  preview: string;
+  /** Full content (only when include_content=true) */
+  content?: string;
+  /** Last modified date (ISO string) */
+  modified: string;
+  /** Combined relevance score (higher = more relevant) */
+  score: number;
+}

package/src/utils/debug.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+describe("debug utility", () => {
+  const originalEnv = process.env.DEBUG;
+
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.DEBUG = originalEnv;
+    } else {
+      delete process.env.DEBUG;
+    }
+  });
+
+  it("createDebugLogger returns a function", async () => {
+    const { createDebugLogger } = await import("./debug.js");
+    const logger = createDebugLogger("TEST");
+    expect(typeof logger).toBe("function");
+  });
+
+  it("isDebugEnabled returns false when DEBUG not set", async () => {
+    delete process.env.DEBUG;
+    const { isDebugEnabled } = await import("./debug.js");
+    expect(isDebugEnabled()).toBe(false);
+  });
+
+  it("isDebugEnabled returns true when DEBUG is true", async () => {
+    process.env.DEBUG = "true";
+    const { isDebugEnabled } = await import("./debug.js");
+    expect(isDebugEnabled()).toBe(true);
+  });
+
+  it("isDebugEnabled returns false when DEBUG is false", async () => {
+    process.env.DEBUG = "false";
+    const { isDebugEnabled } = await import("./debug.js");
+    expect(isDebugEnabled()).toBe(false);
+  });
+});

package/src/utils/debug.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared debug logging utility.
+ * Logs to stderr to avoid polluting stdout/MCP protocol.
+ * Uses dim styling to distinguish from errors.
+ */
+
+// ANSI color codes
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+} as const;
+
+/**
+ * Create a debug logger with a specific prefix.
+ * Checks DEBUG env var at call time for runtime control.
+ * Output is dim cyan to distinguish from errors.
+ */
+export function createDebugLogger(prefix: string) {
+  return (...args: unknown[]): void => {
+    // Check at call time, not load time
+    if (process.env.DEBUG === "true") {
+      const formattedPrefix = `${COLORS.dim}${COLORS.cyan}[${prefix}]${COLORS.reset}`;
+      const formattedArgs = args.map(arg =>
+        typeof arg === "string" ? `${COLORS.dim}${arg}${COLORS.reset}` : arg
+      );
+      console.error(formattedPrefix, ...formattedArgs);
+    }
+  };
+}
+
+/**
+ * Create a warning logger (yellow output).
+ */
+export function createWarningLogger(prefix: string) {
+  return (...args: unknown[]): void => {
+    const formattedPrefix = `${COLORS.yellow}[${prefix}]${COLORS.reset}`;
+    console.error(formattedPrefix, ...args);
+  };
+}
+
+/**
+ * Check if debug mode is enabled.
+ * Checks at call time for runtime control.
+ */
+export function isDebugEnabled(): boolean {
+  return process.env.DEBUG === "true";
+}

package/src/utils/errors.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeErrorMessage } from "./errors.js";
+
+describe("sanitizeErrorMessage", () => {
+  it("preserves user-friendly messages", () => {
+    expect(sanitizeErrorMessage("Note not found")).toBe("Note not found");
+    expect(sanitizeErrorMessage("Invalid title")).toBe("Invalid title");
+  });
+
+  it("removes file paths", () => {
+    const error = "ENOENT: no such file at /Users/john/secret/file.ts";
+    expect(sanitizeErrorMessage(error)).not.toContain("/Users/john");
+  });
+
+  it("removes stack traces", () => {
+    const error = "Error: failed\n    at Function.module (/path/to/file.js:123:45)";
+    expect(sanitizeErrorMessage(error)).not.toContain("/path/to");
+  });
+
+  it("handles generic errors gracefully", () => {
+    const error = "TypeError: Cannot read property 'x' of undefined";
+    expect(sanitizeErrorMessage(error)).toBe("An internal error occurred");
+  });
+
+  it("preserves known safe error patterns", () => {
+    expect(sanitizeErrorMessage("Title must be a non-empty string")).toBe("Title must be a non-empty string");
+    expect(sanitizeErrorMessage("Note not found: \"My Note\"")).toBe("Note not found: \"My Note\"");
+  });
+});