@telvok/librarian-mcp 1.5.3 → 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/parsers/jsonl.d.ts

@@ -1,9 +1,14 @@
 import type { ParseResult } from './types.js';
 /**
- * Parse a JSONL file (Anthropic MCP Memory / mcp-knowledge-graph format).
+ * Parse a JSONL file. Supports multiple formats:
  *
- * Input format:
- * {"type":"entity","name":"Stripe Webhooks","entityType":"concept","observations":["Need idempotency checks"]}
- * {"type":"relation","from":"Stripe Webhooks","to":"Payment Processing","relationType":"part_of"}
+ * mcp-knowledge-graph:
+ * {"type":"entity","name":"Topic","observations":["fact 1","fact 2"]}
+ *
+ * Generic memory formats:
+ * {"title":"Topic","content":"..."}
+ * {"content":"...","timestamp":"..."}
+ * {"text":"...","metadata":{}}
+ * {"memory":"...","created_at":"..."}
  */
 export declare function parseJSONL(filePath: string): Promise<ParseResult>;

package/dist/library/parsers/jsonl.js

@@ -1,10 +1,15 @@
 import * as fs from 'fs/promises';
 /**
- * Parse a JSONL file (Anthropic MCP Memory / mcp-knowledge-graph format).
+ * Parse a JSONL file. Supports multiple formats:
  *
- * Input format:
- * {"type":"entity","name":"Stripe Webhooks","entityType":"concept","observations":["Need idempotency checks"]}
- * {"type":"relation","from":"Stripe Webhooks","to":"Payment Processing","relationType":"part_of"}
+ * mcp-knowledge-graph:
+ * {"type":"entity","name":"Topic","observations":["fact 1","fact 2"]}
+ *
+ * Generic memory formats:
+ * {"title":"Topic","content":"..."}
+ * {"content":"...","timestamp":"..."}
+ * {"text":"...","metadata":{}}
+ * {"memory":"...","created_at":"..."}
  */
 export async function parseJSONL(filePath) {
     const entries = [];
@@ -17,28 +22,55 @@ export async function parseJSONL(filePath) {
             const line = lines[i];
             try {
                 const item = JSON.parse(line);
-                // Skip safety markers and relations
+                // Skip internal markers and relations
                 if (item.type === '_aim' || item.type === 'relation') {
                     skipped++;
                     continue;
                 }
-                // Only process entities
-                if (item.type === 'entity' && item.name) {
-                    // Skip if no observations (empty content)
-                    if (!item.observations || item.observations.length === 0) {
-                        skipped++;
-                        continue;
-                    }
-                    entries.push({
-                        title: item.name,
-                        content: item.observations.join('\n\n'),
-                        context: item.entityType || undefined,
-                        source: 'jsonl',
-                    });
-                }
-                else {
+                // Extract title (try multiple fields)
+                const title = item.name || item.title || item.key || `Entry ${i + 1}`;
+                // Extract content (try multiple fields)
+                let entryContent;
+                // Check observations array first (mcp-knowledge-graph)
+                if (item.observations && Array.isArray(item.observations) && item.observations.length > 0) {
+                    entryContent = item.observations.join('\n\n');
+                }
+                // Fall back to common content fields
+                if (!entryContent) {
+                    entryContent = item.content || item.text || item.description ||
+                        item.value || item.memory || item.observation || item.body;
+                }
+                // Skip if no content found
+                if (!entryContent) {
                     skipped++;
+                    continue;
+                }
+                // Extract context
+                let context;
+                if (item.entityType) {
+                    context = item.entityType;
+                }
+                else if (item.context) {
+                    context = item.context;
+                }
+                else if (item.category) {
+                    context = item.category;
+                }
+                else if (item.type && item.type !== 'entity' && item.type !== 'memory') {
+                    context = item.type;
+                }
+                else if (item.tags && Array.isArray(item.tags)) {
+                    context = item.tags.join(', ');
                 }
+                entries.push({
+                    title: String(title),
+                    content: String(entryContent),
+                    context,
+                    intent: item.intent ? String(item.intent) : undefined,
+                    reasoning: item.reasoning ? String(item.reasoning) : undefined,
+                    example: item.example ? String(item.example) : undefined,
+                    source: 'jsonl',
+                });
             }
             catch (parseError) {
                 errors.push(`Line ${i + 1}: Invalid JSON - ${parseError instanceof Error ? parseError.message : String(parseError)}`);

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;
+}