@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/tools/mark-hit.js

@@ -2,19 +2,27 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import matter from 'gray-matter';
 import { getLibraryPath } from '../library/storage.js';
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
 // ============================================================================
 // Tool Definition
 // ============================================================================
 export const markHitTool = {
     name: 'mark_hit',
-    description: `Mark a library entry as helpful - call this when knowledge from the library helped solve a problem.
+    title: 'Mark Entry as Helpful',
+    description: `CALL THIS when an entry from brief() actually helped. Fire and forget.
 
-When an entry from brief() actually helped you complete a task or make a decision,
-call mark_hit() on it. This helps the library learn which entries are most useful.
+USE THIS TOOL WHEN:
+- A brief() result helped you solve the problem
+- You used information from an entry to make a decision
+- An entry saved you from making a mistake
 
-Entries with more hits bubble up in future brief() results.
+DO NOT SKIP - this is how the library learns what's useful.
+Entries with more hits rank higher in future searches.
 
-Fire and forget - call it and move on.
+TRIGGER PATTERNS:
+- Used entry from brief() → mark_hit({ path: "<path from brief result>" })
+- Entry prevented a mistake → mark_hit({ path: "..." })
 
 Example:
 - mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })`,
@@ -33,6 +41,48 @@ Example:
         if (!entryPath) {
             throw new Error('path is required');
         }
+        // Handle cloud entries (from purchased books via brief())
+        // These have paths like "cloud:book-slug"
+        if (entryPath.startsWith('cloud:')) {
+            const bookSlug = entryPath.slice(6); // Remove "cloud:" prefix
+            if (!bookSlug) {
+                throw new Error('Invalid cloud entry path');
+            }
+            // Get API key for authenticated request
+            const apiKey = await loadApiKey();
+            if (!apiKey) {
+                // Can't track hit without auth, but don't fail - fire and forget
+                return {
+                    success: true,
+                    path: entryPath,
+                    hits: 1, // We don't know actual count for cloud entries
+                };
+            }
+            // POST hit to server with auth
+            try {
+                await fetch(`${TELVOK_API_URL}/api/hits`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        hits: [{
+                                slug: bookSlug,
+                                timestamp: new Date().toISOString(),
+                            }],
+                    }),
+                });
+            }
+            catch {
+                // Silently ignore server errors - fire and forget
+            }
+            return {
+                success: true,
+                path: entryPath,
+                hits: 1, // We don't track local count for cloud entries
+            };
+        }
         const libraryPath = getLibraryPath();
         // Resolve the full path
         let fullPath;
@@ -62,6 +112,34 @@ Example:
         const updatedContent = matter.stringify(body, data);
         // Write back
         await fs.writeFile(fullPath, updatedContent, 'utf-8');
+        // Sync to server if this is an imported/packages entry
+        const normalizedPath = entryPath.replace(/\\/g, '/');
+        if (normalizedPath.startsWith('packages/') || normalizedPath.includes('/packages/')) {
+            try {
+                // Extract library slug from path: packages/{slug}/entry.md
+                const parts = normalizedPath.split('/');
+                const packagesIndex = parts.indexOf('packages');
+                if (packagesIndex !== -1 && parts.length > packagesIndex + 1) {
+                    const librarySlug = parts[packagesIndex + 1];
+                    // POST to server - fire and forget
+                    fetch(`${TELVOK_API_URL}/api/hits`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            hits: [{
+                                    slug: librarySlug,
+                                    timestamp: new Date().toISOString(),
+                                }],
+                        }),
+                    }).catch(() => {
+                        // Silently ignore server sync errors - local update already succeeded
+                    });
+                }
+            }
+            catch {
+                // Ignore errors - local update already succeeded
+            }
+        }
         return {
             success: true,
             path: entryPath,

package/dist/tools/my-books.d.ts

@@ -0,0 +1,51 @@
+interface PublishedBook {
+    slug: string;
+    name: string;
+    entries_count: number;
+    pricing: {
+        type: string;
+        display: string;
+    };
+    created_at: string;
+    url: string;
+}
+interface PurchasedBook {
+    slug: string;
+    name: string;
+    author: string;
+    entries_count: number;
+    pricing: {
+        type: string;
+        display: string;
+    };
+    purchased_at: string;
+    status: string;
+}
+interface MyBooksResult {
+    success: boolean;
+    message: string;
+    published?: PublishedBook[];
+    purchased?: PurchasedBook[];
+    summary?: {
+        published_count: number;
+        purchased_count: number;
+    };
+}
+export declare const myBooksTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filter: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<MyBooksResult>;
+};
+export default myBooksTool;

package/dist/tools/my-books.js

@@ -0,0 +1,115 @@
+// ============================================================================
+// My Books Tool
+// View published and purchased books from Telvok library
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const myBooksTool = {
+    name: 'my_books',
+    title: 'View My Books',
+    description: `View your published and purchased books.
+
+USE THIS TOOL WHEN:
+- User asks "what books do I have" or "show my library"
+- Need to find a book slug for sync(), rate_book(), or other operations
+- Checking what content user owns
+
+Shows published (created) and purchased (bought/claimed) books.
+
+TRIGGER PATTERNS:
+- "Show my books" → my_books()
+- "What have I published?" → my_books({ filter: "published" })
+- "What books did I buy?" → my_books({ filter: "purchased" })
+- Need book slugs → my_books()
+
+Examples:
+- my_books() - Show all your books
+- my_books({ filter: "published" }) - Only your published books
+- my_books({ filter: "purchased" }) - Only books you've bought`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'string',
+                enum: ['all', 'published', 'purchased'],
+                description: 'Filter results (default: all)',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { filter = 'all' } = (args || {});
+        // Validate filter
+        if (filter && !['all', 'published', 'purchased'].includes(filter)) {
+            return {
+                success: false,
+                message: 'Invalid filter. Must be: all, published, or purchased',
+            };
+        }
+        // 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 url = new URL(`${TELVOK_API_URL}/api/my-books`);
+            if (filter && filter !== 'all') {
+                url.searchParams.set('filter', filter);
+            }
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to fetch books: HTTP ${response.status}`,
+                };
+            }
+            // Format output message
+            const publishedCount = data.published?.length || 0;
+            const purchasedCount = data.purchased?.length || 0;
+            let message = '';
+            if (filter === 'published') {
+                message = publishedCount === 0
+                    ? 'You haven\'t published any books yet.'
+                    : `You have ${publishedCount} published book${publishedCount === 1 ? '' : 's'}.`;
+            }
+            else if (filter === 'purchased') {
+                message = purchasedCount === 0
+                    ? 'You haven\'t purchased any books yet.'
+                    : `You have ${purchasedCount} purchased book${purchasedCount === 1 ? '' : 's'}.`;
+            }
+            else {
+                const total = publishedCount + purchasedCount;
+                message = total === 0
+                    ? 'No books yet. Publish with library_publish() or browse with library_search().'
+                    : `${publishedCount} published, ${purchasedCount} purchased.`;
+            }
+            return {
+                success: true,
+                message,
+                published: data.published,
+                purchased: data.purchased,
+                summary: data.summary,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to fetch books: ${message}`);
+        }
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default myBooksTool;

package/dist/tools/my-bounties.d.ts

@@ -0,0 +1,43 @@
+interface BountyItem {
+    id: string;
+    title: string;
+    description: string | null;
+    amount: string;
+    amount_cents: number;
+    status: string;
+    created_at: string;
+    expires_at: string;
+    claimed_at: string | null;
+    submitted_at: string | null;
+    completed_at: string | null;
+}
+interface MyBountiesResult {
+    success: boolean;
+    message: string;
+    created: BountyItem[];
+    claimed: BountyItem[];
+    summary?: {
+        total_created: number;
+        total_claimed: number;
+        pending_approval: number;
+        in_progress: number;
+    };
+}
+export declare const myBountiesTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            role: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<MyBountiesResult>;
+};
+export {};

package/dist/tools/my-bounties.js

@@ -0,0 +1,126 @@
+// ============================================================================
+// My Bounties Tool
+// View your created and claimed bounties
+// ============================================================================
+import { loadApiKey } from './auth.js';
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const myBountiesTool = {
+    name: 'my_bounties',
+    title: 'View My Bounties',
+    description: `View your bounty activity and pending actions.
+
+USE THIS TOOL WHEN:
+- User asks "what bounties do I have"
+- Checking status of created or claimed bounties
+- User needs to see pending approvals or submissions
+
+Shows bounties you created (as buyer) and claimed (as seller).
+
+TRIGGER PATTERNS:
+- "Show my bounties" → my_bounties()
+- "What bounties am I working on?" → my_bounties({ role: "claimer" })
+- "Check bounty status" → my_bounties()
+
+Examples:
+- my_bounties() - Show all your bounties
+- my_bounties({ role: "creator" }) - Only bounties you created
+- my_bounties({ role: "claimer" }) - Only bounties you claimed`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            role: {
+                type: 'string',
+                enum: ['creator', 'claimer', 'all'],
+                description: 'Filter by role (default: all)',
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { role = 'all' } = (args || {});
+        // Check authentication
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return {
+                success: false,
+                message: 'Not authenticated. Run auth({ action: "login" }) to connect your Telvok account first.',
+                created: [],
+                claimed: [],
+            };
+        }
+        try {
+            const params = new URLSearchParams();
+            if (role !== 'all') {
+                params.set('role', role);
+            }
+            const response = await fetch(`${TELVOK_API_URL}/api/my-bounties?${params}`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            const data = await response.json();
+            if (!response.ok) {
+                return {
+                    success: false,
+                    message: data.error || `Failed to fetch bounties: HTTP ${response.status}`,
+                    created: [],
+                    claimed: [],
+                };
+            }
+            const created = data.created || [];
+            const claimed = data.claimed || [];
+            const summary = data.summary;
+            // Build summary message
+            const parts = [];
+            if (created.length > 0) {
+                parts.push(`**Bounties You Created (${created.length}):**`);
+                created.forEach((b, i) => {
+                    const statusEmoji = b.status === 'submitted' ? '⏳' : b.status === 'completed' ? '✅' : '📝';
+                    parts.push(`${i + 1}. ${statusEmoji} ${b.title} (${b.amount}) - ${b.status}`);
+                });
+            }
+            if (claimed.length > 0) {
+                if (parts.length > 0)
+                    parts.push('');
+                parts.push(`**Bounties You Claimed (${claimed.length}):**`);
+                claimed.forEach((b, i) => {
+                    const statusEmoji = b.status === 'submitted' ? '⏳' : b.status === 'completed' ? '✅' : '🔨';
+                    parts.push(`${i + 1}. ${statusEmoji} ${b.title} (${b.amount}) - ${b.status}`);
+                });
+            }
+            if (parts.length === 0) {
+                parts.push('No bounties found. Create one with bounty_create() or browse with bounty_list().');
+            }
+            // Add action hints
+            if (summary?.pending_approval > 0) {
+                parts.push('');
+                parts.push(`💡 You have ${summary.pending_approval} submission(s) awaiting your approval.`);
+            }
+            if (summary?.in_progress > 0) {
+                parts.push('');
+                parts.push(`💡 You have ${summary.in_progress} claimed bounty(s) to complete.`);
+            }
+            return {
+                success: true,
+                created,
+                claimed,
+                summary,
+                message: parts.join('\n'),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                message: `Failed to fetch bounties: ${message}`,
+                created: [],
+                claimed: [],
+            };
+        }
+    },
+};

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

@@ -0,0 +1,40 @@
+interface RateBookResult {
+    success: boolean;
+    message: string;
+    review?: {
+        id: string;
+        rating: number;
+        is_verified_purchase: boolean;
+    };
+}
+export declare const rateBookTool: {
+    name: string;
+    title: 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/rate-book.js

@@ -0,0 +1,147 @@
+// ============================================================================
+// Rate Book Tool
+// Rate a book you've purchased on the Telvok library
+// ============================================================================
+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',
+    title: 'Rate a Book',
+    description: `Rate a purchased book to help others find quality content.
+
+USE THIS TOOL WHEN:
+- A purchased book was helpful (or not) - share the experience
+- User says "rate that book" or "leave a review"
+- After using a book's knowledge successfully
+
+Rating scale: 1 (poor) to 5 (excellent). Requires purchase.
+
+TRIGGER PATTERNS:
+- Book helped solve problem → rate_book({ slug: "...", rating: 5 })
+- "Rate that book 4 stars" → rate_book({ slug: "...", rating: 4 })
+- "Leave a review" → rate_book({ slug: "...", rating: X, comment: "..." })
+
+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 library_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/rebuild-index.d.ts

@@ -13,6 +13,7 @@ export interface RebuildResult {
 }
 export declare const rebuildIndexTool: {
     name: string;
+    title: string;
     description: string;
     inputSchema: {
         type: "object";