Skip to main content
Glama
brendon92

Specialized AI Search Tools

by brendon92
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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

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

  2. AI wywołuje scientific_publications_search z parametrami:

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

  3. AI następnie wywołuje repositories_search:

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

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

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

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

  1. 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

  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:

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ą

  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

Open-Source Repozytoria MCP Server

TypeScript/Node.js Implementacje

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

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

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

Przeglądy i Analizy

Badania i Benchmarki

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

Rate Limiting i Circuit Breaker

Optymalizacja Zapytań API

Monitoring i Performance

Artykuły i Przewodniki (2024-2025)

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:

  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

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

⚠️ 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

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)

  • 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

# 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

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/brendon92/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server