MkDocs MCP Search Server

# Implementation Plan - [x] 1. Enhance version management infrastructure - Create enhanced VersionManager class with robust version resolution and alias handling - Implement comprehensive error types for version-related failures - Add version validation methods that return detailed resolution results - _Requirements: 3.1, 3.2, 5.2, 5.3_ - [x] 1.1 Create enhanced VersionManager class - Write VersionManager class with detectVersioning, fetchVersions, and resolveVersion methods - Implement alias resolution logic that maps version aliases to actual version identifiers - Add caching for version detection results and version file data - _Requirements: 3.1, 3.2, 3.3_ - [x] 1.2 Implement version-specific error types - Create VersionNotFoundError class with requestedVersion and availableVersions properties - Create VersionDetectionError class with baseUrl and cause properties - Add IndexLoadError class for search index loading failures - _Requirements: 5.2, 5.3_ - [x] 1.3 Add version validation and resolution methods - Implement resolveVersion method that handles aliases, latest resolution, and validation - Add getAvailableVersions method with caching and error handling - Create buildVersionedUrl method that constructs correct URLs based on version detection - _Requirements: 3.1, 3.2, 3.4_ - [x] 1.4 Write unit tests for VersionManager - Create tests for version detection with and without versions.json - Test alias resolution and latest version determination - Test error scenarios and fallback behavior - _Requirements: 3.1, 3.2, 5.1, 5.2_ - [x] 2. Implement advanced caching system - Create IndexCache class with LRU eviction and memory management - Add concurrent access control to prevent duplicate index loading - Implement cache statistics and monitoring capabilities - _Requirements: 4.1, 4.2, 4.3_ - [x] 2.1 Create IndexCache class with LRU eviction - Write IndexCache class with get, set, has, delete, and clear methods - Implement LRU eviction algorithm that removes least-recently-used indexes when memory limits are exceeded - Add configurable cache options for maxSize, maxMemoryMB, and ttlMinutes - _Requirements: 4.1, 4.2_ - [x] 2.2 Add concurrent access control - Implement loading locks to prevent duplicate index loading for the same version - Add promise-based coordination for concurrent requests to the same version - Create cache key strategy for versioned and non-versioned sites - _Requirements: 4.3_ - [x] 2.3 Implement cache statistics and monitoring - Add getStats method that returns cache hit/miss ratios, memory usage, and eviction counts - Implement memory usage tracking for loaded indexes - Add cache performance logging for debugging and optimization - _Requirements: 4.1, 4.2_ - [x] 2.4 Write unit tests for IndexCache - Test LRU eviction behavior with various cache sizes - Test concurrent access scenarios and loading coordination - Test memory management and statistics tracking - _Requirements: 4.1, 4.2, 4.3_ - [x] 3. Create enhanced index loading system - Implement IndexLoader class with retry logic and error handling - Add loading coordination to prevent duplicate fetches - Implement exponential backoff for network failures - _Requirements: 1.1, 1.2, 4.3, 5.4_ - [x] 3.1 Implement IndexLoader class with retry logic - Write IndexLoader class with loadIndex method that handles version-specific index loading - Implement exponential backoff retry logic for network failures (3 attempts maximum) - Add detailed error reporting that includes available versions on failure - _Requirements: 1.1, 1.2, 5.4_ - [x] 3.2 Add loading coordination and duplicate prevention - Implement isLoading and getLoadingPromise methods to track in-progress loads - Add promise-based coordination to prevent multiple simultaneous loads of the same index - Create loading state management for concurrent requests - _Requirements: 4.3_ - [x] 3.3 Enhance error handling and recovery - Implement comprehensive error handling for malformed version files and missing indexes - Add fallback logic that switches to non-versioned behavior when version detection fails - Create detailed error messages that include troubleshooting information - _Requirements: 5.1, 5.2, 5.4_ - [x] 3.4 Write unit tests for IndexLoader - Test retry logic and exponential backoff behavior - Test loading coordination and duplicate prevention - Test error handling and recovery scenarios - _Requirements: 1.1, 1.2, 4.3, 5.4_ - [x] 4. Integrate components into enhanced SearchIndexFactory - Refactor SearchIndexFactory to use new VersionManager, IndexCache, and IndexLoader - Update getSearchIndex method to handle version-aware loading and caching - Maintain backward compatibility with existing API - _Requirements: 1.1, 1.2, 1.3, 2.1, 2.2_ - [x] 4.1 Refactor SearchIndexFactory constructor and dependencies - Update SearchIndexFactory constructor to instantiate VersionManager, IndexCache, and IndexLoader - Add SearchIndexOptions interface for configurable cache and retry settings - Maintain existing constructor signature for backward compatibility - _Requirements: 1.1, 4.1_ - [x] 4.2 Update getSearchIndex method for version-aware operation - Modify getSearchIndex to use VersionManager for version resolution - Implement cache-first lookup with IndexCache before loading new indexes - Add proper error handling that returns detailed version information on failures - _Requirements: 1.1, 1.2, 1.3, 2.1, 2.2_ - [x] 4.3 Add new public methods for version management - Implement resolveVersion method that exposes version validation and resolution - Add clearCache method for cache management and testing - Create getAvailableVersions method that returns cached or fresh version data - _Requirements: 3.1, 3.2, 4.1_ - [x] 4.4 Ensure backward compatibility - Verify existing getIndex method continues to work for legacy code - Test that non-versioned sites continue to work without changes - Ensure existing error handling behavior is preserved - _Requirements: 2.1, 2.2, 2.3_ - [x] 4.5 Write integration tests for SearchIndexFactory - Test end-to-end version resolution and index loading - Test cache behavior with multiple versions and eviction scenarios - Test error scenarios and backward compatibility - _Requirements: 1.1, 1.2, 2.1, 2.2, 4.1_ - [x] 5. Update search tool to use enhanced version capabilities - Modify searchMkDoc tool to handle version resolution errors gracefully - Add better error messages that include available versions - Update error handling to provide actionable feedback to users - _Requirements: 1.3, 5.2, 5.3_ - [x] 5.1 Update searchMkDoc error handling - Modify searchMkDoc to catch VersionNotFoundError and return available versions - Add handling for VersionDetectionError with appropriate fallback behavior - Improve error messages to be more user-friendly and actionable - _Requirements: 1.3, 5.2, 5.3_ - [x] 5.2 Add version validation in search requests - Implement version parameter validation before attempting search - Add early validation that returns helpful error messages for invalid versions - Update search response format to include version resolution information - _Requirements: 1.3, 3.1, 5.3_ - [x] 5.3 Write integration tests for search tool - Test search tool with valid and invalid version parameters - Test error handling and user-friendly error messages - Test search functionality across different versions - _Requirements: 1.1, 1.3, 5.2, 5.3_ - [x] 6. Add comprehensive error handling and logging - Enhance logging throughout the version-aware system - Add performance monitoring and cache statistics logging - Implement proper error propagation and user feedback - _Requirements: 5.1, 5.2, 5.3, 5.4_ - [x] 6.1 Enhance logging and monitoring - Add structured logging for version detection, resolution, and index loading operations - Implement performance logging for cache hit/miss ratios and load times - Add debug logging for troubleshooting version-related issues - _Requirements: 5.1, 5.4_ - [x] 6.2 Implement comprehensive error propagation - Ensure all version-related errors include sufficient context for debugging - Add error correlation IDs for tracking issues across components - Implement proper error serialization for API responses - _Requirements: 5.2, 5.3_ - [x] 6.3 Write end-to-end tests - Create tests that simulate real MkDocs sites with and without versioning - Test complete error scenarios from search request to error response - Test performance under various load conditions and cache scenarios - _Requirements: 1.1, 2.1, 4.1, 5.1_