rag-lite-ts 2.1.1 → 2.3.0

package/dist/esm/mcp-server.js

@@ -0,0 +1,1820 @@
+#!/usr/bin/env node
+/**
+ * MCP server entry point for rag-lite-ts with Chameleon Multimodal Architecture
+ *
+ * This is a thin wrapper around the polymorphic search and ingestion functions
+ * that exposes them as MCP tools without creating REST/GraphQL endpoints.
+ *
+ * The MCP server supports both text-only and multimodal modes:
+ * - Text mode: Optimized for text documents using sentence-transformer models
+ * - Multimodal mode: Supports mixed text and image content using CLIP models
+ *
+ * Key Features:
+ * - Automatic mode detection from database configuration
+ * - Polymorphic runtime that adapts to stored mode settings
+ * - Support for multiple embedding models and reranking strategies
+ * - Content type filtering and multimodal search capabilities
+ * - Comprehensive model and strategy information tools
+ *
+ * The MCP server lives in the same package as CLI with dual entry points
+ * and provides proper MCP tool definitions for search and indexing capabilities.
+ *
+ * Requirements addressed: 6.2, 6.4, 6.5, 6.6, 9.1, 9.2, 9.3
+ */
+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 { existsSync, statSync, createWriteStream } from 'fs';
+import { resolve } from 'path';
+import { SearchFactory } from './factories/search-factory.js';
+import { IngestionFactory } from './factories/ingestion-factory.js';
+import { getSystemInfo } from './core/db.js';
+import { DatabaseConnectionManager } from './core/database-connection-manager.js';
+import { config, validateCoreConfig, ConfigurationError } from './core/config.js';
+/**
+ * Detect MIME type from file path or extension
+ */
+function getMimeTypeFromPath(filePath) {
+    const ext = filePath.toLowerCase().split('.').pop() || '';
+    const mimeTypes = {
+        'jpg': 'image/jpeg',
+        'jpeg': 'image/jpeg',
+        'png': 'image/png',
+        'gif': 'image/gif',
+        'webp': 'image/webp',
+        'bmp': 'image/bmp',
+        'svg': 'image/svg+xml'
+    };
+    return mimeTypes[ext] || 'image/jpeg'; // Default to JPEG if unknown
+}
+/**
+ * MCP Server class that wraps RAG-lite TS functionality
+ * Implements MCP protocol interface without creating REST/GraphQL endpoints
+ */
+class RagLiteMCPServer {
+    server;
+    searchEngine = null;
+    isSearchEngineInitialized = false;
+    constructor() {
+        this.server = new Server({
+            name: 'rag-lite-ts',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupToolHandlers();
+    }
+    /**
+     * Set up MCP tool handlers for search and indexing capabilities
+     * Add proper MCP tool definitions for search and indexing capabilities
+     */
+    setupToolHandlers() {
+        // List available tools - with dynamic descriptions based on database mode
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // Detect current mode and capabilities from database
+            const capabilities = await this.detectCapabilities();
+            return {
+                tools: [
+                    {
+                        name: 'search',
+                        description: this.generateSearchDescription(capabilities),
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                query: {
+                                    type: 'string',
+                                    description: 'Search query string to find relevant documents',
+                                    minLength: 1,
+                                    maxLength: 500
+                                },
+                                top_k: {
+                                    type: 'number',
+                                    description: 'Number of results to return (default: 10, max: 100)',
+                                    minimum: 1,
+                                    maximum: 100,
+                                    default: 10
+                                },
+                                rerank: {
+                                    type: 'boolean',
+                                    description: 'Enable reranking for better result quality (default: false)',
+                                    default: false
+                                }
+                            },
+                            required: ['query'],
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'ingest',
+                        description: 'Ingest documents from a file or directory path. Supports both text-only and multimodal modes. In text mode, processes .md and .txt files. In multimodal mode, also processes images (.jpg, .png, .gif, .webp).',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                path: {
+                                    type: 'string',
+                                    description: 'File or directory path to ingest. Can be a single file or directory containing supported files.'
+                                },
+                                mode: {
+                                    type: 'string',
+                                    description: 'Processing mode: text for text-only content, multimodal for mixed text and image content (default: text)',
+                                    enum: ['text', 'multimodal'],
+                                    default: 'text'
+                                },
+                                model: {
+                                    type: 'string',
+                                    description: 'Embedding model to use. For text mode: sentence-transformers/all-MiniLM-L6-v2 (default), Xenova/all-mpnet-base-v2. For multimodal mode: Xenova/clip-vit-base-patch32 (default), Xenova/clip-vit-base-patch16',
+                                    enum: [
+                                        'sentence-transformers/all-MiniLM-L6-v2',
+                                        'Xenova/all-mpnet-base-v2',
+                                        'Xenova/clip-vit-base-patch32',
+                                        'Xenova/clip-vit-base-patch16'
+                                    ]
+                                },
+                                rerank_strategy: {
+                                    type: 'string',
+                                    description: 'Reranking strategy for multimodal mode. Options: text-derived (default), disabled',
+                                    enum: ['text-derived', 'disabled']
+                                },
+                                force_rebuild: {
+                                    type: 'boolean',
+                                    description: 'Force rebuild of the entire index (default: false)',
+                                    default: false
+                                }
+                            },
+                            required: ['path'],
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'ingest_image',
+                        description: 'Ingest image files or image URLs into the multimodal index. Automatically sets mode to multimodal and uses CLIP embeddings. Supports local image files and remote image URLs (http/https).',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                source: {
+                                    type: 'string',
+                                    description: 'Image file path or URL. Can be a local file path (e.g., ./image.jpg) or a remote URL (e.g., https://example.com/image.jpg). Supported formats: jpg, jpeg, png, gif, webp.'
+                                },
+                                model: {
+                                    type: 'string',
+                                    description: 'CLIP model to use for image embedding (default: Xenova/clip-vit-base-patch32)',
+                                    enum: [
+                                        'Xenova/clip-vit-base-patch32',
+                                        'Xenova/clip-vit-base-patch16'
+                                    ],
+                                    default: 'Xenova/clip-vit-base-patch32'
+                                },
+                                rerank_strategy: {
+                                    type: 'string',
+                                    description: 'Reranking strategy for multimodal mode. Options: text-derived (default), disabled',
+                                    enum: ['text-derived', 'disabled'],
+                                    default: 'text-derived'
+                                },
+                                title: {
+                                    type: 'string',
+                                    description: 'Optional title for the image. If not provided, will use filename or URL.'
+                                },
+                                metadata: {
+                                    type: 'object',
+                                    description: 'Optional metadata to associate with the image (e.g., tags, description, source info)'
+                                }
+                            },
+                            required: ['source'],
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'rebuild_index',
+                        description: 'Rebuild the entire vector index from scratch. Useful when model version changes or for maintenance. This will regenerate all embeddings.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'get_stats',
+                        description: 'Get statistics about the current search index including number of documents, chunks, and index status.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'get_mode_info',
+                        description: 'Get current system mode and configuration information including detected mode, model, and reranking strategy.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'multimodal_search',
+                        description: 'Search indexed documents with multimodal capabilities and content type filtering. Returns relevant document chunks with content type information. Image results include base64-encoded image data for display in MCP clients. Supports cross-modal search in multimodal mode (text queries can find images, image queries can find text).',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                query: {
+                                    type: 'string',
+                                    description: 'Search query string to find relevant documents. In multimodal mode, text queries can find semantically similar images.',
+                                    minLength: 1,
+                                    maxLength: 500
+                                },
+                                top_k: {
+                                    type: 'number',
+                                    description: 'Number of results to return (default: 10, max: 100)',
+                                    minimum: 1,
+                                    maximum: 100,
+                                    default: 10
+                                },
+                                rerank: {
+                                    type: 'boolean',
+                                    description: 'Enable reranking for better result quality (default: false)',
+                                    default: false
+                                },
+                                content_type: {
+                                    type: 'string',
+                                    description: 'Filter results by content type (text, image, pdf, docx). If not specified, returns all content types. Use "image" to find only images, "text" for only text.',
+                                    enum: ['text', 'image', 'pdf', 'docx']
+                                }
+                            },
+                            required: ['query'],
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'list_supported_models',
+                        description: 'List all supported embedding models with their capabilities, dimensions, and supported content types.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                model_type: {
+                                    type: 'string',
+                                    description: 'Filter models by type (sentence-transformer, clip). If not specified, returns all models.',
+                                    enum: ['sentence-transformer', 'clip']
+                                },
+                                content_type: {
+                                    type: 'string',
+                                    description: 'Filter models by supported content type (text, image). If not specified, returns all models.',
+                                    enum: ['text', 'image']
+                                }
+                            },
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'list_reranking_strategies',
+                        description: 'List all supported reranking strategies for different modes with their descriptions and requirements.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                mode: {
+                                    type: 'string',
+                                    description: 'Filter strategies by mode (text, multimodal). If not specified, returns strategies for all modes.',
+                                    enum: ['text', 'multimodal']
+                                }
+                            },
+                            additionalProperties: false
+                        }
+                    },
+                    {
+                        name: 'get_system_stats',
+                        description: 'Get comprehensive system statistics including mode-specific metrics, performance data, and resource usage.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                include_performance: {
+                                    type: 'boolean',
+                                    description: 'Include performance metrics and timing data (default: false)',
+                                    default: false
+                                },
+                                include_content_breakdown: {
+                                    type: 'boolean',
+                                    description: 'Include breakdown of content by type (default: false)',
+                                    default: false
+                                }
+                            },
+                            additionalProperties: false
+                        }
+                    }
+                ],
+            };
+        });
+        // Handle tool calls
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case 'search':
+                        return await this.handleSearch(args);
+                    case 'ingest':
+                        return await this.handleIngest(args);
+                    case 'ingest_image':
+                        return await this.handleIngestImage(args);
+                    case 'rebuild_index':
+                        return await this.handleRebuildIndex(args);
+                    case 'get_stats':
+                        return await this.handleGetStats(args);
+                    case 'get_mode_info':
+                        return await this.handleGetModeInfo(args);
+                    case 'multimodal_search':
+                        return await this.handleMultimodalSearch(args);
+                    case 'list_supported_models':
+                        return await this.handleListSupportedModels(args);
+                    case 'list_reranking_strategies':
+                        return await this.handleListRerankingStrategies(args);
+                    case 'get_system_stats':
+                        return await this.handleGetSystemStats(args);
+                    default:
+                        throw new Error(`Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                };
+            }
+        });
+    }
+    /**
+     * Handle search tool calls
+     * Wraps existing search functionality as MCP tool
+     */
+    async handleSearch(args) {
+        try {
+            // Validate arguments
+            if (!args.query || typeof args.query !== 'string') {
+                throw new Error('Query parameter is required and must be a string');
+            }
+            if (args.query.trim().length === 0) {
+                throw new Error('Query cannot be empty');
+            }
+            if (args.query.length > 500) {
+                throw new Error('Query is too long (maximum 500 characters)');
+            }
+            // Validate optional parameters
+            if (args.top_k !== undefined) {
+                if (typeof args.top_k !== 'number' || args.top_k < 1 || args.top_k > 100) {
+                    throw new Error('top_k must be a number between 1 and 100');
+                }
+            }
+            if (args.rerank !== undefined && typeof args.rerank !== 'boolean') {
+                throw new Error('rerank must be a boolean');
+            }
+            // Check if database and index exist
+            if (!existsSync(config.db_file)) {
+                throw new Error('No database found. You need to ingest documents first using the ingest tool.');
+            }
+            if (!existsSync(config.index_file)) {
+                throw new Error('No vector index found. The ingestion may not have completed successfully. Try using the ingest tool or rebuild_index tool.');
+            }
+            // Initialize search engine if needed
+            if (!this.isSearchEngineInitialized) {
+                await this.initializeSearchEngine();
+            }
+            // Prepare search options
+            const searchOptions = {
+                top_k: args.top_k || config.top_k || 10,
+                rerank: args.rerank !== undefined ? args.rerank : config.rerank_enabled
+            };
+            // Perform search using existing search functionality
+            const startTime = Date.now();
+            const results = await this.searchEngine.search(args.query, searchOptions);
+            const searchTime = Date.now() - startTime;
+            // Format results for MCP response with proper image content support
+            const textResults = {
+                query: args.query,
+                results_count: results.length,
+                search_time_ms: searchTime,
+                results: results.map((result, index) => ({
+                    rank: index + 1,
+                    score: Math.round(result.score * 100) / 100,
+                    content_type: result.contentType,
+                    document: {
+                        id: result.document.id,
+                        title: result.document.title,
+                        source: result.document.source,
+                        content_type: result.document.contentType
+                    },
+                    text: result.content,
+                    metadata: result.metadata,
+                    // Reference to image content if applicable
+                    has_image: result.contentType === 'image' && !!result.document.contentId
+                }))
+            };
+            // Build MCP response content array
+            const responseContent = [
+                {
+                    type: 'text',
+                    text: JSON.stringify(textResults, null, 2)
+                }
+            ];
+            // Add proper MCP image content for each image result
+            for (const result of results) {
+                if (result.contentType === 'image' && result.document.contentId) {
+                    try {
+                        const imageData = await this.searchEngine.getContent(result.document.contentId, 'base64');
+                        const mimeType = getMimeTypeFromPath(result.document.source);
+                        responseContent.push({
+                            type: 'image',
+                            data: imageData,
+                            mimeType: mimeType,
+                            annotations: {
+                                audience: ['user'],
+                                priority: 0.8,
+                                title: result.document.title,
+                                source: result.document.source
+                            }
+                        });
+                    }
+                    catch (error) {
+                        // If image retrieval fails, log but don't fail the entire search
+                        console.error(`Failed to retrieve image for ${result.document.source}:`, error);
+                    }
+                }
+            }
+            return {
+                content: responseContent
+            };
+        }
+        catch (error) {
+            // Handle model mismatch errors specifically
+            if (error instanceof Error && error.message.includes('Model mismatch detected')) {
+                const modelMismatchError = {
+                    error: 'MODEL_MISMATCH',
+                    message: 'Cannot perform search due to model mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The embedding model configuration does not match the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check if the model mismatch is intentional',
+                            'If you want to use a different model, manually run the rebuild_index tool',
+                            'Verify your model configuration matches your indexing setup'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(modelMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Handle dimension mismatch errors
+            if (error instanceof Error && error.message.includes('dimension mismatch')) {
+                const dimensionMismatchError = {
+                    error: 'DIMENSION_MISMATCH',
+                    message: 'Cannot perform search due to vector dimension mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The vector dimensions do not match between the current model and the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check your model configuration',
+                            'If you want to change models, manually run the rebuild_index tool',
+                            'Ensure consistency between indexing and search models'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(dimensionMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Re-throw other errors to be handled by the main error handler
+            throw error;
+        }
+    }
+    /**
+     * Handle ingest tool calls
+     * Wraps existing ingestion functionality as MCP tool
+     */
+    async handleIngest(args) {
+        try {
+            // Validate arguments
+            if (!args.path || typeof args.path !== 'string') {
+                throw new Error('Path parameter is required and must be a string');
+            }
+            // Validate path exists
+            const resolvedPath = resolve(args.path);
+            if (!existsSync(resolvedPath)) {
+                throw new Error(`Path does not exist: ${args.path}`);
+            }
+            // Check if it's a file or directory and validate
+            let stats;
+            try {
+                stats = statSync(resolvedPath);
+            }
+            catch (error) {
+                throw new Error(`Cannot access path: ${args.path}. Check permissions.`);
+            }
+            // Validate mode parameter
+            const mode = args.mode || 'text';
+            // Validate file type for single files (only formats with actual processing implementations)
+            if (stats.isFile()) {
+                const textExtensions = ['.md', '.txt', '.mdx', '.pdf', '.docx'];
+                const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'];
+                const validExtensions = mode === 'multimodal'
+                    ? [...textExtensions, ...imageExtensions]
+                    : textExtensions;
+                const hasValidExtension = validExtensions.some(ext => args.path.toLowerCase().endsWith(ext));
+                if (!hasValidExtension) {
+                    const supportedTypes = mode === 'multimodal'
+                        ? '.md, .txt, .mdx, .pdf, .docx, .jpg, .jpeg, .png, .gif, .webp, .bmp'
+                        : '.md, .txt, .mdx, .pdf, .docx';
+                    throw new Error(`Unsupported file type: ${args.path}. Supported types: ${supportedTypes}`);
+                }
+            }
+            if (!['text', 'multimodal'].includes(mode)) {
+                throw new Error(`Invalid mode: ${mode}. Supported modes: text, multimodal`);
+            }
+            // Validate model parameter if provided
+            const supportedModels = [
+                'sentence-transformers/all-MiniLM-L6-v2',
+                'Xenova/all-mpnet-base-v2',
+                'Xenova/clip-vit-base-patch32',
+                'Xenova/clip-vit-base-patch16'
+            ];
+            if (args.model && !supportedModels.includes(args.model)) {
+                throw new Error(`Unsupported model: ${args.model}. Supported models: ${supportedModels.join(', ')}`);
+            }
+            // Validate model compatibility with mode
+            if (mode === 'text' && args.model) {
+                const textModels = ['sentence-transformers/all-MiniLM-L6-v2', 'Xenova/all-mpnet-base-v2'];
+                if (!textModels.includes(args.model)) {
+                    throw new Error(`Model ${args.model} is not compatible with text mode. Use: ${textModels.join(', ')}`);
+                }
+            }
+            if (mode === 'multimodal' && args.model) {
+                const multimodalModels = ['Xenova/clip-vit-base-patch32', 'Xenova/clip-vit-base-patch16'];
+                if (!multimodalModels.includes(args.model)) {
+                    throw new Error(`Model ${args.model} is not compatible with multimodal mode. Use: ${multimodalModels.join(', ')}`);
+                }
+            }
+            // Validate reranking strategy for multimodal mode
+            if (args.rerank_strategy) {
+                if (mode === 'text') {
+                    throw new Error('Reranking strategy parameter is only supported in multimodal mode');
+                }
+                const validStrategies = ['text-derived', 'disabled'];
+                if (!validStrategies.includes(args.rerank_strategy)) {
+                    throw new Error(`Invalid reranking strategy: ${args.rerank_strategy}. Supported strategies: ${validStrategies.join(', ')}`);
+                }
+            }
+            // Prepare factory options
+            const factoryOptions = {
+                mode: mode
+            };
+            if (args.model) {
+                factoryOptions.embeddingModel = args.model;
+            }
+            if (args.rerank_strategy && mode === 'multimodal') {
+                factoryOptions.rerankingStrategy = args.rerank_strategy;
+            }
+            if (args.force_rebuild) {
+                factoryOptions.forceRebuild = true;
+            }
+            // Create and run ingestion pipeline using text factory
+            // The IngestionFactory already supports mode and reranking strategy parameters
+            const pipeline = await IngestionFactory.create(config.db_file, config.index_file, factoryOptions);
+            try {
+                const result = await pipeline.ingestPath(resolvedPath);
+                // Reset search engine initialization flag since index may have changed
+                this.isSearchEngineInitialized = false;
+                this.searchEngine = null;
+                // Format results for MCP response
+                const ingestionSummary = {
+                    path: resolvedPath,
+                    path_type: stats.isDirectory() ? 'directory' : 'file',
+                    mode: mode,
+                    model: args.model || (mode === 'multimodal' ? 'Xenova/clip-vit-base-patch32' : 'sentence-transformers/all-MiniLM-L6-v2'),
+                    reranking_strategy: args.rerank_strategy || (mode === 'multimodal' ? 'text-derived' : 'cross-encoder'),
+                    documents_processed: result.documentsProcessed,
+                    chunks_created: result.chunksCreated,
+                    embeddings_generated: result.embeddingsGenerated,
+                    document_errors: result.documentErrors,
+                    embedding_errors: result.embeddingErrors,
+                    processing_time_ms: result.processingTimeMs,
+                    processing_time_seconds: Math.round(result.processingTimeMs / 1000 * 100) / 100,
+                    chunks_per_second: result.processingTimeMs > 0 ?
+                        Math.round(result.chunksCreated / (result.processingTimeMs / 1000) * 100) / 100 : 0,
+                    supported_file_types: mode === 'multimodal'
+                        ? ['md', 'txt', 'mdx', 'pdf', 'docx', 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp']
+                        : ['md', 'txt', 'mdx', 'pdf', 'docx'],
+                    success: true
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(ingestionSummary, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                await pipeline.cleanup();
+            }
+        }
+        catch (error) {
+            // Handle model mismatch errors specifically
+            if (error instanceof Error && error.message.includes('Model mismatch detected')) {
+                const modelMismatchError = {
+                    error: 'MODEL_MISMATCH',
+                    message: 'Cannot perform ingestion due to model mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The embedding model configuration does not match the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check if the model mismatch is intentional',
+                            'If you want to use a different model, manually run the rebuild_index tool',
+                            'Use force_rebuild: true parameter if you want to rebuild during ingestion',
+                            'Verify your model configuration matches your indexing setup'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(modelMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Handle dimension mismatch errors
+            if (error instanceof Error && error.message.includes('dimension mismatch')) {
+                const dimensionMismatchError = {
+                    error: 'DIMENSION_MISMATCH',
+                    message: 'Cannot perform ingestion due to vector dimension mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The vector dimensions do not match between the current model and the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check your model configuration',
+                            'If you want to change models, manually run the rebuild_index tool',
+                            'Use force_rebuild: true parameter if you want to rebuild during ingestion',
+                            'Ensure consistency between indexing and search models'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(dimensionMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Handle initialization errors that might contain model mismatch information
+            if (error instanceof Error && error.message.includes('Failed to initialize')) {
+                // Check if the underlying error is a model mismatch
+                if (error.message.includes('Model mismatch') || error.message.includes('dimension mismatch')) {
+                    const initializationError = {
+                        error: 'INITIALIZATION_FAILED',
+                        message: 'Cannot initialize ingestion due to model compatibility issues',
+                        details: error.message,
+                        resolution: {
+                            action: 'manual_intervention_required',
+                            explanation: 'The system cannot initialize due to model compatibility issues. Please verify your setup before proceeding.',
+                            options: [
+                                'Check your model configuration',
+                                'If you want to change models, manually run the rebuild_index tool',
+                                'Verify consistency between your indexing and search setup'
+                            ],
+                            warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                        }
+                    };
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(initializationError, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+            // Re-throw other errors to be handled by the main error handler
+            throw error;
+        }
+    }
+    /**
+     * Handle ingest image tool calls
+     * Specialized tool for ingesting images from local files or URLs
+     */
+    async handleIngestImage(args) {
+        try {
+            // Validate arguments
+            if (!args.source || typeof args.source !== 'string') {
+                throw new Error('Source parameter is required and must be a string (file path or URL)');
+            }
+            const source = args.source.trim();
+            if (source.length === 0) {
+                throw new Error('Source cannot be empty');
+            }
+            // Check if source is a URL or local file
+            const isUrl = source.startsWith('http://') || source.startsWith('https://');
+            let resolvedPath;
+            let isTemporaryFile = false;
+            let tempFilePath = null;
+            if (isUrl) {
+                // Download image from URL to temporary location
+                console.error(`📥 Downloading image from URL: ${source}`);
+                try {
+                    // Import required modules for URL download
+                    const https = await import('https');
+                    const http = await import('http');
+                    const { promises: fs } = await import('fs');
+                    const { join } = await import('path');
+                    const { tmpdir } = await import('os');
+                    const { randomBytes } = await import('crypto');
+                    // Generate temporary file path
+                    const tempDir = tmpdir();
+                    const randomName = randomBytes(16).toString('hex');
+                    const urlExt = source.split('.').pop()?.split('?')[0] || 'jpg';
+                    tempFilePath = join(tempDir, `mcp-image-${randomName}.${urlExt}`);
+                    // Download the image
+                    await new Promise((resolve, reject) => {
+                        const protocol = source.startsWith('https://') ? https : http;
+                        protocol.get(source, (response) => {
+                            if (response.statusCode === 301 || response.statusCode === 302) {
+                                // Handle redirects
+                                const redirectUrl = response.headers.location;
+                                if (redirectUrl) {
+                                    const redirectProtocol = redirectUrl.startsWith('https://') ? https : http;
+                                    redirectProtocol.get(redirectUrl, (redirectResponse) => {
+                                        if (redirectResponse.statusCode !== 200) {
+                                            reject(new Error(`Failed to download image: HTTP ${redirectResponse.statusCode}`));
+                                            return;
+                                        }
+                                        const fileStream = createWriteStream(tempFilePath);
+                                        redirectResponse.pipe(fileStream);
+                                        fileStream.on('finish', () => {
+                                            fileStream.close();
+                                            resolve();
+                                        });
+                                        fileStream.on('error', reject);
+                                    }).on('error', reject);
+                                }
+                            }
+                            else if (response.statusCode !== 200) {
+                                reject(new Error(`Failed to download image: HTTP ${response.statusCode}`));
+                                return;
+                            }
+                            else {
+                                const fileStream = createWriteStream(tempFilePath);
+                                response.pipe(fileStream);
+                                fileStream.on('finish', () => {
+                                    fileStream.close();
+                                    resolve();
+                                });
+                                fileStream.on('error', reject);
+                            }
+                        }).on('error', reject);
+                    });
+                    resolvedPath = tempFilePath;
+                    isTemporaryFile = true;
+                    console.error(`✅ Image downloaded to: ${tempFilePath}`);
+                }
+                catch (downloadError) {
+                    throw new Error(`Failed to download image from URL: ${downloadError instanceof Error ? downloadError.message : 'Unknown error'}`);
+                }
+            }
+            else {
+                // Local file path
+                resolvedPath = resolve(source);
+                if (!existsSync(resolvedPath)) {
+                    throw new Error(`Image file does not exist: ${source}`);
+                }
+                // Validate it's a file
+                try {
+                    const stats = statSync(resolvedPath);
+                    if (!stats.isFile()) {
+                        throw new Error(`Source is not a file: ${source}`);
+                    }
+                }
+                catch (error) {
+                    throw new Error(`Cannot access image file: ${source}. Check permissions.`);
+                }
+            }
+            // Validate image file extension
+            const validExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp'];
+            const hasValidExtension = validExtensions.some(ext => resolvedPath.toLowerCase().endsWith(ext));
+            if (!hasValidExtension) {
+                if (isTemporaryFile && tempFilePath) {
+                    // Clean up temp file
+                    try {
+                        const { promises: fs } = await import('fs');
+                        await fs.unlink(tempFilePath);
+                    }
+                    catch { }
+                }
+                throw new Error(`Unsupported image format. Supported formats: ${validExtensions.join(', ')}`);
+            }
+            // Prepare factory options for multimodal mode
+            const factoryOptions = {
+                mode: 'multimodal' // Always use multimodal mode for image ingestion
+            };
+            if (args.model) {
+                factoryOptions.embeddingModel = args.model;
+            }
+            else {
+                factoryOptions.embeddingModel = 'Xenova/clip-vit-base-patch32'; // Default CLIP model
+            }
+            if (args.rerank_strategy) {
+                factoryOptions.rerankingStrategy = args.rerank_strategy;
+            }
+            else {
+                factoryOptions.rerankingStrategy = 'text-derived'; // Default for multimodal
+            }
+            // Create and run ingestion pipeline
+            const pipeline = await IngestionFactory.create(config.db_file, config.index_file, factoryOptions);
+            try {
+                const result = await pipeline.ingestFile(resolvedPath);
+                // Reset search engine initialization flag since index may have changed
+                this.isSearchEngineInitialized = false;
+                this.searchEngine = null;
+                // Format results for MCP response
+                const ingestionSummary = {
+                    source: isUrl ? source : resolvedPath,
+                    source_type: isUrl ? 'url' : 'file',
+                    mode: 'multimodal',
+                    model: args.model || 'Xenova/clip-vit-base-patch32',
+                    reranking_strategy: args.rerank_strategy || 'text-derived',
+                    documents_processed: result.documentsProcessed,
+                    chunks_created: result.chunksCreated,
+                    embeddings_generated: result.embeddingsGenerated,
+                    document_errors: result.documentErrors,
+                    embedding_errors: result.embeddingErrors,
+                    processing_time_ms: result.processingTimeMs,
+                    processing_time_seconds: Math.round(result.processingTimeMs / 1000 * 100) / 100,
+                    content_type: 'image',
+                    title: args.title || (isUrl ? source.split('/').pop() : resolvedPath.split(/[/\\]/).pop()),
+                    metadata: args.metadata || {},
+                    success: true
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(ingestionSummary, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                await pipeline.cleanup();
+                // Clean up temporary file if it was downloaded
+                if (isTemporaryFile && tempFilePath) {
+                    try {
+                        const { promises: fs } = await import('fs');
+                        await fs.unlink(tempFilePath);
+                        console.error(`🧹 Cleaned up temporary file: ${tempFilePath}`);
+                    }
+                    catch (cleanupError) {
+                        console.error(`⚠️  Failed to clean up temporary file: ${cleanupError}`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Handle model mismatch errors specifically
+            if (error instanceof Error && error.message.includes('Model mismatch detected')) {
+                const modelMismatchError = {
+                    error: 'MODEL_MISMATCH',
+                    message: 'Cannot perform image ingestion due to model mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The embedding model configuration does not match the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check if the model mismatch is intentional',
+                            'If you want to use a different model, manually run the rebuild_index tool',
+                            'Verify your model configuration matches your indexing setup'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(modelMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Re-throw other errors to be handled by the main error handler
+            throw error;
+        }
+    }
+    /**
+     * Handle rebuild index tool calls
+     * Wraps existing rebuild functionality as MCP tool
+     */
+    async handleRebuildIndex(_args) {
+        try {
+            // Create ingestion pipeline with force rebuild using factory
+            const pipeline = await IngestionFactory.create(config.db_file, config.index_file, { forceRebuild: true });
+            try {
+                // Get all documents from database and re-ingest them - use shared connection
+                const db = await DatabaseConnectionManager.getConnection(config.db_file);
+                try {
+                    const documents = await db.all('SELECT DISTINCT source FROM documents ORDER BY source');
+                    if (documents.length === 0) {
+                        throw new Error('No documents found in database. Nothing to rebuild.');
+                    }
+                    let totalResult = {
+                        documentsProcessed: 0,
+                        chunksCreated: 0,
+                        embeddingsGenerated: 0,
+                        documentErrors: 0,
+                        embeddingErrors: 0,
+                        processingTimeMs: 0
+                    };
+                    // Re-ingest each document
+                    for (const doc of documents) {
+                        if (existsSync(doc.source)) {
+                            const result = await pipeline.ingestFile(doc.source);
+                            totalResult.documentsProcessed += result.documentsProcessed;
+                            totalResult.chunksCreated += result.chunksCreated;
+                            totalResult.embeddingsGenerated += result.embeddingsGenerated;
+                            totalResult.documentErrors += result.documentErrors;
+                            totalResult.embeddingErrors += result.embeddingErrors;
+                            totalResult.processingTimeMs += result.processingTimeMs;
+                        }
+                        else {
+                            totalResult.documentErrors++;
+                        }
+                    }
+                    // Reset search engine initialization flag since index was rebuilt
+                    this.isSearchEngineInitialized = false;
+                    this.searchEngine = null;
+                    const rebuildSummary = {
+                        operation: 'rebuild_index',
+                        success: true,
+                        message: 'Vector index has been successfully rebuilt. All embeddings have been regenerated with the current model.',
+                        documents_processed: totalResult.documentsProcessed,
+                        chunks_created: totalResult.chunksCreated,
+                        embeddings_generated: totalResult.embeddingsGenerated,
+                        document_errors: totalResult.documentErrors,
+                        embedding_errors: totalResult.embeddingErrors,
+                        processing_time_ms: totalResult.processingTimeMs,
+                        processing_time_seconds: Math.round(totalResult.processingTimeMs / 1000 * 100) / 100
+                    };
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(rebuildSummary, null, 2),
+                            },
+                        ],
+                    };
+                }
+                finally {
+                    // Release instead of close - keeps connection alive for reuse
+                    await DatabaseConnectionManager.releaseConnection(config.db_file);
+                }
+            }
+            finally {
+                await pipeline.cleanup();
+            }
+        }
+        catch (error) {
+            throw new Error(`Index rebuild failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Handle get stats tool calls
+     * Provides statistics about the current search index
+     */
+    async handleGetStats(_args) {
+        try {
+            const stats = {
+                database_exists: existsSync(config.db_file),
+                index_exists: existsSync(config.index_file),
+                search_engine_initialized: this.isSearchEngineInitialized
+            };
+            // Get model information and compatibility status
+            const { getModelDefaults } = await import('./config.js');
+            const currentModel = config.embedding_model;
+            const currentDefaults = getModelDefaults(currentModel);
+            stats.model_info = {
+                current_model: currentModel,
+                current_dimensions: currentDefaults.dimensions,
+                model_specific_config: {
+                    chunk_size: currentDefaults.chunk_size,
+                    chunk_overlap: currentDefaults.chunk_overlap,
+                    batch_size: currentDefaults.batch_size
+                }
+            };
+            // Check model compatibility if database exists
+            if (stats.database_exists) {
+                try {
+                    const db = await DatabaseConnectionManager.getConnection(config.db_file);
+                    try {
+                        const systemInfo = await getSystemInfo(db);
+                        if (systemInfo && systemInfo.modelName && systemInfo.modelDimensions) {
+                            stats.model_info.stored_model = systemInfo.modelName;
+                            stats.model_info.stored_dimensions = systemInfo.modelDimensions;
+                            // Check for compatibility issues
+                            const modelMatch = systemInfo.modelName === currentModel;
+                            const dimensionMatch = systemInfo.modelDimensions === currentDefaults.dimensions;
+                            stats.model_info.compatibility = {
+                                model_matches: modelMatch,
+                                dimensions_match: dimensionMatch,
+                                compatible: modelMatch && dimensionMatch
+                            };
+                            if (!stats.model_info.compatibility.compatible) {
+                                stats.model_info.compatibility.issue = 'Model mismatch detected - rebuild required';
+                                stats.model_info.compatibility.resolution = 'Run "npm run rebuild" to rebuild the index with the new model';
+                            }
+                        }
+                        else {
+                            stats.model_info.compatibility = {
+                                status: 'No stored model info - first run or needs rebuild'
+                            };
+                        }
+                        // Get basic database stats
+                        const docCount = await db.get('SELECT COUNT(*) as count FROM documents');
+                        const chunkCount = await db.get('SELECT COUNT(*) as count FROM chunks');
+                        stats.total_documents = docCount?.count || 0;
+                        stats.total_chunks = chunkCount?.count || 0;
+                    }
+                    finally {
+                        // Release instead of close - keeps connection alive for reuse
+                        await DatabaseConnectionManager.releaseConnection(config.db_file);
+                    }
+                }
+                catch (error) {
+                    stats.database_error = error instanceof Error ? error.message : 'Unknown error';
+                    stats.model_info.compatibility = {
+                        status: 'Error checking model compatibility',
+                        error: error instanceof Error ? error.message : 'Unknown error'
+                    };
+                }
+            }
+            else {
+                // No database exists - indicate this is a fresh setup
+                stats.model_info.compatibility = {
+                    status: 'No database exists - fresh setup, no compatibility issues'
+                };
+            }
+            // If search engine is initialized, get detailed stats
+            if (this.isSearchEngineInitialized && this.searchEngine) {
+                const searchStats = await this.searchEngine.getStats();
+                stats.total_chunks = searchStats.totalChunks;
+                stats.index_size = searchStats.indexSize;
+                stats.reranking_enabled = searchStats.rerankingEnabled;
+            }
+            // Show effective configuration (with model-specific defaults applied)
+            const effectiveConfig = {
+                db_file: config.db_file,
+                index_file: config.index_file,
+                embedding_model: config.embedding_model,
+                chunk_size: currentDefaults.chunk_size, // Use model-specific default
+                chunk_overlap: currentDefaults.chunk_overlap, // Use model-specific default
+                batch_size: currentDefaults.batch_size, // Use model-specific default
+                top_k: config.top_k,
+                rerank_enabled: config.rerank_enabled
+            };
+            stats.config = effectiveConfig;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(stats, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get stats: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Handle get mode info tool calls
+     * Provides information about the current system mode and configuration
+     */
+    async handleGetModeInfo(_args) {
+        try {
+            const modeInfo = {
+                database_exists: existsSync(config.db_file),
+                index_exists: existsSync(config.index_file)
+            };
+            if (!modeInfo.database_exists) {
+                modeInfo.mode_status = 'No database found - system not initialized';
+                modeInfo.default_mode = 'text';
+                modeInfo.message = 'Run ingestion first to initialize the system with a specific mode';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(modeInfo, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Import mode detection service
+            const { ModeDetectionService } = await import('./core/mode-detection-service.js');
+            const modeService = new ModeDetectionService(config.db_file);
+            try {
+                const systemInfo = await modeService.detectMode();
+                modeInfo.mode_status = 'Mode detected from database';
+                modeInfo.current_mode = systemInfo.mode;
+                modeInfo.model_name = systemInfo.modelName;
+                modeInfo.model_type = systemInfo.modelType;
+                modeInfo.model_dimensions = systemInfo.modelDimensions;
+                modeInfo.supported_content_types = systemInfo.supportedContentTypes;
+                modeInfo.reranking_strategy = systemInfo.rerankingStrategy;
+                if (systemInfo.rerankingModel) {
+                    modeInfo.reranking_model = systemInfo.rerankingModel;
+                }
+                if (systemInfo.rerankingConfig) {
+                    modeInfo.reranking_config = systemInfo.rerankingConfig;
+                }
+                modeInfo.created_at = systemInfo.createdAt;
+                modeInfo.updated_at = systemInfo.updatedAt;
+                // Add mode-specific capabilities
+                if (systemInfo.mode === 'text') {
+                    modeInfo.capabilities = {
+                        text_search: true,
+                        image_search: false,
+                        multimodal_reranking: false,
+                        supported_file_types: ['md', 'txt', 'mdx', 'pdf', 'docx']
+                    };
+                }
+                else if (systemInfo.mode === 'multimodal') {
+                    modeInfo.capabilities = {
+                        text_search: true,
+                        image_search: true,
+                        multimodal_reranking: true,
+                        supported_file_types: ['md', 'txt', 'mdx', 'pdf', 'docx', 'jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp']
+                    };
+                }
+            }
+            catch (error) {
+                modeInfo.mode_status = 'Error detecting mode from database';
+                modeInfo.error = error instanceof Error ? error.message : 'Unknown error';
+                modeInfo.fallback_mode = 'text';
+                modeInfo.message = 'System will fall back to text mode. Consider rebuilding the database.';
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(modeInfo, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get mode info: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Handle multimodal search tool calls with content type filtering
+     * Extends regular search with multimodal capabilities and content type filtering
+     */
+    async handleMultimodalSearch(args) {
+        try {
+            // Validate arguments (same as regular search)
+            if (!args.query || typeof args.query !== 'string') {
+                throw new Error('Query parameter is required and must be a string');
+            }
+            if (args.query.trim().length === 0) {
+                throw new Error('Query cannot be empty');
+            }
+            if (args.query.length > 500) {
+                throw new Error('Query is too long (maximum 500 characters)');
+            }
+            // Validate optional parameters
+            if (args.top_k !== undefined) {
+                if (typeof args.top_k !== 'number' || args.top_k < 1 || args.top_k > 100) {
+                    throw new Error('top_k must be a number between 1 and 100');
+                }
+            }
+            if (args.rerank !== undefined && typeof args.rerank !== 'boolean') {
+                throw new Error('rerank must be a boolean');
+            }
+            if (args.content_type !== undefined) {
+                const validContentTypes = ['text', 'image', 'pdf', 'docx'];
+                if (!validContentTypes.includes(args.content_type)) {
+                    throw new Error(`content_type must be one of: ${validContentTypes.join(', ')}`);
+                }
+            }
+            // Check if database and index exist
+            if (!existsSync(config.db_file)) {
+                throw new Error('No database found. You need to ingest documents first using the ingest tool.');
+            }
+            if (!existsSync(config.index_file)) {
+                throw new Error('No vector index found. The ingestion may not have completed successfully. Try using the ingest tool or rebuild_index tool.');
+            }
+            // Initialize search engine if needed
+            if (!this.isSearchEngineInitialized) {
+                await this.initializeSearchEngine();
+            }
+            // Prepare search options with content type filtering
+            const searchOptions = {
+                top_k: args.top_k || config.top_k || 10,
+                rerank: args.rerank !== undefined ? args.rerank : config.rerank_enabled,
+                contentType: args.content_type // Add content type filtering
+            };
+            // Perform search using existing search functionality
+            const startTime = Date.now();
+            const results = await this.searchEngine.search(args.query, searchOptions);
+            const searchTime = Date.now() - startTime;
+            // Format results for MCP response with proper image content support
+            const textResults = {
+                query: args.query,
+                content_type_filter: args.content_type || 'all',
+                results_count: results.length,
+                search_time_ms: searchTime,
+                results: results.map((result, index) => ({
+                    rank: index + 1,
+                    score: Math.round(result.score * 100) / 100,
+                    content_type: result.contentType,
+                    document: {
+                        id: result.document.id,
+                        title: result.document.title,
+                        source: result.document.source,
+                        content_type: result.document.contentType
+                    },
+                    text: result.content,
+                    metadata: result.metadata,
+                    // Reference to image content if applicable
+                    has_image: result.contentType === 'image' && !!result.document.contentId
+                }))
+            };
+            // Build MCP response content array
+            const responseContent = [
+                {
+                    type: 'text',
+                    text: JSON.stringify(textResults, null, 2)
+                }
+            ];
+            // Add proper MCP image content for each image result
+            for (const result of results) {
+                if (result.contentType === 'image' && result.document.contentId) {
+                    try {
+                        const imageData = await this.searchEngine.getContent(result.document.contentId, 'base64');
+                        const mimeType = getMimeTypeFromPath(result.document.source);
+                        responseContent.push({
+                            type: 'image',
+                            data: imageData,
+                            mimeType: mimeType,
+                            annotations: {
+                                audience: ['user'],
+                                priority: 0.8,
+                                title: result.document.title,
+                                source: result.document.source
+                            }
+                        });
+                    }
+                    catch (error) {
+                        // If image retrieval fails, log but don't fail the entire search
+                        console.error(`Failed to retrieve image for ${result.document.source}:`, error);
+                    }
+                }
+            }
+            return {
+                content: responseContent
+            };
+        }
+        catch (error) {
+            // Handle the same errors as regular search
+            if (error instanceof Error && error.message.includes('Model mismatch detected')) {
+                const modelMismatchError = {
+                    error: 'MODEL_MISMATCH',
+                    message: 'Cannot perform multimodal search due to model mismatch',
+                    details: error.message,
+                    resolution: {
+                        action: 'manual_intervention_required',
+                        explanation: 'The embedding model configuration does not match the indexed data. Please verify your setup before proceeding.',
+                        options: [
+                            'Check if the model mismatch is intentional',
+                            'If you want to use a different model, manually run the rebuild_index tool',
+                            'Verify your model configuration matches your indexing setup'
+                        ],
+                        warning: 'Rebuilding will regenerate all embeddings and may take significant time'
+                    }
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(modelMismatchError, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Re-throw other errors to be handled by the main error handler
+            throw error;
+        }
+    }
+    /**
+     * Handle list supported models tool calls
+     * Lists all supported embedding models with their capabilities
+     */
+    async handleListSupportedModels(args) {
+        try {
+            // Import model registry
+            const { ModelRegistry } = await import('./core/model-registry.js');
+            const { getSupportedModelsForContentType } = await import('./core/embedder-factory.js');
+            let models;
+            // Filter by model type if specified
+            if (args.model_type) {
+                models = ModelRegistry.getSupportedModels(args.model_type);
+            }
+            else if (args.content_type) {
+                // Filter by content type if specified
+                models = getSupportedModelsForContentType(args.content_type);
+            }
+            else {
+                // Get all models
+                models = ModelRegistry.getSupportedModels();
+            }
+            // Get detailed information for each model
+            const modelDetails = models.map(modelName => {
+                const info = ModelRegistry.getModelInfo(modelName);
+                return {
+                    name: modelName,
+                    type: info?.type,
+                    dimensions: info?.dimensions,
+                    supported_content_types: info?.supportedContentTypes || [],
+                    memory_requirement: info?.requirements?.minimumMemory,
+                    description: `${info?.type} model for ${info?.supportedContentTypes?.join(', ')} content`,
+                    is_default: ModelRegistry.getDefaultModel(info?.type) === modelName,
+                    capabilities: {
+                        supports_text: info?.capabilities?.supportsText || false,
+                        supports_images: info?.capabilities?.supportsImages || false,
+                        supports_batch_processing: info?.capabilities?.supportsBatchProcessing || false,
+                        max_batch_size: info?.capabilities?.maxBatchSize,
+                        max_text_length: info?.capabilities?.maxTextLength,
+                        supported_image_formats: info?.capabilities?.supportedImageFormats || []
+                    },
+                    requirements: {
+                        transformers_js_version: info?.requirements?.transformersJsVersion,
+                        minimum_memory_mb: info?.requirements?.minimumMemory,
+                        required_features: info?.requirements?.requiredFeatures || [],
+                        platform_support: info?.requirements?.platformSupport || []
+                    }
+                };
+            });
+            const response = {
+                filter_applied: {
+                    model_type: args.model_type || 'all',
+                    content_type: args.content_type || 'all'
+                },
+                total_models: modelDetails.length,
+                models: modelDetails,
+                model_types: {
+                    'sentence-transformer': 'Text-only embedding models optimized for semantic similarity',
+                    'clip': 'Multimodal models supporting both text and image embeddings'
+                },
+                usage_examples: {
+                    text_only: 'Use sentence-transformer models for text documents, markdown files, and text-based search',
+                    multimodal: 'Use CLIP models when working with mixed content including images, diagrams, and visual content'
+                }
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to list supported models: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Handle list reranking strategies tool calls
+     * Lists all supported reranking strategies for different modes
+     */
+    async handleListRerankingStrategies(args) {
+        try {
+            // Import reranking configuration
+            const { getSupportedStrategies, getDefaultRerankingConfig } = await import('./core/reranking-config.js');
+            const modes = args.mode ? [args.mode] : ['text', 'multimodal'];
+            const strategiesByMode = {};
+            for (const mode of modes) {
+                const supportedStrategies = getSupportedStrategies(mode);
+                const defaultConfig = getDefaultRerankingConfig(mode);
+                strategiesByMode[mode] = {
+                    default_strategy: defaultConfig.strategy,
+                    mode_description: mode === 'text'
+                        ? 'Text-only mode optimized for document and text-based content'
+                        : 'Multimodal mode supporting mixed text and image content',
+                    supported_strategies: supportedStrategies.map(strategy => {
+                        const strategyInfo = {
+                            name: strategy,
+                            is_default: strategy === defaultConfig.strategy,
+                            performance_impact: 'medium'
+                        };
+                        // Add descriptions for each strategy
+                        switch (strategy) {
+                            case 'cross-encoder':
+                                strategyInfo.description = 'Uses cross-encoder models to rerank results based on query-document relevance';
+                                strategyInfo.requirements = ['Cross-encoder model (e.g., ms-marco-MiniLM-L-6-v2)'];
+                                strategyInfo.supported_content_types = ['text'];
+                                strategyInfo.performance_impact = 'high';
+                                strategyInfo.accuracy = 'high';
+                                strategyInfo.use_cases = ['Text documents', 'Academic papers', 'Technical documentation'];
+                                break;
+                            case 'text-derived':
+                                strategyInfo.description = 'Converts images to text descriptions using image-to-text models, then applies cross-encoder reranking';
+                                strategyInfo.requirements = ['Image-to-text model (e.g., vit-gpt2-image-captioning)', 'Cross-encoder model'];
+                                strategyInfo.supported_content_types = ['text', 'image'];
+                                strategyInfo.performance_impact = 'high';
+                                strategyInfo.accuracy = 'high';
+                                strategyInfo.use_cases = ['Mixed content with images', 'Visual documentation', 'Diagrams and charts'];
+                                break;
+                            case 'disabled':
+                                strategyInfo.description = 'No reranking applied - results ordered by vector similarity scores only';
+                                strategyInfo.requirements = ['None'];
+                                strategyInfo.supported_content_types = ['text', 'image', 'pdf', 'docx'];
+                                strategyInfo.performance_impact = 'none';
+                                strategyInfo.accuracy = 'baseline';
+                                strategyInfo.use_cases = ['Maximum performance', 'Simple similarity search', 'Development/testing'];
+                                break;
+                        }
+                        return strategyInfo;
+                    })
+                };
+            }
+            const response = {
+                filter_applied: {
+                    mode: args.mode || 'all'
+                },
+                strategies_by_mode: strategiesByMode,
+                recommendations: {
+                    text_mode: 'Use cross-encoder for best accuracy, disabled for best performance',
+                    multimodal_mode: 'Use text-derived for best accuracy, disabled for best performance',
+                    development: 'Start with disabled for fast iteration, upgrade to cross-encoder/text-derived for production'
+                }
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to list reranking strategies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Handle get system stats tool calls with mode-specific metrics
+     * Provides comprehensive system statistics including mode-specific data
+     */
+    async handleGetSystemStats(args) {
+        try {
+            // Start with basic stats from existing get_stats handler
+            const basicStats = await this.handleGetStats({});
+            const basicStatsData = JSON.parse(basicStats.content[0].text);
+            // Enhanced stats with mode-specific information
+            const enhancedStats = {
+                ...basicStatsData,
+                mode_specific_metrics: {}
+            };
+            // Add mode detection information
+            if (basicStatsData.database_exists) {
+                try {
+                    const { ModeDetectionService } = await import('./core/mode-detection-service.js');
+                    const modeService = new ModeDetectionService(config.db_file);
+                    const systemInfo = await modeService.detectMode();
+                    enhancedStats.mode_specific_metrics = {
+                        current_mode: systemInfo.mode,
+                        model_name: systemInfo.modelName,
+                        model_type: systemInfo.modelType,
+                        model_dimensions: systemInfo.modelDimensions,
+                        supported_content_types: systemInfo.supportedContentTypes,
+                        reranking_strategy: systemInfo.rerankingStrategy
+                    };
+                    // Add content breakdown if requested
+                    if (args.include_content_breakdown) {
+                        const db = await DatabaseConnectionManager.getConnection(config.db_file);
+                        try {
+                            // Get document count by content type
+                            const docsByType = await db.all(`
+                SELECT content_type, COUNT(*) as count 
+                FROM documents 
+                GROUP BY content_type
+              `);
+                            // Get chunk count by content type
+                            const chunksByType = await db.all(`
+                SELECT content_type, COUNT(*) as count 
+                FROM chunks 
+                GROUP BY content_type
+              `);
+                            enhancedStats.content_breakdown = {
+                                documents_by_type: docsByType.reduce((acc, row) => {
+                                    acc[row.content_type] = row.count;
+                                    return acc;
+                                }, {}),
+                                chunks_by_type: chunksByType.reduce((acc, row) => {
+                                    acc[row.content_type] = row.count;
+                                    return acc;
+                                }, {})
+                            };
+                        }
+                        finally {
+                            // Release instead of close - keeps connection alive for reuse
+                            await DatabaseConnectionManager.releaseConnection(config.db_file);
+                        }
+                    }
+                    // Add performance metrics if requested
+                    if (args.include_performance && this.isSearchEngineInitialized && this.searchEngine) {
+                        const searchStats = await this.searchEngine.getStats();
+                        enhancedStats.performance_metrics = {
+                            search_engine_initialized: true,
+                            index_size: searchStats.indexSize,
+                            reranking_enabled: searchStats.rerankingEnabled,
+                            total_chunks: searchStats.totalChunks,
+                            // Add timing information if available
+                            last_search_time_ms: undefined, // Would need to track this
+                            average_search_time_ms: undefined // Would need to track this
+                        };
+                    }
+                }
+                catch (error) {
+                    enhancedStats.mode_specific_metrics.error = error instanceof Error ? error.message : 'Unknown error';
+                }
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(enhancedStats, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get system stats: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Initialize search engine components using factory
+     * Lazy initialization to avoid startup overhead when not needed
+     */
+    async initializeSearchEngine() {
+        if (this.isSearchEngineInitialized) {
+            return;
+        }
+        try {
+            // Validate configuration
+            validateCoreConfig(config);
+            // Create search engine using SearchFactory (auto-detects mode)
+            // This will automatically detect the mode from the database and create the appropriate engine
+            console.error('🎭 MCP Server: Initializing search engine with automatic mode detection...');
+            this.searchEngine = await SearchFactory.create(config.index_file, config.db_file);
+            // Log successful initialization with mode information
+            const stats = await this.searchEngine.getStats();
+            // Try to get mode information for enhanced logging
+            try {
+                const { ModeDetectionService } = await import('./core/mode-detection-service.js');
+                const modeService = new ModeDetectionService(config.db_file);
+                const systemInfo = await modeService.detectMode();
+                console.error(`✅ MCP Server: Search engine initialized successfully`);
+                console.error(`🎭 Mode: ${systemInfo.mode} | Model: ${systemInfo.modelName}`);
+                console.error(`📊 Total chunks: ${stats.totalChunks} | Reranking: ${stats.rerankingEnabled ? 'enabled' : 'disabled'}`);
+                console.error(`🔧 Content types: ${systemInfo.supportedContentTypes.join(', ')}`);
+                if (systemInfo.mode === 'multimodal') {
+                    console.error(`🌈 Multimodal capabilities: Text + Image processing enabled`);
+                    console.error(`⚡ Reranking strategy: ${systemInfo.rerankingStrategy}`);
+                }
+            }
+            catch (modeError) {
+                // Fallback to basic logging if mode detection fails
+                console.error(`✅ MCP Server: Search engine initialized successfully`);
+                console.error(`📊 Total chunks: ${stats.totalChunks}, Reranking: ${stats.rerankingEnabled ? 'enabled' : 'disabled'}`);
+                console.error(`⚠️  Mode detection unavailable: ${modeError instanceof Error ? modeError.message : 'Unknown error'}`);
+            }
+            this.isSearchEngineInitialized = true;
+        }
+        catch (error) {
+            console.error('❌ MCP Server: Search engine initialization failed');
+            console.error(`❌ Error: ${error instanceof Error ? error.message : String(error)}`);
+            // Check if this is a mode detection error
+            if (error instanceof Error && error.message.includes('mode detection')) {
+                console.error('⚠️  MCP Server: Mode detection failed, falling back to text mode');
+                throw new Error(`Mode detection failed: ${error.message}. The system will attempt to fall back to text mode.`);
+            }
+            // Check if this is a model mismatch error and re-throw with more context
+            if (error instanceof Error && (error.message.includes('Model mismatch detected') || error.message.includes('dimension mismatch'))) {
+                console.error('⚠️  MCP Server: Model compatibility issue detected');
+                // Re-throw the original error - it already has good formatting from factory
+                throw error;
+            }
+            // For other initialization errors, provide a generic wrapper
+            throw new Error(`Failed to initialize search engine: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Detect capabilities of the current database
+     * Returns information about mode, content types, and features
+     */
+    async detectCapabilities() {
+        // Default capabilities if database doesn't exist
+        if (!existsSync(config.db_file)) {
+            return {
+                mode: 'unknown',
+                contentTypes: [],
+                modelName: 'none',
+                hasImages: false,
+                documentCount: 0
+            };
+        }
+        try {
+            const { ModeDetectionService } = await import('./core/mode-detection-service.js');
+            const modeService = new ModeDetectionService(config.db_file);
+            const systemInfo = await modeService.detectMode();
+            // Check if database has any images - use shared connection
+            const db = await DatabaseConnectionManager.getConnection(config.db_file);
+            let hasImages = false;
+            let documentCount = 0;
+            try {
+                const imageCount = await db.get("SELECT COUNT(*) as count FROM documents WHERE content_type = 'image'");
+                hasImages = (imageCount?.count || 0) > 0;
+                const docCount = await db.get('SELECT COUNT(*) as count FROM documents');
+                documentCount = docCount?.count || 0;
+            }
+            finally {
+                // Release instead of close - keeps connection alive for reuse
+                await DatabaseConnectionManager.releaseConnection(config.db_file);
+            }
+            return {
+                mode: systemInfo.mode,
+                contentTypes: systemInfo.supportedContentTypes,
+                modelName: systemInfo.modelName,
+                hasImages,
+                documentCount
+            };
+        }
+        catch (error) {
+            // If detection fails, return unknown
+            return {
+                mode: 'unknown',
+                contentTypes: [],
+                modelName: 'unknown',
+                hasImages: false,
+                documentCount: 0
+            };
+        }
+    }
+    /**
+     * Generate dynamic search tool description based on actual capabilities
+     */
+    generateSearchDescription(capabilities) {
+        const baseDesc = 'Search indexed documents using semantic similarity.';
+        if (capabilities.mode === 'unknown' || capabilities.documentCount === 0) {
+            return `${baseDesc} Database not initialized - ingest documents first.`;
+        }
+        if (capabilities.mode === 'text') {
+            return `[TEXT MODE] ${baseDesc} This database contains ${capabilities.documentCount} text documents. Supports .md and .txt files only.`;
+        }
+        if (capabilities.mode === 'multimodal') {
+            const imageInfo = capabilities.hasImages
+                ? 'Contains both text and image content. Image results include base64-encoded data for display.'
+                : 'Configured for multimodal but currently contains only text.';
+            return `[MULTIMODAL MODE] ${baseDesc} This database contains ${capabilities.documentCount} documents. ${imageInfo} Supports cross-modal search (text queries can find images).`;
+        }
+        return baseDesc;
+    }
+    /**
+     * Cleanup MCP server resources
+     * Closes database connections and cleans up search engine
+     */
+    async cleanup() {
+        console.error('🧹 MCP Server: Cleaning up resources...');
+        try {
+            if (this.searchEngine) {
+                await this.searchEngine.cleanup();
+                this.searchEngine = null;
+                this.isSearchEngineInitialized = false;
+            }
+            // Close all database connections
+            await DatabaseConnectionManager.closeAllConnections();
+            console.error('✅ MCP Server: Cleanup completed successfully');
+        }
+        catch (error) {
+            console.error('⚠️  MCP Server: Error during cleanup:', error);
+        }
+    }
+    /**
+     * Start the MCP server
+     * Ensures MCP server lives in same package as CLI with dual entry points
+     */
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        // Server will run until the transport is closed
+        console.error('RAG-lite TS MCP Server started successfully');
+    }
+}
+// Global server instance for cleanup
+let globalServer = null;
+/**
+ * Main entry point for MCP server
+ * Implements MCP protocol interface without creating REST/GraphQL endpoints
+ */
+async function main() {
+    try {
+        globalServer = new RagLiteMCPServer();
+        await globalServer.start();
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError) {
+            console.error('Configuration Error:', error.message);
+            process.exit(error.exitCode);
+        }
+        else {
+            console.error('Failed to start MCP server:', error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    }
+}
+// Handle process signals for graceful shutdown
+process.on('SIGINT', async () => {
+    console.error('Received SIGINT, shutting down gracefully...');
+    if (globalServer) {
+        await globalServer.cleanup();
+    }
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    console.error('Received SIGTERM, shutting down gracefully...');
+    if (globalServer) {
+        await globalServer.cleanup();
+    }
+    process.exit(0);
+});
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, _promise) => {
+    console.error('Unhandled Promise Rejection:', reason);
+    process.exit(1);
+});
+// Handle uncaught exceptions
+process.on('uncaughtException', (error) => {
+    console.error('Uncaught Exception:', error.message);
+    process.exit(1);
+});
+// Start the server
+main().catch((error) => {
+    console.error('Fatal error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+/**
+ * MCP Server Multimodal Integration Complete
+ *
+ * This implementation addresses task 9.3 requirements:
+ * ✅ Updated MCP server configuration to support multimodal parameters
+ * ✅ Added new MCP tools for mode configuration and multimodal search
+ * ✅ Integrated with polymorphic runtime system and mode detection
+ * ✅ Enhanced error handling for multimodal-specific errors
+ * ✅ Created comprehensive documentation and examples
+ * ✅ Added support for content type filtering and model selection
+ * ✅ Implemented reranking strategy configuration
+ * ✅ Provided detailed system information and statistics tools
+ *
+ * Key Features Added:
+ * - Multimodal ingestion with mode and model parameters
+ * - Content type filtering in search operations
+ * - Comprehensive model and strategy information tools
+ * - Enhanced error handling with recovery guidance
+ * - Automatic mode detection and polymorphic behavior
+ * - Detailed documentation and configuration examples
+ */ 
+//# sourceMappingURL=mcp-server.js.map