@telvok/librarian-mcp 1.5.3 → 2.0.0

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

@@ -0,0 +1,21 @@
+interface HelpResult {
+    topic: string;
+    content: string;
+}
+export declare const helpTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            topic: {
+                type: string;
+                description: string;
+                enum: string[];
+            };
+        };
+        required: never[];
+    };
+    handler(args: unknown): Promise<HelpResult>;
+};
+export default helpTool;

package/dist/tools 2/help.js

@@ -0,0 +1,267 @@
+// ============================================================================
+// Help Tool
+// Self-documenting system for the Librarian MCP
+// ============================================================================
+// ============================================================================
+// Help Content
+// ============================================================================
+const HELP_TOPICS = {
+    overview: `LIBRARIAN - Memory layer for AI agents
+
+Your library lives in .librarian/ with three folders:
+- local/     Your knowledge (created via record())
+- imported/  Downloaded books (via marketplace_buy())
+- packages/  Git-synced packages
+
+QUICK START:
+  brief({ query: "auth" })     Check what we know before diving in
+  record({ insight: "..." })   Save what we learned
+  mark_hit({ path: "..." })    This entry helped
+
+MARKETPLACE:
+  auth({ action: "login" })    Connect your Telvok account
+  marketplace_search({ ... })  Find books
+  marketplace_buy({ ... })     Purchase or claim a book
+  my_books()                   View your books
+  sync()                       Get updates for owned books
+  rate_book({ ... })           Rate a purchased book
+
+SELLING:
+  marketplace_publish({ ... }) Publish entries as a book
+  seller_analytics()           View sales and reviews
+
+Run help({ topic: "name" }) for details on any tool.`,
+    brief: `brief({ query?, limit?, include_marketplace? })
+
+Check what we already know before diving in.
+
+PARAMETERS:
+  query              What are you working on? (optional)
+  limit              Max entries to return (default: 5)
+  include_marketplace  Also search Telvok (default: false)
+
+EXAMPLES:
+  brief({ query: "stripe webhooks" })
+  brief({ query: "auth", include_marketplace: true })
+  brief({})  Returns recent entries
+
+RANKING: 60% recency + 40% hits. Entries that helped bubble up.
+
+When an entry helps, call mark_hit() so it ranks higher next time.`,
+    record: `record({ insight, intent?, reasoning?, context?, example?, title? })
+
+Save knowledge worth keeping. Call this proactively!
+
+PARAMETERS:
+  insight    (required) What did we learn?
+  intent     What were we trying to accomplish?
+  reasoning  Why does this work?
+  context    Topic, area, or when this applies
+  example    Code snippet or illustration
+  title      Entry title (auto-generated if not provided)
+
+EXAMPLES:
+  record({ insight: "Stripe webhooks need idempotency checks" })
+
+  record({
+    intent: "Setting up auth flow",
+    insight: "Add 30s buffer to token validation for clock skew",
+    reasoning: "Server clocks drift between services",
+    context: "auth, tokens"
+  })
+
+QUALITY BAR: "I wish we knew this yesterday"`,
+    auth: `auth({ action })
+
+Connect to your Telvok marketplace account.
+
+ACTIONS:
+  login     Start device code flow
+  complete  Finish login after browser authorization
+  status    Check if authenticated
+  logout    Remove stored credentials
+
+FLOW:
+  1. auth({ action: "login" })    Get code and URL
+  2. Visit URL, authorize in browser
+  3. auth({ action: "complete" }) Finish login
+
+Credentials saved in .librarian/.auth`,
+    marketplace_search: `marketplace_search({ query, filters? })
+
+Search Telvok marketplace for books.
+
+PARAMETERS:
+  query    Search terms
+  filters  Optional filters:
+    - pricing: "open" | "one_time" | "subscription"
+    - tags: ["tag1", "tag2"]
+    - min_rating: 1-5
+
+EXAMPLES:
+  marketplace_search({ query: "react patterns" })
+  marketplace_search({ query: "auth", filters: { pricing: "open" } })`,
+    marketplace_buy: `marketplace_buy({ slug })
+
+Purchase or claim a book from Telvok.
+
+PARAMETERS:
+  slug  Book slug from search results
+
+BEHAVIOR:
+  Free (open) books: Instantly adds to library
+  Paid books: Returns checkout URL
+
+EXAMPLE:
+  marketplace_buy({ slug: "react-best-practices" })
+
+After purchase, use sync() for updates.`,
+    rate_book: `rate_book({ slug, rating, title?, comment? })
+
+Rate a book you've purchased.
+
+PARAMETERS:
+  slug     Book slug to rate
+  rating   1 to 5 stars
+  title    Optional review title
+  comment  Optional review comment
+
+EXAMPLES:
+  rate_book({ slug: "auth-patterns", rating: 5 })
+  rate_book({
+    slug: "stripe-patterns",
+    rating: 4,
+    title: "Saved me hours",
+    comment: "Webhook section was exactly what I needed"
+  })
+
+Ratings help surface quality content.`,
+    sync: `sync({ slug?, force?, include_content? })
+
+Check for and receive updates to owned books.
+
+PARAMETERS:
+  slug             Specific book (omit for all)
+  force            Include manual preference books
+  include_content  Download open book content
+
+SYNC PREFERENCES (per-book):
+  auto    Synced automatically (default)
+  manual  Requires force: true
+  pinned  Never synced
+
+EXAMPLES:
+  sync()
+  sync({ slug: "premium-patterns" })
+  sync({ force: true })`,
+    my_books: `my_books({ filter? })
+
+View your published and purchased books.
+
+PARAMETERS:
+  filter  "all" (default), "published", or "purchased"
+
+EXAMPLES:
+  my_books()
+  my_books({ filter: "published" })
+
+Shows slugs for sync(), rate_book(), etc.`,
+    seller_analytics: `seller_analytics()
+
+View analytics for books you've published.
+
+SHOWS:
+  - Total revenue and purchases
+  - Per-book breakdown
+  - Recent reviews
+  - Hit counts (query frequency)
+
+Requires authentication.`,
+    mark_hit: `mark_hit({ path })
+
+Mark an entry as helpful. Call when brief() helped.
+
+PARAMETERS:
+  path  Path to entry (from brief() results)
+
+EXAMPLE:
+  mark_hit({ path: "local/stripe-webhooks.md" })
+
+Fire and forget. Entries with more hits rank higher.`,
+    adopt: `adopt({ path, title? })
+
+Make imported knowledge yours.
+
+When an imported entry proves useful, adopt it into local/.
+
+PARAMETERS:
+  path   Path to entry (e.g., "imported/package/entry")
+  title  New title (optional)
+
+EXAMPLE:
+  adopt({ path: "imported/stripe-patterns/webhooks" })`,
+    marketplace_publish: `marketplace_publish({ name, description?, pricing, entries?, attestation })
+
+Publish local entries as a book on Telvok.
+
+PARAMETERS:
+  name         Book name
+  description  Short description
+  pricing      { type: "open" | "one_time" | "subscription", price_cents? }
+  entries      Entry paths to include (default: all local/)
+  attestation  { original_work: true, terms_accepted: true }
+
+EXAMPLES:
+  marketplace_publish({
+    name: "React Patterns",
+    pricing: { type: "open" },
+    attestation: { original_work: true, terms_accepted: true }
+  })
+
+Paid books require Stripe Connect setup.`,
+};
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const helpTool = {
+    name: 'help',
+    description: `Get help on how to use the Librarian.
+
+Run with no arguments for an overview, or specify a topic for details.
+
+Examples:
+- help()                     Overview of all tools
+- help({ topic: "brief" })   Details on brief()
+- help({ topic: "auth" })    Details on authentication`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            topic: {
+                type: 'string',
+                description: 'Specific topic to get help on',
+                enum: Object.keys(HELP_TOPICS),
+            },
+        },
+        required: [],
+    },
+    async handler(args) {
+        const { topic } = (args || {});
+        const helpTopic = topic?.toLowerCase() || 'overview';
+        const content = HELP_TOPICS[helpTopic];
+        if (!content) {
+            const availableTopics = Object.keys(HELP_TOPICS).filter(t => t !== 'overview').join(', ');
+            return {
+                topic: 'error',
+                content: `Unknown topic: "${topic}"\n\nAvailable topics: ${availableTopics}`,
+            };
+        }
+        return {
+            topic: helpTopic,
+            content: content.trim(),
+        };
+    },
+};
+// ============================================================================
+// Export
+// ============================================================================
+export default helpTool;

package/dist/tools 2/import-memories.d.ts

@@ -0,0 +1,32 @@
+export interface ImportResult {
+    success: boolean;
+    imported: number;
+    skipped: number;
+    errors: string[];
+    outputPath: string;
+    message: string;
+}
+export declare const importMemoriesTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            path: {
+                type: string;
+                description: string;
+            };
+            source_name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<ImportResult>;
+};

package/dist/tools 2/import-memories.js

@@ -0,0 +1,231 @@
+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';
+import { parseJSONL, parseMarkdown, parseCursorMemory, parseJSON, parseSQLite } from '../library/parsers/index.js';
+// ============================================================================
+// Tool Definition
+// ============================================================================
+export const importMemoriesTool = {
+    name: 'import_memories',
+    description: `Import memories from other AI tools into Librarian.
+
+Use this when you see memory files from other AI tools (Cursor .cursor-memory/, Anthropic ~/.aim/, mcp-memory-service .db files, Obsidian vaults) or when user mentions having knowledge in other tools. Import them so past knowledge becomes searchable.
+
+Supported formats:
+- jsonl: Anthropic MCP Memory, mcp-knowledge-graph (.jsonl files)
+- markdown: Basic Memory, Obsidian, any .md files
+- cursor: Cursor Memory Bank (.cursor-memory/)
+- json: Simple memory servers, knowledge stores (.json files)
+- sqlite: mcp-memory-service, SQLite-vec (.db, .sqlite files)
+
+Imports go to .librarian/local/[source-name]/ and are automatically indexed for semantic search.
+
+Examples:
+- import_memories({ format: "jsonl", path: "~/.aim/memory.jsonl", source_name: "anthropic-memory" })
+- import_memories({ format: "markdown", path: "~/basic-memory/", source_name: "basic-memory" })
+- import_memories({ format: "cursor", path: ".cursor-memory/", source_name: "cursor-memory" })
+- import_memories({ format: "json", path: "~/memories.json", source_name: "json-memory" })
+- import_memories({ format: "sqlite", path: "~/memory.db", source_name: "sqlite-memory" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            format: {
+                type: 'string',
+                enum: ['jsonl', 'markdown', 'cursor', 'json', 'sqlite'],
+                description: 'Format of the source memories',
+            },
+            path: {
+                type: 'string',
+                description: 'Path to memory file or folder',
+            },
+            source_name: {
+                type: 'string',
+                description: 'Name for the import folder (e.g., "anthropic-memory"). Auto-generated if not provided.',
+            },
+        },
+        required: ['format', 'path'],
+    },
+    async handler(args) {
+        const { format, path: inputPath, source_name } = args;
+        if (!format || !inputPath) {
+            throw new Error('format and path are required');
+        }
+        // Expand ~ to home directory
+        const expandedPath = inputPath.replace(/^~/, process.env.HOME || '');
+        // Generate source name if not provided
+        const sourceName = source_name || generateSourceName(format, expandedPath);
+        // Setup output directory
+        const libraryPath = getLibraryPath();
+        const localPath = getLocalPath(libraryPath);
+        const outputPath = path.join(localPath, sourceName);
+        // Check if output directory already exists
+        try {
+            await fs.access(outputPath);
+            // Directory exists - we'll add to it but warn about potential duplicates
+        }
+        catch {
+            // Directory doesn't exist - create it
+            await fs.mkdir(outputPath, { recursive: true });
+        }
+        // Parse the source based on format
+        let parseResult;
+        switch (format) {
+            case 'jsonl':
+                parseResult = await parseJSONL(expandedPath);
+                break;
+            case 'markdown':
+                parseResult = await parseMarkdown(expandedPath);
+                break;
+            case 'cursor':
+                parseResult = await parseCursorMemory(expandedPath);
+                break;
+            case 'json':
+                parseResult = await parseJSON(expandedPath);
+                break;
+            case 'sqlite':
+                parseResult = await parseSQLite(expandedPath);
+                break;
+            default:
+                throw new Error(`Unknown format: ${format}`);
+        }
+        // Convert and save entries
+        const index = await loadIndex();
+        let imported = 0;
+        const errors = [...parseResult.errors];
+        for (const entry of parseResult.entries) {
+            try {
+                const relativePath = await saveEntry(entry, outputPath, libraryPath);
+                // Add to vector index
+                const fullContent = [
+                    entry.title,
+                    entry.intent || '',
+                    entry.content,
+                    entry.reasoning || '',
+                    entry.example || '',
+                    entry.context || '',
+                ].filter(Boolean).join('\n\n');
+                await addToIndex(index, relativePath, entry.title, fullContent);
+                imported++;
+            }
+            catch (saveError) {
+                errors.push(`Failed to save "${entry.title}": ${saveError instanceof Error ? saveError.message : String(saveError)}`);
+            }
+        }
+        // Save the updated index
+        await saveIndex(index);
+        const message = imported > 0
+            ? `Imported ${imported} entries from ${format} format into ${sourceName}/`
+            : `No entries imported. ${parseResult.skipped} skipped, ${errors.length} errors.`;
+        return {
+            success: imported > 0,
+            imported,
+            skipped: parseResult.skipped,
+            errors,
+            outputPath: path.relative(libraryPath, outputPath),
+            message,
+        };
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Generate a source name from the format and path.
+ */
+function generateSourceName(format, inputPath) {
+    const basename = path.basename(inputPath, path.extname(inputPath));
+    switch (format) {
+        case 'jsonl':
+            if (basename.includes('memory')) {
+                return 'imported-memory';
+            }
+            return `imported-${basename}`;
+        case 'cursor':
+            return 'cursor-memory';
+        case 'markdown':
+            return basename.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'imported-markdown';
+        case 'json':
+            return basename.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'imported-json';
+        case 'sqlite':
+            return basename.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'imported-sqlite';
+        default:
+            return `imported-${format}`;
+    }
+}
+/**
+ * Save a parsed entry to the output directory.
+ * Returns the relative path from library root.
+ */
+async function saveEntry(entry, outputPath, libraryPath) {
+    const slug = slugify(entry.title);
+    const created = new Date().toISOString();
+    // Handle filename collisions
+    let filename = `${slug}.md`;
+    let filePath = path.join(outputPath, filename);
+    let counter = 1;
+    while (await fileExists(filePath)) {
+        filename = `${slug}-${counter}.md`;
+        filePath = path.join(outputPath, filename);
+        counter++;
+    }
+    // Build frontmatter
+    const frontmatterLines = ['---'];
+    if (entry.intent) {
+        frontmatterLines.push(`intent: "${escapeYaml(entry.intent)}"`);
+    }
+    if (entry.context) {
+        frontmatterLines.push(`context: "${escapeYaml(entry.context)}"`);
+    }
+    frontmatterLines.push(`created: "${created}"`);
+    frontmatterLines.push(`updated: "${created}"`);
+    frontmatterLines.push(`source: "${entry.source}"`);
+    if (entry.originalPath) {
+        frontmatterLines.push(`original_path: "${escapeYaml(entry.originalPath)}"`);
+    }
+    frontmatterLines.push('hits: 0');
+    frontmatterLines.push('last_hit: null');
+    frontmatterLines.push('---');
+    // Build body
+    const bodyLines = [];
+    bodyLines.push(`# ${entry.title}`);
+    bodyLines.push('');
+    bodyLines.push(entry.content);
+    if (entry.reasoning) {
+        bodyLines.push('');
+        bodyLines.push('## Reasoning');
+        bodyLines.push('');
+        bodyLines.push(entry.reasoning);
+    }
+    if (entry.example) {
+        bodyLines.push('');
+        bodyLines.push('## Example');
+        bodyLines.push('');
+        bodyLines.push('```');
+        bodyLines.push(entry.example);
+        bodyLines.push('```');
+    }
+    // Combine and write
+    const fileContent = frontmatterLines.join('\n') + '\n\n' + bodyLines.join('\n') + '\n';
+    await fs.writeFile(filePath, fileContent, 'utf-8');
+    return path.relative(libraryPath, filePath);
+}
+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/index.d.ts

@@ -0,0 +1,12 @@
+export { briefTool } from './brief.js';
+export { recordTool } from './record.js';
+export { adoptTool } from './adopt.js';
+export { markHitTool } from './mark-hit.js';
+export { importMemoriesTool } from './import-memories.js';
+export { rebuildIndexTool } from './rebuild-index.js';
+export { authTool, loadApiKey } from './auth.js';
+export { myBooksTool } from './my-books.js';
+export { syncTool } from './sync.js';
+export { sellerAnalyticsTool } from './seller-analytics.js';
+export { rateBookTool } from './rate-book.js';
+export { helpTool } from './help.js';

package/dist/tools 2/index.js

@@ -0,0 +1,12 @@
+export { briefTool } from './brief.js';
+export { recordTool } from './record.js';
+export { adoptTool } from './adopt.js';
+export { markHitTool } from './mark-hit.js';
+export { importMemoriesTool } from './import-memories.js';
+export { rebuildIndexTool } from './rebuild-index.js';
+export { authTool, loadApiKey } from './auth.js';
+export { myBooksTool } from './my-books.js';
+export { syncTool } from './sync.js';
+export { sellerAnalyticsTool } from './seller-analytics.js';
+export { rateBookTool } from './rate-book.js';
+export { helpTool } from './help.js';

package/dist/tools 2/mark-hit.d.ts

@@ -0,0 +1,20 @@
+export interface MarkHitResult {
+    success: boolean;
+    path: string;
+    hits: number;
+}
+export declare const markHitTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: unknown): Promise<MarkHitResult>;
+};

package/dist/tools 2/mark-hit.js

@@ -0,0 +1,71 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { getLibraryPath } from '../library/storage.js';
+// ============================================================================
+// 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.
+
+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.
+
+Entries with more hits bubble up in future brief() results.
+
+Fire and forget - call it and move on.
+
+Example:
+- mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the entry that helped (from brief() results)',
+            },
+        },
+        required: ['path'],
+    },
+    async handler(args) {
+        const { path: entryPath } = args;
+        if (!entryPath) {
+            throw new Error('path is required');
+        }
+        const libraryPath = getLibraryPath();
+        // Resolve the full path
+        let fullPath;
+        if (path.isAbsolute(entryPath)) {
+            fullPath = entryPath;
+        }
+        else {
+            fullPath = path.join(libraryPath, entryPath);
+        }
+        // Read existing file
+        let content;
+        try {
+            content = await fs.readFile(fullPath, 'utf-8');
+        }
+        catch {
+            throw new Error(`Entry not found: ${entryPath}`);
+        }
+        // Parse frontmatter
+        const { data, content: body } = matter(content);
+        // Increment hits
+        const currentHits = typeof data.hits === 'number' ? data.hits : 0;
+        const newHits = currentHits + 1;
+        // Update frontmatter
+        data.hits = newHits;
+        data.last_hit = new Date().toISOString();
+        // Rebuild file content
+        const updatedContent = matter.stringify(body, data);
+        // Write back
+        await fs.writeFile(fullPath, updatedContent, 'utf-8');
+        return {
+            success: true,
+            path: entryPath,
+            hits: newHits,
+        };
+    },
+};