@orellbuehler/paperless-mcp 1.0.0

package/dist/tools/helpers.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { buildQS, ok, err } from "../paperless/format.js";
+export function registerHelperTools(server, client) {
+    server.tool("get_document_content", "Get the text content of a document (OCR'd text for PDFs, raw text for text files)", {
+        id: z.number().describe("Document ID"),
+        max_length: z.number().optional().describe("Truncate content to this many characters"),
+    }, async ({ id, max_length }) => {
+        try {
+            let content = await client.getDocumentContent(id);
+            if (!content) {
+                const doc = (await client.fetch(`/api/documents/${id}/`));
+                content = doc.content || "";
+            }
+            if (!content)
+                return ok({ id, content: "", note: "No text content available for this document" });
+            if (max_length && content.length > max_length) {
+                content =
+                    content.slice(0, max_length) +
+                        `\n\n[Truncated at ${max_length} characters, total: ${content.length}]`;
+            }
+            return ok({ id, length: content.length, content });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_documents", "Get full details (including OCR text content) for one or more documents by ID. Use this after list_documents/search_documents, which return metadata only.", {
+        ids: z.array(z.number()).describe("Document IDs to fetch in full"),
+        max_content_length: z
+            .number()
+            .optional()
+            .describe("Truncate each document's content to this many characters"),
+    }, async ({ ids, max_content_length }) => {
+        try {
+            const docs = await Promise.all(ids.map((id) => client.fetch(`/api/documents/${id}/`)));
+            const result = docs.map((doc) => {
+                if (max_content_length &&
+                    typeof doc.content === "string" &&
+                    doc.content.length > max_content_length) {
+                    return {
+                        ...doc,
+                        content: doc.content.slice(0, max_content_length),
+                        content_length: doc.content.length,
+                        content_truncated: true,
+                    };
+                }
+                return doc;
+            });
+            return ok(result);
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_documents_by_correspondent", "Find a correspondent by name and list their documents", {
+        name: z.string().describe("Correspondent name (partial match)"),
+        page: z.number().optional(),
+        page_size: z.number().optional(),
+    }, async ({ name, page, page_size }) => {
+        try {
+            const corrs = (await client.fetch(`/api/correspondents/${buildQS({ name__icontains: name })}`));
+            if (corrs.results.length === 0) {
+                return ok({ query: name, message: "No correspondents found matching that name" });
+            }
+            const correspondent = corrs.results[0];
+            const docs = (await client.fetch(`/api/documents/${buildQS({
+                correspondent__id: correspondent.id,
+                page: page || 1,
+                page_size: page_size || 25,
+                ordering: "-created",
+            })}`));
+            return ok({
+                correspondent: {
+                    id: correspondent.id,
+                    name: correspondent.name,
+                    document_count: correspondent.document_count,
+                },
+                other_matches: corrs.results.length > 1
+                    ? corrs.results.slice(1).map((c) => ({ id: c.id, name: c.name }))
+                    : undefined,
+                documents: docs,
+            });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("monthly_summary", "Get a summary of documents added or created in a given month", {
+        year: z.number().describe("Year (e.g. 2024)"),
+        month: z.number().describe("Month (1-12)"),
+    }, async ({ year, month }) => {
+        try {
+            const startDate = `${year}-${String(month).padStart(2, "0")}-01`;
+            const endMonth = month === 12 ? 1 : month + 1;
+            const endYear = month === 12 ? year + 1 : year;
+            const endDate = `${endYear}-${String(endMonth).padStart(2, "0")}-01`;
+            const allDocs = await client.fetchAllPages(`/api/documents/${buildQS({
+                added__date__gte: startDate,
+                added__date__lt: endDate,
+                ordering: "-added",
+            })}`);
+            const byType = {};
+            const byCorrespondent = {};
+            for (const doc of allDocs) {
+                const typeKey = doc.document_type ? String(doc.document_type) : "unclassified";
+                byType[typeKey] = (byType[typeKey] || 0) + 1;
+                const corrKey = doc.correspondent ? String(doc.correspondent) : "unknown";
+                byCorrespondent[corrKey] = (byCorrespondent[corrKey] || 0) + 1;
+            }
+            return ok({
+                period: `${year}-${String(month).padStart(2, "0")}`,
+                total_added: allDocs.length,
+                by_document_type_id: byType,
+                by_correspondent_id: byCorrespondent,
+                documents: allDocs.map((d) => ({
+                    id: d.id,
+                    title: d.title,
+                    created: d.created,
+                    added: d.added,
+                    correspondent: d.correspondent,
+                    document_type: d.document_type,
+                })),
+            });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("upload_from_url", "Download a file from a URL and upload it to Paperless-ngx", {
+        url: z.string().describe("URL to download the file from"),
+        title: z.string().optional(),
+        correspondent: z.number().optional(),
+        document_type: z.number().optional(),
+        storage_path: z.number().optional(),
+        tags: z.array(z.number()).optional(),
+    }, async ({ url, title, correspondent, document_type, storage_path, tags }) => {
+        try {
+            const parsed = new URL(url);
+            if (!["http:", "https:"].includes(parsed.protocol)) {
+                throw new Error(`Unsupported URL scheme: ${parsed.protocol}. Only http and https are allowed.`);
+            }
+            const MAX_DOWNLOAD_SIZE = 100 * 1024 * 1024; // 100 MB
+            const fileRes = await fetch(url, { redirect: "error" });
+            if (!fileRes.ok)
+                throw new Error(`Failed to download: ${fileRes.status} ${fileRes.statusText}`);
+            const contentLength = parseInt(fileRes.headers.get("content-length") || "0", 10);
+            if (contentLength > MAX_DOWNLOAD_SIZE) {
+                throw new Error(`File too large: ${contentLength} bytes (max ${MAX_DOWNLOAD_SIZE})`);
+            }
+            const contentDisposition = fileRes.headers.get("content-disposition");
+            let filename = url.split("/").pop()?.split("?")[0] || "document";
+            if (contentDisposition) {
+                const match = contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/);
+                if (match)
+                    filename = match[1].replace(/['"]/g, "");
+            }
+            const blob = await fileRes.blob();
+            const form = new FormData();
+            form.append("document", blob, filename);
+            if (title !== undefined)
+                form.append("title", title);
+            if (correspondent !== undefined)
+                form.append("correspondent", String(correspondent));
+            if (document_type !== undefined)
+                form.append("document_type", String(document_type));
+            if (storage_path !== undefined)
+                form.append("storage_path", String(storage_path));
+            if (tags)
+                tags.forEach((t) => form.append("tags", String(t)));
+            const res = await client.upload("/api/documents/post_document/", form);
+            if (!res.ok)
+                throw new Error(`Upload failed: ${res.status}: ${await res.text()}`);
+            return ok(await res.json().catch(() => ({
+                status: "accepted",
+                task: res.headers.get("location"),
+                filename,
+                source_url: url,
+            })));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/search.js

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import { createHash } from "node:crypto";
+import { ok, err, buildQS } from "../paperless/format.js";
+import { config, adminClient } from "../config.js";
+import { embed, embedSingle, getProviderInfo } from "../embeddings.js";
+import { upsertDocument, searchSimilar, getIndexedDocIds, getDocumentHash, getStats, removeDocument, } from "../vectordb.js";
+function contentHash(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+export function registerSearchTools(server, client) {
+    server.tool("semantic_search", "Search documents by meaning using vector embeddings. Requires sync_embeddings to be run first.", {
+        query: z.string().describe("Natural language search query"),
+        limit: z.number().optional().describe("Max results (default 10)"),
+    }, async ({ query, limit }) => {
+        try {
+            const limitN = limit || 10;
+            const queryEmbedding = await embedSingle(query);
+            // Over-fetch from the global index, then drop docs the user's token
+            // cannot see, so permission filtering doesn't starve restricted users.
+            const hits = searchSimilar(queryEmbedding, limitN * 5);
+            if (hits.length === 0)
+                return ok({ count: 0, results: [] });
+            const ids = hits.map((h) => h.id);
+            const resp = (await client.fetch(`/api/documents/${buildQS({ id__in: ids, page_size: ids.length })}`));
+            const allowed = new Set((resp.results || []).map((d) => d.id));
+            const results = hits
+                .filter((h) => allowed.has(h.id))
+                .slice(0, limitN)
+                .map((h) => ({ id: h.id, title: h.title, distance: h.distance }));
+            return ok({ count: results.length, results });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    if (client.token === config.adminToken) {
+        server.tool("sync_embeddings", "Sync document embeddings to the local vector database. Indexes all documents for semantic search. Only re-embeds documents whose content has changed. Admin only.", {
+            force: z.boolean().optional().describe("Force re-embedding of all documents"),
+        }, async ({ force }) => {
+            try {
+                const provider = getProviderInfo();
+                const docs = await adminClient.fetchAllPages("/api/documents/");
+                const indexedIds = new Set(getIndexedDocIds());
+                let indexed = 0;
+                let skipped = 0;
+                let removed = 0;
+                const errors = [];
+                const BATCH_SIZE = 20;
+                const currentIds = new Set(docs.map((d) => d.id));
+                for (const id of indexedIds) {
+                    if (!currentIds.has(id)) {
+                        removeDocument(id);
+                        removed++;
+                    }
+                }
+                for (let i = 0; i < docs.length; i += BATCH_SIZE) {
+                    const batch = docs.slice(i, i + BATCH_SIZE);
+                    const toEmbed = [];
+                    for (const doc of batch) {
+                        try {
+                            let content = doc.content;
+                            if (!content) {
+                                const detail = (await adminClient.fetch(`/api/documents/${doc.id}/`));
+                                content = detail.content;
+                            }
+                            if (!content) {
+                                skipped++;
+                                continue;
+                            }
+                            const hash = contentHash(content);
+                            if (!force && getDocumentHash(doc.id) === hash) {
+                                skipped++;
+                                continue;
+                            }
+                            toEmbed.push({ doc, content, hash });
+                        }
+                        catch (e) {
+                            errors.push(`Doc ${doc.id}: ${e}`);
+                        }
+                    }
+                    if (toEmbed.length === 0)
+                        continue;
+                    try {
+                        const texts = toEmbed.map((t) => `${t.doc.title}\n\n${t.content}`.slice(0, 8000));
+                        const embeddings = await embed(texts);
+                        for (let j = 0; j < toEmbed.length; j++) {
+                            upsertDocument(toEmbed[j].doc.id, toEmbed[j].doc.title, toEmbed[j].hash, embeddings[j]);
+                            indexed++;
+                        }
+                    }
+                    catch (e) {
+                        errors.push(`Batch embed error: ${e}`);
+                    }
+                }
+                const stats = getStats();
+                return ok({
+                    provider,
+                    indexed,
+                    skipped,
+                    removed,
+                    total_in_db: stats.indexed_documents,
+                    db_path: stats.db_path,
+                    errors: errors.length > 0 ? errors : undefined,
+                });
+            }
+            catch (e) {
+                return err(e);
+            }
+        });
+    }
+    server.tool("embedding_status", "Get the status of the local vector embedding database", {}, async () => {
+        try {
+            const { db_path, ...stats } = getStats();
+            const provider = getProviderInfo();
+            const isAdmin = client.token === config.adminToken;
+            return ok({ ...stats, ...(isAdmin ? { db_path } : {}), ...provider });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/users.js

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import { buildQS, ok, err } from "../paperless/format.js";
+export function registerUserTools(server, client) {
+    // --- Users ---
+    server.tool("list_users", "List all users", {
+        page: z.number().optional(),
+        page_size: z.number().optional(),
+        ordering: z.string().optional(),
+    }, async (params) => {
+        try {
+            return ok(await client.fetch(`/api/users/${buildQS(params)}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_user", "Get a single user by ID. Reveals the permission-string format used by user_permissions.", { id: z.number() }, async ({ id }) => {
+        try {
+            return ok(await client.fetch(`/api/users/${id}/`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("create_user", "Create a new user (requires Paperless admin privileges)", {
+        username: z.string(),
+        password: z.string().optional(),
+        email: z.string().optional(),
+        first_name: z.string().optional(),
+        last_name: z.string().optional(),
+        is_active: z.boolean().optional(),
+        is_staff: z.boolean().optional(),
+        is_superuser: z.boolean().optional(),
+        groups: z.array(z.number()).optional().describe("Group IDs"),
+        user_permissions: z
+            .array(z.string())
+            .optional()
+            .describe("Permission codenames like 'documents.view_document'. Call get_user/get_group to see valid strings."),
+    }, async (body) => {
+        try {
+            return ok(await client.fetch("/api/users/", {
+                method: "POST",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("update_user", "Update an existing user (partial update; requires Paperless admin privileges)", {
+        id: z.number(),
+        username: z.string().optional(),
+        password: z.string().optional(),
+        email: z.string().optional(),
+        first_name: z.string().optional(),
+        last_name: z.string().optional(),
+        is_active: z.boolean().optional(),
+        is_staff: z.boolean().optional(),
+        is_superuser: z.boolean().optional(),
+        groups: z.array(z.number()).optional().describe("Group IDs"),
+        user_permissions: z.array(z.string()).optional(),
+    }, async ({ id, ...body }) => {
+        try {
+            return ok(await client.fetch(`/api/users/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    // --- Groups ---
+    server.tool("list_groups", "List all groups", {
+        page: z.number().optional(),
+        page_size: z.number().optional(),
+        ordering: z.string().optional(),
+    }, async (params) => {
+        try {
+            return ok(await client.fetch(`/api/groups/${buildQS(params)}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_group", "Get a single group by ID. Reveals the permission-string format used by permissions.", { id: z.number() }, async ({ id }) => {
+        try {
+            return ok(await client.fetch(`/api/groups/${id}/`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("create_group", "Create a new group (requires Paperless admin privileges)", {
+        name: z.string(),
+        permissions: z
+            .array(z.string())
+            .optional()
+            .describe("Permission codenames like 'documents.view_document'"),
+    }, async (body) => {
+        try {
+            return ok(await client.fetch("/api/groups/", {
+                method: "POST",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("update_group", "Update an existing group (partial update; requires Paperless admin privileges)", {
+        id: z.number(),
+        name: z.string().optional(),
+        permissions: z.array(z.string()).optional(),
+    }, async ({ id, ...body }) => {
+        try {
+            return ok(await client.fetch(`/api/groups/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/tools/workflow.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { buildQS, ok, err } from "../paperless/format.js";
+export function registerWorkflowTools(server, client) {
+    server.tool("auto_classify_document", "Get AI suggestions for a document and apply them in one step. Returns what was changed.", {
+        id: z.number().describe("Document ID"),
+        apply_correspondent: z
+            .boolean()
+            .optional()
+            .describe("Apply suggested correspondent (default true)"),
+        apply_document_type: z
+            .boolean()
+            .optional()
+            .describe("Apply suggested document type (default true)"),
+        apply_tags: z.boolean().optional().describe("Apply suggested tags (default true)"),
+        apply_storage_path: z
+            .boolean()
+            .optional()
+            .describe("Apply suggested storage path (default true)"),
+    }, async ({ id, apply_correspondent, apply_document_type, apply_tags, apply_storage_path }) => {
+        try {
+            const [suggestions, doc] = await Promise.all([
+                client.fetch(`/api/documents/${id}/suggestions/`),
+                client.fetch(`/api/documents/${id}/`),
+            ]);
+            const updates = {};
+            if ((apply_correspondent ?? true) && suggestions.correspondents?.length > 0) {
+                updates.correspondent = suggestions.correspondents[0];
+            }
+            if ((apply_document_type ?? true) && suggestions.document_types?.length > 0) {
+                updates.document_type = suggestions.document_types[0];
+            }
+            if ((apply_tags ?? true) && suggestions.tags?.length > 0) {
+                const merged = [...new Set([...doc.tags, ...suggestions.tags])];
+                updates.tags = merged;
+            }
+            if ((apply_storage_path ?? true) && suggestions.storage_paths?.length > 0) {
+                updates.storage_path = suggestions.storage_paths[0];
+            }
+            if (Object.keys(updates).length === 0) {
+                return ok({ id, message: "No suggestions available", suggestions });
+            }
+            const updated = await client.fetch(`/api/documents/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(updates),
+            });
+            return ok({ id, applied: updates, suggestions, updated_document: updated });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("process_inbox", "Review all inbox documents and return proposed classifications. Does NOT apply changes — returns a plan for review.", {
+        limit: z.number().optional().describe("Max documents to process (default 20)"),
+    }, async ({ limit }) => {
+        try {
+            const maxDocs = limit || 20;
+            const data = (await client.fetch(`/api/documents/${buildQS({ is_in_inbox: true, page_size: maxDocs })}`));
+            const proposals = [];
+            for (const doc of data.results) {
+                try {
+                    const suggestions = (await client.fetch(`/api/documents/${doc.id}/suggestions/`));
+                    proposals.push({
+                        id: doc.id,
+                        title: doc.title,
+                        current: {
+                            correspondent: doc.correspondent,
+                            document_type: doc.document_type,
+                            tags: doc.tags,
+                            storage_path: doc.storage_path,
+                        },
+                        suggested: {
+                            correspondent: suggestions.correspondents?.[0] ?? null,
+                            document_type: suggestions.document_types?.[0] ?? null,
+                            tags: suggestions.tags ?? [],
+                            storage_path: suggestions.storage_paths?.[0] ?? null,
+                        },
+                    });
+                }
+                catch (e) {
+                    proposals.push({ id: doc.id, title: doc.title, error: String(e) });
+                }
+            }
+            return ok({
+                total_inbox: data.count,
+                processed: proposals.length,
+                proposals,
+                note: "Use auto_classify_document or update_document to apply changes.",
+            });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("bulk_tag_by_content", "Search for documents matching a query and add a tag to all results", {
+        query: z.string().describe("Search query to find matching documents"),
+        tag_id: z.number().describe("Tag ID to add to matching documents"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("If true, only return matching documents without tagging"),
+    }, async ({ query, tag_id, dry_run }) => {
+        try {
+            const data = (await client.fetch(`/api/documents/${buildQS({ query, page_size: 100 })}`));
+            const docIds = data.results.map((d) => d.id);
+            if (dry_run) {
+                return ok({
+                    query,
+                    tag_id,
+                    matching_documents: data.results.map((d) => ({ id: d.id, title: d.title })),
+                    count: docIds.length,
+                    total_matches: data.count,
+                    note: "Dry run — no changes made. Set dry_run to false to apply.",
+                });
+            }
+            if (docIds.length === 0) {
+                return ok({ query, tag_id, message: "No documents matched the query" });
+            }
+            const result = await client.fetch("/api/documents/bulk_edit/", {
+                method: "POST",
+                body: JSON.stringify({
+                    documents: docIds,
+                    method: "add_tag",
+                    parameters: { tag: tag_id },
+                }),
+            });
+            return ok({
+                query,
+                tag_id,
+                tagged_count: docIds.length,
+                total_matches: data.count,
+                result,
+                note: data.count > 100
+                    ? `Only tagged first 100 of ${data.count} matches. Run again to tag more.`
+                    : undefined,
+            });
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}

package/dist/vectordb.js

@@ -0,0 +1,109 @@
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { getEmbeddingDimensions } from "./embeddings.js";
+const DB_DIR = process.env.PAPERLESS_MCP_DATA || join(homedir(), ".paperless-mcp");
+const DB_PATH = join(DB_DIR, "vectors.db");
+let db = null;
+export function getDb() {
+    if (db)
+        return db;
+    mkdirSync(DB_DIR, { recursive: true });
+    db = new Database(DB_PATH);
+    sqliteVec.load(db);
+    const dims = getEmbeddingDimensions();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS documents (
+      id INTEGER PRIMARY KEY,
+      title TEXT,
+      content_hash TEXT,
+      updated_at TEXT
+    )
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sync_state (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    )
+  `);
+    const storedDims = db
+        .prepare("SELECT value FROM sync_state WHERE key = 'embedding_dimensions'")
+        .get();
+    if (storedDims && parseInt(storedDims.value, 10) !== dims) {
+        db.exec("DROP TABLE IF EXISTS vec_documents");
+        db.exec("DELETE FROM documents");
+        db.prepare("DELETE FROM sync_state WHERE key = 'embedding_dimensions'").run();
+        console.error(`Embedding dimensions changed from ${storedDims.value} to ${dims}. Vector index has been reset. Run sync_embeddings to re-index.`);
+    }
+    db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_documents USING vec0(
+      embedding float[${dims}]
+    )
+  `);
+    if (!storedDims || parseInt(storedDims.value, 10) !== dims) {
+        db.prepare("INSERT OR REPLACE INTO sync_state (key, value) VALUES ('embedding_dimensions', ?)").run(String(dims));
+    }
+    return db;
+}
+export function upsertDocument(id, title, contentHash, embedding) {
+    const d = getDb();
+    const embBuf = Buffer.from(new Float32Array(embedding).buffer);
+    const tx = d.transaction(() => {
+        const existing = d.prepare("SELECT content_hash FROM documents WHERE id = ?").get(id);
+        if (existing) {
+            d.prepare("UPDATE documents SET title = ?, content_hash = ?, updated_at = ? WHERE id = ?").run(title, contentHash, new Date().toISOString(), id);
+            d.prepare("UPDATE vec_documents SET embedding = ? WHERE rowid = ?").run(embBuf, BigInt(id));
+        }
+        else {
+            d.prepare("INSERT INTO documents (id, title, content_hash, updated_at) VALUES (?, ?, ?, ?)").run(id, title, contentHash, new Date().toISOString());
+            d.prepare("INSERT INTO vec_documents (rowid, embedding) VALUES (?, ?)").run(BigInt(id), embBuf);
+        }
+    });
+    tx();
+}
+export function removeDocument(id) {
+    const d = getDb();
+    const tx = d.transaction(() => {
+        d.prepare("DELETE FROM documents WHERE id = ?").run(id);
+        d.prepare("DELETE FROM vec_documents WHERE rowid = ?").run(BigInt(id));
+    });
+    tx();
+}
+export function searchSimilar(embedding, limit = 10) {
+    const d = getDb();
+    const rows = d
+        .prepare(`
+    SELECT v.rowid as id, d.title, v.distance
+    FROM vec_documents v
+    JOIN documents d ON d.id = v.rowid
+    WHERE v.embedding MATCH ? AND k = ?
+    ORDER BY v.distance
+  `)
+        .all(Buffer.from(new Float32Array(embedding).buffer), limit);
+    return rows;
+}
+export function getIndexedDocIds() {
+    const d = getDb();
+    return d.prepare("SELECT id FROM documents").all().map((r) => r.id);
+}
+export function getDocumentHash(id) {
+    const d = getDb();
+    const row = d.prepare("SELECT content_hash FROM documents WHERE id = ?").get(id);
+    return row?.content_hash;
+}
+export function getSyncState(key) {
+    const d = getDb();
+    const row = d.prepare("SELECT value FROM sync_state WHERE key = ?").get(key);
+    return row?.value;
+}
+export function setSyncState(key, value) {
+    const d = getDb();
+    d.prepare("INSERT OR REPLACE INTO sync_state (key, value) VALUES (?, ?)").run(key, value);
+}
+export function getStats() {
+    const d = getDb();
+    const count = d.prepare("SELECT COUNT(*) as c FROM documents").get().c;
+    return { indexed_documents: count, db_path: DB_PATH };
+}