@telvok/librarian-mcp 1.5.3 → 2.0.0

package/dist/library 2/schemas.js

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+// ============================================================================
+// Core Types
+// ============================================================================
+export const SourceTypeSchema = z.enum(['local', 'imported', 'archived']);
+export const EntrySourceSchema = z.enum(['manual', 'precompact', 'imported']);
+// ============================================================================
+// Library Entry
+// ============================================================================
+export const LibraryEntrySchema = z.object({
+    id: z.string().uuid(),
+    topics: z.array(z.string().min(1)).min(1),
+    content: z.string().min(1),
+    created: z.string().datetime(),
+    source: SourceTypeSchema,
+    origin: EntrySourceSchema.optional(),
+    imported_from: z.string().optional(),
+});
+// ============================================================================
+// File Frontmatter (YAML)
+// ============================================================================
+export const FrontmatterSchema = z.object({
+    id: z.string().uuid(),
+    topics: z.array(z.string().min(1)).min(1),
+    created: z.string().datetime(),
+    source: EntrySourceSchema.optional(),
+    imported_from: z.string().optional(),
+});
+// ============================================================================
+// MCP Tool Parameters
+// ============================================================================
+export const BriefParamsSchema = z.object({
+    topic: z.string().min(1).describe('What to query (e.g., "deployment", "api-design")'),
+    context: z.string().optional().describe('Additional context to narrow results'),
+});
+export const RecordParamsSchema = z.object({
+    topics: z.union([
+        z.string().min(1),
+        z.array(z.string().min(1)).min(1),
+    ]).describe('Topic tags - string or array (e.g., "deployment" or ["stripe", "webhooks"])'),
+    content: z.string().min(1).describe('The reasoning to record'),
+});
+export const AdoptParamsSchema = z.object({
+    entry_id: z.string().uuid().describe('ID of the imported entry to adopt'),
+    library_name: z.string().optional().describe('Name of the imported library'),
+});
+// ============================================================================
+// MCP Tool Results
+// ============================================================================
+export const BriefResultSchema = z.object({
+    entries: z.array(LibraryEntrySchema),
+    conflict: z.boolean().optional(),
+    conflict_summary: z.string().optional(),
+});
+export const ImportedLibrarySchema = z.object({
+    name: z.string(),
+    entry_count: z.number(),
+    purchased_at: z.string().datetime(),
+    sync_preference: z.enum(['auto', 'manual', 'pinned']).optional(),
+    last_synced: z.string().datetime().optional(),
+});
+export const StateResultSchema = z.object({
+    entries: z.array(LibraryEntrySchema),
+    imported_libraries: z.array(ImportedLibrarySchema),
+});
+export const RecordResultSchema = z.object({
+    entry: LibraryEntrySchema,
+    path: z.string(),
+});
+// ============================================================================
+// Extraction Types
+// ============================================================================
+export const ExtractedEntrySchema = z.object({
+    topics: z.array(z.string().min(1)).min(1),
+    content: z.string().min(1),
+});
+export const ExtractionResultSchema = z.object({
+    entries: z.array(ExtractedEntrySchema),
+});

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

@@ -0,0 +1,22 @@
+/**
+ * Get the library root path.
+ * Uses .librarian/ in the current working directory.
+ */
+export declare function getLibraryPath(): string;
+/**
+ * Get the local entries path.
+ */
+export declare function getLocalPath(libraryPath: string): string;
+/**
+ * Get the imported entries path.
+ * @deprecated Use getPackagesPath for marketplace content
+ */
+export declare function getImportedPath(libraryPath: string): string;
+/**
+ * Get the packages path (marketplace content from others).
+ */
+export declare function getPackagesPath(libraryPath: string): string;
+/**
+ * Get the archived entries path.
+ */
+export declare function getArchivedPath(libraryPath: string): string;

package/dist/library 2/storage.js

@@ -0,0 +1,36 @@
+import * as path from 'path';
+// ============================================================================
+// Path Utilities
+// ============================================================================
+/**
+ * Get the library root path.
+ * Uses .librarian/ in the current working directory.
+ */
+export function getLibraryPath() {
+    return path.join(process.cwd(), '.librarian');
+}
+/**
+ * Get the local entries path.
+ */
+export function getLocalPath(libraryPath) {
+    return path.join(libraryPath, 'local');
+}
+/**
+ * Get the imported entries path.
+ * @deprecated Use getPackagesPath for marketplace content
+ */
+export function getImportedPath(libraryPath) {
+    return path.join(libraryPath, 'imported');
+}
+/**
+ * Get the packages path (marketplace content from others).
+ */
+export function getPackagesPath(libraryPath) {
+    return path.join(libraryPath, 'packages');
+}
+/**
+ * Get the archived entries path.
+ */
+export function getArchivedPath(libraryPath) {
+    return path.join(libraryPath, 'archived');
+}

package/dist/library 2/vector-index.d.ts

@@ -0,0 +1,55 @@
+export interface IndexEntry {
+    path: string;
+    title: string;
+    embedding: number[];
+    chunk: number;
+    preview: string;
+}
+export interface VectorIndex {
+    version: number;
+    rebuilt: string;
+    modelId: string;
+    entries: IndexEntry[];
+}
+export interface SemanticMatch {
+    path: string;
+    title: string;
+    similarity: number;
+    preview: string;
+}
+/**
+ * Load the vector index from disk.
+ * Returns empty index if file doesn't exist or is invalid.
+ */
+export declare function loadIndex(): Promise<VectorIndex>;
+/**
+ * Save the vector index to disk.
+ */
+export declare function saveIndex(index: VectorIndex): Promise<void>;
+/**
+ * Add or update an entry in the index.
+ * Chunks the content and generates embeddings for each chunk.
+ */
+export declare function addToIndex(index: VectorIndex, entryPath: string, title: string, content: string): Promise<void>;
+/**
+ * Remove an entry from the index.
+ */
+export declare function removeFromIndex(index: VectorIndex, entryPath: string): void;
+/**
+ * Search the index for entries semantically similar to the query.
+ * Returns paths ranked by similarity, deduped to best chunk per entry.
+ */
+export declare function semanticSearch(index: VectorIndex, query: string, limit?: number): Promise<SemanticMatch[]>;
+/**
+ * Check if the index might be stale (model changed).
+ */
+export declare function isIndexStale(index: VectorIndex): boolean;
+/**
+ * Get index statistics.
+ */
+export declare function getIndexStats(index: VectorIndex): {
+    entryCount: number;
+    chunkCount: number;
+    modelId: string;
+    rebuilt: string;
+};

package/dist/library 2/vector-index.js

@@ -0,0 +1,160 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { getLibraryPath } from './storage.js';
+import { getEmbedding, chunkText, cosineSimilarity, EMBEDDING_MODEL_ID } from './embeddings.js';
+// ============================================================================
+// Constants
+// ============================================================================
+const INDEX_FILENAME = 'index.json';
+const CURRENT_VERSION = 1;
+// ============================================================================
+// Index File Operations
+// ============================================================================
+/**
+ * Get path to the index file.
+ */
+function getIndexPath() {
+    return path.join(getLibraryPath(), INDEX_FILENAME);
+}
+/**
+ * Load the vector index from disk.
+ * Returns empty index if file doesn't exist or is invalid.
+ */
+export async function loadIndex() {
+    const indexPath = getIndexPath();
+    try {
+        const data = await fs.readFile(indexPath, 'utf-8');
+        const index = JSON.parse(data);
+        // Validate structure
+        if (!index.version || !Array.isArray(index.entries)) {
+            return createEmptyIndex();
+        }
+        return index;
+    }
+    catch {
+        // File doesn't exist or is invalid
+        return createEmptyIndex();
+    }
+}
+/**
+ * Save the vector index to disk.
+ */
+export async function saveIndex(index) {
+    const indexPath = getIndexPath();
+    // Update metadata
+    index.rebuilt = new Date().toISOString();
+    index.modelId = EMBEDDING_MODEL_ID;
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(indexPath), { recursive: true });
+    // Write atomically by writing to temp file first
+    const tempPath = indexPath + '.tmp';
+    await fs.writeFile(tempPath, JSON.stringify(index, null, 2), 'utf-8');
+    await fs.rename(tempPath, indexPath);
+}
+/**
+ * Create an empty index.
+ */
+function createEmptyIndex() {
+    return {
+        version: CURRENT_VERSION,
+        rebuilt: '',
+        modelId: EMBEDDING_MODEL_ID,
+        entries: [],
+    };
+}
+// ============================================================================
+// Index Operations
+// ============================================================================
+/**
+ * Add or update an entry in the index.
+ * Chunks the content and generates embeddings for each chunk.
+ */
+export async function addToIndex(index, entryPath, title, content) {
+    // Remove any existing entries for this path
+    index.entries = index.entries.filter(e => e.path !== entryPath);
+    // Chunk the content
+    const chunks = chunkText(content);
+    // Generate embeddings for each chunk
+    for (let i = 0; i < chunks.length; i++) {
+        const chunk = chunks[i];
+        try {
+            const embedding = await getEmbedding(chunk);
+            index.entries.push({
+                path: entryPath,
+                title,
+                embedding,
+                chunk: i,
+                preview: chunk.slice(0, 100) + (chunk.length > 100 ? '...' : ''),
+            });
+        }
+        catch (error) {
+            // Log but don't fail - entry will still be searchable via keywords
+            console.error(`Failed to embed chunk ${i} for ${entryPath}:`, error);
+        }
+    }
+}
+/**
+ * Remove an entry from the index.
+ */
+export function removeFromIndex(index, entryPath) {
+    index.entries = index.entries.filter(e => e.path !== entryPath);
+}
+// ============================================================================
+// Semantic Search
+// ============================================================================
+/**
+ * Search the index for entries semantically similar to the query.
+ * Returns paths ranked by similarity, deduped to best chunk per entry.
+ */
+export async function semanticSearch(index, query, limit = 5) {
+    if (index.entries.length === 0) {
+        return [];
+    }
+    // Get query embedding
+    const queryEmbedding = await getEmbedding(query);
+    // Score all entries
+    const scored = index.entries.map(entry => ({
+        ...entry,
+        similarity: cosineSimilarity(queryEmbedding, entry.embedding),
+    }));
+    // Dedupe by path - keep the chunk with highest similarity
+    const byPath = new Map();
+    for (const entry of scored) {
+        const existing = byPath.get(entry.path);
+        if (!existing || entry.similarity > existing.similarity) {
+            byPath.set(entry.path, entry);
+        }
+    }
+    // Sort by similarity descending and apply limit
+    const results = [...byPath.values()]
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, limit)
+        .map(entry => ({
+        path: entry.path,
+        title: entry.title,
+        similarity: entry.similarity,
+        preview: entry.preview,
+    }));
+    return results;
+}
+// ============================================================================
+// Index Health
+// ============================================================================
+/**
+ * Check if the index might be stale (model changed).
+ */
+export function isIndexStale(index) {
+    return index.modelId !== EMBEDDING_MODEL_ID;
+}
+/**
+ * Get index statistics.
+ */
+export function getIndexStats(index) {
+    const uniquePaths = new Set(index.entries.map(e => e.path));
+    return {
+        entryCount: uniquePaths.size,
+        chunkCount: index.entries.length,
+        modelId: index.modelId,
+        rebuilt: index.rebuilt,
+    };
+}

package/dist/server 2.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { briefTool } from './tools/brief.js';
+import { recordTool } from './tools/record.js';
+import { adoptTool } from './tools/adopt.js';
+import { markHitTool } from './tools/mark-hit.js';
+import { importMemoriesTool } from './tools/import-memories.js';
+import { rebuildIndexTool } from './tools/rebuild-index.js';
+import { authTool } from './tools/auth.js';
+import { marketplaceSearchTool } from './tools/marketplace-search.js';
+import { marketplaceBuyTool } from './tools/marketplace-buy.js';
+import { marketplaceDownloadTool } from './tools/marketplace-download.js';
+import { marketplacePublishTool } from './tools/marketplace-publish.js';
+import { myBooksTool } from './tools/my-books.js';
+import { syncTool } from './tools/sync.js';
+import { sellerAnalyticsTool } from './tools/seller-analytics.js';
+import { rateBookTool } from './tools/rate-book.js';
+import { helpTool } from './tools/help.js';
+const server = new Server({
+    name: 'librarian',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: briefTool.name,
+                description: briefTool.description,
+                inputSchema: briefTool.inputSchema,
+            },
+            {
+                name: recordTool.name,
+                description: recordTool.description,
+                inputSchema: recordTool.inputSchema,
+            },
+            {
+                name: adoptTool.name,
+                description: adoptTool.description,
+                inputSchema: adoptTool.inputSchema,
+            },
+            {
+                name: markHitTool.name,
+                description: markHitTool.description,
+                inputSchema: markHitTool.inputSchema,
+            },
+            {
+                name: importMemoriesTool.name,
+                description: importMemoriesTool.description,
+                inputSchema: importMemoriesTool.inputSchema,
+            },
+            {
+                name: rebuildIndexTool.name,
+                description: rebuildIndexTool.description,
+                inputSchema: rebuildIndexTool.inputSchema,
+            },
+            {
+                name: authTool.name,
+                description: authTool.description,
+                inputSchema: authTool.inputSchema,
+            },
+            {
+                name: marketplaceSearchTool.name,
+                description: marketplaceSearchTool.description,
+                inputSchema: marketplaceSearchTool.inputSchema,
+            },
+            {
+                name: marketplaceBuyTool.name,
+                description: marketplaceBuyTool.description,
+                inputSchema: marketplaceBuyTool.inputSchema,
+            },
+            {
+                name: marketplaceDownloadTool.name,
+                description: marketplaceDownloadTool.description,
+                inputSchema: marketplaceDownloadTool.inputSchema,
+            },
+            {
+                name: marketplacePublishTool.name,
+                description: marketplacePublishTool.description,
+                inputSchema: marketplacePublishTool.inputSchema,
+            },
+            {
+                name: myBooksTool.name,
+                description: myBooksTool.description,
+                inputSchema: myBooksTool.inputSchema,
+            },
+            {
+                name: syncTool.name,
+                description: syncTool.description,
+                inputSchema: syncTool.inputSchema,
+            },
+            {
+                name: sellerAnalyticsTool.name,
+                description: sellerAnalyticsTool.description,
+                inputSchema: sellerAnalyticsTool.inputSchema,
+            },
+            {
+                name: rateBookTool.name,
+                description: rateBookTool.description,
+                inputSchema: rateBookTool.inputSchema,
+            },
+            {
+                name: helpTool.name,
+                description: helpTool.description,
+                inputSchema: helpTool.inputSchema,
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case 'brief':
+                result = await briefTool.handler(args);
+                break;
+            case 'record':
+                result = await recordTool.handler(args);
+                break;
+            case 'adopt':
+                result = await adoptTool.handler(args);
+                break;
+            case 'mark_hit':
+                result = await markHitTool.handler(args);
+                break;
+            case 'import_memories':
+                result = await importMemoriesTool.handler(args);
+                break;
+            case 'rebuild_index':
+                result = await rebuildIndexTool.handler(args);
+                break;
+            case 'auth':
+                result = await authTool.handler(args);
+                break;
+            case 'marketplace_search':
+                result = await marketplaceSearchTool.handler(args);
+                break;
+            case 'marketplace_buy':
+                result = await marketplaceBuyTool.handler(args);
+                break;
+            case 'marketplace_download':
+                result = await marketplaceDownloadTool.handler(args);
+                break;
+            case 'marketplace_publish':
+                result = await marketplacePublishTool.handler(args);
+                break;
+            case 'my_books':
+                result = await myBooksTool.handler(args);
+                break;
+            case 'sync':
+                result = await syncTool.handler(args);
+                break;
+            case 'seller_analytics':
+                result = await sellerAnalyticsTool.handler();
+                break;
+            case 'rate_book':
+                result = await rateBookTool.handler(args);
+                break;
+            case 'help':
+                result = await helpTool.handler(args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: message }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/server.d 2.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};