@telvok/librarian-mcp 1.5.4 → 2.0.0

package/dist/library/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Error codes following JSON-RPC 2.0 conventions
+ * -32xxx: Standard JSON-RPC errors
+ * -31xxx: Authentication errors
+ * -30xxx: Resource errors
+ * -29xxx: Network errors
+ */
+export declare const ErrorCodes: {
+    readonly AUTH_REQUIRED: -31001;
+    readonly AUTH_EXPIRED: -31002;
+    readonly AUTH_INVALID_SCOPE: -31003;
+    readonly AUTH_INVALID_KEY: -31004;
+    readonly ENTRY_NOT_FOUND: -30001;
+    readonly BOOK_NOT_FOUND: -30002;
+    readonly INDEX_STALE: -30003;
+    readonly FILE_NOT_FOUND: -30004;
+    readonly INVALID_PATH: -30005;
+    readonly INVALID_PARAMS: -32602;
+    readonly INVALID_REQUEST: -32600;
+    readonly API_UNAVAILABLE: -29001;
+    readonly NETWORK_TIMEOUT: -29002;
+    readonly API_ERROR: -29003;
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Custom error class for Librarian MCP
+ * Includes error code and retryable flag for AI agents
+ */
+export declare class LibrarianError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    constructor(code: ErrorCode, message: string, retryable?: boolean);
+    /**
+     * Convert to JSON-RPC compatible error object
+     */
+    toJSON(): {
+        error: string;
+        code: ErrorCode;
+        retryable: boolean;
+    };
+}
+export declare function authRequired(): LibrarianError;
+export declare function authExpired(): LibrarianError;
+export declare function entryNotFound(path: string): LibrarianError;
+export declare function bookNotFound(slug: string): LibrarianError;
+export declare function apiError(message: string): LibrarianError;
+export declare function networkTimeout(): LibrarianError;
+export declare function invalidParams(message: string): LibrarianError;

package/dist/library/errors.js

@@ -0,0 +1,80 @@
+// ============================================================================
+// Error Code Definitions
+// JSON-RPC compatible error codes for MCP
+// ============================================================================
+/**
+ * Error codes following JSON-RPC 2.0 conventions
+ * -32xxx: Standard JSON-RPC errors
+ * -31xxx: Authentication errors
+ * -30xxx: Resource errors
+ * -29xxx: Network errors
+ */
+export const ErrorCodes = {
+    // Auth errors (-31xxx)
+    AUTH_REQUIRED: -31001,
+    AUTH_EXPIRED: -31002,
+    AUTH_INVALID_SCOPE: -31003,
+    AUTH_INVALID_KEY: -31004,
+    // Resource errors (-30xxx)
+    ENTRY_NOT_FOUND: -30001,
+    BOOK_NOT_FOUND: -30002,
+    INDEX_STALE: -30003,
+    FILE_NOT_FOUND: -30004,
+    INVALID_PATH: -30005,
+    // Validation errors (-32xxx - JSON-RPC standard)
+    INVALID_PARAMS: -32602,
+    INVALID_REQUEST: -32600,
+    // Network errors (-29xxx)
+    API_UNAVAILABLE: -29001,
+    NETWORK_TIMEOUT: -29002,
+    API_ERROR: -29003,
+};
+/**
+ * Custom error class for Librarian MCP
+ * Includes error code and retryable flag for AI agents
+ */
+export class LibrarianError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.name = 'LibrarianError';
+        this.code = code;
+        this.retryable = retryable;
+    }
+    /**
+     * Convert to JSON-RPC compatible error object
+     */
+    toJSON() {
+        return {
+            error: this.message,
+            code: this.code,
+            retryable: this.retryable,
+        };
+    }
+}
+// ============================================================================
+// Helper Functions for Common Errors
+// ============================================================================
+export function authRequired() {
+    return new LibrarianError(ErrorCodes.AUTH_REQUIRED, 'Authentication required. Use auth({ action: "login" }) to connect.', false);
+}
+export function authExpired() {
+    return new LibrarianError(ErrorCodes.AUTH_EXPIRED, 'API key has expired. Use auth({ action: "login" }) to get a new key.', false);
+}
+export function entryNotFound(path) {
+    return new LibrarianError(ErrorCodes.ENTRY_NOT_FOUND, `Entry not found: ${path}`, false);
+}
+export function bookNotFound(slug) {
+    return new LibrarianError(ErrorCodes.BOOK_NOT_FOUND, `Book not found: ${slug}`, false);
+}
+export function apiError(message) {
+    return new LibrarianError(ErrorCodes.API_ERROR, message, true // Network errors are typically retryable
+    );
+}
+export function networkTimeout() {
+    return new LibrarianError(ErrorCodes.NETWORK_TIMEOUT, 'Request timed out. Please try again.', true);
+}
+export function invalidParams(message) {
+    return new LibrarianError(ErrorCodes.INVALID_PARAMS, message, false);
+}

package/dist/library/schemas.d.ts

@@ -146,14 +146,14 @@ export declare const ImportedLibrarySchema: z.ZodObject<{
     name: string;
     entry_count: number;
     purchased_at: string;
-    sync_preference?: "manual" | "auto" | "pinned" | undefined;
     last_synced?: string | undefined;
+    sync_preference?: "pinned" | "manual" | "auto" | undefined;
 }, {
     name: string;
     entry_count: number;
     purchased_at: string;
-    sync_preference?: "manual" | "auto" | "pinned" | undefined;
     last_synced?: string | undefined;
+    sync_preference?: "pinned" | "manual" | "auto" | undefined;
 }>;
 export type ImportedLibrary = z.infer<typeof ImportedLibrarySchema>;
 export declare const StateResultSchema: z.ZodObject<{
@@ -192,14 +192,14 @@ export declare const StateResultSchema: z.ZodObject<{
         name: string;
         entry_count: number;
         purchased_at: string;
-        sync_preference?: "manual" | "auto" | "pinned" | undefined;
         last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
     }, {
         name: string;
         entry_count: number;
         purchased_at: string;
-        sync_preference?: "manual" | "auto" | "pinned" | undefined;
         last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     entries: {
@@ -215,8 +215,8 @@ export declare const StateResultSchema: z.ZodObject<{
         name: string;
         entry_count: number;
         purchased_at: string;
-        sync_preference?: "manual" | "auto" | "pinned" | undefined;
         last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
     }[];
 }, {
     entries: {
@@ -232,8 +232,8 @@ export declare const StateResultSchema: z.ZodObject<{
         name: string;
         entry_count: number;
         purchased_at: string;
-        sync_preference?: "manual" | "auto" | "pinned" | undefined;
         last_synced?: string | undefined;
+        sync_preference?: "pinned" | "manual" | "auto" | undefined;
     }[];
 }>;
 export type StateResult = z.infer<typeof StateResultSchema>;

package/dist/library/storage.d.ts

@@ -9,11 +9,11 @@ export declare function getLibraryPath(): string;
 export declare function getLocalPath(libraryPath: string): string;
 /**
  * Get the imported entries path.
- * @deprecated Use getPackagesPath for marketplace content
+ * @deprecated Use getPackagesPath for library content
  */
 export declare function getImportedPath(libraryPath: string): string;
 /**
- * Get the packages path (marketplace content from others).
+ * Get the packages path (library content from others).
  */
 export declare function getPackagesPath(libraryPath: string): string;
 /**

package/dist/library/storage.js

@@ -17,13 +17,13 @@ export function getLocalPath(libraryPath) {
 }
 /**
  * Get the imported entries path.
- * @deprecated Use getPackagesPath for marketplace content
+ * @deprecated Use getPackagesPath for library content
  */
 export function getImportedPath(libraryPath) {
     return path.join(libraryPath, 'imported');
 }
 /**
- * Get the packages path (marketplace content from others).
+ * Get the packages path (library content from others).
  */
 export function getPackagesPath(libraryPath) {
     return path.join(libraryPath, 'packages');

package/dist/library 2/embeddings.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Get embedding for a text string.
+ * Returns a 384-dimensional normalized vector.
+ */
+export declare function getEmbedding(text: string): Promise<number[]>;
+/**
+ * Check if embeddings are available (model can load).
+ */
+export declare function isEmbeddingAvailable(): Promise<boolean>;
+/**
+ * Calculate cosine similarity between two vectors.
+ * Since vectors are normalized, this is just the dot product.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Split text into chunks at sentence boundaries.
+ * Aims for ~500 chars per chunk to preserve semantic meaning.
+ */
+export declare function chunkText(text: string, maxChars?: number): string[];
+export declare const EMBEDDING_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+export declare const EMBEDDING_DIMENSION = 384;

package/dist/library 2/embeddings.js

@@ -0,0 +1,86 @@
+import { pipeline, env } from '@huggingface/transformers';
+import * as path from 'path';
+import { getLibraryPath } from './storage.js';
+// ============================================================================
+// Configuration
+// ============================================================================
+// Cache model in .librarian/models
+env.allowRemoteModels = true;
+const MODEL_ID = 'Xenova/all-MiniLM-L6-v2';
+// ============================================================================
+// Embedding Generation
+// ============================================================================
+let embedder = null;
+/**
+ * Get embedding for a text string.
+ * Returns a 384-dimensional normalized vector.
+ */
+export async function getEmbedding(text) {
+    if (!embedder) {
+        // Set local model path on first call
+        const libraryPath = getLibraryPath();
+        env.localModelPath = path.join(libraryPath, 'models');
+        embedder = await pipeline('feature-extraction', MODEL_ID);
+    }
+    const result = await embedder(text, { pooling: 'mean', normalize: true });
+    return Array.from(result.data);
+}
+/**
+ * Check if embeddings are available (model can load).
+ */
+export async function isEmbeddingAvailable() {
+    try {
+        await getEmbedding('test');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Similarity Calculation
+// ============================================================================
+/**
+ * Calculate cosine similarity between two vectors.
+ * Since vectors are normalized, this is just the dot product.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have same dimension');
+    }
+    return a.reduce((sum, val, i) => sum + val * b[i], 0);
+}
+// ============================================================================
+// Text Chunking
+// ============================================================================
+/**
+ * Split text into chunks at sentence boundaries.
+ * Aims for ~500 chars per chunk to preserve semantic meaning.
+ */
+export function chunkText(text, maxChars = 500) {
+    // Split at sentence boundaries (. ! ? followed by whitespace)
+    const sentences = text.split(/(?<=[.!?])\s+/);
+    const chunks = [];
+    let current = '';
+    for (const sentence of sentences) {
+        // If adding this sentence exceeds limit and we have content, start new chunk
+        if ((current + ' ' + sentence).length > maxChars && current.trim()) {
+            chunks.push(current.trim());
+            current = sentence;
+        }
+        else {
+            current = current ? current + ' ' + sentence : sentence;
+        }
+    }
+    // Don't forget the last chunk
+    if (current.trim()) {
+        chunks.push(current.trim());
+    }
+    // If no chunks created (e.g., no sentence boundaries), return original text
+    return chunks.length > 0 ? chunks : [text];
+}
+// ============================================================================
+// Constants
+// ============================================================================
+export const EMBEDDING_MODEL_ID = MODEL_ID;
+export const EMBEDDING_DIMENSION = 384;

package/dist/library 2/manager.d.ts

@@ -0,0 +1,42 @@
+import type { LibraryEntry } from './schemas.js';
+export declare class LibraryManager {
+    private libraryPath;
+    constructor();
+    /**
+     * Initialize the library directory structure.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get all entries from local library.
+     */
+    getLocalEntries(): Promise<LibraryEntry[]>;
+    /**
+     * Get all entries from imported libraries.
+     */
+    getImportedEntries(): Promise<LibraryEntry[]>;
+    /**
+     * Get all archived entries.
+     */
+    getArchivedEntries(): Promise<LibraryEntry[]>;
+    /**
+     * Query entries by topic.
+     */
+    queryByTopic(topic: string): Promise<LibraryEntry[]>;
+    /**
+     * Record a new entry to local library.
+     */
+    record(topics: string[], content: string): Promise<{
+        entry: LibraryEntry;
+        path: string;
+    }>;
+    /**
+     * Archive an entry (move to archived/).
+     */
+    archive(entryId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    private readEntriesFromPath;
+    private findEntryById;
+    private fileExists;
+}

package/dist/library 2/manager.js

@@ -0,0 +1,218 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import { glob } from 'glob';
+import { v4 as uuidv4 } from 'uuid';
+import { getLibraryPath, getLocalPath, getImportedPath, getArchivedPath, } from './storage.js';
+// ============================================================================
+// Library Manager
+// ============================================================================
+export class LibraryManager {
+    libraryPath;
+    constructor() {
+        this.libraryPath = getLibraryPath();
+    }
+    /**
+     * Initialize the library directory structure.
+     */
+    async initialize() {
+        const dirs = [
+            getLocalPath(this.libraryPath),
+            getImportedPath(this.libraryPath),
+            getArchivedPath(this.libraryPath),
+        ];
+        for (const dir of dirs) {
+            await fs.mkdir(dir, { recursive: true });
+        }
+    }
+    /**
+     * Get all entries from local library.
+     */
+    async getLocalEntries() {
+        const localPath = getLocalPath(this.libraryPath);
+        return this.readEntriesFromPath(localPath, 'local');
+    }
+    /**
+     * Get all entries from imported libraries.
+     */
+    async getImportedEntries() {
+        const importedPath = getImportedPath(this.libraryPath);
+        return this.readEntriesFromPath(importedPath, 'imported');
+    }
+    /**
+     * Get all archived entries.
+     */
+    async getArchivedEntries() {
+        const archivedPath = getArchivedPath(this.libraryPath);
+        return this.readEntriesFromPath(archivedPath, 'archived');
+    }
+    /**
+     * Query entries by topic.
+     */
+    async queryByTopic(topic) {
+        const [local, imported] = await Promise.all([
+            this.getLocalEntries(),
+            this.getImportedEntries(),
+        ]);
+        const allEntries = [...local, ...imported];
+        const searchTerm = topic.toLowerCase();
+        return allEntries.filter(entry => entry.topics.some(t => t.toLowerCase().includes(searchTerm)) ||
+            entry.content.toLowerCase().includes(searchTerm));
+    }
+    /**
+     * Record a new entry to local library.
+     */
+    async record(topics, content) {
+        const localPath = getLocalPath(this.libraryPath);
+        await fs.mkdir(localPath, { recursive: true });
+        const id = uuidv4();
+        const created = new Date().toISOString();
+        const entry = {
+            id,
+            topics,
+            content,
+            created,
+            source: 'local',
+            origin: 'manual',
+        };
+        // Generate filename
+        const slug = topics[0]
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '');
+        const timestamp = created.slice(0, 10);
+        let filename = `${slug}-${timestamp}.md`;
+        let filePath = path.join(localPath, filename);
+        // Handle collisions
+        let counter = 1;
+        while (await this.fileExists(filePath)) {
+            filename = `${slug}-${timestamp}-${counter}.md`;
+            filePath = path.join(localPath, filename);
+            counter++;
+        }
+        // Write file
+        const frontmatter = {
+            id,
+            topics,
+            created,
+            source: 'manual',
+        };
+        const fileContent = matter.stringify(content, frontmatter);
+        await fs.writeFile(filePath, fileContent, 'utf-8');
+        return {
+            entry,
+            path: path.relative(this.libraryPath, filePath),
+        };
+    }
+    /**
+     * Archive an entry (move to archived/).
+     */
+    async archive(entryId) {
+        const localPath = getLocalPath(this.libraryPath);
+        const archivedPath = getArchivedPath(this.libraryPath);
+        // Find the entry
+        const found = await this.findEntryById(localPath, entryId);
+        if (!found) {
+            return { success: false, message: `Entry not found: ${entryId}` };
+        }
+        await fs.mkdir(archivedPath, { recursive: true });
+        const filename = path.basename(found.filePath);
+        const newPath = path.join(archivedPath, filename);
+        await fs.rename(found.filePath, newPath);
+        return {
+            success: true,
+            message: `Archived to ${path.relative(this.libraryPath, newPath)}`,
+        };
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    async readEntriesFromPath(dirPath, source) {
+        const entries = [];
+        try {
+            const files = await glob(path.join(dirPath, '**/*.md'), { nodir: true });
+            for (const filePath of files) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const { data, content: body } = matter(content);
+                    let topics;
+                    if (Array.isArray(data.topics)) {
+                        topics = data.topics;
+                    }
+                    else if (data.topic) {
+                        topics = [data.topic];
+                    }
+                    else {
+                        topics = ['general'];
+                    }
+                    entries.push({
+                        id: data.id || uuidv4(),
+                        topics,
+                        content: body.trim(),
+                        created: data.created || new Date().toISOString(),
+                        source,
+                        origin: data.source,
+                        imported_from: data.imported_from,
+                    });
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist
+        }
+        return entries;
+    }
+    async findEntryById(dirPath, entryId) {
+        try {
+            const files = await glob(path.join(dirPath, '**/*.md'), { nodir: true });
+            for (const filePath of files) {
+                try {
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    const { data, content: body } = matter(content);
+                    if (data.id === entryId) {
+                        let topics;
+                        if (Array.isArray(data.topics)) {
+                            topics = data.topics;
+                        }
+                        else if (data.topic) {
+                            topics = [data.topic];
+                        }
+                        else {
+                            topics = ['general'];
+                        }
+                        return {
+                            entry: {
+                                id: data.id,
+                                topics,
+                                content: body.trim(),
+                                created: data.created || new Date().toISOString(),
+                                source: 'local',
+                                origin: data.source,
+                            },
+                            filePath,
+                        };
+                    }
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist
+        }
+        return null;
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/library 2/parsers/cursor.d.ts

@@ -0,0 +1,15 @@
+import type { ParseResult } from './types.js';
+/**
+ * Parse a Cursor Memory Bank folder (.cursor-memory/).
+ *
+ * Cursor Memory Bank typically contains:
+ * - activeContext.md - Current working context
+ * - progress.md - Progress log
+ * - projectBrief.md - Project overview
+ * - systemPatterns.md - System patterns
+ * - decisionLog.md - Decision history
+ * - techStack.md - Technology stack info
+ *
+ * Can also contain JSON files and subdirectories.
+ */
+export declare function parseCursorMemory(dirPath: string): Promise<ParseResult>;