@telvok/librarian-mcp 1.5.4 → 2.0.0

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

package/dist/server.js

@@ -2,12 +2,85 @@
 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 { LibrarianError } from './library/errors.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 { librarySearchTool } from './tools/library-search.js';
+import { libraryBuyTool } from './tools/library-buy.js';
+import { libraryDownloadTool } from './tools/library-download.js';
+import { libraryPublishTool } from './tools/library-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';
+import { feedbackTool } from './tools/feedback.js';
+import { bountyCreateTool } from './tools/bounty-create.js';
+import { bountyListTool } from './tools/bounty-list.js';
+import { bountyClaimTool } from './tools/bounty-claim.js';
+import { bountySubmitTool } from './tools/bounty-submit.js';
+import { myBountiesTool } from './tools/my-bounties.js';
+import { deleteTool } from './tools/delete.js';
+import { unsubscribeTool } from './tools/unsubscribe.js';
+const allTools = [
+    // Core tools — local knowledge management
+    { tool: briefTool, group: 'core' },
+    { tool: recordTool, group: 'core' },
+    { tool: adoptTool, group: 'core' },
+    { tool: markHitTool, group: 'core' },
+    { tool: importMemoriesTool, group: 'core' },
+    { tool: rebuildIndexTool, group: 'core' },
+    { tool: deleteTool, group: 'core' },
+    // Marketplace tools — cloud features
+    { tool: librarySearchTool, group: 'marketplace' },
+    { tool: libraryBuyTool, group: 'marketplace' },
+    { tool: libraryDownloadTool, group: 'marketplace' },
+    { tool: libraryPublishTool, group: 'marketplace' },
+    { tool: myBooksTool, group: 'marketplace' },
+    { tool: syncTool, group: 'marketplace' },
+    { tool: sellerAnalyticsTool, group: 'marketplace' },
+    { tool: rateBookTool, group: 'marketplace' },
+    { tool: bountyCreateTool, group: 'marketplace' },
+    { tool: bountyListTool, group: 'marketplace' },
+    { tool: bountyClaimTool, group: 'marketplace' },
+    { tool: bountySubmitTool, group: 'marketplace' },
+    { tool: myBountiesTool, group: 'marketplace' },
+    { tool: unsubscribeTool, group: 'marketplace' },
+    // Both — shared across core and marketplace
+    { tool: authTool, group: 'both' },
+    { tool: helpTool, group: 'both' },
+    { tool: feedbackTool, group: 'both' },
+];
+function parseServerMode() {
+    const serverArg = process.argv.find(a => a.startsWith('--server='));
+    if (!serverArg)
+        return 'all';
+    const mode = serverArg.split('=')[1];
+    if (mode === 'core' || mode === 'marketplace')
+        return mode;
+    console.error(`Unknown --server mode: "${mode}". Valid: core, marketplace. Defaulting to all.`);
+    return 'all';
+}
+const serverMode = parseServerMode();
+function isToolIncluded(entry) {
+    if (serverMode === 'all')
+        return true;
+    return entry.group === serverMode || entry.group === 'both';
+}
+const enabledTools = allTools.filter(isToolIncluded);
+// Build lookup map for call handler
+const toolMap = new Map();
+for (const entry of enabledTools) {
+    toolMap.set(entry.tool.name, entry.tool);
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
 const server = new Server({
     name: 'librarian',
     version: '1.0.0',
@@ -19,67 +92,29 @@ const server = new Server({
 // 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,
-            },
-        ],
+        tools: enabledTools.map(({ tool }) => {
+            const entry = {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            };
+            if (tool.title)
+                entry.title = tool.title;
+            if (tool.outputSchema)
+                entry.outputSchema = tool.outputSchema;
+            return entry;
+        }),
     };
 });
 // 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;
-            default:
-                throw new Error(`Unknown tool: ${name}`);
+        const tool = toolMap.get(name);
+        if (!tool) {
+            throw new Error(`Unknown tool: ${name}`);
         }
+        const result = await tool.handler(args);
         return {
             content: [
                 {
@@ -90,6 +125,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
     catch (error) {
+        // Handle LibrarianError with error codes
+        if (error instanceof LibrarianError) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(error.toJSON()),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle generic errors
         const message = error instanceof Error ? error.message : String(error);
         return {
             content: [

package/dist/tools/adopt.d.ts

@@ -5,6 +5,7 @@ export interface AdoptResult {
 }
 export declare const adoptTool: {
     name: string;
+    title: string;
     description: string;
     inputSchema: {
         type: "object";

package/dist/tools/adopt.js

@@ -1,20 +1,29 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import matter from 'gray-matter';
-import { getLibraryPath, getImportedPath, getLocalPath } from '../library/storage.js';
+import { getLibraryPath, getImportedPath, getLocalPath, getPackagesPath } from '../library/storage.js';
 // ============================================================================
 // Tool Definition
 // ============================================================================
 export const adoptTool = {
     name: 'adopt',
-    description: `Make imported knowledge ours.
+    title: 'Adopt Imported Entry',
+    description: `Move an imported/packages entry to local library for editing.
 
-When an entry from an imported package proves useful, adopt it into our
-local library. It graduates from "their knowledge" to "our knowledge" -
-now we can edit and evolve it.
+USE THIS TOOL WHEN:
+- An imported entry is useful but needs customization
+- Want to evolve third-party knowledge with our learnings
+- Entry from packages/ or imported/ should become our own
+
+Copies to local/ where we can edit it. Original stays in place.
+
+TRIGGER PATTERNS:
+- Entry from brief() needs edits → adopt({ path: "..." })
+- "Make that entry ours" → adopt({ path: "...", title: "Our version" })
+- Want to customize purchased content → adopt({ path: "packages/..." })
 
 Examples:
-- adopt({ path: "imported/stripe-patterns/webhook-idempotency" })
+- adopt({ path: "packages/stripe-patterns/webhook-idempotency" })
 - adopt({ path: "imported/auth-patterns/token-refresh", title: "Our token refresh" })`,
     inputSchema: {
         type: 'object',
@@ -37,22 +46,40 @@ Examples:
         }
         const libraryPath = getLibraryPath();
         const importedPath = getImportedPath(libraryPath);
+        const packagesPath = getPackagesPath(libraryPath);
         const localPath = getLocalPath(libraryPath);
-        // Normalize path: strip "imported/" prefix if present, add .md if missing
+        // Normalize path: strip "imported/" or "packages/" prefix if present, add .md if missing
         let normalizedPath = entryPath;
         if (normalizedPath.startsWith('imported/')) {
             normalizedPath = normalizedPath.slice('imported/'.length);
         }
+        else if (normalizedPath.startsWith('packages/')) {
+            normalizedPath = normalizedPath.slice('packages/'.length);
+        }
         if (!normalizedPath.endsWith('.md')) {
             normalizedPath += '.md';
         }
-        const sourcePath = path.join(importedPath, normalizedPath);
-        // Check if source exists
+        // Try both imported/ and packages/ paths
+        let sourcePath = path.resolve(importedPath, normalizedPath);
+        // Prevent path traversal
+        if (!sourcePath.startsWith(path.resolve(importedPath)) && !sourcePath.startsWith(path.resolve(packagesPath))) {
+            throw new Error('Invalid path: must be within imported/ or packages/');
+        }
         try {
             await fs.access(sourcePath);
         }
         catch {
-            throw new Error(`Entry not found: ${entryPath}`);
+            // Try packages path (for library downloads)
+            sourcePath = path.resolve(packagesPath, normalizedPath);
+            if (!sourcePath.startsWith(path.resolve(packagesPath))) {
+                throw new Error('Invalid path: must be within imported/ or packages/');
+            }
+            try {
+                await fs.access(sourcePath);
+            }
+            catch {
+                throw new Error(`Entry not found: ${entryPath}`);
+            }
         }
         // Read source file
         const content = await fs.readFile(sourcePath, 'utf-8');