@telvok/librarian-mcp 1.5.3 → 2.0.0

package/dist/tools/rebuild-index.js

@@ -9,16 +9,24 @@ import { saveIndex, addToIndex, getIndexStats } from '../library/vector-index.js
 // ============================================================================
 export const rebuildIndexTool = {
     name: 'rebuild_index',
-    description: `Rebuild the semantic search index for all library entries.
+    title: 'Rebuild Search Index',
+    description: `Rebuild the semantic search index.
 
-Use this when semantic search returns poor results, when user reports search seems broken, or after manually adding entries outside the normal workflow.
+USE THIS TOOL WHEN:
+- brief() returns poor or no results when entries exist
+- After import_memories() to index new content
+- User reports search seems broken
+- Manually edited .librarian/ files outside normal workflow
 
-Use this after:
-- Upgrading to v1.2.0 (existing entries need embeddings)
-- Importing memories from other tools
-- If semantic search seems broken
+Reads all .md entries and regenerates embeddings. May take a minute.
 
-Reads all .md entries and generates embeddings. May take a minute on first run.`,
+TRIGGER PATTERNS:
+- brief() returning nothing when it shouldn't → rebuild_index()
+- After bulk import → rebuild_index()
+- "Search seems broken" → rebuild_index()
+
+Example:
+- rebuild_index()`,
     inputSchema: {
         type: 'object',
         properties: {},
@@ -39,6 +47,8 @@ Reads all .md entries and generates embeddings. May take a minute on first run.`
         let indexed = 0;
         let skipped = 0;
         const errors = [];
+        // Progress file for status checks during rebuild
+        const progressFile = path.join(libraryPath, '.rebuild-progress.json');
         // Collect all .md files from all directories
         const allDirs = [localPath, importedPath, packagesPath];
         const allFiles = [];
@@ -51,8 +61,28 @@ Reads all .md entries and generates embeddings. May take a minute on first run.`
                 // Directory doesn't exist, skip
             }
         }
+        // Write initial progress
+        await fs.writeFile(progressFile, JSON.stringify({
+            status: 'processing',
+            current: 0,
+            total: allFiles.length,
+            currentFile: '',
+            percent: 0,
+            startedAt: new Date().toISOString(),
+        }), 'utf-8').catch(() => { });
         // Process each file
-        for (const filePath of allFiles) {
+        for (let i = 0; i < allFiles.length; i++) {
+            const filePath = allFiles[i];
+            // Update progress file
+            await fs.writeFile(progressFile, JSON.stringify({
+                status: 'processing',
+                current: i + 1,
+                total: allFiles.length,
+                currentFile: path.basename(filePath),
+                percent: Math.round(((i + 1) / allFiles.length) * 100),
+                indexed,
+                skipped,
+            }), 'utf-8').catch(() => { });
             try {
                 const content = await fs.readFile(filePath, 'utf-8');
                 const { data, content: body } = matter(content);
@@ -91,6 +121,8 @@ Reads all .md entries and generates embeddings. May take a minute on first run.`
         }
         // Save the index
         await saveIndex(index);
+        // Cleanup progress file
+        await fs.unlink(progressFile).catch(() => { });
         const stats = getIndexStats(index);
         const message = indexed > 0
             ? `Rebuilt index with ${indexed} entries (${stats.chunkCount} chunks). ${skipped} skipped.`

package/dist/tools/record.d.ts

@@ -5,6 +5,7 @@ export interface RecordResult {
 }
 export declare const recordTool: {
     name: string;
+    title: string;
     description: string;
     inputSchema: {
         type: "object";
@@ -36,5 +37,22 @@ export declare const recordTool: {
         };
         required: string[];
     };
+    outputSchema: {
+        type: "object";
+        properties: {
+            success: {
+                type: string;
+            };
+            path: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
     handler(args: unknown): Promise<RecordResult>;
 };

package/dist/tools/record.js

@@ -7,42 +7,37 @@ import { loadIndex, saveIndex, addToIndex } from '../library/vector-index.js';
 // ============================================================================
 export const recordTool = {
     name: 'record',
-    description: `Use this tool proactively throughout every conversation.
+    title: 'Save New Insight',
+    description: `CALL THIS IMMEDIATELY when you learn something worth keeping. Do NOT wait to be asked.
 
-CALL THIS IMMEDIATELY when you:
-- Solve a problem (before moving to the next thing)
-- Make a decision (capture the reasoning NOW)
-- Hit a gotcha (it WILL come up again)
-- Learn something non-obvious (context dies fast)
+USE THIS TOOL WHEN:
+- You solve a problem (BEFORE moving to the next thing)
+- You make a decision (capture the WHY now, not later)
+- You hit a gotcha or unexpected behavior
+- You learn something non-obvious about this codebase
+- You discover credentials, API keys, or configuration
+- You find out how something actually works vs how you assumed
 
-Do NOT wait for the user to ask. Do NOT batch multiple insights.
-One insight = one record() call. Call it the moment you notice it.
+DO NOT BATCH insights. One insight = one record() call.
+DO NOT SKIP because it seems minor. If it cost us 5+ minutes, record it.
 
 Quality bar: "I wish we knew this yesterday"
 
+TRIGGER PATTERNS:
+- Fixed a bug → record({ insight: "The issue was X because Y" })
+- Found credentials → record({ insight: "Auth uses X", context: "credentials" })
+- Made architectural choice → record({ insight: "Chose X over Y", reasoning: "..." })
+- Something didn't work as expected → record({ insight: "X actually does Y, not Z" })
+
 Good entries:
 - "Stripe retries webhooks but doesn't dedupe - always check idempotency key"
-- "Clock skew between services - add 30s buffer to token validation"
-- "GitHub org names are squattable even if you own the domain"
+- "Next.js 16 renamed middleware.ts to proxy.ts"
+- "API key format is tvk_ prefix + 32 chars"
 
 Not worth recording:
 - Generic docs (search exists)
 - Temporary hacks
-- Stuff that'll change next week
-
-Examples:
-
-Quick:
-- record({ insight: "Stripe webhooks need idempotency checks" })
-
-Rich:
-- record({
-    intent: "Setting up GitHub org for Telvok",
-    insight: "GitHub org names are first-come-first-served regardless of domain ownership",
-    context: "GitHub, npm, branding",
-    reasoning: "We owned telvok.com but someone squatted telvok org years ago",
-    example: "Had to use telvokdev instead of telvok"
-  })`,
+- Things that'll change next week`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -73,9 +68,18 @@ Rich:
         },
         required: ['insight'],
     },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            success: { type: 'boolean' },
+            path: { type: 'string', description: 'Path to the created entry file' },
+            title: { type: 'string', description: 'Title of the created entry' },
+        },
+        required: ['success', 'path', 'title'],
+    },
     async handler(args) {
         const { insight, intent, reasoning, context, example, title: providedTitle } = args;
-        if (!insight) {
+        if (!insight || !insight.trim()) {
             throw new Error('insight is required');
         }
         const libraryPath = getLibraryPath();

package/dist/tools/seller-analytics.d.ts

@@ -0,0 +1,53 @@
+interface SellerAnalyticsResult {
+    success: boolean;
+    message: string;
+    overview?: {
+        revenue: string;
+        downloads: number;
+        hits: number;
+        avgRating: string;
+        libraryCount: number;
+    };
+    books?: Array<{
+        name: string;
+        revenue: string;
+        downloads: number;
+        hits: number;
+        rating: string;
+        topEntries?: Array<{
+            title: string;
+            hits: number;
+            trend: string;
+        }>;
+        searchTerms?: Array<{
+            term: string;
+            count: number;
+        }>;
+    }>;
+    recent_reviews?: Array<{
+        book: string;
+        rating: string;
+        title: string;
+        reviewer: string;
+    }>;
+    insights?: {
+        totalSearches: number;
+        uniqueSearchTerms: number;
+        gapAnalysis?: Array<{
+            term: string;
+            count: number;
+        }>;
+    };
+}
+export declare const sellerAnalyticsTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: never[];
+    };
+    handler(): Promise<SellerAnalyticsResult>;
+};
+export default sellerAnalyticsTool;

package/dist/tools/seller-analytics.js

@@ -0,0 +1,180 @@
+// ============================================================================
+// Seller Analytics Tool
+// View your seller analytics - revenue, downloads, hits, ratings
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function formatGhostModeMessage(data) {
+    const lines = [];
+    lines.push(`Analytics for ${data.overview.libraryCount} book${data.overview.libraryCount === 1 ? '' : 's'}`);
+    lines.push('');
+    lines.push(`Overview:`);
+    lines.push(`  Revenue: $${data.overview.revenue.toFixed(2)}`);
+    lines.push(`  Downloads: ${data.overview.downloads}`);
+    lines.push(`  Hits: ${data.overview.hits}`);
+    if (data.overview.avgRating) {
+        lines.push(`  Avg Rating: ${data.overview.avgRating}/5`);
+    }
+    // Per-book breakdown with Ghost Mode data
+    if (data.byLibrary.length > 0) {
+        lines.push('');
+        lines.push('━'.repeat(40));
+        for (const book of data.byLibrary) {
+            lines.push('');
+            lines.push(`📚 ${book.name} - $${book.revenue.toFixed(2)} - ${book.hits} hits`);
+            // Top entries
+            if (book.topEntries && book.topEntries.length > 0) {
+                lines.push('');
+                lines.push('  Top Entries:');
+                book.topEntries.slice(0, 5).forEach((entry, i) => {
+                    lines.push(`    ${i + 1}. ${entry.title} - ${entry.hits} hits (${entry.trend})`);
+                });
+            }
+            // Search terms
+            if (book.searchTerms && book.searchTerms.length > 0) {
+                lines.push('');
+                lines.push('  Users searched for:');
+                book.searchTerms.slice(0, 5).forEach(term => {
+                    lines.push(`    • "${term.term}" (${term.count} queries)`);
+                });
+            }
+        }
+    }
+    // Gap analysis
+    if (data.insights?.zeroResultSearches && data.insights.zeroResultSearches.length > 0) {
+        lines.push('');
+        lines.push('━'.repeat(40));
+        lines.push('');
+        lines.push('💡 Gap Analysis (searches with no results):');
+        data.insights.zeroResultSearches.slice(0, 5).forEach(z => {
+            lines.push(`    • "${z.term}" (${z.count} searches)`);
+        });
+    }
+    return lines.join('\n');
+}
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const sellerAnalyticsTool = {
+    name: 'seller_analytics',
+    title: 'View Seller Analytics',
+    description: `View seller analytics for your published books.
+
+USE THIS TOOL WHEN:
+- User asks "how are my books doing" or "show my sales"
+- Checking revenue, downloads, or ratings
+- User wants to see which entries are most useful (Ghost Mode data)
+
+Shows revenue, downloads, hits, ratings, top entries, and search terms.
+
+TRIGGER PATTERNS:
+- "How are my books selling?" → seller_analytics()
+- "Show my revenue" → seller_analytics()
+- "What are people searching for?" → seller_analytics() (shows search terms)
+
+Example:
+- seller_analytics() - View all your analytics`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    async handler() {
+        // 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 {
+            const response = await fetch(`${TELVOK_API_URL}/api/seller/analytics`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to fetch analytics: HTTP ${response.status}`,
+                };
+            }
+            // Check if user has any libraries
+            if (data.overview.libraryCount === 0) {
+                return {
+                    success: true,
+                    message: 'You haven\'t published any books yet. Use library_publish() to publish your first book.',
+                    overview: {
+                        revenue: '$0.00',
+                        downloads: 0,
+                        hits: 0,
+                        avgRating: 'N/A',
+                        libraryCount: 0,
+                    },
+                    books: [],
+                    recent_reviews: [],
+                };
+            }
+            // Format for terminal display with Ghost Mode data
+            const result = {
+                success: true,
+                message: formatGhostModeMessage(data),
+                overview: {
+                    revenue: `$${data.overview.revenue.toFixed(2)}`,
+                    downloads: data.overview.downloads,
+                    hits: data.overview.hits,
+                    avgRating: data.overview.avgRating ? `${data.overview.avgRating}/5` : 'No ratings yet',
+                    libraryCount: data.overview.libraryCount,
+                },
+                books: data.byLibrary.map(b => ({
+                    name: b.name,
+                    revenue: `$${b.revenue.toFixed(2)}`,
+                    downloads: b.downloads,
+                    hits: b.hits,
+                    rating: b.rating ? `${b.rating}/5` : 'No ratings',
+                    topEntries: b.topEntries?.slice(0, 5).map(e => ({
+                        title: e.title,
+                        hits: e.hits,
+                        trend: e.trend,
+                    })),
+                    searchTerms: b.searchTerms?.slice(0, 5).map(t => ({
+                        term: t.term,
+                        count: t.count,
+                    })),
+                })),
+                recent_reviews: data.recentReviews.slice(0, 5).map(r => ({
+                    book: r.library.name,
+                    rating: `${r.rating}/5`,
+                    title: r.title || '(no title)',
+                    reviewer: r.reviewer?.name || 'Anonymous',
+                })),
+            };
+            // Add Ghost Mode insights if available
+            if (data.insights) {
+                result.insights = {
+                    totalSearches: data.insights.totalSearches,
+                    uniqueSearchTerms: data.insights.uniqueSearchTerms,
+                    gapAnalysis: data.insights.zeroResultSearches?.slice(0, 10).map(z => ({
+                        term: z.term,
+                        count: z.count,
+                    })),
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch analytics: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default sellerAnalyticsTool;

package/dist/tools/sync.d.ts

@@ -0,0 +1,55 @@
+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;
+    title: 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;