@telvok/librarian-mcp 1.5.4 → 2.3.0

package/dist/tools 2/auth.js

@@ -0,0 +1,229 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getLibraryPath } from '../library/storage.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const TELVOK_API_URL = process.env.TELVOK_API_URL || 'https://telvok.com';
+const POLL_INTERVAL_MS = 5000; // 5 seconds
+const MAX_POLL_ATTEMPTS = 120; // 10 minutes / 5 seconds
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const authTool = {
+    name: 'auth',
+    description: `Handle Telvok marketplace authentication.
+
+Use this to connect your agent to your Telvok account.
+
+Actions:
+- login: Start device code flow. Returns a code to enter at telvok.com/device
+- complete: After user authorizes, call this to finish login and save credentials
+- logout: Remove stored credentials
+- status: Check if authenticated and show current user
+
+Examples:
+- auth({ action: 'login' })  → Get code, visit URL, authorize
+- auth({ action: 'complete' }) → After authorizing, complete the login
+- auth({ action: 'status' }) → Check if logged in
+- auth({ action: 'logout' }) → Clear credentials`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['login', 'complete', 'logout', 'status'],
+                description: 'Auth action to perform',
+            },
+        },
+        required: ['action'],
+    },
+    async handler(args) {
+        const { action } = args;
+        const libraryPath = getLibraryPath();
+        const authFile = path.join(libraryPath, '.auth');
+        const pendingFile = path.join(libraryPath, '.auth-pending');
+        switch (action) {
+            case 'status':
+                return await checkStatus(authFile);
+            case 'logout':
+                return await logout(authFile);
+            case 'login':
+                return await login(authFile, pendingFile);
+            case 'complete':
+                return await completeLogin(authFile, pendingFile);
+            default:
+                throw new Error(`Unknown action: ${action}`);
+        }
+    },
+};
+// ============================================================================
+// Action Handlers
+// ============================================================================
+async function checkStatus(authFile) {
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        return {
+            authenticated: true,
+            user_email: data.user_email,
+            user_id: data.user_id,
+            message: `Authenticated as ${data.user_email}`,
+        };
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'Not authenticated. Use auth({ action: "login" }) to connect your Telvok account.',
+        };
+    }
+}
+async function logout(authFile) {
+    try {
+        await fs.unlink(authFile);
+        return {
+            authenticated: false,
+            message: 'Logged out successfully. Credentials removed.',
+        };
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'Already logged out.',
+        };
+    }
+}
+async function login(authFile, pendingFile) {
+    // Check if already authenticated
+    try {
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        return {
+            authenticated: true,
+            user_email: data.user_email,
+            user_id: data.user_id,
+            message: `Already authenticated as ${data.user_email}. Use auth({ action: "logout" }) first to switch accounts.`,
+        };
+    }
+    catch {
+        // Not authenticated, proceed with login
+    }
+    // Request a new device code
+    try {
+        const response = await fetch(`${TELVOK_API_URL}/api/auth/device`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const data = await response.json();
+        // Save device code to pending file for later completion
+        const libraryPath = getLibraryPath();
+        await fs.mkdir(libraryPath, { recursive: true });
+        await fs.writeFile(pendingFile, JSON.stringify({
+            device_code: data.device_code,
+            user_code: data.user_code,
+            verification_url: data.verification_url,
+            created_at: new Date().toISOString(),
+        }, null, 2), 'utf-8');
+        // Return immediately with direct auth URL
+        const directAuthUrl = `${TELVOK_API_URL}/auth/${data.device_code}`;
+        return {
+            authenticated: false,
+            verification_url: directAuthUrl,
+            user_code: data.user_code,
+            message: `Click to authorize: ${directAuthUrl}\n\nAfter authorizing, call auth({ action: "complete" }) to finish.`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to start login: ${message}`);
+    }
+}
+async function completeLogin(authFile, pendingFile) {
+    // Read pending device code
+    let deviceCode;
+    try {
+        const content = await fs.readFile(pendingFile, 'utf-8');
+        const pending = JSON.parse(content);
+        deviceCode = pending.device_code;
+    }
+    catch {
+        return {
+            authenticated: false,
+            message: 'No pending login. Call auth({ action: "login" }) first.',
+        };
+    }
+    // Poll for completion (try a few times)
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const response = await fetch(`${TELVOK_API_URL}/api/auth/device/poll`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ device_code: deviceCode }),
+            });
+            const data = await response.json();
+            if (data.status === 'pending') {
+                await sleep(2000);
+                continue;
+            }
+            if (data.status === 'expired') {
+                await fs.unlink(pendingFile).catch(() => { });
+                throw new Error('Code expired. Please call auth({ action: "login" }) to get a new code.');
+            }
+            if (data.status === 'success') {
+                // Save credentials
+                const authData = {
+                    api_key: data.api_key,
+                    user_email: data.user.email,
+                    user_id: data.user.id,
+                    created_at: new Date().toISOString(),
+                };
+                await fs.writeFile(authFile, JSON.stringify(authData, null, 2), 'utf-8');
+                await fs.unlink(pendingFile).catch(() => { });
+                return {
+                    authenticated: true,
+                    user_email: data.user.email,
+                    user_id: data.user.id,
+                    message: `Successfully authenticated as ${data.user.email}`,
+                };
+            }
+            throw new Error(`Unexpected status: ${data.status}`);
+        }
+        catch (error) {
+            if (error instanceof Error && (error.message.includes('expired') || error.message.includes('Unexpected'))) {
+                throw error;
+            }
+            // Network error, try again
+            await sleep(1000);
+        }
+    }
+    return {
+        authenticated: false,
+        message: 'Authorization not yet complete. Make sure you authorized at telvok.com/device, then call auth({ action: "complete" }) again.',
+    };
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Load saved API key from auth file
+ * Used by other tools that need authenticated access
+ */
+export async function loadApiKey() {
+    try {
+        const libraryPath = getLibraryPath();
+        const authFile = path.join(libraryPath, '.auth');
+        const content = await fs.readFile(authFile, 'utf-8');
+        const data = JSON.parse(content);
+        return data.api_key;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,56 @@
+export interface BriefEntry {
+    title: string;
+    intent: string | null;
+    context: string | null;
+    preview: string;
+    path: string;
+    created: string;
+    hits: number;
+    last_hit: string | null;
+    source?: 'local' | 'cloud' | 'packages';
+    book_name?: string;
+    book_slug?: string;
+}
+export interface MarketplaceBook {
+    slug: string;
+    name: string;
+    description: string;
+    pricing: string;
+    price: string;
+    entries: number;
+}
+export interface BriefResult {
+    entries: BriefEntry[];
+    total: number;
+    message: string;
+    libraryPath: string;
+    marketplace?: {
+        books: MarketplaceBook[];
+        total: number;
+    };
+}
+export declare const briefTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            include_marketplace: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<BriefResult>;
+};

package/dist/tools 2/brief.js

@@ -0,0 +1,414 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+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.
+
+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.
+
+Examples:
+- brief({ query: "stripe webhooks" })
+- brief({ query: "auth token" })
+- brief({}) → returns recent entries
+- brief({ query: "react", include_marketplace: true }) → also search marketplace`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'What are we working on? Searches our library. Leave empty to see recent entries.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Max entries to return',
+                default: 5,
+            },
+            include_marketplace: {
+                type: 'boolean',
+                description: 'Also search Telvok marketplace for relevant books',
+                default: false,
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { query, limit = 5, include_marketplace = false } = args;
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        const importedPath = getImportedPath(libraryPath);
+        const packagesPath = getPackagesPath(libraryPath);
+        let allEntries = [];
+        let useSemanticSearch = false;
+        let semanticMatches = [];
+        // Try semantic search if query is provided
+        if (query) {
+            try {
+                const index = await loadIndex();
+                // Only use semantic search if index has entries and isn't stale
+                if (index.entries.length > 0 && !isIndexStale(index)) {
+                    semanticMatches = await semanticSearch(index, query, limit);
+                    useSemanticSearch = semanticMatches.length > 0;
+                }
+            }
+            catch {
+                // Semantic search unavailable, fall back to keyword search
+                useSemanticSearch = false;
+            }
+        }
+        if (useSemanticSearch && semanticMatches.length > 0) {
+            // Load only the entries that matched semantically
+            const matchedPaths = new Set(semanticMatches.map(m => m.path));
+            for (const match of semanticMatches) {
+                const fullPath = path.join(libraryPath, match.path);
+                const entry = await readEntry(fullPath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+            // Sort by semantic similarity (order preserved from semanticSearch)
+            // Re-order allEntries to match semanticMatches order
+            const pathToEntry = new Map(allEntries.map(e => [e.path, e]));
+            allEntries = semanticMatches
+                .map(m => pathToEntry.get(m.path))
+                .filter((e) => e !== undefined);
+            const total = allEntries.length;
+            const entries = allEntries.slice(0, limit);
+            // Optionally fetch cloud content and marketplace results
+            let cloudResult;
+            let marketplaceResult;
+            if (include_marketplace && query) {
+                // Fetch cloud content from owned books (in parallel with marketplace)
+                const [cloudData, marketplaceData] = await Promise.all([
+                    fetchCloudContent(query, limit),
+                    fetchMarketplaceResults(query, 5),
+                ]);
+                cloudResult = cloudData;
+                marketplaceResult = marketplaceData;
+                // Filter marketplace to exclude books user already owns
+                // (we got cloud results from them, so they own them)
+                if (cloudResult.entries.length > 0) {
+                    const ownedSlugs = new Set(cloudResult.entries.map(e => e.book_slug));
+                    marketplaceResult.books = marketplaceResult.books.filter(b => !ownedSlugs.has(b.slug));
+                    marketplaceResult.total = marketplaceResult.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 (marketplaceResult && marketplaceResult.books.length > 0) {
+                message += ` ${marketplaceResult.total} book(s) available on marketplace.`;
+            }
+            return {
+                entries: finalEntries,
+                total: finalEntries.length,
+                message,
+                libraryPath: localPath,
+                marketplace: marketplaceResult,
+            };
+        }
+        // Fall back to keyword search
+        // Read local entries
+        try {
+            const localFiles = await glob(path.join(localPath, '**/*.md'), { nodir: true });
+            for (const filePath of localFiles) {
+                const entry = await readEntry(filePath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+        }
+        catch {
+            // No local files yet
+        }
+        // Read imported entries (legacy - deprecated)
+        try {
+            const importedFiles = await glob(path.join(importedPath, '**/*.md'), { nodir: true });
+            for (const filePath of importedFiles) {
+                const entry = await readEntry(filePath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+        }
+        catch {
+            // No imported files
+        }
+        // Read packages entries (marketplace content)
+        try {
+            const packagesFiles = await glob(path.join(packagesPath, '**/*.md'), { nodir: true });
+            for (const filePath of packagesFiles) {
+                const entry = await readEntry(filePath, libraryPath);
+                if (entry) {
+                    allEntries.push(entry);
+                }
+            }
+        }
+        catch {
+            // No packages files
+        }
+        // If no entries at all
+        if (allEntries.length === 0) {
+            return {
+                entries: [],
+                total: 0,
+                message: 'No entries yet. Start recording!',
+                libraryPath: localPath,
+            };
+        }
+        // Filter by query if provided
+        if (query) {
+            const searchTerm = query.toLowerCase();
+            allEntries = allEntries.filter(entry => matchesSearch(entry, searchTerm));
+        }
+        // Sort by blended score: 60% recency + 40% hits
+        // Entries that helped before bubble up, but new entries still surface
+        allEntries = rankEntries(allEntries);
+        const total = allEntries.length;
+        // Apply limit
+        const entries = allEntries.slice(0, limit);
+        // Optionally fetch cloud content and marketplace results
+        let cloudResult;
+        let marketplaceResult;
+        if (include_marketplace && query) {
+            // Fetch cloud content from owned books (in parallel with marketplace)
+            const [cloudData, marketplaceData] = await Promise.all([
+                fetchCloudContent(query, limit),
+                fetchMarketplaceResults(query, 5),
+            ]);
+            cloudResult = cloudData;
+            marketplaceResult = marketplaceData;
+            // Filter marketplace to exclude books user already owns
+            if (cloudResult.entries.length > 0) {
+                const ownedSlugs = new Set(cloudResult.entries.map(e => e.book_slug));
+                marketplaceResult.books = marketplaceResult.books.filter(b => !ownedSlugs.has(b.slug));
+                marketplaceResult.total = marketplaceResult.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 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 (marketplaceResult && marketplaceResult.books.length > 0) {
+            message += ` ${marketplaceResult.total} book(s) available on marketplace.`;
+        }
+        return {
+            entries: finalEntries,
+            total: finalEntries.length,
+            message,
+            libraryPath: localPath,
+            marketplace: marketplaceResult,
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+async function readEntry(filePath, libraryPath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const { data, content: body } = matter(content);
+        // Extract title from H1 or filename
+        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, ' ');
+            }
+        }
+        // Extract preview - first 100 chars of body content
+        const bodyText = body.trim();
+        const preview = bodyText.length > 100
+            ? bodyText.slice(0, 100) + '...'
+            : bodyText;
+        return {
+            title,
+            intent: data.intent || null,
+            context: data.context || null,
+            preview,
+            path: path.relative(libraryPath, filePath),
+            created: data.created || new Date().toISOString(),
+            hits: typeof data.hits === 'number' ? data.hits : 0,
+            last_hit: data.last_hit || null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function matchesSearch(entry, searchTerm) {
+    // Check title
+    if (entry.title.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check intent
+    if (entry.intent && entry.intent.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check context
+    if (entry.context && entry.context.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    // Check preview (basic substring match - Claude does semantic filtering)
+    if (entry.preview.toLowerCase().includes(searchTerm)) {
+        return true;
+    }
+    return false;
+}
+// ============================================================================
+// Smart Ranking
+// ============================================================================
+const RECENCY_WEIGHT = 0.6;
+const HITS_WEIGHT = 0.4;
+const RECENCY_DECAY_DAYS = 30; // Entries older than this get minimal recency score
+function rankEntries(entries) {
+    if (entries.length === 0)
+        return entries;
+    const now = Date.now();
+    // Find max hits for normalization (avoid divide by zero)
+    const maxHits = Math.max(1, ...entries.map(e => e.hits));
+    // Calculate scores
+    const scored = entries.map(entry => {
+        // Recency score: 1.0 for today, decays over RECENCY_DECAY_DAYS
+        const ageMs = now - new Date(entry.created).getTime();
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        const recencyScore = Math.max(0, 1 - (ageDays / RECENCY_DECAY_DAYS));
+        // Hits score: normalized 0-1 against max hits in library
+        const hitsScore = entry.hits / maxHits;
+        // Blended score
+        const score = (RECENCY_WEIGHT * recencyScore) + (HITS_WEIGHT * hitsScore);
+        return { entry, score };
+    });
+    // Sort by score descending
+    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 marketplace 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 };
+    }
+}