Specialized AI Search Tools

# 📋 Plan Wdrożenia MCP Server - Specialized AI Search Tools > Plan wdrożenia oparty na założeniach projektowych, architekturze MCP i wymaganiach funkcjonalnych z README.md --- ## 🎯 Założenia Projektowe ### Kluczowe Cele - ✅ **Standardyzacja Integracji**: Jednolity protokół MCP dla wszystkich narzędzi - ✅ **Modularność**: Niezależne moduły łatwe do dodawania/usuwania - ✅ **Bezpieczeństwo**: Kontrola dostępu, walidacja danych, rate limiting - ✅ **Elastyczność**: Obsługa STDIO i HTTP+SSE transportów - ✅ **Wydajność**: Multi-layer caching, request optimization, circuit breaker ### Architektura MCP - **Tools**: Funkcje wykonywane przez AI (wyszukiwanie, konwersja, scraping) - **Resources**: Dane dostępne dla AI (opcjonalnie w przyszłości) - **Prompts**: Szablony promptów (opcjonalnie w przyszłości) --- ## 📦 FAZA 1: Core Infrastructure ### 1.1 Struktura Projektu - [x] Utworzenie struktury katalogów zgodnie z dokumentacją - [x] `src/index.ts` - Entry point - [x] `src/server.ts` - MCP Server setup - [x] `src/tools/` - Katalog narzędzi - [x] `src/types/` - TypeScript types - [x] `src/utils/` - Utilities (logger, cache, validators) - [x] `tests/` - Testy - [x] `examples/` - Przykłady konfiguracji ### 1.2 Bazowa Klasa Narzędzi - [x] Implementacja `BaseTool` w `src/tools/base.ts` - [x] Abstract properties: `name`, `description`, `schema` - [x] Abstract method: `execute(params)` - [x] Walidacja parametrów z użyciem Zod - [x] Error handling wrapper - [x] Logging integration ### 1.3 System Walidacji - [x] Integracja Zod do walidacji schematów - [x] TypeScript types dla wszystkich narzędzi - [x] Error messages w języku angielskim - [x] Walidacja parametrów przed wykonaniem ### 1.4 Logging System - [x] Implementacja loggera w `src/utils/logger.ts` - [x] Poziomy logowania (debug, info, warn, error) - [x] Formatowanie logów - [ ] Opcjonalne logowanie do pliku - [ ] Context tracking (tool name, request ID) ### 1.5 MCP Server Setup - [x] Instalacja `@modelcontextprotocol/sdk` - [x] Konfiguracja serwera MCP w `src/server.ts` - [x] STDIO transport (podstawowy) - [x] Rejestracja narzędzi - [x] Error handling - [x] Lifecycle management ### 1.6 TypeScript Configuration - [x] Konfiguracja `tsconfig.json` - [x] ES modules support - [x] Strict mode - [ ] Path aliases (opcjonalnie) - [x] Output configuration ### 1.7 Development Environment - [x] Konfiguracja ESLint - [x] Konfiguracja Prettier - [x] Skrypty npm (dev, build, start, test) - [x] `.env.example` template - [x] `.gitignore` configuration --- ## 🔍 FAZA 2: Basic Search Tools ### 2.1 General Web Search Tool - [ ] Implementacja `src/tools/websearch.ts` - [ ] Schemat parametrów (query, engine, filters, sortBy, limit) - [ ] Obsługa silników: Google, Bing, DuckDuckGo, Brave Search - [ ] Filtry: fileType, language, region, dateRange, domain, exactPhrase - [ ] Normalizacja wyników do wspólnego formatu - [ ] Error handling dla każdego silnika ### 2.2 WebFetch Tool - [ ] Implementacja `src/tools/webfetch.ts` - [ ] Pobieranie HTML z URL (axios) - [ ] Parsowanie z Cheerio - [ ] Ekstrakcja: tekst, nagłówki, linki, metadane, obrazy - [ ] Obsługa selektorów CSS - [ ] Timeout configuration - [ ] User-agent customization - [ ] Error handling (404, timeout, network errors) ### 2.3 Type Conversion Tools - [ ] Implementacja `src/tools/conversion.ts` - [ ] Konwersje: JSON ↔ XML ↔ YAML ↔ CSV ↔ TOML - [ ] Pretty printing i minification - [ ] Walidacja struktury danych - [ ] Obsługa zagnieżdżonych struktur - [ ] Error handling dla nieprawidłowych formatów ### 2.4 Tool Registration - [ ] Utworzenie `src/tools/index.ts` - [ ] Eksport wszystkich narzędzi - [ ] Centralna rejestracja - [ ] Dynamiczne ładowanie narzędzi ### 2.5 Testing Basic Tools - [ ] Testy jednostkowe dla WebSearch - [ ] Testy jednostkowe dla WebFetch - [ ] Testy jednostkowe dla Type Conversion - [ ] Testy integracyjne z MCP Server --- ## 🛒 FAZA 3: Specialized Search Tools ### 3.1 E-commerce Search Tools #### 3.1.1 Amazon Search - [ ] Implementacja `src/tools/ecommerce/amazon.ts` - [ ] Integracja z Amazon Product Advertising API - [ ] Filtry: priceMin, priceMax, minRating, minReviews, category, region, condition - [ ] Sortowanie: price, rating, popularity, date - [ ] Normalizacja wyników - [ ] Error handling i rate limiting #### 3.1.2 eBay Search - [ ] Implementacja `src/tools/ecommerce/ebay.ts` - [ ] Integracja z eBay Finding API - [ ] Filtry: price range, condition, seller location, shipping options - [ ] Sortowanie i paginacja - [ ] Normalizacja wyników #### 3.1.3 Allegro Search - [ ] Implementacja `src/tools/ecommerce/allegro.ts` - [ ] Integracja z Allegro API - [ ] Filtry specyficzne dla Allegro - [ ] Obsługa polskiego języka - [ ] Normalizacja wyników #### 3.1.4 AliExpress Search - [ ] Implementacja `src/tools/ecommerce/aliexpress.ts` - [ ] Web scraping lub API integration - [ ] Filtry: price, rating, shipping - [ ] Normalizacja wyników #### 3.1.5 Etsy Search - [ ] Implementacja `src/tools/ecommerce/etsy.ts` - [ ] Integracja z Etsy API - [ ] Filtry: handmade, vintage, custom - [ ] Normalizacja wyników #### 3.1.6 E-commerce Tool Registry - [ ] Utworzenie `src/tools/ecommerce/index.ts` - [ ] Wspólny interfejs dla wszystkich platform - [ ] Agregacja wyników z wielu platform (opcjonalnie) ### 3.2 Scientific Publications Search Tools #### 3.2.1 arXiv Search - [ ] Implementacja `src/tools/scientific/arxiv.ts` - [ ] Integracja z arXiv API - [ ] Filtry: dateFrom, dateTo, field, authorAffiliation - [ ] Sortowanie: relevance, date, citations - [ ] Ekstrakcja: title, authors, abstract, PDF link #### 3.2.2 PubMed Search - [ ] Implementacja `src/tools/scientific/pubmed.ts` - [ ] Integracja z PubMed API (E-utilities) - [ ] Filtry: publicationType, minCitations, language - [ ] Ekstrakcja: DOI, journal, keywords #### 3.2.3 Google Scholar Search - [ ] Implementacja `src/tools/scientific/scholar.ts` - [ ] Web scraping (lub API jeśli dostępne) - [ ] Filtry: date range, citations - [ ] Ekstrakcja: citations count, PDF links #### 3.2.4 IEEE Xplore Search - [ ] Implementacja `src/tools/scientific/ieee.ts` - [ ] Integracja z IEEE Xplore API - [ ] Filtry: publication type, date range - [ ] Normalizacja wyników #### 3.2.5 ResearchGate Search - [ ] Implementacja `src/tools/scientific/researchgate.ts` - [ ] Web scraping (lub API jeśli dostępne) - [ ] Filtry: field, citations - [ ] Normalizacja wyników #### 3.2.6 Scientific Tool Registry - [ ] Utworzenie `src/tools/scientific/index.ts` - [ ] Wspólny interfejs dla wszystkich baz danych ### 3.3 Code Repositories Search Tools #### 3.3.1 GitHub Search - [ ] Implementacja `src/tools/repositories/github.ts` - [ ] Integracja z GitHub REST API - [ ] Filtry: language, minStars, license, topics, lastUpdated - [ ] Sortowanie: stars, forks, updated, relevance - [ ] Ekstrakcja: description, author, stars, forks, license #### 3.3.2 GitLab Search - [ ] Implementacja `src/tools/repositories/gitlab.ts` - [ ] Integracja z GitLab API - [ ] Filtry podobne do GitHub - [ ] Normalizacja wyników #### 3.3.3 npm Search - [ ] Implementacja `src/tools/repositories/npm.ts` - [ ] Integracja z npm Registry API - [ ] Filtry: minDownloads, keywords, license - [ ] Ekstrakcja: version, downloads, dependencies #### 3.3.4 PyPI Search - [ ] Implementacja `src/tools/repositories/pypi.ts` - [ ] Integracja z PyPI API - [ ] Filtry: minDownloads, license - [ ] Normalizacja wyników #### 3.3.5 Docker Hub Search - [ ] Implementacja `src/tools/repositories/docker.ts` - [ ] Integracja z Docker Hub API - [ ] Filtry: official, stars - [ ] Normalizacja wyników #### 3.3.6 Maven Central Search - [ ] Implementacja `src/tools/repositories/maven.ts` - [ ] Integracja z Maven Central API - [ ] Filtry: groupId, artifactId, version - [ ] Normalizacja wyników #### 3.3.7 Repository Tool Registry - [ ] Utworzenie `src/tools/repositories/index.ts` - [ ] Wspólny interfejs dla wszystkich repozytoriów ### 3.4 Social Media Search Tools #### 3.4.1 Twitter/X Search - [ ] Implementacja `src/tools/social/twitter.ts` - [ ] Integracja z Twitter API v2 - [ ] Filtry: timeRange, author, minInteractions, hashtags - [ ] Sortowanie: popularity, date, relevance - [ ] Ekstrakcja: content, author, interactions, media #### 3.4.2 Reddit Search - [ ] Implementacja `src/tools/social/reddit.ts` - [ ] Integracja z Reddit API - [ ] Filtry: subreddit, timeRange, minUpvotes - [ ] Ekstrakcja: title, content, upvotes, comments #### 3.4.3 LinkedIn Search - [ ] Implementacja `src/tools/social/linkedin.ts` - [ ] Integracja z LinkedIn API (jeśli dostępne) - [ ] Filtry: author, contentType - [ ] Normalizacja wyników #### 3.4.4 YouTube Search - [ ] Implementacja `src/tools/social/youtube.ts` - [ ] Integracja z YouTube Data API - [ ] Filtry: channel, timeRange, minViews - [ ] Ekstrakcja: title, description, views, duration #### 3.4.5 Hacker News Search - [ ] Implementacja `src/tools/social/hackernews.ts` - [ ] Integracja z Hacker News API - [ ] Filtry: timeRange, minPoints - [ ] Ekstrakcja: title, points, comments, URL #### 3.4.6 Social Media Tool Registry - [ ] Utworzenie `src/tools/social/index.ts` - [ ] Wspólny interfejs dla wszystkich platform ### 3.5 Testing Specialized Tools - [ ] Testy jednostkowe dla każdego narzędzia e-commerce - [ ] Testy jednostkowe dla każdego narzędzia scientific - [ ] Testy jednostkowe dla każdego narzędzia repository - [ ] Testy jednostkowe dla każdego narzędzia social media - [ ] Testy integracyjne z rzeczywistymi API (mockowane w CI) --- ## ⚡ FAZA 4: Advanced Features ### 4.1 Multi-Layer Caching System #### 4.1.1 L1 Cache (In-Memory) - [ ] Instalacja `lru-cache` lub `node-cache` - [ ] Implementacja `src/utils/cache/l1-cache.ts` - [ ] LRU cache configuration - [ ] TTL support - [ ] Cache size limits - [ ] Statistics (hit/miss ratio) #### 4.1.2 L2 Cache (Redis) - [ ] Instalacja `keyv`, `@keyv/redis`, `ioredis` - [ ] Implementacja `src/utils/cache/l2-cache.ts` - [ ] Redis connection management - [ ] TTL configuration - [ ] Error handling (fallback to L1) - [ ] Connection pooling #### 4.1.3 L3 Cache (HTTP Cache Headers) - [ ] Instalacja `axios-cache-interceptor` - [ ] Implementacja `src/utils/cache/http-cache.ts` - [ ] ETag support - [ ] Last-Modified support - [ ] Cache-Control parsing - [ ] Conditional requests #### 4.1.4 Cache Manager - [ ] Implementacja `src/utils/cache/cache-manager.ts` - [ ] Multi-layer cache coordination - [ ] Cache promotion (L2 → L1) - [ ] Cache invalidation strategies - [ ] Time-based (TTL) - [ ] Tag-based invalidation - [ ] Manual invalidation - [ ] Statistics and monitoring #### 4.1.5 Integration with BaseTool - [ ] Rozszerzenie `BaseTool` o cache support - [ ] Metoda `executeWithCache()` w BaseTool - [ ] Automatyczne cache key generation - [ ] Cache-aware error handling ### 4.2 Request Optimization #### 4.2.1 Request Deduplication - [ ] Implementacja `src/utils/optimization/request-deduplication.ts` - [ ] Map pending requests - [ ] Key generation dla identycznych żądań - [ ] Promise sharing dla równoległych żądań - [ ] Cleanup po zakończeniu #### 4.2.2 Request Batching - [ ] Implementacja `src/utils/optimization/request-batching.ts` - [ ] Grupowanie żądań do tego samego API - [ ] Batch size limits - [ ] Timeout dla batch collection - [ ] Obsługa API wspierających batching #### 4.2.3 Intelligent Pagination - [ ] Implementacja `src/utils/optimization/pagination.ts` - [ ] Automatyczne pobieranie kolejnych stron - [ ] Configurable page size - [ ] Early termination (gdy wystarczająco wyników) - [ ] Memory-efficient streaming #### 4.2.4 Field Filtering - [ ] Implementacja `src/utils/optimization/field-filtering.ts` - [ ] Pobieranie tylko wymaganych pól z API - [ ] Query parameter optimization - [ ] Response size reduction ### 4.3 Rate Limiting & Circuit Breaker #### 4.3.1 Rate Limiter - [ ] Instalacja `bottleneck` i `p-limit` - [ ] Implementacja `src/utils/rate-limiting/rate-limiter.ts` - [ ] Token bucket algorithm - [ ] Sliding window algorithm - [ ] Per-API rate limit configuration - [ ] Queue management - [ ] Priority support #### 4.3.2 Circuit Breaker - [ ] Implementacja `src/utils/resilience/circuit-breaker.ts` - [ ] Trzy stany: CLOSED, OPEN, HALF_OPEN - [ ] Failure threshold configuration - [ ] Timeout configuration - [ ] Automatic recovery - [ ] Metrics tracking #### 4.3.3 Retry Strategy - [ ] Instalacja `axios-retry` - [ ] Implementacja `src/utils/resilience/retry-strategy.ts` - [ ] Exponential backoff - [ ] Jitter (random delay) - [ ] Max retry attempts - [ ] Retryable error detection - [ ] Configurable per API #### 4.3.4 Integration with HTTP Client - [ ] Konfiguracja Axios z interceptors - [ ] Rate limiting interceptor - [ ] Retry interceptor - [ ] Circuit breaker interceptor - [ ] Cache interceptor - [ ] Error handling interceptor ### 4.4 Data Aggregation #### 4.4.1 Parallel Search Execution - [ ] Implementacja `src/utils/aggregation/parallel-search.ts` - [ ] Równoległe wyszukiwanie w wielu platformach - [ ] Concurrency control (p-limit) - [ ] Timeout dla całej operacji - [ ] Partial results handling #### 4.4.2 Result Deduplication - [ ] Implementacja `src/utils/aggregation/deduplication.ts` - [ ] Identyfikacja duplikatów (URL, title similarity) - [ ] Merge strategy dla duplikatów - [ ] Confidence scoring #### 4.4.3 Result Normalization - [ ] Implementacja `src/utils/aggregation/normalization.ts` - [ ] Wspólny format wyników - [ ] Field mapping z różnych API - [ ] Data type conversion - [ ] Missing field handling #### 4.4.4 Ranking and Sorting - [ ] Implementacja `src/utils/aggregation/ranking.ts` - [ ] Multi-criteria ranking - [ ] Relevance scoring - [ ] Custom sort functions - [ ] Weighted scoring #### 4.4.5 Statistics and Summaries - [ ] Implementacja `src/utils/aggregation/statistics.ts` - [ ] Aggregated statistics (total results, avg price, etc.) - [ ] Summary generation - [ ] Trend analysis (opcjonalnie) ### 4.5 Advanced Filtering #### 4.5.1 Composite Filters - [ ] Implementacja `src/utils/filtering/composite-filters.ts` - [ ] AND/OR/NOT logic - [ ] Nested filters - [ ] Filter validation #### 4.5.2 Full-Text Search Optimization - [ ] Implementacja `src/utils/filtering/fulltext-search.ts` - [ ] Query parsing - [ ] Stop words removal - [ ] Stemming (opcjonalnie) - [ ] Relevance scoring #### 4.5.3 Faceted Search - [ ] Implementacja `src/utils/filtering/faceted-search.ts` - [ ] Facet extraction - [ ] Facet filtering - [ ] Facet counts ### 4.6 Error Recovery & Resilience #### 4.6.1 Fallback Strategies - [ ] Implementacja `src/utils/resilience/fallback.ts` - [ ] Fallback to cache on API errors - [ ] Fallback to alternative API - [ ] Graceful degradation #### 4.6.2 Health Checks - [ ] Implementacja `src/utils/resilience/health-checks.ts` - [ ] Health check dla zewnętrznych API - [ ] Periodic health monitoring - [ ] Automatic service discovery - [ ] Health status reporting #### 4.6.3 Error Classification - [ ] Implementacja `src/utils/resilience/error-classification.ts` - [ ] Retryable vs non-retryable errors - [ ] Error severity levels - [ ] Error context preservation ### 4.7 Monitoring & Metrics #### 4.7.1 Metrics Collection - [ ] Implementacja `src/utils/monitoring/metrics.ts` - [ ] Cache hit/miss ratio - [ ] API response times - [ ] Rate limit usage - [ ] Error rates per endpoint - [ ] Queue depth monitoring #### 4.7.2 Logging Enhancement - [ ] Rozszerzenie loggera o metrics - [ ] Structured logging (JSON format) - [ ] Request/response logging - [ ] Performance logging --- ## 🧪 FAZA 5: Testing & Quality Assurance ### 5.1 Unit Tests - [ ] Testy dla BaseTool - [ ] Testy dla wszystkich narzędzi wyszukiwania - [ ] Testy dla cache system - [ ] Testy dla rate limiting - [ ] Testy dla circuit breaker - [ ] Testy dla aggregation utilities - [ ] Testy dla filtering utilities ### 5.2 Integration Tests - [ ] Testy integracyjne z MCP Server - [ ] Testy integracyjne z zewnętrznymi API (mockowane) - [ ] Testy cache integration - [ ] Testy error handling flows ### 5.3 End-to-End Tests - [ ] E2E testy dla podstawowych scenariuszy - [ ] E2E testy dla zaawansowanych funkcji - [ ] Testy wydajnościowe ### 5.4 Test Coverage - [ ] Minimum 80% code coverage - [ ] Coverage reports generation - [ ] Coverage monitoring w CI/CD ### 5.5 Test Infrastructure - [ ] Konfiguracja Jest - [ ] Mock setup dla zewnętrznych API - [ ] Test fixtures i helpers - [ ] CI/CD integration --- ## 📚 FAZA 6: Documentation & Examples ### 6.1 API Documentation - [ ] Dokumentacja wszystkich narzędzi - [ ] Przykłady użycia dla każdego narzędzia - [ ] Schema documentation (JSON Schema) - [ ] Error codes i messages ### 6.2 Integration Guides - [ ] Przewodnik integracji z Cursor AI - [ ] Przewodnik integracji z Claude Desktop - [ ] Przewodnik integracji z Flutter/Dart - [ ] Przewodnik konfiguracji środowiska ### 6.3 Examples - [ ] Przykładowe konfiguracje w `examples/` - [ ] Przykładowe scenariusze użycia - [ ] Code samples dla każdego narzędzia - [ ] Best practices guide ### 6.4 README Updates - [ ] Aktualizacja README z aktualnym statusem - [ ] Dodanie screenshots/diagramów - [ ] Troubleshooting guide - [ ] FAQ section --- ## 🔒 FAZA 7: Security & Best Practices ### 7.1 Authentication & Authorization - [ ] API keys management (environment variables) - [ ] Secure storage dla credentials - [ ] Role-based access control (opcjonalnie) - [ ] API key rotation support ### 7.2 Input Validation - [ ] Comprehensive input validation - [ ] Sanitization dla web scraping - [ ] SQL injection prevention (jeśli używasz DB) - [ ] XSS protection ### 7.3 API Security - [ ] HTTPS enforcement - [ ] Request signing (dla wymagających API) - [ ] Timeout protection - [ ] Error message sanitization ### 7.4 Security Audit - [ ] Code security review - [ ] Dependency vulnerability scanning - [ ] Penetration testing (opcjonalnie) - [ ] Security best practices documentation --- ## 🚀 FAZA 8: Deployment & Production ### 8.1 Build Optimization - [ ] Production build configuration - [ ] Code minification - [ ] Tree shaking - [ ] Bundle size optimization ### 8.2 Environment Configuration - [ ] Production environment setup - [ ] Environment-specific configs - [ ] Secrets management - [ ] Configuration validation ### 8.3 Monitoring & Observability - [ ] Production logging setup - [ ] Error tracking (Sentry lub podobne) - [ ] Performance monitoring - [ ] Health check endpoints (dla HTTP transport) ### 8.4 Deployment - [ ] Docker containerization (opcjonalnie) - [ ] CI/CD pipeline - [ ] Deployment documentation - [ ] Rollback procedures --- ## 📊 Status Wdrożenia ### Ogólny Postęp - **Faza 1 (Core Infrastructure)**: ✅ Ukończona (95%) - **Faza 2 (Basic Search Tools)**: ⏸️ Oczekuje - **Faza 3 (Specialized Search)**: ⏸️ Oczekuje - **Faza 4 (Advanced Features)**: ⏸️ Oczekuje - **Faza 5 (Testing)**: ⏸️ Oczekuje - **Faza 6 (Documentation)**: ⏸️ Oczekuje - **Faza 7 (Security)**: ⏸️ Oczekuje - **Faza 8 (Deployment)**: ⏸️ Oczekuje ### Statystyki - **Całkowite zadania**: ~200+ - **Ukończone**: ~10 (szacunkowo) - **W trakcie**: ~5 - **Oczekuje**: ~185+ --- ## 📝 Uwagi ### Priorytety 1. **Wysoki priorytet**: Faza 1, Faza 2 (podstawowe narzędzia) 2. **Średni priorytet**: Faza 3 (wyspecjalizowane narzędzia) 3. **Niski priorytet**: Faza 4 (zaawansowane funkcje), Faza 5-8 ### Zależności - Niektóre narzędzia wymagają API keys (Amazon, Twitter, etc.) - Redis jest opcjonalny, ale zalecany dla produkcji - Niektóre API mają rate limits (wymagają odpowiedniego planu) ### Rozszerzenia (Future) - Firecrawl integration (opcjonalnie) - Resources support (MCP) - Prompts support (MCP) - HTTP+SSE transport (oprócz STDIO) - WebSocket transport --- **Ostatnia aktualizacja**: 2025-01-XX **Wersja planu**: 1.0