# 🤖 MCP Server - Specialized AI Search Tools

Zaawansowany **Model Context Protocol (MCP) Server** z wyspecjalizowanymi narzędziami wyszukiwania dla agentów AI, zbudowany w Node.js i TypeScript.

## 🚀 Implementation Status

### ✅ Phase 1: Core Infrastructure (COMPLETED)
- ✅ MCP Server setup with STDIO transport
- ✅ BaseTool class with Zod validation
- ✅ Logging system
- ✅ TypeScript configuration
- ✅ Development environment (ESLint, Prettier)

### ✅ Phase 2: Basic Search Tools (COMPLETED)
- ✅ **WebSearchTool** - Search with DuckDuckGo, Brave, Google, Bing
- ✅ **WebFetchTool** - Fetch and parse HTML content
- ✅ **TypeConversionTool** - Convert between JSON, XML, YAML, CSV, TOML
- ⏳ Unit tests (pending)

### ⏸️ Phase 3: Specialized Search Tools (PLANNED)
- ⏸️ E-commerce search (Amazon, eBay, Allegro, AliExpress, Etsy)
- ⏸️ Scientific publications (arXiv, PubMed, Google Scholar, IEEE)
- ⏸️ Code repositories (GitHub, GitLab, npm, PyPI, Docker Hub)
- ⏸️ Social media (Twitter/X, Reddit, LinkedIn, YouTube, Hacker News)

### ⏸️ Phase 4: Advanced Features (PLANNED)
- ⏸️ Multi-layer caching (L1/L2/L3)
- ⏸️ Request optimization and deduplication
- ⏸️ Rate limiting and circuit breaker
- ⏸️ Data aggregation and ranking

---

## 📖 O Model Context Protocol (MCP)

### Czym jest MCP?

**Model Context Protocol (MCP)** to otwarty standard wprowadzony przez Anthropic, który standaryzuje sposób, w jaki aplikacje AI komunikują się z zewnętrznymi narzędziami, usługami i źródłami danych. MCP eliminuje potrzebę tworzenia dedykowanych integracji dla każdego narzędzia, oferując uniwersalny protokół komunikacji.

### Kluczowe Założenia Projektowe

1. **Standardyzacja Integracji**: MCP zapewnia jednolity sposób łączenia AI z różnymi systemami, eliminując fragmentację w ekosystemie AI
2. **Modularność**: Serwery MCP są niezależnymi modułami, które można łatwo dodawać, usuwać i konfigurować
3. **Bezpieczeństwo**: Protokół został zaprojektowany z myślą o bezpieczeństwie, z kontrolą dostępu i walidacją danych
4. **Elastyczność**: Obsługa różnych transportów (STDIO, HTTP+SSE) i formatów danych
5. **Open Source**: Otwarty standard dostępny dla wszystkich, promujący interoperacyjność

### Architektura MCP

MCP składa się z trzech głównych komponentów:

#### 1. **Tools (Narzędzia)**
Funkcje, które AI może wywołać do wykonania konkretnych akcji:
- **Definicja**: Każde narzędzie ma nazwę, opis i schemat parametrów (JSON Schema)
- **Wykonanie**: Narzędzie przyjmuje parametry i zwraca wynik
- **Przykłady**: Wyszukiwanie w bazie danych, wysyłanie emaili, wykonywanie obliczeń

#### 2. **Resources (Zasoby)**
Dane, do których AI może uzyskać dostęp:
- **Definicja**: Zasób ma URI, nazwę, opis i typ MIME
- **Dostęp**: AI może odczytać zawartość zasobu na żądanie
- **Przykłady**: Pliki w systemie, wpisy w bazie danych, dokumenty w chmurze

#### 3. **Prompts (Prompty)**
Szablony promptów, które AI może wykorzystać:
- **Definicja**: Prompt ma nazwę, opis i opcjonalne argumenty
- **Użycie**: AI może wywołać prompt z argumentami, aby wygenerować gotowy prompt
- **Przykłady**: Szablony do code review, generowania dokumentacji, analizy danych

### Jak Działa MCP?

```
┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│  AI Client  │◄──────►│  MCP Server  │◄──────►│  External   │
│ (Claude,    │  MCP   │  (This       │  API   │  Services   │
│  Cursor)    │Protocol│  Project)    │ Calls  │  (APIs, DB) │
└─────────────┘         └──────────────┘         └─────────────┘
```

1. **Inicjalizacja**: Klient AI łączy się z serwerem MCP przez wybrany transport (STDIO/HTTP+SSE)
2. **Odkrywanie**: Klient pobiera listę dostępnych narzędzi, zasobów i promptów
3. **Użycie**: AI wywołuje narzędzia lub odczytuje zasoby w odpowiedzi na zapytania użytkownika
4. **Wyniki**: Serwer MCP wykonuje operacje i zwraca wyniki do klienta AI

### Transporty MCP

- **STDIO (Standard Input/Output)**: Dla lokalnych integracji, proces komunikuje się przez stdin/stdout
- **HTTP+SSE (Server-Sent Events)**: Dla zdalnych serwerów, komunikacja przez HTTP z SSE dla strumieniowania
- **WebSocket**: (Planowane) Dla aplikacji webowych wymagających dwukierunkowej komunikacji

### Zalety MCP

✅ **Uniwersalność**: Jeden protokół dla wszystkich integracji  
✅ **Bezpieczeństwo**: Kontrola dostępu i walidacja na poziomie protokołu  
✅ **Skalowalność**: Łatwe dodawanie nowych narzędzi bez modyfikacji klienta  
✅ **Interoperacyjność**: Różne klienty AI mogą używać tych samych serwerów MCP  
✅ **Modularność**: Każdy serwer MCP jest niezależnym modułem funkcjonalności

---

## ✨ Wyspecjalizowane Narzędzia Wyszukiwania

### 🛒 E-commerce Search
Wyszukiwanie produktów w popularnych sklepach internetowych:
- **Obsługiwane platformy**: Amazon, eBay, Allegro, AliExpress, Etsy
- **Filtry**:
  - 💰 Zakres cenowy (min-max)
  - ⭐ Oceny (minimalna ocena, liczba opinii)
  - 🚚 Dostępność i opcje wysyłki
  - 🏷️ Kategorie produktów
  - 🌍 Region sprzedawcy
  - 📦 Stan produktu (nowy, używany, odnowiony)
- **Sortowanie**: cena, popularność, oceny, data dodania
- **Zwraca**: tytuł, cena, ocena, link, zdjęcie, dostępność

### 🔬 Scientific Publications Search
Wyszukiwanie publikacji naukowych i artykułów badawczych:
- **Obsługiwane bazy**: arXiv, PubMed, Google Scholar, IEEE Xplore, ResearchGate
- **Filtry**:
  - 📅 Zakres dat publikacji
  - 🏫 Afiliacja autorów
  - 📄 Typ publikacji (artykuł, konferencja, preprint)
  - 🔬 Dziedzina nauki
  - 📊 Liczba cytowań (minimum)
  - 🌐 Język publikacji
- **Sortowanie**: relevancja, data, cytowania
- **Zwraca**: tytuł, autorzy, abstrakt, DOI, PDF link, cytowania

### 💻 Hosting & Repositories Search
Wyszukiwanie kodu, pakietów i zasobów deweloperskich:
- **Obsługiwane platformy**: GitHub, GitLab, npm, PyPI, Docker Hub, Maven Central
- **Filtry**:
  - 💻 Język programowania
  - ⭐ Minimalna liczba gwiazdek/pobrań
  - 📅 Ostatnia aktualizacja (aktywność projektu)
  - 📜 Licencja (MIT, Apache, GPL, itp.)
  - 🏷️ Tagi i tematy
  - 👥 Liczba kontrybutorów
- **Sortowanie**: gwiazdki, forki, ostatnia aktualizacja, relevancja
- **Zwraca**: nazwa, opis, autor, gwiazdki, język, licencja, link

### 📱 Social Media Search
Wyszukiwanie treści w mediach społecznościowych:
- **Obsługiwane platformy**: Twitter/X, Reddit, LinkedIn, YouTube, Hacker News
- **Filtry**:
  - 📅 Zakres czasowy (ostatnia godzina, dzień, tydzień, miesiąc)
  - 🌍 Język i lokalizacja
  - 👤 Autor/kanał
  - 💬 Minimalna liczba interakcji (lajki, komentarze, udostępnienia)
  - 🏷️ Hashtagi i słowa kluczowe
  - 📊 Typ treści (tekst, obraz, wideo, link)
- **Sortowanie**: popularność, data, relevancja
- **Zwraca**: treść, autor, data, interakcje, link, media

### 🌐 General Web Search
Uniwersalne wyszukiwanie w internecie:
- **Obsługiwane silniki**: Google, Bing, DuckDuckGo, Brave Search
- **Filtry**:
  - 📄 Formaty plików (PDF, DOCX, XLSX, CSV, JSON, XML, PPT)
  - 🌍 Język i region
  - 📅 Zakres dat
  - 🔒 SafeSearch
  - 🌐 Domena (np. tylko .edu, .gov)
  - 📍 Dokładna fraza vs. podobne wyniki
- **Sortowanie**: relevancja, data
- **Zwraca**: tytuł, URL, snippet, data publikacji, typ pliku

---

## 🔧 Dodatkowe Funkcjonalności

### 🌐 WebFetch Tool
Pobieranie i parsowanie treści stron internetowych:
- Pobieranie HTML z dowolnego URL
- Parsowanie z wykorzystaniem Cheerio
- Ekstrakcja: tekst, nagłówki, linki, metadane, obrazy
- Obsługa selektorów CSS
- Timeout i error handling
- User-agent customization

> [!NOTE]
> **Alternatywa: Firecrawl Integration**
> Rozważ użycie [Firecrawl](https://github.com/firecrawl/firecrawl) jako zaawansowanej alternatywy lub uzupełnienia dla WebFetch. Zobacz sekcję [Firecrawl Integration](#firecrawl-integration-consideration) poniżej.

### 🔄 Type Conversion Tools
Konwersja między różnymi formatami danych:
- **Obsługiwane formaty**: JSON, XML, YAML, CSV, TOML
- **Konwersje**: JSON ↔ XML ↔ YAML ↔ CSV ↔ TOML
- Pretty printing i minification
- Walidacja struktury danych
- Obsługa zagnieżdżonych struktur

### 📊 Data Aggregation
Agregacja wyników z wielu źródeł:
- Równoległe wyszukiwanie w wielu platformach
- Deduplikacja wyników
- Normalizacja formatów odpowiedzi
- Ranking i sortowanie zagregowanych wyników
- Statystyki i podsumowania

### 🛠️ Extensible Architecture
Łatwe dodawanie własnych narzędzi:
- Bazowa klasa `BaseTool` z wspólną logiką
- Automatyczna walidacja z Zod
- Centralna rejestracja narzędzi
- Standardowy error handling
- Plugin system dla nowych źródeł danych

### ⚡ Cache'owanie i Optymalizacja Zapytań

#### Strategie Cache'owania

**1. Multi-Layer Caching**
- **L1 Cache (In-Memory)**: Szybki dostęp do często używanych wyników (node-cache/lru-cache)
- **L2 Cache (Redis)**: Dzielony cache między instancjami serwera
- **L3 Cache (HTTP Cache Headers)**: Wykorzystanie cache'u przeglądarki/CDN

**2. Cache Patterns**
- **Cache-Aside (Lazy Loading)**: Aplikacja sprawdza cache, jeśli brak - pobiera z API i zapisuje
- **Write-Through**: Zapis do cache i API jednocześnie
- **Stale-While-Revalidate**: Zwracanie przestarzałych danych podczas aktualizacji w tle
- **Time-Based Invalidation**: Automatyczne wygaszanie po określonym czasie (TTL)
- **Tag-Based Invalidation**: Inwalidacja po tagach dla precyzyjnej kontroli

**3. Request Optimization**
- **Request Deduplication**: Grupowanie identycznych równoległych żądań
- **Batching**: Łączenie wielu zapytań w jedno żądanie (gdy API wspiera)
- **Pagination**: Pobieranie danych w mniejszych porcjach
- **Field Filtering**: Pobieranie tylko wymaganych pól z API

**4. Rate Limiting & Circuit Breaker**
- **Token Bucket**: Kontrola przepustowości z tokenami
- **Sliding Window**: Ograniczenie liczby żądań w oknie czasowym
- **Circuit Breaker**: Automatyczne wyłączanie usługi przy błędach
- **Exponential Backoff**: Stopniowe zwiększanie opóźnień przy ponawianiu

**5. Monitoring & Metrics**
- Cache hit/miss ratio
- API response times
- Rate limit usage tracking
- Error rates per API endpoint
- Queue depth monitoring

---

## 📚 Dokumentacja Funkcjonalności i Przykłady

### 🎯 Scenariusze Użycia

#### Scenariusz 1: Research Assistant
**Cel**: Pomoc w badaniach naukowych poprzez agregację informacji z wielu źródeł

**Przepływ**:
1. Użytkownik: "Znajdź najnowsze publikacje o quantum computing"
2. AI wywołuje `scientific_publications_search` z parametrami:
   ```typescript
   {
     query: "quantum computing",
     database: "arxiv",
     dateFrom: "2024-01-01",
     sortBy: "date"
   }
   ```
3. AI następnie wywołuje `repositories_search`:
   ```typescript
   {
     query: "quantum computing implementation",
     platform: "github",
     language: "python",
     minStars: 100
   }
   ```
4. AI agreguje wyniki i generuje podsumowanie

**Wartość**: Automatyczna agregacja informacji z różnych źródeł w jednym miejscu

#### Scenariusz 2: Product Research & Comparison
**Cel**: Porównanie produktów z różnych platform e-commerce

**Przepływ**:
1. Użytkownik: "Porównaj ceny iPhone 15 Pro na różnych platformach"
2. AI równolegle wywołuje narzędzia dla każdej platformy:
   - `ecommerce_search` (platform: "amazon")
   - `ecommerce_search` (platform: "ebay")
   - `ecommerce_search` (platform: "allegro")
3. AI agreguje wyniki, normalizuje formaty i porównuje ceny
4. Zwraca tabelę porównawczą z najlepszymi ofertami

**Wartość**: Oszczędność czasu na ręcznym przeszukiwaniu wielu sklepów

#### Scenariusz 3: Developer Tool Discovery
**Cel**: Znalezienie odpowiednich bibliotek i narzędzi dla projektu

**Przepływ**:
1. Użytkownik: "Znajdź biblioteki do walidacji danych w TypeScript"
2. AI wywołuje `repositories_search`:
   ```typescript
   {
     query: "data validation",
     platform: "github",
     language: "typescript",
     minStars: 500,
     sortBy: "stars"
   }
   ```
3. AI następnie używa `webfetch` do pobrania dokumentacji najlepszych wyników
4. Zwraca listę z opisami, ocenami i linkami do dokumentacji

**Wartość**: Szybkie znalezienie sprawdzonych narzędzi

### 📋 Szczegółowa Dokumentacja Narzędzi

#### 🛒 E-commerce Search Tool

**Funkcjonalność**: Wyszukiwanie produktów w popularnych sklepach internetowych z zaawansowanymi filtrami

**Parametry wejściowe**:
```typescript
interface EcommerceSearchParams {
  query: string;              // Fraza wyszukiwania
  platform: 'amazon' | 'ebay' | 'allegro' | 'alexpress' | 'etsy';
  priceMin?: number;          // Minimalna cena
  priceMax?: number;          // Maksymalna cena
  minRating?: number;         // Minimalna ocena (1-5)
  minReviews?: number;         // Minimalna liczba opinii
  category?: string;          // Kategoria produktu
  region?: string;            // Region (kod kraju)
  condition?: 'new' | 'used' | 'refurbished';
  sortBy?: 'price' | 'rating' | 'popularity' | 'date';
  limit?: number;             // Maksymalna liczba wyników (domyślnie 10)
}
```

**Format odpowiedzi**:
```typescript
interface EcommerceSearchResult {
  platform: string;
  totalResults: number;
  results: Array<{
    title: string;
    price: number;
    currency: string;
    rating: number;
    reviewCount: number;
    url: string;
    imageUrl?: string;
    availability: 'in_stock' | 'out_of_stock' | 'limited';
    shippingInfo?: string;
  }>;
}
```

**Przykład użycia**:
```typescript
// Wywołanie przez AI
{
  query: "laptop gaming",
  platform: "allegro",
  priceMin: 2000,
  priceMax: 5000,
  minRating: 4.5,
  minReviews: 10,
  sortBy: "rating"
}
```

#### 🔬 Scientific Publications Search Tool

**Funkcjonalność**: Wyszukiwanie publikacji naukowych w bazach danych z filtrowaniem po datach, autorach i cytowaniach

**Parametry wejściowe**:
```typescript
interface ScientificSearchParams {
  query: string;
  database: 'arxiv' | 'pubmed' | 'scholar' | 'ieee' | 'researchgate';
  dateFrom?: string;          // Format: YYYY-MM-DD
  dateTo?: string;            // Format: YYYY-MM-DD
  authorAffiliation?: string; // Afiliacja autora
  publicationType?: 'article' | 'conference' | 'preprint';
  field?: string;             // Dziedzina nauki
  minCitations?: number;      // Minimalna liczba cytowań
  language?: string;           // Kod języka (ISO 639-1)
  sortBy?: 'relevance' | 'date' | 'citations';
  limit?: number;
}
```

**Format odpowiedzi**:
```typescript
interface ScientificSearchResult {
  database: string;
  totalResults: number;
  results: Array<{
    title: string;
    authors: string[];
    abstract: string;
    doi?: string;
    pdfUrl?: string;
    publicationDate: string;
    citationCount: number;
    journal?: string;
    keywords?: string[];
  }>;
}
```

#### 💻 Repositories Search Tool

**Funkcjonalność**: Wyszukiwanie projektów, bibliotek i pakietów w repozytoriach kodu

**Parametry wejściowe**:
```typescript
interface RepositorySearchParams {
  query: string;
  platform: 'github' | 'gitlab' | 'npm' | 'pypi' | 'docker' | 'maven';
  language?: string;          // Język programowania
  minStars?: number;          // Minimalna liczba gwiazdek
  minDownloads?: number;      // Minimalna liczba pobrań (dla npm/pypi)
  lastUpdated?: string;       // Ostatnia aktualizacja po dacie
  license?: string;           // Typ licencji (MIT, Apache, GPL, etc.)
  topics?: string[];          // Tagi/tematy
  minContributors?: number;   // Minimalna liczba kontrybutorów
  sortBy?: 'stars' | 'forks' | 'updated' | 'relevance';
  limit?: number;
}
```

**Format odpowiedzi**:
```typescript
interface RepositorySearchResult {
  platform: string;
  totalResults: number;
  results: Array<{
    name: string;
    description: string;
    author: string;
    stars: number;
    forks: number;
    language: string;
    license?: string;
    url: string;
    lastUpdated: string;
    topics?: string[];
  }>;
}
```

#### 📱 Social Media Search Tool

**Funkcjonalność**: Wyszukiwanie treści w mediach społecznościowych z filtrowaniem po czasie i popularności

**Parametry wejściowe**:
```typescript
interface SocialMediaSearchParams {
  query: string;
  platform: 'twitter' | 'reddit' | 'linkedin' | 'youtube' | 'hackernews';
  timeRange?: 'hour' | 'day' | 'week' | 'month' | 'year';
  language?: string;
  author?: string;            // Nazwa użytkownika/kanału
  minInteractions?: number;   // Minimalna liczba lajków/komentarzy
  hashtags?: string[];        // Hashtagi
  contentType?: 'text' | 'image' | 'video' | 'link';
  sortBy?: 'popularity' | 'date' | 'relevance';
  limit?: number;
}
```

#### 🌐 General Web Search Tool

**Funkcjonalność**: Uniwersalne wyszukiwanie w internecie z filtrowaniem po typach plików i domenach

**Parametry wejściowe**:
```typescript
interface WebSearchParams {
  query: string;
  engine: 'google' | 'bing' | 'duckduckgo' | 'brave';
  fileType?: 'pdf' | 'docx' | 'xlsx' | 'csv' | 'json' | 'xml' | 'ppt';
  language?: string;
  region?: string;
  dateFrom?: string;
  dateTo?: string;
  domain?: string;            // np. ".edu", ".gov"
  exactPhrase?: boolean;      // Dokładna fraza vs. podobne wyniki
  safeSearch?: boolean;
  sortBy?: 'relevance' | 'date';
  limit?: number;
}
```

### 🔄 Type Conversion Tool

**Funkcjonalność**: Konwersja między różnymi formatami danych (JSON, XML, YAML, CSV, TOML)

**Przykład użycia**:
```typescript
// Konwersja JSON do YAML
{
  inputFormat: "json",
  outputFormat: "yaml",
  data: '{"name": "test", "value": 123}',
  prettyPrint: true
}
```

### 🌐 WebFetch Tool

**Funkcjonalność**: Pobieranie i parsowanie treści stron internetowych

**Parametry**:
```typescript
interface WebFetchParams {
  url: string;
  selector?: string;          // CSS selector dla ekstrakcji fragmentu
  extractImages?: boolean;
  extractLinks?: boolean;
  timeout?: number;           // Timeout w sekundach
}
```

**Format odpowiedzi**:
```typescript
interface WebFetchResult {
  url: string;
  title?: string;
  text: string;
  html?: string;
  metadata?: {
    description?: string;
    keywords?: string[];
    author?: string;
  };
  images?: string[];
  links?: string[];
}
```

---

## 🔧 Development

### Struktura projektu

```
mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP Server setup
│   ├── tools/                # Narzędzia wyszukiwania
│   │   ├── index.ts          # Eksport wszystkich narzędzi
│   │   ├── base.ts           # Bazowa klasa
│   │   ├── ecommerce/        # E-commerce search tools
│   │   │   ├── amazon.ts
│   │   │   ├── ebay.ts
│   │   │   └── allegro.ts
│   │   ├── scientific/       # Scientific search tools
│   │   │   ├── arxiv.ts
│   │   │   ├── pubmed.ts
│   │   │   └── scholar.ts
│   │   ├── repositories/     # Code repository tools
│   │   │   ├── github.ts
│   │   │   ├── npm.ts
│   │   │   └── pypi.ts
│   │   ├── social/           # Social media tools
│   │   │   ├── twitter.ts
│   │   │   ├── reddit.ts
│   │   │   └── youtube.ts
│   │   ├── websearch.ts      # General web search
│   │   ├── webfetch.ts       # Web scraping
│   │   └── conversion.ts     # Type conversion
│   ├── types/                # TypeScript types
│   └── utils/                # Utilities
│       ├── logger.ts
│       ├── cache.ts
│       └── validators.ts
├── tests/                    # Testy
├── examples/                 # Przykłady konfiguracji
└── dist/                     # Skompilowany kod
```

### Skrypty npm

```bash
# Development
npm run dev          # Uruchomienie w trybie dev (watch mode)
npm run build        # Build produkcyjny
npm start            # Uruchomienie serwera

# Testing
npm test             # Uruchomienie testów
npm run test:watch   # Testy w trybie watch
npm run test:coverage # Coverage report

# Linting
npm run lint         # ESLint check
npm run lint:fix     # ESLint auto-fix
npm run format       # Prettier formatting
```

### Dodawanie nowego źródła wyszukiwania

1. Utwórz nowy plik w odpowiednim katalogu, np. `src/tools/ecommerce/shopify.ts`:

```typescript
import { z } from 'zod';
import { BaseTool } from '../base.js';

const ShopifySearchSchema = z.object({
  query: z.string().describe('Search query'),
  priceMin: z.number().optional().describe('Minimum price'),
  priceMax: z.number().optional().describe('Maximum price'),
  limit: z.number().default(10).describe('Number of results'),
});

export class ShopifySearchTool extends BaseTool {
  name = 'ecommerce_shopify';
  description = 'Search for products on Shopify stores';
  schema = ShopifySearchSchema;

  async execute(params: z.infer<typeof ShopifySearchSchema>) {
    // Implementacja wyszukiwania w Shopify
    const results = await this.searchShopify(params);
    return {
      platform: 'shopify',
      results,
    };
  }

  private async searchShopify(params: any) {
    // Logika API call do Shopify
  }
}
```

2. Zarejestruj w `src/tools/index.ts`:

```typescript
import { ShopifySearchTool } from './ecommerce/shopify.js';

export const tools = [
  // ... existing tools
  new ShopifySearchTool(),
];
```

### Implementacja Cache'owania

#### Przykład: Multi-Layer Cache z keyv

```typescript
// src/utils/cache.ts
import Keyv from 'keyv';
import KeyvRedis from '@keyv/redis';
import { LRUCache } from 'lru-cache';

// L1: In-memory LRU cache (szybki dostęp)
const l1Cache = new LRUCache<string, any>({
  max: 500, // maksymalna liczba wpisów
  ttl: 1000 * 60 * 5, // 5 minut TTL
});

// L2: Redis cache (współdzielony między instancjami)
const l2Cache = new Keyv({
  store: new KeyvRedis(process.env.REDIS_URL),
  ttl: 1000 * 60 * 30, // 30 minut TTL
});

export class CacheManager {
  async get<T>(key: string): Promise<T | undefined> {
    // Sprawdź L1 cache
    const l1Value = l1Cache.get(key);
    if (l1Value !== undefined) {
      return l1Value as T;
    }

    // Sprawdź L2 cache
    const l2Value = await l2Cache.get(key);
    if (l2Value !== undefined) {
      // Promuj do L1
      l1Cache.set(key, l2Value);
      return l2Value as T;
    }

    return undefined;
  }

  async set(key: string, value: any, ttl?: number): Promise<void> {
    // Zapisz w obu warstwach
    l1Cache.set(key, value, { ttl: ttl || 1000 * 60 * 5 });
    await l2Cache.set(key, value, ttl);
  }

  async invalidate(pattern: string): Promise<void> {
    // Inwalidacja po wzorcu (dla tag-based invalidation)
    // Implementacja zależy od używanego store
  }
}
```

#### Przykład: Request Deduplication

```typescript
// src/utils/request-deduplication.ts
import { CacheManager } from './cache.js';

class RequestDeduplicator {
  private pendingRequests = new Map<string, Promise<any>>();

  async deduplicate<T>(
    key: string,
    requestFn: () => Promise<T>
  ): Promise<T> {
    // Sprawdź czy żądanie jest już w trakcie
    const pending = this.pendingRequests.get(key);
    if (pending) {
      return pending;
    }

    // Utwórz nowe żądanie
    const promise = requestFn().finally(() => {
      // Usuń z mapy po zakończeniu
      this.pendingRequests.delete(key);
    });

    this.pendingRequests.set(key, promise);
    return promise;
  }
}
```

#### Przykład: Rate Limiting z bottleneck

```typescript
// src/utils/rate-limiter.ts
import Bottleneck from 'bottleneck';

// Rate limiter per API endpoint
const rateLimiters = new Map<string, Bottleneck>();

export function getRateLimiter(
  apiName: string,
  maxConcurrent: number = 5,
  minTime: number = 1000
): Bottleneck {
  if (!rateLimiters.has(apiName)) {
    rateLimiters.set(
      apiName,
      new Bottleneck({
        maxConcurrent,
        minTime, // minimum time between requests (ms)
        reservoir: 100, // initial number of requests
        reservoirRefreshAmount: 100,
        reservoirRefreshInterval: 60 * 1000, // refresh every minute
      })
    );
  }
  return rateLimiters.get(apiName)!;
}
```

#### Przykład: Circuit Breaker Pattern

```typescript
// src/utils/circuit-breaker.ts
enum CircuitState {
  CLOSED = 'CLOSED',
  OPEN = 'OPEN',
  HALF_OPEN = 'HALF_OPEN',
}

export class CircuitBreaker {
  private state = CircuitState.CLOSED;
  private failures = 0;
  private lastFailureTime = 0;

  constructor(
    private threshold: number = 5,
    private timeout: number = 60000 // 1 minute
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === CircuitState.OPEN) {
      if (Date.now() - this.lastFailureTime > this.timeout) {
        this.state = CircuitState.HALF_OPEN;
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = CircuitState.CLOSED;
  }

  private onFailure() {
    this.failures++;
    this.lastFailureTime = Date.now();

    if (this.failures >= this.threshold) {
      this.state = CircuitState.OPEN;
    }
  }
}
```

#### Przykład: Integracja z BaseTool

```typescript
// src/tools/base.ts (rozszerzenie)
import { CacheManager } from '../utils/cache.js';
import { RequestDeduplicator } from '../utils/request-deduplication.js';
import { getRateLimiter } from '../utils/rate-limiter.js';
import { CircuitBreaker } from '../utils/circuit-breaker.js';

export abstract class BaseTool {
  protected cache = new CacheManager();
  protected deduplicator = new RequestDeduplicator();
  protected circuitBreaker = new CircuitBreaker();

  protected async executeWithCache<T>(
    cacheKey: string,
    apiCall: () => Promise<T>,
    ttl?: number
  ): Promise<T> {
    // Sprawdź cache
    const cached = await this.cache.get<T>(cacheKey);
    if (cached !== undefined) {
      return cached;
    }

    // Request deduplication
    const result = await this.deduplicator.deduplicate(
      cacheKey,
      async () => {
        // Rate limiting
        const limiter = getRateLimiter(this.name);
        return limiter.schedule(async () => {
          // Circuit breaker
          return this.circuitBreaker.execute(apiCall);
        });
      }
    );

    // Zapisz w cache
    await this.cache.set(cacheKey, result, ttl);
    return result;
  }
}
```

---

## 🧪 Testing

```bash
# Wszystkie testy
npm test

# Testy dla konkretnej kategorii
npm test -- ecommerce
npm test -- scientific

# Coverage
npm run test:coverage
```

---

## 🏗️ Architektura Projektu

### Założenia Architektoniczne

1. **Modularność**: Każde narzędzie wyszukiwania jest niezależnym modułem, łatwym do dodania/usunięcia
2. **Walidacja Schematów**: Wszystkie parametry narzędzi są walidowane przez Zod przed wykonaniem
3. **Error Handling**: Centralny system obsługi błędów z informatywnymi komunikatami
4. **Multi-Layer Caching**: Inteligentne cachowanie wyników wyszukiwań w wielu warstwach (L1: in-memory, L2: Redis) dla poprawy wydajności
5. **Request Optimization**: Deduplikacja żądań, batching, i paginacja dla minimalizacji wywołań API
6. **Rate Limiting & Resilience**: Rate limiting per API, circuit breaker pattern, i exponential backoff retry
7. **Extensibility**: Bazowa klasa `BaseTool` umożliwia łatwe dodawanie nowych narzędzi z automatycznym cache'owaniem

### Struktura Komunikacji

```
┌─────────────────────────────────────────────────────────┐
│                    AI Client (Claude/Cursor)            │
└────────────────────┬────────────────────────────────────┘
                     │ MCP Protocol (JSON-RPC)
                     │
┌────────────────────▼────────────────────────────────────┐
│              MCP Server (This Project)                   │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Tool Registry                                    │  │
│  │  - E-commerce Search Tools                        │  │
│  │  - Scientific Publication Tools                   │  │
│  │  - Repository Search Tools                        │  │
│  │  - Social Media Tools                            │  │
│  │  - Web Search Tools                              │  │
│  └────────────────────────────────────────────────────┘  │
│                     │                                     │
│  ┌──────────────────▼────────────────────────────────┐  │
│  │  BaseTool Abstract Class                          │  │
│  │  - Schema Validation (Zod)                        │  │
│  │  - Error Handling                                 │  │
│  │  - Logging                                        │  │
│  └────────────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/API Calls
                     │
┌────────────────────▼────────────────────────────────────┐
│         External APIs & Services                         │
│  - Google Search API                                    │
│  - Amazon Product API                                   │
│  - GitHub API                                           │
│  - arXiv API                                            │
│  - Twitter API                                          │
│  - ... (20+ services)                                   │
└──────────────────────────────────────────────────────────┘
```

### Wzorce Projektowe

#### 1. **Strategy Pattern**
Każde narzędzie wyszukiwania implementuje wspólny interfejs `BaseTool`, ale ma własną strategię wykonania:
```typescript
abstract class BaseTool {
  abstract name: string;
  abstract description: string;
  abstract schema: ZodSchema;
  abstract execute(params: unknown): Promise<unknown>;
}
```

#### 2. **Factory Pattern**
Centralna rejestracja narzędzi w `tools/index.ts`:
```typescript
export const tools = [
  new AmazonSearchTool(),
  new GitHubSearchTool(),
  // ... inne narzędzia
];
```

#### 3. **Adapter Pattern**
Normalizacja różnych formatów odpowiedzi API do jednolitego formatu MCP:
```typescript
class SearchResultAdapter {
  normalize(apiResponse: unknown): MCPToolResult {
    // Konwersja do standardowego formatu
  }
}
```

### Przepływ Danych z Cache'owaniem i Optymalizacją

1. **Żądanie od AI**: Klient AI wysyła żądanie wywołania narzędzia z parametrami
2. **Walidacja**: Parametry są walidowane przez schemat Zod
3. **Cache Check (L1)**: Sprawdzenie in-memory cache dla szybkiego dostępu
4. **Request Deduplication**: Sprawdzenie, czy identyczne żądanie jest już w trakcie przetwarzania
5. **Rate Limiting Check**: Weryfikacja limitów dla danego API endpoint
6. **Cache Check (L2)**: Jeśli L1 miss, sprawdzenie Redis cache
7. **Circuit Breaker Check**: Weryfikacja stanu circuit breakera dla API
8. **Wykonanie**: Narzędzie wykonuje zapytanie do zewnętrznego API (z retry logic)
9. **Przetwarzanie**: Odpowiedź API jest parsowana i normalizowana
10. **Caching**: Wynik jest cachowany w L1 i L2 (z TTL i tagami)
11. **Odpowiedź**: Znormalizowany wynik jest zwracany do klienta AI
12. **Metrics**: Aktualizacja metryk (cache hit/miss, response time, error rate)

### Obsługa Błędów

- **Walidacja Parametrów**: Błędy walidacji są zwracane przed wykonaniem
- **API Errors**: Błędy zewnętrznych API są przechwytywane i konwertowane na format MCP
- **Timeout Protection**: Wszystkie żądania mają timeouty, aby uniknąć zawieszenia
- **Retry Logic**: Automatyczne ponawianie z exponential backoff i jitter (axios-retry)
- **Circuit Breaker**: Automatyczne wyłączanie usługi przy wysokim wskaźniku błędów
- **Fallback to Cache**: W przypadku błędów API, zwracanie danych z cache (jeśli dostępne)
- **Graceful Degradation**: Stopniowe obniżanie funkcjonalności zamiast całkowitego błędu

---

## 🛠️ Tech Stack

### Core Technologies
- **Runtime**: Node.js 20+ - Najnowsze funkcje ES2023, wydajność i stabilność
- **Language**: TypeScript 5.7+ - Type safety, lepsze IDE support, refactoring
- **MCP SDK**: `@modelcontextprotocol/sdk` - Oficjalne SDK dla protokołu MCP

### Validation & Schema
- **Zod**: Walidacja schematów JSON Schema dla parametrów narzędzi
- **Type Safety**: Pełne typowanie TypeScript dla wszystkich komponentów

### HTTP & Networking
- **Axios**: HTTP client z interceptors, retry logic i error handling
- **axios-retry**: Automatyczne ponawianie żądań z konfigurowalnymi strategiami
- **axios-cache-interceptor**: Cache interceptor dla Axios z obsługą HTTP cache headers
- **Cheerio**: Server-side HTML parsing (jQuery-like API) dla web scraping
- **undici**: Wysokowydajny HTTP client (alternatywa dla Axios, natywny w Node.js 18+)

### Data Processing
- **xml2js**: Parsowanie XML do obiektów JavaScript
- **js-yaml**: Parsowanie i generowanie YAML
- **csv-parse**: Parsowanie plików CSV

### Performance & Caching
- **keyv**: Uniwersalny key-value store z adapterami dla Redis, Memcached, MongoDB, PostgreSQL, SQLite
- **cache-manager**: Elastyczny system cache'owania z wieloma backendami (Redis, Memcached, memory)
- **node-cache**: In-memory caching dla wyników wyszukiwań (lightweight alternative)
- **ioredis**: Zaawansowany Redis client z cluster support, pub/sub, pipeline
- **lru-cache**: Wysokowydajna implementacja LRU cache z TypeScript support
- **p-limit**: Kontrola współbieżności dla równoległych operacji API
- **bottleneck**: Zaawansowany rate limiter z queue management
- **axios-retry**: Automatyczne ponawianie żądań z exponential backoff

### Development Tools
- **Jest**: Framework testowy z coverage reports
- **ESLint**: Linting kodu z regułami TypeScript
- **Prettier**: Automatyczne formatowanie kodu
- **ts-node**: TypeScript execution environment dla development

### Security & Rate Limiting
- **dotenv**: Zarządzanie zmiennymi środowiskowymi
- **helmet**: (Planowane) Security headers dla HTTP transport
- **bottleneck**: Rate limiting z queue management i priority support
- **p-limit**: Kontrola współbieżności i rate limiting dla równoległych operacji
- **express-rate-limit**: Rate limiting middleware (dla HTTP transport)

---

## 📖 Zasoby

### MCP Protocol - Oficjalne Źródła
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - Oficjalna dokumentacja MCP
- [MCP SDK GitHub](https://github.com/modelcontextprotocol/sdk) - Oficjalne SDK dla różnych języków
- [MCP Specification](https://spec.modelcontextprotocol.io/) - Pełna specyfikacja protokołu
- [Cursor AI MCP Integration](https://docs.cursor.com/mcp) - Integracja MCP z Cursor AI
- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp) - Przewodnik integracji z Claude Desktop
- [OpenAI MCP Server Documentation](https://developers.openai.com/apps-sdk/concepts/mcp-server/) - Dokumentacja OpenAI dotycząca MCP Server

### Open-Source Repozytoria MCP Server

#### TypeScript/Node.js Implementacje
- [MCP SDK TypeScript](https://github.com/modelcontextprotocol/sdk-typescript) - Oficjalne SDK TypeScript
- [Learn MCP by Building](https://mcp.so/ja/server/learn-mcp-by-building) - Przewodnik krok po kroku z przykładami
- [OPNsense MCP Server](https://github.com/floriangrousset/opnsense-mcp-server) - Przykład integracji z OPNsense API

#### Flutter/Dart Implementacje (dla integracji z AI Code Box)
- [flutter_mcp_server](https://github.com/Centinol-alt/flutter_mcp_server) - Open-source implementacja MCP dla Flutter/Dart
- [mcp_dart](https://github.com/leehack/mcp_dart) - SDK MCP w Dart, umożliwiające tworzenie serwerów i klientów
- [mcp_flutter](https://github.com/Arenukvern/mcp_flutter) - MCP Server i Toolkit dla Flutter z dynamiczną rejestracją narzędzi
- [figma-flutter-mcp](https://github.com/mhmzdev/figma-flutter-mcp) - MCP Server konwertujący projekty Figma na kod Flutter
- [Flutter MCP Server Documentation](https://docs.flutter.dev/ai/mcp-server) - Oficjalna dokumentacja Flutter dotycząca MCP

#### Integracja z Flutter/Dart (AI Code Box)

Dla projektu **AI Code Box** w Flutter, możesz zintegrować ten MCP Server na kilka sposobów:

**Opcja 1: HTTP/SSE Transport**
Uruchom Node.js MCP Server jako osobny proces i połącz się przez HTTP+SSE używając `mcp_dart`:
```dart
import 'package:mcp_dart/mcp_dart.dart';

final client = MCPClient(
  transport: StreamableHTTPTransport(url: 'http://localhost:3000/mcp'),
);
await client.connect();
```

**Opcja 2: Native Dart MCP Server**
Użyj biblioteki `mcp_dart` do stworzenia natywnego serwera MCP w Dart, portując narzędzia z tego projektu.

**Opcja 3: Bridge Pattern**
Stwórz bridge między Node.js MCP Server a Flutter aplikacją przez REST API.

**Zalecane biblioteki:**
- [mcp_dart](https://github.com/leehack/mcp_dart) - Pełne SDK MCP dla Dart
- [mcp_flutter](https://github.com/Arenukvern/mcp_flutter) - Flutter-specific MCP toolkit
- [dio](https://pub.dev/packages/dio) - HTTP client dla komunikacji z Node.js serverem

#### Inne Implementacje
- [Java MCP Server](https://modelcontextprotocol.io/sdk/java/mcp-server) - Implementacja w Javie
- [Python MCP Examples](https://github.com/modelcontextprotocol/python-sdk) - Przykłady w Pythonie

### Artykuły i Najlepsze Praktyki

#### Podstawowe Wprowadzenie do MCP
- [MCP Explained: The New Standard Connecting AI to Everything](https://medium.com/@elisowski/mcp-explained-the-new-standard-connecting-ai-to-everything-79c5a1c98288) - **Polecany!** Kompleksowe wyjaśnienie MCP, jego architektury, komponentów (tools, resources, prompts) oraz jak MCP standaryzuje integrację AI z zewnętrznymi systemami. Artykuł zawiera praktyczne przykłady i case studies.
- [Model Context Protocol (MCP) in AI](https://blog.stackademic.com/model-context-protocol-mcp-in-ai-9858b5ecd9ce) - **Polecany!** Szczegółowe omówienie MCP jako otwartego standardu łączącego AI z systemami danych. Artykuł opisuje założenia projektowe, architekturę i praktyczne zastosowania MCP w ekosystemie AI.

#### Zaawansowane Implementacje
- [Advanced MCP Implementation and Best Practices for Scaling AI Systems](https://medium.com/@cloudelligent_/advanced-mcp-implementation-and-best-practices-for-scaling-ai-systems-part-2-794f975746c6) - Zaawansowane techniki implementacji i skalowania systemów AI z MCP
- [MCP Security: Best Practices & Implementation Guide](https://vulnerablemcp.info/security.html) - Wytyczne dotyczące zabezpieczania serwera MCP
- [MCP Security Best Practices](https://mcp.harishgarg.com/learn/mcp-security-best-practices) - Najlepsze praktyki bezpieczeństwa

#### Przeglądy i Analizy
- [The Future of AI Applications: MCP Servers](https://www.techradar.com/pro/the-future-of-ai-applications-mcp-servers) - Przegląd przyszłości aplikacji AI z MCP
- [What is Model Context Protocol (MCP)?](https://www.itpro.com/technology/artificial-intelligence/what-is-model-context-protocol-mcp) - Wprowadzenie do MCP
- [Model Context Protocol - Wikipedia](https://en.wikipedia.org/wiki/Model_Context_Protocol) - Ogólne informacje o protokole

### Badania i Benchmarki
- [MCP-Bench: Benchmarking LLM Agents with MCP](https://arxiv.org/abs/2508.20453) - Narzędzie do benchmarkingu agentów LLM wykorzystujących MCP
- [MCP Safety Audit](https://arxiv.org/abs/2504.03767) - Analiza bezpieczeństwa LLM korzystających z MCP

### Cache'owanie i Optymalizacja API - Najnowsze Źródła (2024-2025)

#### Biblioteki i Narzędzia
- **[keyv](https://github.com/jaredwray/keyv)** - Uniwersalny key-value store z adapterami dla Redis, Memcached, MongoDB, PostgreSQL, SQLite. Idealny do multi-layer caching.
- **[cache-manager](https://github.com/node-cache-manager/node-cache-manager)** - Elastyczny system cache'owania z wieloma backendami i strategiami TTL.
- **[ioredis](https://github.com/redis/ioredis)** - Zaawansowany Redis client z cluster support, pub/sub, pipeline i TypeScript support.
- **[lru-cache](https://github.com/isaacs/node-lru-cache)** - Wysokowydajna implementacja LRU cache z TypeScript, idealna dla in-memory caching.
- **[axios-cache-interceptor](https://github.com/arthurfioretto/axios-cache-interceptor)** - Cache interceptor dla Axios z obsługą HTTP cache headers (ETag, Last-Modified, Cache-Control).
- **[axios-retry](https://github.com/softonic/axios-retry)** - Automatyczne ponawianie żądań z exponential backoff i konfigurowalnymi strategiami.
- **[bottleneck](https://github.com/SGrondin/bottleneck)** - Zaawansowany rate limiter z queue management, priority support i distributed rate limiting.
- **[p-limit](https://github.com/sindresorhus/p-limit)** - Kontrola współbieżności dla równoległych operacji API z Promise-based API.

#### Wzorce i Strategie Cache'owania
- **[Stale-While-Revalidate Pattern](https://web.dev/stale-while-revalidate/)** - Strategia cache'owania zapewniająca szybkie odpowiedzi przy jednoczesnej aktualizacji danych w tle.
- **[Cache-Aside Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside)** - Wzorzec cache'owania, gdzie aplikacja zarządza cache'em niezależnie od źródła danych.
- **[HTTP Caching Best Practices](https://web.dev/http-cache/)** - Najlepsze praktyki wykorzystania HTTP cache headers (Cache-Control, ETag, Last-Modified).
- **[Redis Caching Patterns](https://redis.io/docs/manual/patterns/)** - Oficjalne wzorce cache'owania w Redis z przykładami użycia.

#### Rate Limiting i Circuit Breaker
- **[Rate Limiting Strategies](https://www.cloudflare.com/learning/bots/what-is-rate-limiting/)** - Przegląd strategii rate limiting (Token Bucket, Sliding Window, Fixed Window).
- **[Circuit Breaker Pattern](https://martinfowler.com/bliki/CircuitBreaker.html)** - Wzorzec projektowy dla odporności na błędy w systemach rozproszonych.
- **[Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)** - Strategie ponawiania żądań z losowym opóźnieniem.

#### Optymalizacja Zapytań API
- **[Request Deduplication](https://www.patterns.dev/posts/request-deduplication-pattern/)** - Wzorzec eliminujący duplikaty równoległych żądań.
- **[API Batching Best Practices](https://www.apollographql.com/blog/query-batching-in-graphql/)** - Najlepsze praktyki grupowania zapytań (GraphQL, REST).
- **[Pagination Strategies](https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/)** - Strategie paginacji i filtrowania w API.

#### Monitoring i Performance
- **[Node.js Performance Best Practices](https://nodejs.org/en/docs/guides/simple-profiling/)** - Oficjalne wytyczne optymalizacji wydajności Node.js.
- **[Redis Performance Optimization](https://redis.io/docs/manual/optimization/)** - Optymalizacja wydajności Redis dla cache'owania.
- **[Application Performance Monitoring](https://www.datadoghq.com/knowledge-center/application-monitoring/)** - Monitorowanie wydajności aplikacji i identyfikacja wąskich gardeł.

#### Artykuły i Przewodniki (2024-2025)
- **[Node.js Caching Strategies: A Complete Guide](https://blog.logrocket.com/node-js-caching-complete-guide/)** - Kompleksowy przewodnik po strategiach cache'owania w Node.js.
- **[Building Resilient APIs with Rate Limiting](https://www.twilio.com/blog/building-resilient-apis-rate-limiting-node-js)** - Budowanie odpornych API z rate limiting w Node.js.
- **[Optimizing External API Calls in Node.js](https://www.digitalocean.com/community/tutorials/node-js-optimizing-external-api-calls)** - Optymalizacja wywołań zewnętrznych API w Node.js.
- **[Redis vs Memcached: Which Caching Solution is Right for You?](https://www.alibabacloud.com/blog/redis-vs-memcached-which-caching-solution-is-right-for-you_595820)** - Porównanie rozwiązań cache'owania.

### Firecrawl Integration - Analiza i Rekomendacje

#### 🔥 Czym jest Firecrawl?

[Firecrawl](https://github.com/firecrawl/firecrawl) to zaawansowany serwis API do konwersji całych stron internetowych na czysty markdown lub strukturalne dane gotowe dla LLM. Projekt ma **68.6k gwiazdek** na GitHub i jest aktywnie rozwijany.

**Kluczowe funkcjonalności:**
- 🔍 **Crawling całych stron** - Automatyczne przechodzenie przez wszystkie dostępne podstrony
- 📄 **Markdown conversion** - Konwersja HTML do czystego markdown
- 🤖 **LLM Extraction** - Ekstrakcja strukturalnych danych z użyciem LLM (Zod/Pydantic schemas)
- 🎯 **Actions support** - Interakcje z dynamicznymi stronami (kliknięcia, wpisywanie tekstu, screenshoty)
- 📦 **Batch scraping** - Równoległe przetwarzanie wielu URL
- 🔄 **MCP Support** - Oficjalne wsparcie dla Model Context Protocol

#### ⚖️ Self-Hosted vs Cloud - Analiza

**Status Self-Hosted (2024-2025):**
> ⚠️ **Ważne:** Według oficjalnego README: *"This repository is in development, and we're still integrating custom modules into the mono repo. It's not fully ready for self-hosted deployment yet, but you can run it locally."*

**Self-Hosted - Zalety:**
- ✅ **Kontrola nad danymi** - Wszystkie dane pozostają w Twojej infrastrukturze
- ✅ **Brak limitów API** - Nieograniczone użycie (zależne od zasobów)
- ✅ **Customizacja** - Możliwość modyfikacji kodu pod własne potrzeby
- ✅ **Koszty** - Brak opłat za użycie (tylko koszty infrastruktury)
- ✅ **AGPL-3.0 License** - Open source, możliwość modyfikacji

**Self-Hosted - Wady:**
- ❌ **Nie gotowy do produkcji** - Projekt wciąż w development
- ❌ **Wymaga zasobów** - Większe zapotrzebowanie na CPU/RAM niż prosty WebFetch
- ❌ **Maintenance** - Wymaga własnej konserwacji i aktualizacji
- ❌ **Brak niektórych funkcji** - Cloud wersja ma więcej funkcji (Actions, advanced extraction)
- ❌ **Kompleksowość** - Większa złożoność niż obecny WebFetch z Cheerio

**Cloud Offering - Zalety:**
- ✅ **Gotowe do użycia** - Natychmiastowa dostępność
- ✅ **Więcej funkcji** - Actions, advanced extraction, lepsze wsparcie dla dynamicznych stron
- ✅ **Maintenance** - Brak konieczności utrzymywania infrastruktury
- ✅ **Skalowalność** - Automatyczne skalowanie
- ✅ **MCP Server** - Gotowy MCP server dostępny

**Cloud Offering - Wady:**
- ❌ **Koszty** - Płatne API (z darmowym tierem)
- ❌ **Limity** - Ograniczenia w darmowym planie
- ❌ **Zależność zewnętrzna** - Zależność od zewnętrznego serwisu
- ❌ **Dane poza infrastrukturą** - URL są wysyłane do zewnętrznego API

#### 🎯 Rekomendacja dla MCP Server

**Dla obecnego projektu MCP Server:**

1. **Krótkoterminowo (Faza 1-2):**
   - ✅ **Zostań przy WebFetch + Cheerio** - Prostsze, lżejsze, wystarczające dla większości przypadków
   - ✅ **Dodaj Firecrawl jako opcjonalną integrację** - Dla zaawansowanych przypadków użycia

2. **Średnioterminowo (Faza 3-4):**
   - 🔄 **Rozważ Firecrawl Cloud API** - Jako uzupełnienie dla:
     - Crawling całych stron (nie tylko pojedyncze URL)
     - LLM extraction (strukturalne dane)
     - Dynamiczne strony wymagające interakcji
   - 🔄 **Monitoruj rozwój self-hosted** - Gdy będzie gotowy do produkcji, rozważ migrację

3. **Długoterminowo:**
   - 🎯 **Hybrid approach** - WebFetch dla prostych przypadków, Firecrawl dla zaawansowanych
   - 🎯 **Self-hosted Firecrawl** - Gdy będzie stabilny, rozważ jako alternatywę

#### 💡 Proponowana Implementacja

**Opcja 1: Firecrawl jako opcjonalne narzędzie**
```typescript
// src/tools/webfetch-firecrawl.ts
import Firecrawl from '@mendable/firecrawl-js';

export class FirecrawlTool extends BaseTool {
  name = 'firecrawl_scrape';
  description = 'Advanced web scraping with Firecrawl (crawling, LLM extraction)';
  
  async execute(params: {
    url: string;
    crawl?: boolean; // Crawl entire site vs single page
    formats?: ('markdown' | 'html' | 'json')[];
    schema?: ZodSchema; // For LLM extraction
  }) {
    const firecrawl = new Firecrawl({ 
      apiKey: process.env.FIRECRAWL_API_KEY 
    });
    
    if (params.crawl) {
      return await firecrawl.crawl(params.url, {
        limit: 100,
        scrapeOptions: { formats: params.formats || ['markdown'] }
      });
    }
    
    return await firecrawl.scrape(params.url, {
      formats: params.formats || ['markdown'],
      ...(params.schema && { 
        formats: [{ type: 'json', schema: params.schema }] 
      })
    });
  }
}
```

**Opcja 2: Integracja z istniejącym WebFetch**
- WebFetch używa prostego Cheerio (szybkie, lekkie)
- Firecrawl jako fallback dla trudnych przypadków (dynamiczne strony, crawling)

#### 📚 Zasoby Firecrawl

- **[Firecrawl GitHub](https://github.com/firecrawl/firecrawl)** - Oficjalne repozytorium (68.6k ⭐)
- **[Firecrawl Documentation](https://docs.firecrawl.dev/)** - Kompleksowa dokumentacja API
- **[Firecrawl Cloud](https://firecrawl.dev/)** - Hosted version z playground
- **[Firecrawl MCP](https://github.com/firecrawl/firecrawl-mcp)** - Oficjalny MCP server dla Firecrawl
- **[Node.js SDK](https://www.npmjs.com/package/@mendable/firecrawl-js)** - `@mendable/firecrawl-js`
- **[Python SDK](https://pypi.org/project/firecrawl-py/)** - `firecrawl-py`

#### ⚠️ Uwagi Prawne

> **Ważne:** Firecrawl domyślnie respektuje `robots.txt`. Użytkownicy są odpowiedzialni za przestrzeganie polityk stron internetowych podczas scrapingu. Zawsze sprawdzaj Terms of Service i robots.txt przed crawlingiem.

### API Documentation
- [Amazon Product Advertising API](https://webservices.amazon.com/paapi5/documentation/)
- [eBay API](https://developer.ebay.com/)
- [Allegro API](https://developer.allegro.pl/)
- [arXiv API](https://arxiv.org/help/api/)
- [PubMed API](https://www.ncbi.nlm.nih.gov/home/develop/api/)
- [GitHub API](https://docs.github.com/en/rest)
- [Twitter API](https://developer.twitter.com/en/docs/twitter-api)
- [Reddit API](https://www.reddit.com/dev/api/)

---

## 🔒 Bezpieczeństwo

### Najlepsze Praktyki

Implementacja serwera MCP wymaga szczególnej uwagi na bezpieczeństwo, ponieważ serwer może mieć dostęp do wrażliwych danych i zewnętrznych systemów.

#### 1. Uwierzytelnianie i Autoryzacja
- **API Keys**: Przechowuj klucze API w zmiennych środowiskowych, nigdy w kodzie
- **Szyfrowanie**: Używaj szyfrowania dla wrażliwych danych (np. `flutter_secure_storage` dla Flutter)
- **Role-Based Access Control (RBAC)**: Implementuj kontrolę dostępu do narzędzi i zasobów
- **Rate Limiting**: Ogranicz liczbę żądań na użytkownika/IP, aby zapobiec nadużyciom

#### 2. Walidacja Danych
- **Input Validation**: Waliduj wszystkie dane wejściowe używając Zod lub podobnych narzędzi
- **Sanitization**: Oczyszczaj dane przed przetwarzaniem (szczególnie dla web scraping)
- **Schema Validation**: Używaj silnych schematów walidacji dla wszystkich parametrów narzędzi

#### 3. Bezpieczeństwo API
- **HTTPS Only**: Wymuszaj połączenia HTTPS dla wszystkich zewnętrznych API calls
- **Timeout Protection**: Ustaw rozsądne timeouty dla wszystkich żądań zewnętrznych
- **Error Handling**: Nie ujawniaj wrażliwych informacji w komunikatach błędów
- **Request Signing**: Podpisuj żądania do zewnętrznych API (np. Amazon Product Advertising API)

#### 4. Ochrona przed Atakami
- **Prompt Injection**: Waliduj i filtruj dane przed wysłaniem do LLM
- **SQL Injection**: Używaj parametryzowanych zapytań (jeśli używasz bazy danych)
- **XSS Protection**: Sanityzuj dane HTML przed wyświetleniem
- **CSRF Protection**: Implementuj tokeny CSRF dla operacji modyfikujących dane

#### 5. Monitoring i Logging
- **Audit Logs**: Loguj wszystkie operacje na wrażliwych danych
- **Error Tracking**: Monitoruj błędy i nieprawidłowe próby dostępu
- **Performance Monitoring**: Śledź wydajność i wykrywaj anomalie

#### 6. Konfiguracja Środowiska
- **Environment Variables**: Używaj `.env` dla konfiguracji, dodaj `.env` do `.gitignore`
- **Secrets Management**: Rozważ użycie narzędzi do zarządzania sekretami (np. AWS Secrets Manager, HashiCorp Vault)
- **Least Privilege**: Nadawaj minimalne wymagane uprawnienia

### Zasoby Bezpieczeństwa
- [MCP Security Best Practices](https://mcp.harishgarg.com/learn/mcp-security-best-practices) - Kompleksowy przewodnik
- [MCP Safety Audit Research](https://arxiv.org/abs/2504.03767) - Analiza luk bezpieczeństwa
- [OpenAI Platform Security](https://platform.openai.com/docs/mcp/) - Wytyczne bezpieczeństwa OpenAI

> [!WARNING]
> Zawsze testuj swoje narzędzia w środowisku izolowanym przed wdrożeniem produkcyjnym. Nie ufaj danym wejściowym i zawsze waliduj parametry przed wykonaniem operacji.

---

## 🚧 Roadmap

### Faza 1: Core Infrastructure ✅
- [x] Struktura projektu
- [x] Bazowa klasa narzędzi
- [x] System walidacji
- [x] Logging

### Faza 2: Basic Search Tools (W trakcie)
- [ ] General web search (Google, Bing)
- [ ] WebFetch tool
- [ ] Type conversion tools
- [ ] MCP server setup

### Faza 3: Specialized Search
- [ ] E-commerce search (Amazon, eBay, Allegro)
- [ ] Scientific publications (arXiv, PubMed)
- [ ] Code repositories (GitHub, npm, PyPI)
- [ ] Social media (Twitter, Reddit, YouTube)

### Faza 4: Advanced Features (W trakcie)
- [ ] **Multi-layer caching system**
  - [ ] L1: In-memory cache (lru-cache/node-cache)
  - [ ] L2: Redis cache dla współdzielonych danych
  - [ ] L3: HTTP cache headers (ETag, Cache-Control)
  - [ ] Cache invalidation strategies (TTL, tag-based, manual)
- [ ] **Request optimization**
  - [ ] Request deduplication dla równoległych żądań
  - [ ] Batching zapytań (gdy API wspiera)
  - [ ] Intelligent pagination
  - [ ] Field filtering
- [ ] **Rate limiting & circuit breaker**
  - [ ] Token bucket rate limiter (bottleneck)
  - [ ] Per-API rate limit tracking
  - [ ] Circuit breaker pattern
  - [ ] Queue management dla throttled requests
- [ ] **Data aggregation**
  - [ ] Równoległe wyszukiwanie w wielu platformach
  - [ ] Deduplikacja wyników
  - [ ] Normalizacja formatów odpowiedzi
  - [ ] Ranking i sortowanie zagregowanych wyników
- [ ] **Advanced filtering**
  - [ ] Composite filters
  - [ ] Full-text search optimization
  - [ ] Faceted search
- [ ] **Error recovery & resilience**
  - [ ] Exponential backoff retry strategy
  - [ ] Fallback to cache on API errors
  - [ ] Graceful degradation
  - [ ] Health checks dla zewnętrznych API

### Faza 5: Polish & Optimization
- [ ] Comprehensive tests
- [ ] Performance optimization
- [ ] Documentation
- [ ] Example integrations

---

## 📄 Licencja

MIT License - możesz swobodnie używać i modyfikować ten projekt.

---

## 🤝 Contributing

Contributions are welcome! Jeśli chcesz dodać nowe źródło wyszukiwania lub poprawić istniejące:

1. Fork projektu
2. Utwórz branch (`git checkout -b feature/new-search-source`)
3. Commit zmian (`git commit -m 'Add new search source'`)
4. Push do brancha (`git push origin feature/new-search-source`)
5. Otwórz Pull Request

---

## 💡 Use Cases

### Research Assistant
```
Agent: Znajdź najnowsze publikacje o "quantum computing" na arXiv,
       następnie wyszukaj implementacje na GitHub i podsumuj stan badań.
```

### Product Comparison
```
Agent: Porównaj ceny iPhone 15 Pro na Amazon, eBay i Allegro,
       pokaż najlepsze oferty z dobrymi ocenami.
```

### Developer Tools Discovery
```
Agent: Znajdź popularne biblioteki TypeScript do walidacji danych,
       sprawdź ich dokumentację i przykłady użycia.
```

### Trend Analysis
```
Agent: Sprawdź co jest teraz popularne na Reddit i Twitter w temacie AI,
       znajdź powiązane artykuły naukowe i projekty na GitHub.
```

---

## 📦 Instalacja i Konfiguracja

> [!NOTE]
> Ta sekcja zawiera podstawowe informacje o instalacji. Szczegółowa dokumentacja funkcjonalności znajduje się w sekcjach powyżej.

### Wymagania
- **Node.js** 20.x lub wyższy
- **npm** lub **yarn**
- **API Keys** (opcjonalne, w zależności od używanych narzędzi)
- **Redis** (opcjonalne, dla L2 cache - zalecane dla produkcji)

### Szybki Start

```bash
# Klonowanie i instalacja
git clone <repo-url>
cd mcp-server
npm install

# Konfiguracja (opcjonalna)
cp .env.example .env
# Edytuj .env i dodaj API keys

# Instalacja zależności cache'owania (opcjonalne)
npm install keyv @keyv/redis ioredis lru-cache bottleneck axios-retry axios-cache-interceptor p-limit

# Build i uruchomienie
npm run build
npm start
```

### Konfiguracja Cache'owania i Optymalizacji

#### Przykładowy plik `.env`

```bash
# Redis Configuration (opcjonalne, dla L2 cache)
REDIS_URL=redis://localhost:6379
REDIS_TTL=1800000  # 30 minut w milisekundach

# Cache Configuration
CACHE_ENABLED=true
CACHE_L1_MAX_SIZE=500
CACHE_L1_TTL=300000  # 5 minut
CACHE_L2_TTL=1800000  # 30 minut

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_CONCURRENT=5
RATE_LIMIT_MIN_TIME=1000  # minimum time between requests (ms)

# Circuit Breaker
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60000  # 1 minute

# Retry Configuration
RETRY_ENABLED=true
RETRY_ATTEMPTS=3
RETRY_DELAY=1000  # initial delay (ms)
```

#### Przykładowe zależności w `package.json`

```json
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "axios": "^1.6.0",
    "axios-retry": "^4.0.0",
    "axios-cache-interceptor": "^1.5.0",
    "bottleneck": "^2.19.5",
    "cheerio": "^1.0.0",
    "keyv": "^4.5.0",
    "@keyv/redis": "^2.8.0",
    "ioredis": "^5.3.0",
    "lru-cache": "^10.0.0",
    "p-limit": "^5.0.0",
    "zod": "^3.22.0"
  }
}
```

### Integracja z Klientami AI

**Cursor AI**: Dodaj do `~/.cursor/config.json`:
```json
{
  "mcpServers": {
    "specialized-search": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
    }
  }
}
```

**Claude Desktop**: Edytuj plik konfiguracyjny (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`)

**Flutter/Dart**: Zobacz sekcję [Integracja z Flutter/Dart](#integracja-z-flutterdart-ai-code-box) w dokumentacji zasobów.

> [!TIP]
> Większość narzędzi ma darmowe tier API. Serwer działa z dostępnymi narzędziami - narzędzia bez skonfigurowanych kluczy są automatycznie wyłączone.

---

**Status projektu:** 🚧 W trakcie implementacji - Faza 1 & 2

Projekt jest aktywnie rozwijany. Podstawowa infrastruktura gotowa, implementacja narzędzi wyszukiwania w toku!

### ✨ Najnowsze Aktualizacje (2024-2025)

**Cache'owanie i Optymalizacja:**
- ✅ Dokumentacja multi-layer caching (L1: in-memory, L2: Redis)
- ✅ Strategie cache'owania: Cache-Aside, Stale-While-Revalidate, Tag-Based Invalidation
- ✅ Request deduplication i batching
- ✅ Rate limiting z bottleneck i p-limit
- ✅ Circuit breaker pattern dla odporności na błędy
- ✅ Przykłady implementacji z keyv, ioredis, lru-cache
- ✅ Integracja z axios-retry i axios-cache-interceptor
- ✅ Kompleksowa dokumentacja zasobów i najlepszych praktyk

**Zasoby:**
- 📚 20+ nowych źródeł dotyczących cache'owania i optymalizacji API
- 🔧 Przykłady kodu dla wszystkich wzorców projektowych
- 📖 Konfiguracja środowiska i zależności
- 🎯 Roadmap z szczegółowym planem implementacji