@disco_trooper/apple-notes-mcp 1.1.0 → 1.3.0

package/src/errors/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Typed error classes for better error handling.
+ */
+
+export class NoteNotFoundError extends Error {
+  readonly title: string;
+
+  constructor(title: string) {
+    super(`Note not found: "${title}"`);
+    this.name = "NoteNotFoundError";
+    this.title = title;
+  }
+}
+
+export class ReadOnlyModeError extends Error {
+  constructor() {
+    super("Operation disabled in read-only mode");
+    this.name = "ReadOnlyModeError";
+  }
+}
+
+/**
+ * Rich suggestion for duplicate note disambiguation.
+ */
+export interface NoteSuggestion {
+  id: string;
+  folder: string;
+  title: string;
+  created: string;
+}
+
+export class DuplicateNoteError extends Error {
+  readonly title: string;
+  readonly suggestions: NoteSuggestion[];
+
+  constructor(title: string, suggestions: NoteSuggestion[]) {
+    const suggestionList = suggestions
+      .map(s => `id:${s.id} (${s.folder}, created: ${s.created.split("T")[0]})`)
+      .join("\n  - ");
+    super(`Multiple notes found with title "${title}". Use ID prefix:\n  - ${suggestionList}`);
+    this.name = "DuplicateNoteError";
+    this.title = title;
+    this.suggestions = suggestions;
+  }
+}
+
+export class FolderNotFoundError extends Error {
+  readonly folder: string;
+
+  constructor(folder: string) {
+    super(`Folder not found: "${folder}"`);
+    this.name = "FolderNotFoundError";
+    this.folder = folder;
+  }
+}
+
+export class TableOutOfBoundsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TableOutOfBoundsError";
+  }
+}

package/src/graph/export.test.ts

@@ -0,0 +1,81 @@
+// src/graph/export.test.ts
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { exportGraph } from "./export.js";
+
+// Create a shared mock store instance
+const mockStore = {
+  getAll: vi.fn(),
+};
+
+vi.mock("../db/lancedb.js", () => ({
+  getVectorStore: vi.fn(() => mockStore),
+}));
+
+describe("exportGraph", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("JSON format", () => {
+    it("exports nodes and edges", async () => {
+      mockStore.getAll.mockResolvedValue([
+        { id: "1", title: "Note A", folder: "Work", tags: ["project"], outlinks: ["Note B"], vector: [1,0] },
+        { id: "2", title: "Note B", folder: "Work", tags: ["project"], outlinks: [], vector: [0,1] },
+      ]);
+
+      const result = await exportGraph({ format: "json" }) as any;
+
+      expect(result).toHaveProperty("nodes");
+      expect(result).toHaveProperty("edges");
+      expect(result.nodes).toHaveLength(2);
+      expect(result.edges.some((e: any) => e.type === "link")).toBe(true);
+      expect(result.edges.some((e: any) => e.type === "tag")).toBe(true);
+    });
+
+    it("filters by folder", async () => {
+      mockStore.getAll.mockResolvedValue([
+        { id: "1", title: "Note A", folder: "Work", tags: [], outlinks: [], vector: [] },
+        { id: "2", title: "Note B", folder: "Personal", tags: [], outlinks: [], vector: [] },
+      ]);
+
+      const result = await exportGraph({ format: "json", folder: "Work" }) as any;
+
+      expect(result.nodes).toHaveLength(1);
+      expect(result.nodes[0].folder).toBe("Work");
+    });
+  });
+
+  describe("GraphML format", () => {
+    it("exports valid GraphML XML", async () => {
+      mockStore.getAll.mockResolvedValue([
+        { id: "1", title: "Note A", folder: "Work", tags: [], outlinks: ["Note B"], vector: [] },
+        { id: "2", title: "Note B", folder: "Work", tags: [], outlinks: [], vector: [] },
+      ]);
+
+      const result = await exportGraph({ format: "graphml" });
+
+      expect(typeof result).toBe("string");
+      expect(result).toContain('<?xml version="1.0"');
+      expect(result).toContain("<graphml");
+      expect(result).toContain("<node");
+      expect(result).toContain("<edge");
+      expect(result).toContain("</graphml>");
+    });
+
+    it("escapes special XML characters in GraphML", async () => {
+      mockStore.getAll.mockResolvedValue([
+        { id: "1", title: 'Note <with> & "special"', folder: "Work", tags: [], outlinks: [], vector: [] },
+      ]);
+      const result = await exportGraph({ format: "graphml" }) as string;
+      expect(result).toContain("&lt;with&gt;");
+      expect(result).toContain("&amp;");
+    });
+  });
+
+  describe("Unknown format", () => {
+    it("throws for unknown format", async () => {
+      mockStore.getAll.mockResolvedValue([]);
+      await expect(exportGraph({ format: "unknown" as any })).rejects.toThrow("Unknown format");
+    });
+  });
+});

package/src/graph/export.ts

@@ -0,0 +1,163 @@
+// src/graph/export.ts
+/**
+ * Knowledge graph export to various formats.
+ */
+
+import { getVectorStore } from "../db/lancedb.js";
+import { createDebugLogger } from "../utils/debug.js";
+import { GRAPH_LINK_WEIGHT, GRAPH_TAG_WEIGHT } from "../config/constants.js";
+
+const debug = createDebugLogger("EXPORT");
+
+export type GraphFormat = "json" | "graphml";
+
+export interface GraphNode {
+  id: string;
+  label: string;
+  folder: string;
+  tags: string[];
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  type: "link" | "tag" | "similar";
+  weight: number;
+}
+
+export interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+export interface ExportOptions {
+  format: GraphFormat;
+  folder?: string;
+}
+
+/**
+ * Export knowledge graph to specified format.
+ */
+export async function exportGraph(options: ExportOptions): Promise<GraphData | string> {
+  const { format, folder } = options;
+
+  debug(`Exporting graph in ${format} format`);
+
+  const store = getVectorStore();
+  let records = await store.getAll();
+
+  // Filter by folder if specified
+  if (folder) {
+    const normalizedFolder = folder.toLowerCase();
+    records = records.filter(r => r.folder.toLowerCase() === normalizedFolder);
+  }
+
+  // Build graph data
+  const nodes: GraphNode[] = records.map(r => ({
+    id: r.id,
+    label: r.title,
+    folder: r.folder,
+    tags: r.tags ?? [],
+  }));
+
+  const edges: GraphEdge[] = [];
+  const nodeIds = new Set(records.map(r => r.id));
+
+  // Add link edges
+  for (const record of records) {
+    for (const linkTitle of record.outlinks ?? []) {
+      const target = records.find(r => r.title.toLowerCase() === linkTitle.toLowerCase());
+      if (target && nodeIds.has(target.id)) {
+        edges.push({
+          source: record.id,
+          target: target.id,
+          type: "link",
+          weight: GRAPH_LINK_WEIGHT,
+        });
+      }
+    }
+  }
+
+  // Add tag edges (notes sharing same tag)
+  const tagGroups = new Map<string, string[]>();
+  for (const record of records) {
+    for (const tag of record.tags ?? []) {
+      if (!tagGroups.has(tag)) {
+        tagGroups.set(tag, []);
+      }
+      tagGroups.get(tag)!.push(record.id);
+    }
+  }
+
+  const seenTagEdges = new Set<string>();
+  for (const [, noteIds] of tagGroups) {
+    if (noteIds.length < 2) continue;
+    for (let i = 0; i < noteIds.length; i++) {
+      for (let j = i + 1; j < noteIds.length; j++) {
+        const edgeKey = [noteIds[i], noteIds[j]].sort().join("-");
+        if (seenTagEdges.has(edgeKey)) continue;
+        seenTagEdges.add(edgeKey);
+        edges.push({
+          source: noteIds[i],
+          target: noteIds[j],
+          type: "tag",
+          weight: GRAPH_TAG_WEIGHT,
+        });
+      }
+    }
+  }
+
+  const graphData: GraphData = { nodes, edges };
+
+  if (format === "json") {
+    return graphData;
+  }
+
+  if (format === "graphml") {
+    return toGraphML(graphData);
+  }
+
+  throw new Error(`Unknown format: ${format}`);
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function toGraphML(data: GraphData): string {
+  const lines: string[] = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<graphml xmlns="http://graphml.graphdrawing.org/xmlns">',
+    '  <key id="label" for="node" attr.name="label" attr.type="string"/>',
+    '  <key id="folder" for="node" attr.name="folder" attr.type="string"/>',
+    '  <key id="tags" for="node" attr.name="tags" attr.type="string"/>',
+    '  <key id="type" for="edge" attr.name="type" attr.type="string"/>',
+    '  <key id="weight" for="edge" attr.name="weight" attr.type="double"/>',
+    '  <graph id="G" edgedefault="directed">',
+  ];
+
+  for (const node of data.nodes) {
+    lines.push(`    <node id="${escapeXml(node.id)}">`);
+    lines.push(`      <data key="label">${escapeXml(node.label)}</data>`);
+    lines.push(`      <data key="folder">${escapeXml(node.folder)}</data>`);
+    lines.push(`      <data key="tags">${escapeXml(node.tags.join(","))}</data>`);
+    lines.push("    </node>");
+  }
+
+  for (const edge of data.edges) {
+    lines.push(`    <edge source="${escapeXml(edge.source)}" target="${escapeXml(edge.target)}">`);
+    lines.push(`      <data key="type">${edge.type}</data>`);
+    lines.push(`      <data key="weight">${edge.weight}</data>`);
+    lines.push("    </edge>");
+  }
+
+  lines.push("  </graph>");
+  lines.push("</graphml>");
+
+  return lines.join("\n");
+}

package/src/graph/extract.test.ts

@@ -0,0 +1,90 @@
+// src/graph/extract.test.ts
+import { describe, it, expect } from "vitest";
+import { extractTags, extractOutlinks, extractMetadata } from "./extract.js";
+
+describe("extractTags", () => {
+  it("extracts simple hashtags", () => {
+    const content = "This is a #project about #coding";
+    expect(extractTags(content)).toEqual(["project", "coding"]);
+  });
+
+  it("handles hyphenated tags", () => {
+    const content = "Working on #my-project and #some-idea";
+    expect(extractTags(content)).toEqual(["my-project", "some-idea"]);
+  });
+
+  it("normalizes to lowercase", () => {
+    const content = "#Project #IDEA #Mixed";
+    expect(extractTags(content)).toEqual(["project", "idea", "mixed"]);
+  });
+
+  it("deduplicates tags", () => {
+    const content = "#project #idea #project";
+    expect(extractTags(content)).toEqual(["project", "idea"]);
+  });
+
+  it("returns empty array for no tags", () => {
+    expect(extractTags("No tags here")).toEqual([]);
+  });
+
+  it("ignores tags in code blocks", () => {
+    const content = "Real #tag\n```\n#not-a-tag\n```\nAnother #real";
+    expect(extractTags(content)).toEqual(["tag", "real"]);
+  });
+
+  it("ignores tags in inline code", () => {
+    const content = "Real #tag and `#code-tag` should ignore inline";
+    expect(extractTags(content)).toEqual(["tag"]);
+  });
+
+  it("ignores hex colors", () => {
+    const content = "Color #fff and #000000 and #a1b2c3 are not tags";
+    expect(extractTags(content)).toEqual([]);
+  });
+
+  it("keeps tags that contain letters mixed with numbers", () => {
+    const content = "#project1 #2024goals #abc123xyz";
+    expect(extractTags(content)).toEqual(["project1", "2024goals", "abc123xyz"]);
+  });
+
+  it("extracts tag at string boundaries", () => {
+    expect(extractTags("#start of content")).toEqual(["start"]);
+    expect(extractTags("end of #content")).toEqual(["content"]);
+  });
+});
+
+describe("extractOutlinks", () => {
+  it("extracts wiki-style links", () => {
+    const content = "See [[Meeting Notes]] and [[Project Plan]]";
+    expect(extractOutlinks(content)).toEqual(["Meeting Notes", "Project Plan"]);
+  });
+
+  it("handles links with special characters", () => {
+    const content = "Check [[Note with / slash]] and [[Note: with colon]]";
+    expect(extractOutlinks(content)).toEqual(["Note with / slash", "Note: with colon"]);
+  });
+
+  it("deduplicates links", () => {
+    const content = "[[Note]] and [[Other]] and [[Note]]";
+    expect(extractOutlinks(content)).toEqual(["Note", "Other"]);
+  });
+
+  it("returns empty array for no links", () => {
+    expect(extractOutlinks("No links here")).toEqual([]);
+  });
+
+  it("ignores links in code blocks", () => {
+    const content = "Real [[Link]]\n```\n[[not-a-link]]\n```";
+    expect(extractOutlinks(content)).toEqual(["Link"]);
+  });
+});
+
+describe("extractMetadata", () => {
+  it("extracts both tags and outlinks", () => {
+    const content = "A #project note linking to [[Other Note]]";
+    expect(extractMetadata(content)).toEqual({
+      tags: ["project"],
+      outlinks: ["Other Note"],
+    });
+  });
+});

package/src/graph/extract.ts

@@ -0,0 +1,52 @@
+/**
+ * Knowledge graph metadata extraction from note content.
+ */
+
+/** Remove code blocks and inline code to avoid extracting metadata from code. */
+function stripCodeBlocks(content: string): string {
+  return content
+    .replace(/```[\s\S]*?```/g, "") // fenced code blocks
+    .replace(/`[^`]+`/g, ""); // inline code
+}
+
+/** Check if a string is a hex color code (e.g., fff, 000000, a1b2c3) */
+function isHexColor(value: string): boolean {
+  return /^[0-9a-fA-F]+$/.test(value);
+}
+
+/**
+ * Extract hashtags from content.
+ * Ignores tags inside code blocks and hex color codes.
+ */
+export function extractTags(content: string): string[] {
+  const matches = stripCodeBlocks(content).match(/#[\w-]+/g) || [];
+  const tags = matches
+    .map((t) => t.slice(1).toLowerCase())
+    .filter((t) => !isHexColor(t));
+  return [...new Set(tags)];
+}
+
+/**
+ * Extract wiki-style [[links]] from content.
+ * Ignores links inside code blocks.
+ */
+export function extractOutlinks(content: string): string[] {
+  const matches = stripCodeBlocks(content).match(/\[\[([^\]]+)\]\]/g) || [];
+  const links = matches.map((m) => m.slice(2, -2));
+  return [...new Set(links)];
+}
+
+export interface NoteMetadata {
+  tags: string[];
+  outlinks: string[];
+}
+
+/**
+ * Extract all metadata (tags and outlinks) from content.
+ */
+export function extractMetadata(content: string): NoteMetadata {
+  return {
+    tags: extractTags(content),
+    outlinks: extractOutlinks(content),
+  };
+}

package/src/graph/queries.test.ts

@@ -0,0 +1,156 @@
+// src/graph/queries.test.ts
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { listTags, searchByTag, findRelatedNotes } from "./queries.js";
+
+// Create a shared mock store object
+const mockStore = {
+  getAll: vi.fn(),
+  search: vi.fn(),
+};
+
+// Mock the vector store module
+vi.mock("../db/lancedb.js", () => ({
+  getVectorStore: () => mockStore,
+}));
+
+describe("listTags", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("aggregates tags with counts", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Note 1", tags: ["project", "idea"], outlinks: [] },
+      { id: "2", title: "Note 2", tags: ["project", "todo"], outlinks: [] },
+      { id: "3", title: "Note 3", tags: ["idea"], outlinks: [] },
+    ]);
+
+    const result = await listTags();
+
+    expect(result).toEqual([
+      { tag: "project", count: 2 },
+      { tag: "idea", count: 2 },
+      { tag: "todo", count: 1 },
+    ]);
+  });
+
+  it("returns empty array when no tags", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Note 1", tags: [], outlinks: [] },
+    ]);
+
+    const result = await listTags();
+    expect(result).toEqual([]);
+  });
+});
+
+describe("searchByTag", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("finds notes with specific tag", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Note 1", folder: "Work", tags: ["project"], content: "Content 1", modified: "2026-01-01" },
+      { id: "2", title: "Note 2", folder: "Personal", tags: ["project", "idea"], content: "Content 2", modified: "2026-01-02" },
+      { id: "3", title: "Note 3", folder: "Work", tags: ["todo"], content: "Content 3", modified: "2026-01-03" },
+    ]);
+
+    const result = await searchByTag("project");
+
+    expect(result).toHaveLength(2);
+    expect(result[0].title).toBe("Note 1");
+    expect(result[1].title).toBe("Note 2");
+  });
+
+  it("filters by folder", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Note 1", folder: "Work", tags: ["project"], content: "...", modified: "2026-01-01" },
+      { id: "2", title: "Note 2", folder: "Personal", tags: ["project"], content: "...", modified: "2026-01-02" },
+    ]);
+
+    const result = await searchByTag("project", { folder: "Work" });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].folder).toBe("Work");
+  });
+});
+
+describe("findRelatedNotes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("finds notes by shared tags", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Source", folder: "Work", tags: ["project", "idea"], outlinks: [], vector: [1,0,0] },
+      { id: "2", title: "Related", folder: "Work", tags: ["project"], outlinks: [], vector: [0,1,0] },
+      { id: "3", title: "Unrelated", folder: "Work", tags: ["todo"], outlinks: [], vector: [0,0,1] },
+    ]);
+
+    const result = await findRelatedNotes("1", { types: ["tag"] });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("Related");
+    expect(result[0].relationship).toBe("tag");
+  });
+
+  it("finds notes by outlinks", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Source", folder: "Work", tags: [], outlinks: ["Target"], vector: [1,0,0] },
+      { id: "2", title: "Target", folder: "Work", tags: [], outlinks: [], vector: [0,1,0] },
+    ]);
+
+    const result = await findRelatedNotes("1", { types: ["link"] });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("Target");
+    expect(result[0].relationship).toBe("link");
+    expect(result[0].direction).toBe("outgoing");
+  });
+
+  it("finds backlinks", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Target", folder: "Work", tags: [], outlinks: [], vector: [1,0,0] },
+      { id: "2", title: "Source", folder: "Work", tags: [], outlinks: ["Target"], vector: [0,1,0] },
+    ]);
+
+    const result = await findRelatedNotes("1", { types: ["link"] });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].title).toBe("Source");
+    expect(result[0].direction).toBe("incoming");
+  });
+
+  it("throws NoteNotFoundError for non-existent source note", async () => {
+    mockStore.getAll.mockResolvedValue([]);
+    await expect(findRelatedNotes("nonexistent-id")).rejects.toThrow("Note not found");
+  });
+
+  it("finds notes by semantic similarity", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Source", folder: "Work", tags: [], outlinks: [], vector: [1,0,0] },
+    ]);
+    mockStore.search.mockResolvedValue([
+      { id: "2", title: "Similar", folder: "Work", content: "...", modified: "2026-01-01", score: 0.95 }
+    ]);
+
+    const result = await findRelatedNotes("1", { types: ["similar"] });
+    expect(result).toHaveLength(1);
+    expect(result[0].relationship).toBe("similar");
+  });
+});
+
+describe("searchByTag", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("searches tags case-insensitively", async () => {
+    mockStore.getAll.mockResolvedValue([
+      { id: "1", title: "Note", folder: "Work", tags: ["project"], content: "...", modified: "2026-01-01" },
+    ]);
+    const result = await searchByTag("PROJECT");
+    expect(result).toHaveLength(1);
+  });
+});