@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/tools/brief.js

@@ -4,21 +4,36 @@ import matter from 'gray-matter';
 import { glob } from 'glob';
 import { getLibraryPath, getLocalPath, getImportedPath, getPackagesPath } from '../library/storage.js';
 import { loadIndex, semanticSearch, isIndexStale } from '../library/vector-index.js';
+import { loadApiKey } from './auth.js';
 // ============================================================================
 // Tool Definition
 // ============================================================================
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
 export const briefTool = {
     name: 'brief',
-    description: `Check what we already know before diving in.
+    title: 'Search Knowledge Library',
+    description: `CALL THIS PROACTIVELY before thinking through problems, making decisions, or planning.
 
-We've solved problems before. Before thinking through a problem, making
-decisions, or planning - brief yourself on what past-us figured out.
-Searches intent, insight, context, and examples.
+USE THIS TOOL WHEN:
+- Starting work on ANY topic (check what we already know)
+- A problem feels familiar (we probably solved it before)
+- Making architectural or implementation decisions
+- Debugging issues (past-us likely hit the same gotcha)
+- The user mentions something we've worked on before
+
+DO NOT SKIP THIS because you think you know the answer. Our library contains project-specific context, credentials, and decisions that general knowledge doesn't have.
+
+TRIGGER PATTERNS:
+- User asks about auth/tokens → brief({ query: "auth" })
+- Starting Stripe work → brief({ query: "stripe" })
+- Any error/debugging → brief({ query: "<error topic>" })
+- User says "remember when..." → brief({ query: "<topic>" })
+- Beginning any task → brief({}) for recent context
 
 Examples:
 - brief({ query: "stripe webhooks" })
-- brief({ query: "auth token" })
-- brief({}) → returns recent entries`,
+- brief({}) → returns recent entries
+- brief({ query: "react", include_library: true }) → also search library`,
     inputSchema: {
         type: 'object',
         properties: {
@@ -31,11 +46,58 @@ Examples:
                 description: 'Max entries to return',
                 default: 5,
             },
+            include_library: {
+                type: 'boolean',
+                description: 'Also search Telvok library for relevant books',
+                default: false,
+            },
         },
         required: [],
     },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            entries: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        preview: { type: 'string' },
+                        path: { type: 'string' },
+                        hits: { type: 'number' },
+                        source: { type: 'string', enum: ['local', 'cloud', 'packages'] },
+                        book_name: { type: 'string' },
+                    },
+                },
+            },
+            total: { type: 'number' },
+            message: { type: 'string' },
+            libraryPath: { type: 'string' },
+            library: {
+                type: 'object',
+                properties: {
+                    books: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                slug: { type: 'string' },
+                                name: { type: 'string' },
+                                description: { type: 'string' },
+                                pricing: { type: 'string' },
+                                entries: { type: 'number' },
+                            },
+                        },
+                    },
+                    total: { type: 'number' },
+                },
+            },
+        },
+        required: ['entries', 'total', 'message', 'libraryPath'],
+    },
     async handler(args) {
-        const { query, limit = 5 } = args;
+        const { query, limit = 5, include_library = false } = args;
         const libraryPath = getLibraryPath();
         const localPath = getLocalPath(libraryPath);
         const importedPath = getImportedPath(libraryPath);
@@ -76,11 +138,62 @@ Examples:
                 .filter((e) => e !== undefined);
             const total = allEntries.length;
             const entries = allEntries.slice(0, limit);
+            // Always fetch cloud content if authenticated (owned/purchased books)
+            // Only fetch marketplace if include_library flag is set
+            let cloudResult;
+            let libraryResult;
+            if (query) {
+                // Always fetch cloud content from owned books if authenticated
+                cloudResult = await fetchCloudContent(query, limit);
+                // Only fetch marketplace discovery if explicitly requested
+                if (include_library) {
+                    libraryResult = await fetchMarketplaceResults(query, 5);
+                    // Filter library to exclude books user already owns
+                    if (cloudResult.entries.length > 0) {
+                        const ownedSlugs = new Set(cloudResult.entries.map(e => e.book_slug));
+                        libraryResult.books = libraryResult.books.filter(b => !ownedSlugs.has(b.slug));
+                        libraryResult.total = libraryResult.books.length;
+                    }
+                }
+            }
+            // Convert cloud entries to BriefEntry format and merge
+            let finalEntries = [...entries];
+            if (cloudResult && cloudResult.entries.length > 0) {
+                const cloudBriefEntries = cloudResult.entries.map(ce => ({
+                    title: ce.title,
+                    intent: ce.intent,
+                    context: ce.context,
+                    preview: ce.insight.length > 100 ? ce.insight.slice(0, 100) + '...' : ce.insight,
+                    path: `cloud:${ce.book_slug}`, // Virtual path for cloud entries
+                    created: new Date().toISOString(),
+                    hits: 0,
+                    last_hit: null,
+                    source: 'cloud',
+                    book_name: ce.book_name,
+                    book_slug: ce.book_slug,
+                }));
+                // Interleave cloud entries with local: put cloud first (paid content priority)
+                // then fill remaining slots with local entries
+                const cloudCount = Math.min(cloudBriefEntries.length, Math.ceil(limit / 2));
+                const localCount = limit - cloudCount;
+                finalEntries = [
+                    ...cloudBriefEntries.slice(0, cloudCount),
+                    ...entries.slice(0, localCount),
+                ];
+            }
+            let message = `Found ${total} local ${total === 1 ? 'entry' : 'entries'} for "${query}" (semantic search).`;
+            if (cloudResult && cloudResult.entries.length > 0) {
+                message += ` Also found ${cloudResult.total} matching entries from owned books.`;
+            }
+            if (libraryResult && libraryResult.books.length > 0) {
+                message += ` ${libraryResult.total} book(s) available on library.`;
+            }
             return {
-                entries,
-                total,
-                message: `Found ${total} ${total === 1 ? 'entry' : 'entries'} for "${query}" (semantic search).`,
+                entries: finalEntries,
+                total: finalEntries.length,
+                message,
                 libraryPath: localPath,
+                library: libraryResult,
             };
         }
         // Fall back to keyword search
@@ -110,7 +223,7 @@ Examples:
         catch {
             // No imported files
         }
-        // Read packages entries (marketplace content)
+        // Read packages entries (library content)
         try {
             const packagesFiles = await glob(path.join(packagesPath, '**/*.md'), { nodir: true });
             for (const filePath of packagesFiles) {
@@ -143,21 +256,64 @@ Examples:
         const total = allEntries.length;
         // Apply limit
         const entries = allEntries.slice(0, limit);
+        // Always fetch cloud content if authenticated (owned/purchased books)
+        // Only fetch marketplace if include_library flag is set
+        let cloudResult;
+        let libraryResult;
+        if (query) {
+            // Always fetch cloud content from owned books if authenticated
+            cloudResult = await fetchCloudContent(query, limit);
+            // Only fetch marketplace discovery if explicitly requested
+            if (include_library) {
+                libraryResult = await fetchMarketplaceResults(query, 5);
+                // Filter library to exclude books user already owns
+                if (cloudResult.entries.length > 0) {
+                    const ownedSlugs = new Set(cloudResult.entries.map(e => e.book_slug));
+                    libraryResult.books = libraryResult.books.filter(b => !ownedSlugs.has(b.slug));
+                    libraryResult.total = libraryResult.books.length;
+                }
+            }
+        }
+        // Convert cloud entries to BriefEntry format and merge
+        let finalEntries = [...entries];
+        if (cloudResult && cloudResult.entries.length > 0) {
+            const cloudBriefEntries = cloudResult.entries.map(ce => ({
+                title: ce.title,
+                intent: ce.intent,
+                context: ce.context,
+                preview: ce.insight.length > 100 ? ce.insight.slice(0, 100) + '...' : ce.insight,
+                path: `cloud:${ce.book_slug}`, // Virtual path for cloud entries
+                created: new Date().toISOString(),
+                hits: 0,
+                last_hit: null,
+                source: 'cloud',
+                book_name: ce.book_name,
+                book_slug: ce.book_slug,
+            }));
+            finalEntries = [...entries, ...cloudBriefEntries].slice(0, limit);
+        }
         // Build message
         let message;
         if (query) {
             message = total === 0
-                ? `No entries found for "${query}".`
-                : `Found ${total} ${total === 1 ? 'entry' : 'entries'} for "${query}".`;
+                ? `No local entries found for "${query}".`
+                : `Found ${total} local ${total === 1 ? 'entry' : 'entries'} for "${query}".`;
         }
         else {
             message = `${total} ${total === 1 ? 'entry' : 'entries'} in library.`;
         }
+        if (cloudResult && cloudResult.entries.length > 0) {
+            message += ` Also found ${cloudResult.total} matching entries from owned books.`;
+        }
+        if (libraryResult && libraryResult.books.length > 0) {
+            message += ` ${libraryResult.total} book(s) available on library.`;
+        }
         return {
-            entries,
-            total,
+            entries: finalEntries,
+            total: finalEntries.length,
             message,
             libraryPath: localPath,
+            library: libraryResult,
         };
     },
 };
@@ -246,3 +402,66 @@ function rankEntries(entries) {
     scored.sort((a, b) => b.score - a.score);
     return scored.map(s => s.entry);
 }
+async function fetchCloudContent(query, limit) {
+    try {
+        // Check if authenticated
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            return { entries: [], total: 0 };
+        }
+        const response = await fetch(`${TELVOK_API_URL}/api/library/query`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ query, limit }),
+        });
+        if (!response.ok) {
+            // Don't fail if cloud query fails
+            return { entries: [], total: 0 };
+        }
+        const data = await response.json();
+        return {
+            entries: data.entries || [],
+            total: data.total || 0,
+        };
+    }
+    catch {
+        // Network error - silently return empty results
+        return { entries: [], total: 0 };
+    }
+}
+// ============================================================================
+// Marketplace Search
+// ============================================================================
+async function fetchMarketplaceResults(query, limit) {
+    try {
+        const response = await fetch(`${TELVOK_API_URL}/api/search`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, limit }),
+        });
+        if (!response.ok) {
+            // Don't fail the whole brief() if library is down
+            return { books: [], total: 0 };
+        }
+        const data = await response.json();
+        const books = (data.books || []).map((b) => ({
+            slug: b.slug,
+            name: b.name,
+            description: b.description,
+            pricing: b.pricing,
+            price: b.price,
+            entries: b.entries,
+        }));
+        return {
+            books,
+            total: data.total || 0,
+        };
+    }
+    catch {
+        // Network error - silently return empty results
+        return { books: [], total: 0 };
+    }
+}

package/dist/tools/delete.d.ts

@@ -0,0 +1,87 @@
+interface EntryInfo {
+    path: string;
+    title: string;
+    preview: string;
+    created?: string;
+}
+interface DeleteResult {
+    success: boolean;
+    message: string;
+    deleted?: {
+        path: string;
+        title: string;
+    };
+    matches?: EntryInfo[];
+    action_required?: string;
+}
+export declare const deleteTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    outputSchema: {
+        type: "object";
+        properties: {
+            success: {
+                type: string;
+            };
+            message: {
+                type: string;
+            };
+            deleted: {
+                type: string;
+                properties: {
+                    path: {
+                        type: string;
+                    };
+                    title: {
+                        type: string;
+                    };
+                };
+            };
+            matches: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        path: {
+                            type: string;
+                        };
+                        title: {
+                            type: string;
+                        };
+                        preview: {
+                            type: string;
+                        };
+                        created: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+            action_required: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<DeleteResult>;
+};
+export default deleteTool;

package/dist/tools/delete.js

@@ -0,0 +1,266 @@
+// ============================================================================
+// Delete Tool
+// Delete local entries from the library
+// ============================================================================
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { glob } from 'glob';
+import matter from 'gray-matter';
+import { getLibraryPath, getLocalPath } from '../library/storage.js';
+import { loadIndex, saveIndex, removeFromIndex } from '../library/vector-index.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const deleteTool = {
+    name: 'delete',
+    title: 'Delete Local Entry',
+    description: `Delete entries from your local library (.librarian/local/).
+
+USE THIS TOOL WHEN:
+- User wants to remove an outdated entry
+- Entry is wrong or no longer relevant
+- Cleaning up test/experimental entries
+- User says "delete", "remove", or "clean up" an entry
+
+ONLY deletes from local/ (your own entries). Cannot delete:
+- Imported content (use different management)
+- Purchased/packages content (managed by library)
+
+TRIGGER PATTERNS:
+- "Delete that entry" → delete({ path: "local/entry-name.md" })
+- "Remove the auth entry" → delete({ query: "auth" }) // Lists matches first
+- After seeing matches → delete({ path: "local/exact-path.md", confirm: true })
+
+Flow:
+1. With query: Lists matching entries, asks for specific path
+2. With path + confirm: Deletes the entry
+3. Without confirm: Shows what will be deleted, asks for confirmation`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Exact path to delete (e.g., "local/entry-name.md")',
+            },
+            query: {
+                type: 'string',
+                description: 'Search query to find entries to delete',
+            },
+            confirm: {
+                type: 'boolean',
+                description: 'Confirm deletion (required when path is provided)',
+            },
+        },
+        required: [],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            success: { type: 'boolean' },
+            message: { type: 'string' },
+            deleted: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    title: { type: 'string' },
+                },
+            },
+            matches: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string' },
+                        title: { type: 'string' },
+                        preview: { type: 'string' },
+                        created: { type: 'string' },
+                    },
+                },
+            },
+            action_required: { type: 'string' },
+        },
+        required: ['success', 'message'],
+    },
+    async handler(args) {
+        const { path: entryPath, query, confirm } = (args || {});
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        // Mode 1: Search by query - list matching entries
+        if (query && !entryPath) {
+            const matches = await findMatchingEntries(localPath, libraryPath, query);
+            if (matches.length === 0) {
+                return {
+                    success: false,
+                    message: `No entries found matching "${query}" in local library.`,
+                };
+            }
+            if (matches.length === 1) {
+                return {
+                    success: true,
+                    message: `Found 1 entry matching "${query}":`,
+                    matches,
+                    action_required: `To delete, call: delete({ path: "${matches[0].path}", confirm: true })`,
+                };
+            }
+            return {
+                success: true,
+                message: `Found ${matches.length} entries matching "${query}". Specify which one to delete:`,
+                matches,
+                action_required: 'Call delete({ path: "local/exact-path.md", confirm: true }) with the specific path.',
+            };
+        }
+        // Mode 2: Delete by path
+        if (entryPath) {
+            // Normalize path
+            let normalizedPath = entryPath;
+            if (!normalizedPath.startsWith('local/')) {
+                normalizedPath = `local/${normalizedPath}`;
+            }
+            if (!normalizedPath.endsWith('.md')) {
+                normalizedPath += '.md';
+            }
+            const fullPath = path.resolve(libraryPath, normalizedPath);
+            // Prevent path traversal — only allow deleting within local/
+            const localDir = path.resolve(libraryPath, 'local');
+            if (!fullPath.startsWith(localDir)) {
+                return {
+                    success: false,
+                    message: 'Invalid path: can only delete entries within local/',
+                };
+            }
+            // Check if file exists
+            try {
+                await fs.access(fullPath);
+            }
+            catch {
+                return {
+                    success: false,
+                    message: `Entry not found: ${normalizedPath}`,
+                };
+            }
+            // Read entry to get title for confirmation
+            const content = await fs.readFile(fullPath, 'utf-8');
+            const { data: frontmatter, content: body } = matter(content);
+            let title = frontmatter.title;
+            if (!title) {
+                const headingMatch = body.match(/^#\s+(.+)$/m);
+                if (headingMatch) {
+                    title = headingMatch[1].trim();
+                }
+                else {
+                    title = path.basename(normalizedPath, '.md').replace(/-/g, ' ');
+                }
+            }
+            // Mode 2a: Show what will be deleted (no confirm)
+            if (!confirm) {
+                const preview = body.trim().split('\n').slice(0, 3).join('\n');
+                return {
+                    success: true,
+                    message: `Will delete entry:`,
+                    matches: [{
+                            path: normalizedPath,
+                            title,
+                            preview: preview.slice(0, 200) + (preview.length > 200 ? '...' : ''),
+                            created: frontmatter.created,
+                        }],
+                    action_required: `Confirm by calling: delete({ path: "${normalizedPath}", confirm: true })`,
+                };
+            }
+            // Mode 2b: Actually delete (with confirm)
+            try {
+                // Delete the file
+                await fs.unlink(fullPath);
+                // Remove from vector index
+                try {
+                    const index = await loadIndex();
+                    removeFromIndex(index, normalizedPath);
+                    await saveIndex(index);
+                }
+                catch (indexError) {
+                    // Don't fail if index update fails - file is already deleted
+                    console.error('Failed to update index:', indexError);
+                }
+                return {
+                    success: true,
+                    message: `Deleted "${title}" from local library.`,
+                    deleted: {
+                        path: normalizedPath,
+                        title,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    success: false,
+                    message: `Failed to delete: ${message}`,
+                };
+            }
+        }
+        // No path or query provided
+        return {
+            success: false,
+            message: 'Provide either a path or query to find entries to delete.',
+            action_required: 'Use delete({ query: "search term" }) to find entries, or delete({ path: "local/entry.md", confirm: true }) to delete directly.',
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+async function findMatchingEntries(localPath, libraryPath, query) {
+    const matches = [];
+    const queryLower = query.toLowerCase();
+    try {
+        const files = await glob(path.join(localPath, '**/*.md'), { nodir: true });
+        for (const filePath of files) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const { data: frontmatter, content: body } = matter(content);
+                // Extract title
+                let title = frontmatter.title;
+                if (!title) {
+                    const headingMatch = body.match(/^#\s+(.+)$/m);
+                    if (headingMatch) {
+                        title = headingMatch[1].trim();
+                    }
+                    else {
+                        title = path.basename(filePath, '.md').replace(/-/g, ' ');
+                    }
+                }
+                // Check if query matches title, content, context, or filename
+                const filename = path.basename(filePath, '.md');
+                const context = frontmatter.context || '';
+                const searchText = [title, body, context, filename].join(' ').toLowerCase();
+                if (searchText.includes(queryLower)) {
+                    const relativePath = path.relative(libraryPath, filePath);
+                    const preview = body.trim().split('\n').slice(0, 2).join(' ');
+                    matches.push({
+                        path: relativePath,
+                        title,
+                        preview: preview.slice(0, 150) + (preview.length > 150 ? '...' : ''),
+                        created: frontmatter.created,
+                    });
+                }
+            }
+            catch {
+                // Skip files that can't be parsed
+            }
+        }
+    }
+    catch {
+        // No local directory
+    }
+    // Sort by created date (newest first)
+    return matches.sort((a, b) => {
+        if (!a.created)
+            return 1;
+        if (!b.created)
+            return -1;
+        return new Date(b.created).getTime() - new Date(a.created).getTime();
+    });
+}
+// ============================================================================
+// Export
+// ============================================================================
+export default deleteTool;

package/dist/tools/feedback.d.ts

@@ -0,0 +1,27 @@
+interface FeedbackResult {
+    success: boolean;
+    message: string;
+    feedback_id?: string;
+}
+export declare const feedbackTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            message: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<FeedbackResult>;
+};
+export default feedbackTool;