mcp-server by brendon92 - MCP Server

🤖 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

Standardyzacja Integracji: MCP zapewnia jednolity sposób łączenia AI z różnymi systemami, eliminując fragmentację w ekosystemie AI
Modularność: Serwery MCP są niezależnymi modułami, które można łatwo dodawać, usuwać i konfigurować
Bezpieczeństwo: Protokół został zaprojektowany z myślą o bezpieczeństwie, z kontrolą dostępu i walidacją danych
Elastyczność: Obsługa różnych transportów (STDIO, HTTP+SSE) i formatów danych
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) │
└─────────────┘         └──────────────┘         └─────────────┘

Inicjalizacja: Klient AI łączy się z serwerem MCP przez wybrany transport (STDIO/HTTP+SSE)
Odkrywanie: Klient pobiera listę dostępnych narzędzi, zasobów i promptów
Użycie: AI wywołuje narzędzia lub odczytuje zasoby w odpowiedzi na zapytania użytkownika
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 jako zaawansowanej alternatywy lub uzupełnienia dla WebFetch. Zobacz sekcję Firecrawl Integration 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:

Użytkownik: "Znajdź najnowsze publikacje o quantum computing"

AI wywołuje scientific_publications_search z parametrami:

{
  query: "quantum computing",
  database: "arxiv",
  dateFrom: "2024-01-01",
  sortBy: "date"
}

AI następnie wywołuje repositories_search:

{
  query: "quantum computing implementation",
  platform: "github",
  language: "python",
  minStars: 100
}

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:

Użytkownik: "Porównaj ceny iPhone 15 Pro na różnych platformach"
AI równolegle wywołuje narzędzia dla każdej platformy:
- ecommerce_search (platform: "amazon")
- ecommerce_search (platform: "ebay")
- ecommerce_search (platform: "allegro")
AI agreguje wyniki, normalizuje formaty i porównuje ceny
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:

Użytkownik: "Znajdź biblioteki do walidacji danych w TypeScript"

AI wywołuje repositories_search:

{
  query: "data validation",
  platform: "github",
  language: "typescript",
  minStars: 500,
  sortBy: "stars"
}

AI następnie używa webfetch do pobrania dokumentacji najlepszych wyników
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:

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:

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:

// 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:

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:

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:

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:

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:

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:

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:

// 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:

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

Format odpowiedzi:

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

# 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

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

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

Zarejestruj w src/tools/index.ts:

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

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

Implementacja Cache'owania

Przykład: Multi-Layer Cache z keyv

// 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

// 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

// 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

// 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

// 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

# 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

Modularność: Każde narzędzie wyszukiwania jest niezależnym modułem, łatwym do dodania/usunięcia
Walidacja Schematów: Wszystkie parametry narzędzi są walidowane przez Zod przed wykonaniem
Error Handling: Centralny system obsługi błędów z informatywnymi komunikatami
Multi-Layer Caching: Inteligentne cachowanie wyników wyszukiwań w wielu warstwach (L1: in-memory, L2: Redis) dla poprawy wydajności
Request Optimization: Deduplikacja żądań, batching, i paginacja dla minimalizacji wywołań API
Rate Limiting & Resilience: Rate limiting per API, circuit breaker pattern, i exponential backoff retry
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:

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:

export const tools = [
  new AmazonSearchTool(),
  new GitHubSearchTool(),
  // ... inne narzędzia
];

3. Adapter Pattern

Normalizacja różnych formatów odpowiedzi API do jednolitego formatu MCP:

class SearchResultAdapter {
  normalize(apiResponse: unknown): MCPToolResult {
    // Konwersja do standardowego formatu
  }
}

Przepływ Danych z Cache'owaniem i Optymalizacją

Żądanie od AI: Klient AI wysyła żądanie wywołania narzędzia z parametrami
Walidacja: Parametry są walidowane przez schemat Zod
Cache Check (L1): Sprawdzenie in-memory cache dla szybkiego dostępu
Request Deduplication: Sprawdzenie, czy identyczne żądanie jest już w trakcie przetwarzania
Rate Limiting Check: Weryfikacja limitów dla danego API endpoint
Cache Check (L2): Jeśli L1 miss, sprawdzenie Redis cache
Circuit Breaker Check: Weryfikacja stanu circuit breakera dla API
Wykonanie: Narzędzie wykonuje zapytanie do zewnętrznego API (z retry logic)
Przetwarzanie: Odpowiedź API jest parsowana i normalizowana
Caching: Wynik jest cachowany w L1 i L2 (z TTL i tagami)
Odpowiedź: Znormalizowany wynik jest zwracany do klienta AI
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 - Oficjalna dokumentacja MCP
MCP SDK GitHub - Oficjalne SDK dla różnych języków
MCP Specification - Pełna specyfikacja protokołu
Cursor AI MCP Integration - Integracja MCP z Cursor AI
Claude Desktop MCP Guide - Przewodnik integracji z Claude Desktop
OpenAI MCP Server Documentation - Dokumentacja OpenAI dotycząca MCP Server

Open-Source Repozytoria MCP Server

TypeScript/Node.js Implementacje

MCP SDK TypeScript - Oficjalne SDK TypeScript
Learn MCP by Building - Przewodnik krok po kroku z przykładami
OPNsense MCP Server - Przykład integracji z OPNsense API

Flutter/Dart Implementacje (dla integracji z AI Code Box)

flutter_mcp_server - Open-source implementacja MCP dla Flutter/Dart
mcp_dart - SDK MCP w Dart, umożliwiające tworzenie serwerów i klientów
mcp_flutter - MCP Server i Toolkit dla Flutter z dynamiczną rejestracją narzędzi
figma-flutter-mcp - MCP Server konwertujący projekty Figma na kod Flutter
Flutter MCP Server Documentation - 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:

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 - Pełne SDK MCP dla Dart
mcp_flutter - Flutter-specific MCP toolkit
dio - HTTP client dla komunikacji z Node.js serverem

Inne Implementacje

Java MCP Server - Implementacja w Javie
Python MCP Examples - Przykłady w Pythonie

Artykuły i Najlepsze Praktyki

Podstawowe Wprowadzenie do MCP

MCP Explained: The New Standard Connecting AI to Everything - 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 - 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 - Zaawansowane techniki implementacji i skalowania systemów AI z MCP
MCP Security: Best Practices & Implementation Guide - Wytyczne dotyczące zabezpieczania serwera MCP
MCP Security Best Practices - Najlepsze praktyki bezpieczeństwa

Przeglądy i Analizy

The Future of AI Applications: MCP Servers - Przegląd przyszłości aplikacji AI z MCP
What is Model Context Protocol (MCP)? - Wprowadzenie do MCP
Model Context Protocol - Wikipedia - Ogólne informacje o protokole

Badania i Benchmarki

MCP-Bench: Benchmarking LLM Agents with MCP - Narzędzie do benchmarkingu agentów LLM wykorzystujących MCP
MCP Safety Audit - Analiza bezpieczeństwa LLM korzystających z MCP

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

Biblioteki i Narzędzia

keyv - Uniwersalny key-value store z adapterami dla Redis, Memcached, MongoDB, PostgreSQL, SQLite. Idealny do multi-layer caching.
cache-manager - Elastyczny system cache'owania z wieloma backendami i strategiami TTL.
ioredis - Zaawansowany Redis client z cluster support, pub/sub, pipeline i TypeScript support.
lru-cache - Wysokowydajna implementacja LRU cache z TypeScript, idealna dla in-memory caching.
axios-cache-interceptor - Cache interceptor dla Axios z obsługą HTTP cache headers (ETag, Last-Modified, Cache-Control).
axios-retry - Automatyczne ponawianie żądań z exponential backoff i konfigurowalnymi strategiami.
bottleneck - Zaawansowany rate limiter z queue management, priority support i distributed rate limiting.
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 - Strategia cache'owania zapewniająca szybkie odpowiedzi przy jednoczesnej aktualizacji danych w tle.
Cache-Aside Pattern - Wzorzec cache'owania, gdzie aplikacja zarządza cache'em niezależnie od źródła danych.
HTTP Caching Best Practices - Najlepsze praktyki wykorzystania HTTP cache headers (Cache-Control, ETag, Last-Modified).
Redis Caching Patterns - Oficjalne wzorce cache'owania w Redis z przykładami użycia.

Rate Limiting i Circuit Breaker

Rate Limiting Strategies - Przegląd strategii rate limiting (Token Bucket, Sliding Window, Fixed Window).
Circuit Breaker Pattern - Wzorzec projektowy dla odporności na błędy w systemach rozproszonych.
Exponential Backoff and Jitter - Strategie ponawiania żądań z losowym opóźnieniem.

Optymalizacja Zapytań API

Request Deduplication - Wzorzec eliminujący duplikaty równoległych żądań.
API Batching Best Practices - Najlepsze praktyki grupowania zapytań (GraphQL, REST).
Pagination Strategies - Strategie paginacji i filtrowania w API.

Monitoring i Performance

Node.js Performance Best Practices - Oficjalne wytyczne optymalizacji wydajności Node.js.
Redis Performance Optimization - Optymalizacja wydajności Redis dla cache'owania.
Application Performance Monitoring - Monitorowanie wydajności aplikacji i identyfikacja wąskich gardeł.

Artykuły i Przewodniki (2024-2025)

Node.js Caching Strategies: A Complete Guide - Kompleksowy przewodnik po strategiach cache'owania w Node.js.
Building Resilient APIs with Rate Limiting - Budowanie odpornych API z rate limiting w Node.js.
Optimizing External API Calls in Node.js - Optymalizacja wywołań zewnętrznych API w Node.js.
Redis vs Memcached: Which Caching Solution is Right for You? - Porównanie rozwiązań cache'owania.

Firecrawl Integration - Analiza i Rekomendacje

🔥 Czym jest 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:

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
Ś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ę
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

// 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 - Oficjalne repozytorium (68.6k ⭐)
Firecrawl Documentation - Kompleksowa dokumentacja API
Firecrawl Cloud - Hosted version z playground
Firecrawl MCP - Oficjalny MCP server dla Firecrawl
Node.js SDK - @mendable/firecrawl-js
Python SDK - 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

🔒 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 - Kompleksowy przewodnik
MCP Safety Audit Research - Analiza luk bezpieczeństwa
OpenAI Platform Security - 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 ✅

Struktura projektu
Bazowa klasa narzędzi
System walidacji
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)

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:

Fork projektu
Utwórz branch (git checkout -b feature/new-search-source)
Commit zmian (git commit -m 'Add new search source')
Push do brancha (git push origin feature/new-search-source)
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

# 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`

# 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`

{
  "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:

{
  "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 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