@telvok/librarian-mcp 1.5.4 → 2.3.0

package/dist/tools 2/rate-book.d.ts

@@ -0,0 +1,39 @@
+interface RateBookResult {
+    success: boolean;
+    message: string;
+    review?: {
+        id: string;
+        rating: number;
+        is_verified_purchase: boolean;
+    };
+}
+export declare const rateBookTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            slug: {
+                type: string;
+                description: string;
+            };
+            rating: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            comment: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<RateBookResult>;
+};
+export default rateBookTool;

package/dist/tools 2/rate-book.js

@@ -0,0 +1,139 @@
+// ============================================================================
+// Rate Book Tool
+// Rate a book you've purchased on the Telvok marketplace
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const rateBookTool = {
+    name: 'rate_book',
+    description: `Rate a book you've purchased from the Telvok marketplace.
+
+Share your experience to help other agents find quality content.
+Rating scale: 1 (poor) to 5 (excellent).
+
+Requires authentication and purchase.
+
+Examples:
+- rate_book({ slug: "react-best-practices", rating: 5 })
+- rate_book({ slug: "auth-patterns", rating: 4, title: "Very helpful", comment: "Saved hours on token refresh logic" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            slug: {
+                type: 'string',
+                description: 'Book slug to rate',
+            },
+            rating: {
+                type: 'number',
+                description: 'Rating from 1 to 5',
+                minimum: 1,
+                maximum: 5,
+            },
+            title: {
+                type: 'string',
+                description: 'Optional review title',
+            },
+            comment: {
+                type: 'string',
+                description: 'Optional review comment',
+            },
+        },
+        required: ['slug', 'rating'],
+    },
+    async handler(args) {
+        const { slug, rating, title, comment } = args;
+        // Validation
+        if (!slug || typeof slug !== 'string') {
+            return {
+                success: false,
+                message: 'Book slug is required',
+            };
+        }
+        if (typeof rating !== 'number' || rating < 1 || rating > 5) {
+            return {
+                success: false,
+                message: 'Rating must be a number between 1 and 5',
+            };
+        }
+        // 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/reviews`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    slug,
+                    rating: Math.round(rating),
+                    title: title?.trim() || undefined,
+                    comment: comment?.trim() || undefined,
+                }),
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                // Handle specific error cases with user-friendly messages
+                if (response.status === 404) {
+                    return {
+                        success: false,
+                        message: `Book '${slug}' not found. Check the slug with my_books().`,
+                    };
+                }
+                if (response.status === 400 && data.error?.includes('own')) {
+                    return {
+                        success: false,
+                        message: 'Cannot review your own book.',
+                    };
+                }
+                if (response.status === 409) {
+                    return {
+                        success: false,
+                        message: 'You\'ve already reviewed this book.',
+                    };
+                }
+                if (response.status === 403) {
+                    return {
+                        success: false,
+                        message: `You haven't purchased '${slug}'. Buy it first with marketplace_buy().`,
+                    };
+                }
+                return {
+                    success: false,
+                    message: data.error || `Rating failed: HTTP ${response.status}`,
+                };
+            }
+            const stars = '\u2605'.repeat(Math.round(rating)) + '\u2606'.repeat(5 - Math.round(rating));
+            const verifiedBadge = data.is_verified_purchase ? ' - Verified Purchase' : '';
+            return {
+                success: true,
+                message: `Rated '${slug}' ${stars} (${Math.round(rating)}/5)${verifiedBadge}`,
+                review: {
+                    id: data.id,
+                    rating: data.rating,
+                    is_verified_purchase: data.is_verified_purchase,
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Rating failed: ${message}`,
+            };
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default rateBookTool;

package/dist/tools 2/rebuild-index.d.ts

@@ -0,0 +1,23 @@
+export interface RebuildResult {
+    success: boolean;
+    indexed: number;
+    skipped: number;
+    errors: string[];
+    stats: {
+        entryCount: number;
+        chunkCount: number;
+        modelId: string;
+        rebuilt: string;
+    };
+    message: string;
+}
+export declare const rebuildIndexTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: never[];
+    };
+    handler(_args: unknown): Promise<RebuildResult>;
+};

package/dist/tools 2/rebuild-index.js

@@ -0,0 +1,107 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import { getLibraryPath, getLocalPath, getImportedPath, getPackagesPath } from '../library/storage.js';
+import { saveIndex, addToIndex, getIndexStats } from '../library/vector-index.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const rebuildIndexTool = {
+    name: 'rebuild_index',
+    description: `Rebuild the semantic search index for all library entries.
+
+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 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 generates embeddings. May take a minute on first run.`,
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    async handler(_args) {
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        const importedPath = getImportedPath(libraryPath);
+        const packagesPath = getPackagesPath(libraryPath);
+        // Create a fresh index
+        const index = {
+            version: 1,
+            rebuilt: '',
+            modelId: '',
+            entries: [],
+        };
+        let indexed = 0;
+        let skipped = 0;
+        const errors = [];
+        // Collect all .md files from all directories
+        const allDirs = [localPath, importedPath, packagesPath];
+        const allFiles = [];
+        for (const dir of allDirs) {
+            try {
+                const files = await glob(path.join(dir, '**/*.md'), { nodir: true });
+                allFiles.push(...files);
+            }
+            catch {
+                // Directory doesn't exist, skip
+            }
+        }
+        // Process each file
+        for (const filePath of allFiles) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const { data, content: body } = matter(content);
+                // Skip empty files
+                if (!body.trim()) {
+                    skipped++;
+                    continue;
+                }
+                // Extract title
+                let title = data.title;
+                if (!title) {
+                    const headingMatch = body.match(/^#\s+(.+)$/m);
+                    if (headingMatch) {
+                        title = headingMatch[1].trim();
+                    }
+                    else {
+                        title = path.basename(filePath, '.md').replace(/-/g, ' ');
+                    }
+                }
+                // Build full content for embedding
+                const fullContent = [
+                    title,
+                    data.intent || '',
+                    body.trim(),
+                    data.context || '',
+                ].filter(Boolean).join('\n\n');
+                const relativePath = path.relative(libraryPath, filePath);
+                await addToIndex(index, relativePath, title, fullContent);
+                indexed++;
+            }
+            catch (error) {
+                const relativePath = path.relative(libraryPath, filePath);
+                errors.push(`${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+                skipped++;
+            }
+        }
+        // Save the index
+        await saveIndex(index);
+        const stats = getIndexStats(index);
+        const message = indexed > 0
+            ? `Rebuilt index with ${indexed} entries (${stats.chunkCount} chunks). ${skipped} skipped.`
+            : 'No entries found to index.';
+        return {
+            success: indexed > 0 || allFiles.length === 0,
+            indexed,
+            skipped,
+            errors,
+            stats,
+            message,
+        };
+    },
+};

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

@@ -0,0 +1,40 @@
+export interface RecordResult {
+    success: boolean;
+    path: string;
+    title: string;
+}
+export declare const recordTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            insight: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                description: string;
+            };
+            reasoning: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+            };
+            example: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<RecordResult>;
+};

package/dist/tools 2/record.js

@@ -0,0 +1,205 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getLibraryPath, getLocalPath } from '../library/storage.js';
+import { loadIndex, saveIndex, addToIndex } from '../library/vector-index.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const recordTool = {
+    name: 'record',
+    description: `Use this tool proactively throughout every conversation.
+
+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)
+
+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.
+
+Quality bar: "I wish we knew this yesterday"
+
+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"
+
+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"
+  })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            insight: {
+                type: 'string',
+                description: 'What did we learn? The knowledge worth keeping.',
+            },
+            intent: {
+                type: 'string',
+                description: 'What were we trying to accomplish?',
+            },
+            reasoning: {
+                type: 'string',
+                description: 'Why does this work? Why this over alternatives?',
+            },
+            context: {
+                type: 'string',
+                description: "Topic, area, or when this applies (e.g., 'auth', 'payments', 'only on Windows')",
+            },
+            example: {
+                type: 'string',
+                description: 'Code snippet or concrete illustration',
+            },
+            title: {
+                type: 'string',
+                description: 'Entry title. Auto-generated from insight if not provided.',
+            },
+        },
+        required: ['insight'],
+    },
+    async handler(args) {
+        const { insight, intent, reasoning, context, example, title: providedTitle } = args;
+        if (!insight) {
+            throw new Error('insight is required');
+        }
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        // Ensure local directory exists
+        await fs.mkdir(localPath, { recursive: true });
+        // Generate title
+        const title = providedTitle || generateTitle(insight, intent);
+        // Generate slug for filename
+        const slug = slugify(title);
+        const created = new Date().toISOString();
+        // Handle filename collisions
+        let filename = `${slug}.md`;
+        let filePath = path.join(localPath, filename);
+        let counter = 1;
+        while (await fileExists(filePath)) {
+            filename = `${slug}-${counter}.md`;
+            filePath = path.join(localPath, filename);
+            counter++;
+        }
+        // Build frontmatter
+        const frontmatterLines = ['---'];
+        if (intent) {
+            frontmatterLines.push(`intent: "${escapeYaml(intent)}"`);
+        }
+        if (context) {
+            frontmatterLines.push(`context: "${escapeYaml(context)}"`);
+        }
+        frontmatterLines.push(`created: "${created}"`);
+        frontmatterLines.push(`updated: "${created}"`);
+        frontmatterLines.push('source: "local"');
+        frontmatterLines.push('hits: 0');
+        frontmatterLines.push('last_hit: null');
+        frontmatterLines.push('---');
+        // Build body
+        const bodyLines = [];
+        bodyLines.push(`# ${title}`);
+        bodyLines.push('');
+        bodyLines.push(insight);
+        if (reasoning) {
+            bodyLines.push('');
+            bodyLines.push('## Reasoning');
+            bodyLines.push('');
+            bodyLines.push(reasoning);
+        }
+        if (example) {
+            bodyLines.push('');
+            bodyLines.push('## Example');
+            bodyLines.push('');
+            // Detect if it looks like code
+            if (example.includes('\n') || example.includes('{') || example.includes('(')) {
+                bodyLines.push('```');
+                bodyLines.push(example);
+                bodyLines.push('```');
+            }
+            else {
+                bodyLines.push('```');
+                bodyLines.push(example);
+                bodyLines.push('```');
+            }
+        }
+        // Combine and write
+        const fileContent = frontmatterLines.join('\n') + '\n\n' + bodyLines.join('\n') + '\n';
+        await fs.writeFile(filePath, fileContent, 'utf-8');
+        const relativePath = path.relative(libraryPath, filePath);
+        // Add to vector index for semantic search
+        try {
+            const index = await loadIndex();
+            // Combine all text for embedding
+            const fullContent = [
+                title,
+                intent || '',
+                insight,
+                reasoning || '',
+                example || '',
+                context || '',
+            ].filter(Boolean).join('\n\n');
+            await addToIndex(index, relativePath, title, fullContent);
+            await saveIndex(index);
+        }
+        catch (embeddingError) {
+            // Don't fail the record operation if embedding fails
+            // Entry is still saved and searchable via keywords
+            console.error('Failed to add embedding:', embeddingError);
+        }
+        return {
+            success: true,
+            path: relativePath,
+            title,
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function generateTitle(insight, intent) {
+    // Try to extract from first sentence of insight
+    const firstSentence = insight.split(/[.!?\n]/)[0].trim();
+    if (firstSentence.length <= 60) {
+        return firstSentence;
+    }
+    // If insight is too long, try intent
+    if (intent && intent.length <= 60) {
+        return intent;
+    }
+    // Truncate insight
+    return firstSentence.slice(0, 57) + '...';
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+function escapeYaml(text) {
+    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,35 @@
+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;
+    }>;
+    recent_reviews?: Array<{
+        book: string;
+        rating: string;
+        title: string;
+        reviewer: string;
+    }>;
+}
+export declare const sellerAnalyticsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: never[];
+    };
+    handler(): Promise<SellerAnalyticsResult>;
+};
+export default sellerAnalyticsTool;

package/dist/tools 2/seller-analytics.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// 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';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const sellerAnalyticsTool = {
+    name: 'seller_analytics',
+    description: `View your seller analytics - revenue, downloads, hits, and ratings for your published books.
+
+Shows:
+- Overview: Total revenue (after 15% platform fee), downloads, hits, average rating
+- Per-book breakdown: Revenue, downloads, hits, rating for each book
+- Recent reviews: Latest reviews on your books
+
+Requires authentication. Run auth({ action: "login" }) first if not connected.
+
+Examples:
+- 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 marketplace_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
+            return {
+                success: true,
+                message: `Analytics for ${data.overview.libraryCount} book${data.overview.libraryCount === 1 ? '' : 's'}`,
+                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',
+                })),
+                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',
+                })),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch analytics: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default sellerAnalyticsTool;