@telvok/librarian-mcp 1.5.4 → 2.3.0

package/dist/tools 2/sync.d.ts

@@ -0,0 +1,54 @@
+interface SyncedBook {
+    slug: string;
+    name: string;
+    new_entries: number;
+    modified_entries: number;
+    access: 'cloud' | 'downloaded';
+    version?: string;
+    synced_from?: string;
+}
+interface SyncResult {
+    success: boolean;
+    message: string;
+    synced?: SyncedBook[];
+    available?: {
+        slug: string;
+        name: string;
+        new_entries: number;
+    }[];
+    pinned?: {
+        slug: string;
+        name: string;
+    }[];
+    up_to_date?: number;
+}
+export declare const syncTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            slug: {
+                type: string;
+                description: string;
+            };
+            options: {
+                type: string;
+                properties: {
+                    force: {
+                        type: string;
+                        description: string;
+                    };
+                    download: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<SyncResult>;
+};
+export default syncTool;

package/dist/tools 2/sync.js

@@ -0,0 +1,298 @@
+// ============================================================================
+// Sync Tool
+// Check for and receive updates to owned books from Telvok marketplace
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { loadApiKey } from './auth.js';
+import { getLibraryPath, getImportedPath } from '../library/storage.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const syncTool = {
+    name: 'sync',
+    description: `Check for and receive updates to owned books from Telvok marketplace.
+
+Checks all purchased/claimed books for new or modified content since last sync.
+
+Sync preferences:
+- "auto": Synced automatically (default)
+- "manual": Shows as available, requires force: true to sync
+- "pinned": Never synced, locked to specific version
+
+Examples:
+- sync() - Check and sync all auto-sync books
+- sync({ slug: "premium-patterns" }) - Sync specific book
+- sync({ options: { force: true } }) - Include manual preference books
+- sync({ slug: "free-book", options: { download: true } }) - Download open book updates`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Specific book slug to sync (omit for all)',
+            },
+            options: {
+                type: 'object',
+                properties: {
+                    force: {
+                        type: 'boolean',
+                        description: 'Include manual preference books (default: false)',
+                    },
+                    download: {
+                        type: 'boolean',
+                        description: 'Download open book updates to local library (default: false)',
+                    },
+                },
+                description: 'Sync options',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { slug, options } = (args || {});
+        const force = options?.force || false;
+        const download = options?.download || false;
+        // Check authentication
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return {
+                success: false,
+                message: 'Not authenticated. Run auth({ action: "login" }) to connect your Telvok account first.',
+            };
+        }
+        try {
+            // Step 1: Check for available updates
+            const checkUrl = new URL(`${TELVOK_API_URL}/api/sync`);
+            if (slug) {
+                checkUrl.searchParams.set('slug', slug);
+            }
+            const checkResponse = await fetch(checkUrl.toString(), {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const checkData = await checkResponse.json();
+            if (!checkResponse.ok) {
+                return {
+                    success: false,
+                    message: checkData.error || `Failed to check for updates: HTTP ${checkResponse.status}`,
+                };
+            }
+            // If no updates available
+            const updatesAvailable = checkData.updates_available || [];
+            const upToDate = checkData.up_to_date || [];
+            const pinned = checkData.pinned || [];
+            if (updatesAvailable.length === 0) {
+                const totalBooks = upToDate.length + pinned.length;
+                let message = '';
+                if (totalBooks === 0) {
+                    message = 'No books to sync. Purchase or claim books first.';
+                }
+                else if (pinned.length > 0) {
+                    message = `${upToDate.length} book${upToDate.length === 1 ? ' is' : 's are'} up to date. ${pinned.length} pinned (won't sync).`;
+                }
+                else {
+                    message = `All ${totalBooks} book${totalBooks === 1 ? ' is' : 's are'} up to date.`;
+                }
+                return {
+                    success: true,
+                    message,
+                    pinned: pinned.length > 0 ? pinned.map((p) => ({ slug: p.slug, name: p.name })) : undefined,
+                    up_to_date: upToDate.length,
+                };
+            }
+            // Step 2: Perform sync
+            const syncResponse = await fetch(`${TELVOK_API_URL}/api/sync`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    slug,
+                    force,
+                    include_content: download,
+                }),
+            });
+            const syncData = await syncResponse.json();
+            if (!syncResponse.ok) {
+                return {
+                    success: false,
+                    message: syncData.error || `Failed to sync: HTTP ${syncResponse.status}`,
+                };
+            }
+            const synced = [];
+            const available = [];
+            const pinnedBooks = [];
+            // Process synced books
+            for (const book of syncData.synced || []) {
+                const newCount = typeof book.new_entries === 'number' ? book.new_entries : book.new_entries?.length || 0;
+                const modifiedCount = typeof book.modified_entries === 'number' ? book.modified_entries : book.modified_entries?.length || 0;
+                // If download requested and content provided, save to local
+                if (download && book.access_method === 'download' && Array.isArray(book.new_entries)) {
+                    await saveEntriesToLocal(book.slug, book.new_entries, book.modified_entries);
+                }
+                synced.push({
+                    slug: book.slug,
+                    name: book.name,
+                    new_entries: newCount,
+                    modified_entries: modifiedCount,
+                    access: download && book.pricing_type === 'open' ? 'downloaded' : 'cloud',
+                    version: formatVersion(book.new_version),
+                    synced_from: formatVersion(book.previous_version),
+                });
+            }
+            // Process skipped books
+            for (const book of syncData.skipped || []) {
+                if (book.reason === 'manual_no_force') {
+                    const update = updatesAvailable.find((u) => u.slug === book.slug);
+                    if (update) {
+                        available.push({
+                            slug: book.slug,
+                            name: book.name,
+                            new_entries: update.new_entries_count,
+                        });
+                    }
+                }
+                else if (book.reason === 'pinned') {
+                    pinnedBooks.push({
+                        slug: book.slug,
+                        name: book.name,
+                    });
+                }
+            }
+            // Build summary message
+            const messageParts = [];
+            const totalNewEntries = synced.reduce((sum, b) => sum + b.new_entries, 0);
+            const totalModified = synced.reduce((sum, b) => sum + b.modified_entries, 0);
+            if (synced.length > 0) {
+                let syncMsg = `Synced ${synced.length} book${synced.length === 1 ? '' : 's'}`;
+                if (totalNewEntries > 0 || totalModified > 0) {
+                    const parts = [];
+                    if (totalNewEntries > 0)
+                        parts.push(`${totalNewEntries} new`);
+                    if (totalModified > 0)
+                        parts.push(`${totalModified} modified`);
+                    syncMsg += `: ${parts.join(', ')} entries.`;
+                }
+                else {
+                    syncMsg += '.';
+                }
+                messageParts.push(syncMsg);
+            }
+            if (available.length > 0) {
+                messageParts.push(`${available.length} book${available.length === 1 ? ' has' : 's have'} updates available (set to manual).`);
+            }
+            if (pinnedBooks.length > 0) {
+                messageParts.push(`${pinnedBooks.length} book${pinnedBooks.length === 1 ? '' : 's'} pinned (won't sync).`);
+            }
+            if (messageParts.length === 0) {
+                if (upToDate.length > 0) {
+                    messageParts.push(`All ${upToDate.length} book${upToDate.length === 1 ? ' is' : 's are'} up to date.`);
+                }
+                else {
+                    messageParts.push('No books to sync. Purchase or claim books first.');
+                }
+            }
+            return {
+                success: true,
+                message: messageParts.join(' '),
+                synced: synced.length > 0 ? synced : undefined,
+                available: available.length > 0 ? available : undefined,
+                pinned: pinnedBooks.length > 0 ? pinnedBooks : undefined,
+                up_to_date: upToDate.length,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Sync failed: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Helper: Save entries to local imported folder
+// ============================================================================
+async function saveEntriesToLocal(slug, newEntries, modifiedEntries) {
+    const libraryPath = getLibraryPath();
+    const importedPath = getImportedPath(libraryPath);
+    const bookPath = path.join(importedPath, slug);
+    // Ensure directory exists
+    await fs.mkdir(bookPath, { recursive: true });
+    // Save new entries
+    for (const entry of newEntries || []) {
+        const filename = slugify(entry.title) + '.md';
+        const content = formatEntryAsMarkdown(entry);
+        await fs.writeFile(path.join(bookPath, filename), content, 'utf-8');
+    }
+    // Save modified entries (overwrite)
+    for (const entry of modifiedEntries || []) {
+        const filename = slugify(entry.title) + '.md';
+        const content = formatEntryAsMarkdown(entry);
+        await fs.writeFile(path.join(bookPath, filename), content, 'utf-8');
+    }
+    // Update .meta.json
+    const metaPath = path.join(bookPath, '.meta.json');
+    let meta = {};
+    try {
+        const existing = await fs.readFile(metaPath, 'utf-8');
+        meta = JSON.parse(existing);
+    }
+    catch {
+        // No existing meta
+    }
+    meta.last_synced = new Date().toISOString();
+    await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .substring(0, 50);
+}
+/**
+ * Format a timestamp as a human-readable version string
+ */
+function formatVersion(isoTimestamp) {
+    if (!isoTimestamp)
+        return 'never synced';
+    const date = new Date(isoTimestamp);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) {
+        return `today at ${date.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' })}`;
+    }
+    else if (diffDays === 1) {
+        return 'yesterday';
+    }
+    else if (diffDays < 7) {
+        return `${diffDays} days ago`;
+    }
+    else {
+        return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+    }
+}
+function formatEntryAsMarkdown(entry) {
+    let md = '';
+    // Frontmatter
+    if (entry.intent || entry.context) {
+        md += '---\n';
+        if (entry.intent)
+            md += `intent: "${entry.intent}"\n`;
+        if (entry.context)
+            md += `context: "${entry.context}"\n`;
+        md += '---\n\n';
+    }
+    // Title and content
+    md += `# ${entry.title}\n\n`;
+    md += entry.content;
+    return md;
+}
+// ============================================================================
+// Export
+// ============================================================================
+export default syncTool;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telvok/librarian-mcp",
-  "version": "1.5.4",
+  "version": "2.3.0",
   "description": "Knowledge capture MCP server - remember what you learn with AI",
   "type": "module",
   "main": "dist/server.js",