@disco_trooper/apple-notes-mcp 1.2.0 → 1.4.0

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);
+  });
+});

package/src/graph/queries.ts

@@ -0,0 +1,224 @@
+/**
+ * Knowledge graph query operations.
+ */
+
+import { getVectorStore } from "../db/lancedb.js";
+import { createDebugLogger } from "../utils/debug.js";
+import { NoteNotFoundError } from "../errors/index.js";
+import { generatePreview } from "../search/index.js";
+import {
+  DEFAULT_SEARCH_LIMIT,
+  DEFAULT_RELATED_NOTES_LIMIT,
+  GRAPH_TAG_WEIGHT,
+  GRAPH_LINK_WEIGHT,
+  GRAPH_SIMILAR_WEIGHT,
+} from "../config/constants.js";
+import type { SearchResult } from "../types/index.js";
+
+const debug = createDebugLogger("GRAPH");
+
+export interface TagCount {
+  tag: string;
+  count: number;
+}
+
+/**
+ * List all tags with occurrence counts.
+ * Sorted by count descending.
+ */
+export async function listTags(): Promise<TagCount[]> {
+  debug("Listing all tags");
+
+  const store = getVectorStore();
+  const records = await store.getAll();
+
+  // Aggregate tag counts
+  const counts = new Map<string, number>();
+  for (const record of records) {
+    for (const tag of record.tags ?? []) {
+      counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+  }
+
+  // Sort by count descending
+  const result = Array.from(counts.entries())
+    .map(([tag, count]) => ({ tag, count }))
+    .sort((a, b) => b.count - a.count);
+
+  debug(`Found ${result.length} unique tags`);
+  return result;
+}
+
+export interface SearchByTagOptions {
+  folder?: string;
+  limit?: number;
+}
+
+/**
+ * Find notes with a specific tag.
+ */
+export async function searchByTag(
+  tag: string,
+  options: SearchByTagOptions = {}
+): Promise<SearchResult[]> {
+  const { folder, limit = DEFAULT_SEARCH_LIMIT } = options;
+
+  debug(`Searching for tag: ${tag}`);
+
+  const store = getVectorStore();
+  const records = await store.getAll();
+
+  // Filter by tag (case-insensitive)
+  let matches = records.filter((r) =>
+    (r.tags ?? []).includes(tag.toLowerCase())
+  );
+
+  // Filter by folder if specified
+  if (folder) {
+    const normalizedFolder = folder.toLowerCase();
+    matches = matches.filter(
+      (r) => r.folder.toLowerCase() === normalizedFolder
+    );
+  }
+
+  // Transform to SearchResult and limit
+  const results: SearchResult[] = matches.slice(0, limit).map((r, i) => ({
+    id: r.id,
+    title: r.title,
+    folder: r.folder,
+    preview: generatePreview(r.content),
+    modified: r.modified,
+    score: 1 / (1 + i),
+  }));
+
+  debug(`Found ${results.length} notes with tag: ${tag}`);
+  return results;
+}
+
+export type RelationshipType = "tag" | "link" | "similar";
+
+export interface RelatedNote {
+  id: string;
+  title: string;
+  folder: string;
+  relationship: RelationshipType;
+  score: number;
+  sharedTags?: string[];
+  direction?: "outgoing" | "incoming";
+}
+
+export interface FindRelatedOptions {
+  types?: RelationshipType[];
+  limit?: number;
+}
+
+/**
+ * Find notes related to a source note by tags, links, or semantic similarity.
+ */
+export async function findRelatedNotes(
+  sourceId: string,
+  options: FindRelatedOptions = {}
+): Promise<RelatedNote[]> {
+  const { types = ["tag", "link", "similar"], limit = DEFAULT_RELATED_NOTES_LIMIT } = options;
+
+  debug(`Finding related notes for: ${sourceId}`);
+
+  const store = getVectorStore();
+  const allRecords = await store.getAll();
+
+  // Find source note
+  const source = allRecords.find((r) => r.id === sourceId);
+  if (!source) {
+    throw new NoteNotFoundError(sourceId);
+  }
+
+  const results: RelatedNote[] = [];
+  const seen = new Set<string>();
+
+  // Find by shared tags
+  if (types.includes("tag") && source.tags?.length > 0) {
+    for (const record of allRecords) {
+      if (record.id === sourceId || seen.has(record.id)) continue;
+
+      const shared = (record.tags ?? []).filter((t) => source.tags.includes(t));
+      if (shared.length > 0) {
+        results.push({
+          id: record.id,
+          title: record.title,
+          folder: record.folder,
+          relationship: "tag",
+          score: GRAPH_TAG_WEIGHT * (shared.length / source.tags.length),
+          sharedTags: shared,
+        });
+        seen.add(record.id);
+      }
+    }
+  }
+
+  // Find by outlinks (notes this note links to)
+  if (types.includes("link")) {
+    for (const linkTitle of source.outlinks ?? []) {
+      const linked = allRecords.find(
+        (r) =>
+          r.title.toLowerCase() === linkTitle.toLowerCase() &&
+          r.id !== sourceId &&
+          !seen.has(r.id)
+      );
+      if (linked) {
+        results.push({
+          id: linked.id,
+          title: linked.title,
+          folder: linked.folder,
+          relationship: "link",
+          score: GRAPH_LINK_WEIGHT,
+          direction: "outgoing",
+        });
+        seen.add(linked.id);
+      }
+    }
+
+    // Find backlinks (notes that link to this note)
+    for (const record of allRecords) {
+      if (record.id === sourceId || seen.has(record.id)) continue;
+
+      const linksToSource = (record.outlinks ?? []).some(
+        (l) => l.toLowerCase() === source.title.toLowerCase()
+      );
+      if (linksToSource) {
+        results.push({
+          id: record.id,
+          title: record.title,
+          folder: record.folder,
+          relationship: "link",
+          score: GRAPH_LINK_WEIGHT,
+          direction: "incoming",
+        });
+        seen.add(record.id);
+      }
+    }
+  }
+
+  // Find by semantic similarity
+  if (types.includes("similar") && source.vector?.length > 0) {
+    const similarResults = await store.search(source.vector, limit + 1);
+
+    for (const similar of similarResults) {
+      if (similar.id === sourceId || seen.has(similar.id ?? "")) continue;
+
+      results.push({
+        id: similar.id ?? "",
+        title: similar.title,
+        folder: similar.folder,
+        relationship: "similar",
+        score: GRAPH_SIMILAR_WEIGHT * similar.score,
+      });
+      seen.add(similar.id ?? "");
+    }
+  }
+
+  // Sort by score and limit
+  results.sort((a, b) => b.score - a.score);
+
+  debug(`Found ${results.length} related notes`);
+  return results.slice(0, limit);
+}