@disco_trooper/apple-notes-mcp 1.2.0 → 1.4.0

package/src/setup.ts

@@ -12,14 +12,23 @@
 
 import * as p from "@clack/prompts";
 import * as fs from "node:fs";
-import * as path from "node:path";
+import {
+  getEnvPath,
+  ensureConfigDir,
+  hasLegacyConfig,
+  getLegacyEnvPath,
+  hasConfig,
+  isNpmInstall,
+} from "./config/paths.js";
+import {
+  getClaudeConfigEntry,
+  writeClaudeConfig,
+  getExistingInstallMethod,
+} from "./config/claude.js";
+import { checkBunRuntime } from "./utils/runtime.js";
+
 // 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"
-);
+const ENV_FILE = getEnvPath();
 
 interface Config {
   provider: "local" | "openrouter";
@@ -69,6 +78,7 @@ function readExistingEnv(): Record<string, string> {
  * Write configuration to .env file
  */
 function writeEnvFile(config: Config): void {
+  ensureConfigDir();
   const lines: string[] = [
     "# apple-notes-mcp configuration",
     "# Generated by setup wizard",
@@ -114,80 +124,29 @@ function writeEnvFile(config: Config): void {
   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: {},
-  };
+  const entry = getClaudeConfigEntry();
 
-  let config = readClaudeConfig();
+  // Check for install method change
+  const existingMethod = getExistingInstallMethod();
+  const currentMethod = isNpmInstall() ? "npm" : "source";
 
-  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;
+  if (existingMethod && existingMethod !== currentMethod) {
+    p.log.info(`Updating Claude config from ${existingMethod} to ${currentMethod} installation`);
   }
 
-  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;
-  }
+  return writeClaudeConfig(entry);
 }
 
 /**
  * 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
-  );
+  const entry = getClaudeConfigEntry();
+  return JSON.stringify({ "apple-notes": entry }, null, 2);
 }
 
 /**
@@ -217,6 +176,7 @@ async function downloadLocalModel(): Promise<void> {
  * Main setup wizard
  */
 async function main(): Promise<void> {
+  checkBunRuntime();
   console.clear();
 
   p.intro("apple-notes-mcp Setup Wizard");
@@ -233,6 +193,25 @@ async function main(): Promise<void> {
     );
   }
 
+  // Check for legacy config migration
+  if (hasLegacyConfig() && !hasConfig()) {
+    const migrate = await p.confirm({
+      message: "Found config in project directory. Migrate to ~/.apple-notes-mcp/?",
+      initialValue: true,
+    });
+
+    if (p.isCancel(migrate)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    if (migrate) {
+      ensureConfigDir();
+      fs.copyFileSync(getLegacyEnvPath(), getEnvPath());
+      p.log.success("Config migrated to ~/.apple-notes-mcp/.env");
+    }
+  }
+
   // Provider selection
   const provider = await p.select({
     message: "Which embedding provider would you like to use?",

package/src/utils/chunker.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import {
+  chunkText,
+  type ChunkOptions,
+  DEFAULT_CHUNK_OPTIONS,
+  SEPARATORS,
+  findSplitPoint,
+} from "./chunker.js";
+
+describe("chunker", () => {
+  describe("exports", () => {
+    it("exports SEPARATORS array with correct order", () => {
+      expect(SEPARATORS).toEqual([
+        "\n\n",
+        "\n",
+        ". ",
+        "! ",
+        "? ",
+        "; ",
+        ", ",
+        " ",
+        "",
+      ]);
+    });
+
+    it("exports DEFAULT_CHUNK_OPTIONS with correct values", () => {
+      expect(DEFAULT_CHUNK_OPTIONS).toEqual({
+        chunkSize: 500,
+        overlap: 100,
+      });
+    });
+  });
+
+  describe("findSplitPoint", () => {
+    it("finds paragraph boundary near target", () => {
+      const text = "First paragraph.\n\nSecond paragraph.";
+      const target = 20;
+      const result = findSplitPoint(text, target);
+      // Should find the \n\n at position 16
+      expect(result).toBe(18); // After \n\n
+    });
+
+    it("falls back to sentence boundary", () => {
+      const text = "First sentence. Second sentence.";
+      const target = 18;
+      const result = findSplitPoint(text, target);
+      // Should find ". " at position 14-16
+      expect(result).toBe(16); // After ". "
+    });
+
+    it("falls back to word boundary", () => {
+      const text = "oneword anotherword";
+      const target = 10;
+      const result = findSplitPoint(text, target);
+      // Should find space at position 7
+      expect(result).toBe(8); // After " "
+    });
+
+    it("returns target when no separator found", () => {
+      const text = "noseparatorshere";
+      const target = 8;
+      const result = findSplitPoint(text, target);
+      expect(result).toBe(8);
+    });
+  });
+
+  describe("chunkText", () => {
+    it("returns single chunk for short text", () => {
+      const text = "Short text";
+      const options: ChunkOptions = { chunkSize: 100, overlap: 20 };
+
+      const result = chunkText(text, options);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual({
+        content: "Short text",
+        index: 0,
+        totalChunks: 1,
+        startPos: 0,
+        endPos: 10,
+      });
+    });
+
+    it("creates multiple chunks for long text", () => {
+      const text = "Word ".repeat(50).trim(); // 249 chars
+      const options: ChunkOptions = { chunkSize: 50, overlap: 10 };
+
+      const result = chunkText(text, options);
+
+      expect(result.length).toBeGreaterThan(1);
+      // Each chunk should have content
+      result.forEach((chunk) => {
+        expect(chunk.content.length).toBeGreaterThan(0);
+        expect(chunk.content.length).toBeLessThanOrEqual(options.chunkSize);
+      });
+    });
+
+    it("includes overlap between chunks", () => {
+      const text = "First part. Second part. Third part. Fourth part.";
+      const options: ChunkOptions = { chunkSize: 25, overlap: 10 };
+
+      const result = chunkText(text, options);
+
+      // Check that chunks overlap - endPos of chunk N should be > startPos of chunk N+1
+      for (let i = 0; i < result.length - 1; i++) {
+        const currentChunk = result[i];
+        const nextChunk = result[i + 1];
+        // Overlap means next chunk starts before current chunk ends
+        expect(nextChunk.startPos).toBeLessThan(currentChunk.endPos);
+      }
+    });
+
+    it("respects paragraph boundaries when splitting", () => {
+      const text = "First paragraph here.\n\nSecond paragraph here.\n\nThird paragraph.";
+      const options: ChunkOptions = { chunkSize: 30, overlap: 5 };
+
+      const result = chunkText(text, options);
+
+      // At least one chunk should end at a paragraph boundary
+      const hasParaBoundary = result.some((chunk) => {
+        const endContent = text.slice(chunk.startPos, chunk.endPos);
+        return endContent.endsWith("\n\n") || chunk.endPos === text.length;
+      });
+      expect(hasParaBoundary).toBe(true);
+    });
+
+    it("sets correct totalChunks on all chunks", () => {
+      const text = "A ".repeat(100).trim(); // Create text that will be chunked
+      const options: ChunkOptions = { chunkSize: 20, overlap: 5 };
+
+      const result = chunkText(text, options);
+
+      const expectedTotal = result.length;
+      result.forEach((chunk, idx) => {
+        expect(chunk.totalChunks).toBe(expectedTotal);
+        expect(chunk.index).toBe(idx);
+      });
+    });
+
+    it("handles empty text", () => {
+      const result = chunkText("", { chunkSize: 100, overlap: 20 });
+
+      expect(result).toHaveLength(0);
+    });
+
+    it("handles whitespace-only text", () => {
+      const result = chunkText("   \n\n   ", { chunkSize: 100, overlap: 20 });
+
+      expect(result).toHaveLength(0);
+    });
+
+    it("uses default options when not provided", () => {
+      const text = "Test";
+      const result = chunkText(text);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].content).toBe("Test");
+    });
+
+    it("covers all original text with chunks", () => {
+      const text = "The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.";
+      const options: ChunkOptions = { chunkSize: 30, overlap: 10 };
+
+      const result = chunkText(text, options);
+
+      // Verify chunks cover the entire text
+      expect(result[0].startPos).toBe(0);
+      expect(result[result.length - 1].endPos).toBe(text.length);
+
+      // Verify each chunk's content matches its position in original text
+      for (const chunk of result) {
+        expect(chunk.content).toBe(text.slice(chunk.startPos, chunk.endPos));
+      }
+
+      // Verify chunks are contiguous (no gaps)
+      for (let i = 0; i < result.length - 1; i++) {
+        // Next chunk should start before or at current chunk's end (overlap)
+        expect(result[i + 1].startPos).toBeLessThanOrEqual(result[i].endPos);
+      }
+    });
+  });
+});

package/src/utils/chunker.ts

@@ -0,0 +1,170 @@
+/**
+ * Text chunker with recursive character splitting that respects natural boundaries.
+ * Prioritizes splitting at: paragraphs > sentences > words > characters
+ */
+
+/**
+ * Separators in priority order - prefer splitting at larger boundaries first
+ */
+export const SEPARATORS = [
+  "\n\n", // Paragraph
+  "\n", // Line
+  ". ", // Sentence (period)
+  "! ", // Sentence (exclamation)
+  "? ", // Sentence (question)
+  "; ", // Clause
+  ", ", // Phrase
+  " ", // Word
+  "", // Character (fallback)
+] as const;
+
+export interface ChunkOptions {
+  /** Maximum size of each chunk in characters */
+  chunkSize: number;
+  /** Number of characters to overlap between chunks */
+  overlap: number;
+}
+
+export interface ChunkResult {
+  /** The text content of this chunk */
+  content: string;
+  /** Zero-based index of this chunk */
+  index: number;
+  /** Total number of chunks */
+  totalChunks: number;
+  /** Start position in original text */
+  startPos: number;
+  /** End position in original text (exclusive) */
+  endPos: number;
+}
+
+export const DEFAULT_CHUNK_OPTIONS: ChunkOptions = {
+  chunkSize: 500,
+  overlap: 100,
+};
+
+/**
+ * Find the best split point near the target position.
+ * Searches for separators in priority order within a reasonable range.
+ *
+ * @param text - The full text to search in
+ * @param target - The target position to split near
+ * @returns The best split position (after the separator)
+ */
+export function findSplitPoint(text: string, target: number): number {
+  // Search window: look backwards and forwards from target
+  const searchWindow = Math.min(50, Math.floor(target / 2));
+  const searchStart = Math.max(0, target - searchWindow);
+  const searchEnd = Math.min(text.length, target + searchWindow);
+  const searchText = text.slice(searchStart, searchEnd);
+
+  // Try each separator in priority order
+  for (const sep of SEPARATORS) {
+    if (sep === "") continue; // Skip empty string fallback for now
+
+    // Find all occurrences of separator in search window
+    let bestPos = -1;
+    let bestDistance = Infinity;
+
+    let idx = 0;
+    while ((idx = searchText.indexOf(sep, idx)) !== -1) {
+      const absolutePos = searchStart + idx + sep.length;
+      const distance = Math.abs(absolutePos - target);
+
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        bestPos = absolutePos;
+      }
+      idx += 1;
+    }
+
+    if (bestPos !== -1) {
+      return bestPos;
+    }
+  }
+
+  // No separator found, return target as-is
+  return target;
+}
+
+/**
+ * Split text into overlapping chunks that respect natural boundaries.
+ *
+ * @param text - The text to chunk
+ * @param options - Chunk size and overlap options
+ * @returns Array of chunk results
+ */
+export function chunkText(
+  text: string,
+  options: ChunkOptions = DEFAULT_CHUNK_OPTIONS
+): ChunkResult[] {
+  const { chunkSize, overlap } = options;
+
+  // Handle empty or whitespace-only text
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+
+  // If text fits in a single chunk, return it
+  if (text.length <= chunkSize) {
+    return [
+      {
+        content: text,
+        index: 0,
+        totalChunks: 1,
+        startPos: 0,
+        endPos: text.length,
+      },
+    ];
+  }
+
+  const chunks: ChunkResult[] = [];
+  let startPos = 0;
+  // Minimum step size to ensure progress and avoid tiny chunks
+  const minStep = Math.max(1, chunkSize - overlap);
+
+  while (startPos < text.length) {
+    // Calculate target end position
+    let endPos = Math.min(startPos + chunkSize, text.length);
+
+    // If not at the end, find a good split point
+    if (endPos < text.length) {
+      const splitPoint = findSplitPoint(text, endPos);
+      // Only use split point if it creates a reasonably sized chunk
+      if (
+        splitPoint > startPos + minStep / 2 &&
+        splitPoint - startPos <= chunkSize * 1.2
+      ) {
+        endPos = splitPoint;
+      }
+    }
+
+    // Extract chunk content
+    const content = text.slice(startPos, endPos);
+
+    chunks.push({
+      content,
+      index: chunks.length,
+      totalChunks: 0, // Will be set after all chunks are created
+      startPos,
+      endPos,
+    });
+
+    // If we've reached the end, stop
+    if (endPos >= text.length) {
+      break;
+    }
+
+    // Move to next chunk - ensure minimum step for progress
+    startPos = startPos + minStep;
+  }
+
+  // Set totalChunks on all chunks
+  const totalChunks = chunks.length;
+  for (const chunk of chunks) {
+    chunk.totalChunks = totalChunks;
+  }
+
+  return chunks;
+}