README.md•61 kB
# 🤖 MCP Server - Specialized AI Search Tools
Zaawansowany **Model Context Protocol (MCP) Server** z wyspecjalizowanymi narzędziami wyszukiwania dla agentów AI, zbudowany w Node.js i TypeScript.
## 🚀 Implementation Status
### ✅ Phase 1: Core Infrastructure (COMPLETED)
- ✅ MCP Server setup with STDIO transport
- ✅ BaseTool class with Zod validation
- ✅ Logging system
- ✅ TypeScript configuration
- ✅ Development environment (ESLint, Prettier)
### ✅ Phase 2: Basic Search Tools (COMPLETED)
- ✅ **WebSearchTool** - Search with DuckDuckGo, Brave, Google, Bing
- ✅ **WebFetchTool** - Fetch and parse HTML content
- ✅ **TypeConversionTool** - Convert between JSON, XML, YAML, CSV, TOML
- ⏳ Unit tests (pending)
### ⏸️ Phase 3: Specialized Search Tools (PLANNED)
- ⏸️ E-commerce search (Amazon, eBay, Allegro, AliExpress, Etsy)
- ⏸️ Scientific publications (arXiv, PubMed, Google Scholar, IEEE)
- ⏸️ Code repositories (GitHub, GitLab, npm, PyPI, Docker Hub)
- ⏸️ Social media (Twitter/X, Reddit, LinkedIn, YouTube, Hacker News)
### ⏸️ Phase 4: Advanced Features (PLANNED)
- ⏸️ Multi-layer caching (L1/L2/L3)
- ⏸️ Request optimization and deduplication
- ⏸️ Rate limiting and circuit breaker
- ⏸️ Data aggregation and ranking
---
## 📖 O Model Context Protocol (MCP)
### Czym jest MCP?
**Model Context Protocol (MCP)** to otwarty standard wprowadzony przez Anthropic, który standaryzuje sposób, w jaki aplikacje AI komunikują się z zewnętrznymi narzędziami, usługami i źródłami danych. MCP eliminuje potrzebę tworzenia dedykowanych integracji dla każdego narzędzia, oferując uniwersalny protokół komunikacji.
### Kluczowe Założenia Projektowe
1. **Standardyzacja Integracji**: MCP zapewnia jednolity sposób łączenia AI z różnymi systemami, eliminując fragmentację w ekosystemie AI
2. **Modularność**: Serwery MCP są niezależnymi modułami, które można łatwo dodawać, usuwać i konfigurować
3. **Bezpieczeństwo**: Protokół został zaprojektowany z myślą o bezpieczeństwie, z kontrolą dostępu i walidacją danych
4. **Elastyczność**: Obsługa różnych transportów (STDIO, HTTP+SSE) i formatów danych
5. **Open Source**: Otwarty standard dostępny dla wszystkich, promujący interoperacyjność
### Architektura MCP
MCP składa się z trzech głównych komponentów:
#### 1. **Tools (Narzędzia)**
Funkcje, które AI może wywołać do wykonania konkretnych akcji:
- **Definicja**: Każde narzędzie ma nazwę, opis i schemat parametrów (JSON Schema)
- **Wykonanie**: Narzędzie przyjmuje parametry i zwraca wynik
- **Przykłady**: Wyszukiwanie w bazie danych, wysyłanie emaili, wykonywanie obliczeń
#### 2. **Resources (Zasoby)**
Dane, do których AI może uzyskać dostęp:
- **Definicja**: Zasób ma URI, nazwę, opis i typ MIME
- **Dostęp**: AI może odczytać zawartość zasobu na żądanie
- **Przykłady**: Pliki w systemie, wpisy w bazie danych, dokumenty w chmurze
#### 3. **Prompts (Prompty)**
Szablony promptów, które AI może wykorzystać:
- **Definicja**: Prompt ma nazwę, opis i opcjonalne argumenty
- **Użycie**: AI może wywołać prompt z argumentami, aby wygenerować gotowy prompt
- **Przykłady**: Szablony do code review, generowania dokumentacji, analizy danych
### Jak Działa MCP?
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ AI Client │◄──────►│ MCP Server │◄──────►│ External │
│ (Claude, │ MCP │ (This │ API │ Services │
│ Cursor) │Protocol│ Project) │ Calls │ (APIs, DB) │
└─────────────┘ └──────────────┘ └─────────────┘
```
1. **Inicjalizacja**: Klient AI łączy się z serwerem MCP przez wybrany transport (STDIO/HTTP+SSE)
2. **Odkrywanie**: Klient pobiera listę dostępnych narzędzi, zasobów i promptów
3. **Użycie**: AI wywołuje narzędzia lub odczytuje zasoby w odpowiedzi na zapytania użytkownika
4. **Wyniki**: Serwer MCP wykonuje operacje i zwraca wyniki do klienta AI
### Transporty MCP
- **STDIO (Standard Input/Output)**: Dla lokalnych integracji, proces komunikuje się przez stdin/stdout
- **HTTP+SSE (Server-Sent Events)**: Dla zdalnych serwerów, komunikacja przez HTTP z SSE dla strumieniowania
- **WebSocket**: (Planowane) Dla aplikacji webowych wymagających dwukierunkowej komunikacji
### Zalety MCP
✅ **Uniwersalność**: Jeden protokół dla wszystkich integracji
✅ **Bezpieczeństwo**: Kontrola dostępu i walidacja na poziomie protokołu
✅ **Skalowalność**: Łatwe dodawanie nowych narzędzi bez modyfikacji klienta
✅ **Interoperacyjność**: Różne klienty AI mogą używać tych samych serwerów MCP
✅ **Modularność**: Każdy serwer MCP jest niezależnym modułem funkcjonalności
---
## ✨ Wyspecjalizowane Narzędzia Wyszukiwania
### 🛒 E-commerce Search
Wyszukiwanie produktów w popularnych sklepach internetowych:
- **Obsługiwane platformy**: Amazon, eBay, Allegro, AliExpress, Etsy
- **Filtry**:
- 💰 Zakres cenowy (min-max)
- ⭐ Oceny (minimalna ocena, liczba opinii)
- 🚚 Dostępność i opcje wysyłki
- 🏷️ Kategorie produktów
- 🌍 Region sprzedawcy
- 📦 Stan produktu (nowy, używany, odnowiony)
- **Sortowanie**: cena, popularność, oceny, data dodania
- **Zwraca**: tytuł, cena, ocena, link, zdjęcie, dostępność
### 🔬 Scientific Publications Search
Wyszukiwanie publikacji naukowych i artykułów badawczych:
- **Obsługiwane bazy**: arXiv, PubMed, Google Scholar, IEEE Xplore, ResearchGate
- **Filtry**:
- 📅 Zakres dat publikacji
- 🏫 Afiliacja autorów
- 📄 Typ publikacji (artykuł, konferencja, preprint)
- 🔬 Dziedzina nauki
- 📊 Liczba cytowań (minimum)
- 🌐 Język publikacji
- **Sortowanie**: relevancja, data, cytowania
- **Zwraca**: tytuł, autorzy, abstrakt, DOI, PDF link, cytowania
### 💻 Hosting & Repositories Search
Wyszukiwanie kodu, pakietów i zasobów deweloperskich:
- **Obsługiwane platformy**: GitHub, GitLab, npm, PyPI, Docker Hub, Maven Central
- **Filtry**:
- 💻 Język programowania
- ⭐ Minimalna liczba gwiazdek/pobrań
- 📅 Ostatnia aktualizacja (aktywność projektu)
- 📜 Licencja (MIT, Apache, GPL, itp.)
- 🏷️ Tagi i tematy
- 👥 Liczba kontrybutorów
- **Sortowanie**: gwiazdki, forki, ostatnia aktualizacja, relevancja
- **Zwraca**: nazwa, opis, autor, gwiazdki, język, licencja, link
### 📱 Social Media Search
Wyszukiwanie treści w mediach społecznościowych:
- **Obsługiwane platformy**: Twitter/X, Reddit, LinkedIn, YouTube, Hacker News
- **Filtry**:
- 📅 Zakres czasowy (ostatnia godzina, dzień, tydzień, miesiąc)
- 🌍 Język i lokalizacja
- 👤 Autor/kanał
- 💬 Minimalna liczba interakcji (lajki, komentarze, udostępnienia)
- 🏷️ Hashtagi i słowa kluczowe
- 📊 Typ treści (tekst, obraz, wideo, link)
- **Sortowanie**: popularność, data, relevancja
- **Zwraca**: treść, autor, data, interakcje, link, media
### 🌐 General Web Search
Uniwersalne wyszukiwanie w internecie:
- **Obsługiwane silniki**: Google, Bing, DuckDuckGo, Brave Search
- **Filtry**:
- 📄 Formaty plików (PDF, DOCX, XLSX, CSV, JSON, XML, PPT)
- 🌍 Język i region
- 📅 Zakres dat
- 🔒 SafeSearch
- 🌐 Domena (np. tylko .edu, .gov)
- 📍 Dokładna fraza vs. podobne wyniki
- **Sortowanie**: relevancja, data
- **Zwraca**: tytuł, URL, snippet, data publikacji, typ pliku
---
## 🔧 Dodatkowe Funkcjonalności
### 🌐 WebFetch Tool
Pobieranie i parsowanie treści stron internetowych:
- Pobieranie HTML z dowolnego URL
- Parsowanie z wykorzystaniem Cheerio
- Ekstrakcja: tekst, nagłówki, linki, metadane, obrazy
- Obsługa selektorów CSS
- Timeout i error handling
- User-agent customization
> [!NOTE]
> **Alternatywa: Firecrawl Integration**
> Rozważ użycie [Firecrawl](https://github.com/firecrawl/firecrawl) jako zaawansowanej alternatywy lub uzupełnienia dla WebFetch. Zobacz sekcję [Firecrawl Integration](#firecrawl-integration-consideration) poniżej.
### 🔄 Type Conversion Tools
Konwersja między różnymi formatami danych:
- **Obsługiwane formaty**: JSON, XML, YAML, CSV, TOML
- **Konwersje**: JSON ↔ XML ↔ YAML ↔ CSV ↔ TOML
- Pretty printing i minification
- Walidacja struktury danych
- Obsługa zagnieżdżonych struktur
### 📊 Data Aggregation
Agregacja wyników z wielu źródeł:
- Równoległe wyszukiwanie w wielu platformach
- Deduplikacja wyników
- Normalizacja formatów odpowiedzi
- Ranking i sortowanie zagregowanych wyników
- Statystyki i podsumowania
### 🛠️ Extensible Architecture
Łatwe dodawanie własnych narzędzi:
- Bazowa klasa `BaseTool` z wspólną logiką
- Automatyczna walidacja z Zod
- Centralna rejestracja narzędzi
- Standardowy error handling
- Plugin system dla nowych źródeł danych
### ⚡ Cache'owanie i Optymalizacja Zapytań
#### Strategie Cache'owania
**1. Multi-Layer Caching**
- **L1 Cache (In-Memory)**: Szybki dostęp do często używanych wyników (node-cache/lru-cache)
- **L2 Cache (Redis)**: Dzielony cache między instancjami serwera
- **L3 Cache (HTTP Cache Headers)**: Wykorzystanie cache'u przeglądarki/CDN
**2. Cache Patterns**
- **Cache-Aside (Lazy Loading)**: Aplikacja sprawdza cache, jeśli brak - pobiera z API i zapisuje
- **Write-Through**: Zapis do cache i API jednocześnie
- **Stale-While-Revalidate**: Zwracanie przestarzałych danych podczas aktualizacji w tle
- **Time-Based Invalidation**: Automatyczne wygaszanie po określonym czasie (TTL)
- **Tag-Based Invalidation**: Inwalidacja po tagach dla precyzyjnej kontroli
**3. Request Optimization**
- **Request Deduplication**: Grupowanie identycznych równoległych żądań
- **Batching**: Łączenie wielu zapytań w jedno żądanie (gdy API wspiera)
- **Pagination**: Pobieranie danych w mniejszych porcjach
- **Field Filtering**: Pobieranie tylko wymaganych pól z API
**4. Rate Limiting & Circuit Breaker**
- **Token Bucket**: Kontrola przepustowości z tokenami
- **Sliding Window**: Ograniczenie liczby żądań w oknie czasowym
- **Circuit Breaker**: Automatyczne wyłączanie usługi przy błędach
- **Exponential Backoff**: Stopniowe zwiększanie opóźnień przy ponawianiu
**5. Monitoring & Metrics**
- Cache hit/miss ratio
- API response times
- Rate limit usage tracking
- Error rates per API endpoint
- Queue depth monitoring
---
## 📚 Dokumentacja Funkcjonalności i Przykłady
### 🎯 Scenariusze Użycia
#### Scenariusz 1: Research Assistant
**Cel**: Pomoc w badaniach naukowych poprzez agregację informacji z wielu źródeł
**Przepływ**:
1. Użytkownik: "Znajdź najnowsze publikacje o quantum computing"
2. AI wywołuje `scientific_publications_search` z parametrami:
```typescript
{
query: "quantum computing",
database: "arxiv",
dateFrom: "2024-01-01",
sortBy: "date"
}
```
3. AI następnie wywołuje `repositories_search`:
```typescript
{
query: "quantum computing implementation",
platform: "github",
language: "python",
minStars: 100
}
```
4. AI agreguje wyniki i generuje podsumowanie
**Wartość**: Automatyczna agregacja informacji z różnych źródeł w jednym miejscu
#### Scenariusz 2: Product Research & Comparison
**Cel**: Porównanie produktów z różnych platform e-commerce
**Przepływ**:
1. Użytkownik: "Porównaj ceny iPhone 15 Pro na różnych platformach"
2. AI równolegle wywołuje narzędzia dla każdej platformy:
- `ecommerce_search` (platform: "amazon")
- `ecommerce_search` (platform: "ebay")
- `ecommerce_search` (platform: "allegro")
3. AI agreguje wyniki, normalizuje formaty i porównuje ceny
4. Zwraca tabelę porównawczą z najlepszymi ofertami
**Wartość**: Oszczędność czasu na ręcznym przeszukiwaniu wielu sklepów
#### Scenariusz 3: Developer Tool Discovery
**Cel**: Znalezienie odpowiednich bibliotek i narzędzi dla projektu
**Przepływ**:
1. Użytkownik: "Znajdź biblioteki do walidacji danych w TypeScript"
2. AI wywołuje `repositories_search`:
```typescript
{
query: "data validation",
platform: "github",
language: "typescript",
minStars: 500,
sortBy: "stars"
}
```
3. AI następnie używa `webfetch` do pobrania dokumentacji najlepszych wyników
4. Zwraca listę z opisami, ocenami i linkami do dokumentacji
**Wartość**: Szybkie znalezienie sprawdzonych narzędzi
### 📋 Szczegółowa Dokumentacja Narzędzi
#### 🛒 E-commerce Search Tool
**Funkcjonalność**: Wyszukiwanie produktów w popularnych sklepach internetowych z zaawansowanymi filtrami
**Parametry wejściowe**:
```typescript
interface EcommerceSearchParams {
query: string; // Fraza wyszukiwania
platform: 'amazon' | 'ebay' | 'allegro' | 'alexpress' | 'etsy';
priceMin?: number; // Minimalna cena
priceMax?: number; // Maksymalna cena
minRating?: number; // Minimalna ocena (1-5)
minReviews?: number; // Minimalna liczba opinii
category?: string; // Kategoria produktu
region?: string; // Region (kod kraju)
condition?: 'new' | 'used' | 'refurbished';
sortBy?: 'price' | 'rating' | 'popularity' | 'date';
limit?: number; // Maksymalna liczba wyników (domyślnie 10)
}
```
**Format odpowiedzi**:
```typescript
interface EcommerceSearchResult {
platform: string;
totalResults: number;
results: Array<{
title: string;
price: number;
currency: string;
rating: number;
reviewCount: number;
url: string;
imageUrl?: string;
availability: 'in_stock' | 'out_of_stock' | 'limited';
shippingInfo?: string;
}>;
}
```
**Przykład użycia**:
```typescript
// Wywołanie przez AI
{
query: "laptop gaming",
platform: "allegro",
priceMin: 2000,
priceMax: 5000,
minRating: 4.5,
minReviews: 10,
sortBy: "rating"
}
```
#### 🔬 Scientific Publications Search Tool
**Funkcjonalność**: Wyszukiwanie publikacji naukowych w bazach danych z filtrowaniem po datach, autorach i cytowaniach
**Parametry wejściowe**:
```typescript
interface ScientificSearchParams {
query: string;
database: 'arxiv' | 'pubmed' | 'scholar' | 'ieee' | 'researchgate';
dateFrom?: string; // Format: YYYY-MM-DD
dateTo?: string; // Format: YYYY-MM-DD
authorAffiliation?: string; // Afiliacja autora
publicationType?: 'article' | 'conference' | 'preprint';
field?: string; // Dziedzina nauki
minCitations?: number; // Minimalna liczba cytowań
language?: string; // Kod języka (ISO 639-1)
sortBy?: 'relevance' | 'date' | 'citations';
limit?: number;
}
```
**Format odpowiedzi**:
```typescript
interface ScientificSearchResult {
database: string;
totalResults: number;
results: Array<{
title: string;
authors: string[];
abstract: string;
doi?: string;
pdfUrl?: string;
publicationDate: string;
citationCount: number;
journal?: string;
keywords?: string[];
}>;
}
```
#### 💻 Repositories Search Tool
**Funkcjonalność**: Wyszukiwanie projektów, bibliotek i pakietów w repozytoriach kodu
**Parametry wejściowe**:
```typescript
interface RepositorySearchParams {
query: string;
platform: 'github' | 'gitlab' | 'npm' | 'pypi' | 'docker' | 'maven';
language?: string; // Język programowania
minStars?: number; // Minimalna liczba gwiazdek
minDownloads?: number; // Minimalna liczba pobrań (dla npm/pypi)
lastUpdated?: string; // Ostatnia aktualizacja po dacie
license?: string; // Typ licencji (MIT, Apache, GPL, etc.)
topics?: string[]; // Tagi/tematy
minContributors?: number; // Minimalna liczba kontrybutorów
sortBy?: 'stars' | 'forks' | 'updated' | 'relevance';
limit?: number;
}
```
**Format odpowiedzi**:
```typescript
interface RepositorySearchResult {
platform: string;
totalResults: number;
results: Array<{
name: string;
description: string;
author: string;
stars: number;
forks: number;
language: string;
license?: string;
url: string;
lastUpdated: string;
topics?: string[];
}>;
}
```
#### 📱 Social Media Search Tool
**Funkcjonalność**: Wyszukiwanie treści w mediach społecznościowych z filtrowaniem po czasie i popularności
**Parametry wejściowe**:
```typescript
interface SocialMediaSearchParams {
query: string;
platform: 'twitter' | 'reddit' | 'linkedin' | 'youtube' | 'hackernews';
timeRange?: 'hour' | 'day' | 'week' | 'month' | 'year';
language?: string;
author?: string; // Nazwa użytkownika/kanału
minInteractions?: number; // Minimalna liczba lajków/komentarzy
hashtags?: string[]; // Hashtagi
contentType?: 'text' | 'image' | 'video' | 'link';
sortBy?: 'popularity' | 'date' | 'relevance';
limit?: number;
}
```
#### 🌐 General Web Search Tool
**Funkcjonalność**: Uniwersalne wyszukiwanie w internecie z filtrowaniem po typach plików i domenach
**Parametry wejściowe**:
```typescript
interface WebSearchParams {
query: string;
engine: 'google' | 'bing' | 'duckduckgo' | 'brave';
fileType?: 'pdf' | 'docx' | 'xlsx' | 'csv' | 'json' | 'xml' | 'ppt';
language?: string;
region?: string;
dateFrom?: string;
dateTo?: string;
domain?: string; // np. ".edu", ".gov"
exactPhrase?: boolean; // Dokładna fraza vs. podobne wyniki
safeSearch?: boolean;
sortBy?: 'relevance' | 'date';
limit?: number;
}
```
### 🔄 Type Conversion Tool
**Funkcjonalność**: Konwersja między różnymi formatami danych (JSON, XML, YAML, CSV, TOML)
**Przykład użycia**:
```typescript
// Konwersja JSON do YAML
{
inputFormat: "json",
outputFormat: "yaml",
data: '{"name": "test", "value": 123}',
prettyPrint: true
}
```
### 🌐 WebFetch Tool
**Funkcjonalność**: Pobieranie i parsowanie treści stron internetowych
**Parametry**:
```typescript
interface WebFetchParams {
url: string;
selector?: string; // CSS selector dla ekstrakcji fragmentu
extractImages?: boolean;
extractLinks?: boolean;
timeout?: number; // Timeout w sekundach
}
```
**Format odpowiedzi**:
```typescript
interface WebFetchResult {
url: string;
title?: string;
text: string;
html?: string;
metadata?: {
description?: string;
keywords?: string[];
author?: string;
};
images?: string[];
links?: string[];
}
```
---
## 🔧 Development
### Struktura projektu
```
mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP Server setup
│ ├── tools/ # Narzędzia wyszukiwania
│ │ ├── index.ts # Eksport wszystkich narzędzi
│ │ ├── base.ts # Bazowa klasa
│ │ ├── ecommerce/ # E-commerce search tools
│ │ │ ├── amazon.ts
│ │ │ ├── ebay.ts
│ │ │ └── allegro.ts
│ │ ├── scientific/ # Scientific search tools
│ │ │ ├── arxiv.ts
│ │ │ ├── pubmed.ts
│ │ │ └── scholar.ts
│ │ ├── repositories/ # Code repository tools
│ │ │ ├── github.ts
│ │ │ ├── npm.ts
│ │ │ └── pypi.ts
│ │ ├── social/ # Social media tools
│ │ │ ├── twitter.ts
│ │ │ ├── reddit.ts
│ │ │ └── youtube.ts
│ │ ├── websearch.ts # General web search
│ │ ├── webfetch.ts # Web scraping
│ │ └── conversion.ts # Type conversion
│ ├── types/ # TypeScript types
│ └── utils/ # Utilities
│ ├── logger.ts
│ ├── cache.ts
│ └── validators.ts
├── tests/ # Testy
├── examples/ # Przykłady konfiguracji
└── dist/ # Skompilowany kod
```
### Skrypty npm
```bash
# Development
npm run dev # Uruchomienie w trybie dev (watch mode)
npm run build # Build produkcyjny
npm start # Uruchomienie serwera
# Testing
npm test # Uruchomienie testów
npm run test:watch # Testy w trybie watch
npm run test:coverage # Coverage report
# Linting
npm run lint # ESLint check
npm run lint:fix # ESLint auto-fix
npm run format # Prettier formatting
```
### Dodawanie nowego źródła wyszukiwania
1. Utwórz nowy plik w odpowiednim katalogu, np. `src/tools/ecommerce/shopify.ts`:
```typescript
import { z } from 'zod';
import { BaseTool } from '../base.js';
const ShopifySearchSchema = z.object({
query: z.string().describe('Search query'),
priceMin: z.number().optional().describe('Minimum price'),
priceMax: z.number().optional().describe('Maximum price'),
limit: z.number().default(10).describe('Number of results'),
});
export class ShopifySearchTool extends BaseTool {
name = 'ecommerce_shopify';
description = 'Search for products on Shopify stores';
schema = ShopifySearchSchema;
async execute(params: z.infer<typeof ShopifySearchSchema>) {
// Implementacja wyszukiwania w Shopify
const results = await this.searchShopify(params);
return {
platform: 'shopify',
results,
};
}
private async searchShopify(params: any) {
// Logika API call do Shopify
}
}
```
2. Zarejestruj w `src/tools/index.ts`:
```typescript
import { ShopifySearchTool } from './ecommerce/shopify.js';
export const tools = [
// ... existing tools
new ShopifySearchTool(),
];
```
### Implementacja Cache'owania
#### Przykład: Multi-Layer Cache z keyv
```typescript
// src/utils/cache.ts
import Keyv from 'keyv';
import KeyvRedis from '@keyv/redis';
import { LRUCache } from 'lru-cache';
// L1: In-memory LRU cache (szybki dostęp)
const l1Cache = new LRUCache<string, any>({
max: 500, // maksymalna liczba wpisów
ttl: 1000 * 60 * 5, // 5 minut TTL
});
// L2: Redis cache (współdzielony między instancjami)
const l2Cache = new Keyv({
store: new KeyvRedis(process.env.REDIS_URL),
ttl: 1000 * 60 * 30, // 30 minut TTL
});
export class CacheManager {
async get<T>(key: string): Promise<T | undefined> {
// Sprawdź L1 cache
const l1Value = l1Cache.get(key);
if (l1Value !== undefined) {
return l1Value as T;
}
// Sprawdź L2 cache
const l2Value = await l2Cache.get(key);
if (l2Value !== undefined) {
// Promuj do L1
l1Cache.set(key, l2Value);
return l2Value as T;
}
return undefined;
}
async set(key: string, value: any, ttl?: number): Promise<void> {
// Zapisz w obu warstwach
l1Cache.set(key, value, { ttl: ttl || 1000 * 60 * 5 });
await l2Cache.set(key, value, ttl);
}
async invalidate(pattern: string): Promise<void> {
// Inwalidacja po wzorcu (dla tag-based invalidation)
// Implementacja zależy od używanego store
}
}
```
#### Przykład: Request Deduplication
```typescript
// src/utils/request-deduplication.ts
import { CacheManager } from './cache.js';
class RequestDeduplicator {
private pendingRequests = new Map<string, Promise<any>>();
async deduplicate<T>(
key: string,
requestFn: () => Promise<T>
): Promise<T> {
// Sprawdź czy żądanie jest już w trakcie
const pending = this.pendingRequests.get(key);
if (pending) {
return pending;
}
// Utwórz nowe żądanie
const promise = requestFn().finally(() => {
// Usuń z mapy po zakończeniu
this.pendingRequests.delete(key);
});
this.pendingRequests.set(key, promise);
return promise;
}
}
```
#### Przykład: Rate Limiting z bottleneck
```typescript
// src/utils/rate-limiter.ts
import Bottleneck from 'bottleneck';
// Rate limiter per API endpoint
const rateLimiters = new Map<string, Bottleneck>();
export function getRateLimiter(
apiName: string,
maxConcurrent: number = 5,
minTime: number = 1000
): Bottleneck {
if (!rateLimiters.has(apiName)) {
rateLimiters.set(
apiName,
new Bottleneck({
maxConcurrent,
minTime, // minimum time between requests (ms)
reservoir: 100, // initial number of requests
reservoirRefreshAmount: 100,
reservoirRefreshInterval: 60 * 1000, // refresh every minute
})
);
}
return rateLimiters.get(apiName)!;
}
```
#### Przykład: Circuit Breaker Pattern
```typescript
// src/utils/circuit-breaker.ts
enum CircuitState {
CLOSED = 'CLOSED',
OPEN = 'OPEN',
HALF_OPEN = 'HALF_OPEN',
}
export class CircuitBreaker {
private state = CircuitState.CLOSED;
private failures = 0;
private lastFailureTime = 0;
constructor(
private threshold: number = 5,
private timeout: number = 60000 // 1 minute
) {}
async execute<T>(fn: () => Promise<T>): Promise<T> {
if (this.state === CircuitState.OPEN) {
if (Date.now() - this.lastFailureTime > this.timeout) {
this.state = CircuitState.HALF_OPEN;
} else {
throw new Error('Circuit breaker is OPEN');
}
}
try {
const result = await fn();
this.onSuccess();
return result;
} catch (error) {
this.onFailure();
throw error;
}
}
private onSuccess() {
this.failures = 0;
this.state = CircuitState.CLOSED;
}
private onFailure() {
this.failures++;
this.lastFailureTime = Date.now();
if (this.failures >= this.threshold) {
this.state = CircuitState.OPEN;
}
}
}
```
#### Przykład: Integracja z BaseTool
```typescript
// src/tools/base.ts (rozszerzenie)
import { CacheManager } from '../utils/cache.js';
import { RequestDeduplicator } from '../utils/request-deduplication.js';
import { getRateLimiter } from '../utils/rate-limiter.js';
import { CircuitBreaker } from '../utils/circuit-breaker.js';
export abstract class BaseTool {
protected cache = new CacheManager();
protected deduplicator = new RequestDeduplicator();
protected circuitBreaker = new CircuitBreaker();
protected async executeWithCache<T>(
cacheKey: string,
apiCall: () => Promise<T>,
ttl?: number
): Promise<T> {
// Sprawdź cache
const cached = await this.cache.get<T>(cacheKey);
if (cached !== undefined) {
return cached;
}
// Request deduplication
const result = await this.deduplicator.deduplicate(
cacheKey,
async () => {
// Rate limiting
const limiter = getRateLimiter(this.name);
return limiter.schedule(async () => {
// Circuit breaker
return this.circuitBreaker.execute(apiCall);
});
}
);
// Zapisz w cache
await this.cache.set(cacheKey, result, ttl);
return result;
}
}
```
---
## 🧪 Testing
```bash
# Wszystkie testy
npm test
# Testy dla konkretnej kategorii
npm test -- ecommerce
npm test -- scientific
# Coverage
npm run test:coverage
```
---
## 🏗️ Architektura Projektu
### Założenia Architektoniczne
1. **Modularność**: Każde narzędzie wyszukiwania jest niezależnym modułem, łatwym do dodania/usunięcia
2. **Walidacja Schematów**: Wszystkie parametry narzędzi są walidowane przez Zod przed wykonaniem
3. **Error Handling**: Centralny system obsługi błędów z informatywnymi komunikatami
4. **Multi-Layer Caching**: Inteligentne cachowanie wyników wyszukiwań w wielu warstwach (L1: in-memory, L2: Redis) dla poprawy wydajności
5. **Request Optimization**: Deduplikacja żądań, batching, i paginacja dla minimalizacji wywołań API
6. **Rate Limiting & Resilience**: Rate limiting per API, circuit breaker pattern, i exponential backoff retry
7. **Extensibility**: Bazowa klasa `BaseTool` umożliwia łatwe dodawanie nowych narzędzi z automatycznym cache'owaniem
### Struktura Komunikacji
```
┌─────────────────────────────────────────────────────────┐
│ AI Client (Claude/Cursor) │
└────────────────────┬────────────────────────────────────┘
│ MCP Protocol (JSON-RPC)
│
┌────────────────────▼────────────────────────────────────┐
│ MCP Server (This Project) │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Tool Registry │ │
│ │ - E-commerce Search Tools │ │
│ │ - Scientific Publication Tools │ │
│ │ - Repository Search Tools │ │
│ │ - Social Media Tools │ │
│ │ - Web Search Tools │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────▼────────────────────────────────┐ │
│ │ BaseTool Abstract Class │ │
│ │ - Schema Validation (Zod) │ │
│ │ - Error Handling │ │
│ │ - Logging │ │
│ └────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
│ HTTP/API Calls
│
┌────────────────────▼────────────────────────────────────┐
│ External APIs & Services │
│ - Google Search API │
│ - Amazon Product API │
│ - GitHub API │
│ - arXiv API │
│ - Twitter API │
│ - ... (20+ services) │
└──────────────────────────────────────────────────────────┘
```
### Wzorce Projektowe
#### 1. **Strategy Pattern**
Każde narzędzie wyszukiwania implementuje wspólny interfejs `BaseTool`, ale ma własną strategię wykonania:
```typescript
abstract class BaseTool {
abstract name: string;
abstract description: string;
abstract schema: ZodSchema;
abstract execute(params: unknown): Promise<unknown>;
}
```
#### 2. **Factory Pattern**
Centralna rejestracja narzędzi w `tools/index.ts`:
```typescript
export const tools = [
new AmazonSearchTool(),
new GitHubSearchTool(),
// ... inne narzędzia
];
```
#### 3. **Adapter Pattern**
Normalizacja różnych formatów odpowiedzi API do jednolitego formatu MCP:
```typescript
class SearchResultAdapter {
normalize(apiResponse: unknown): MCPToolResult {
// Konwersja do standardowego formatu
}
}
```
### Przepływ Danych z Cache'owaniem i Optymalizacją
1. **Żądanie od AI**: Klient AI wysyła żądanie wywołania narzędzia z parametrami
2. **Walidacja**: Parametry są walidowane przez schemat Zod
3. **Cache Check (L1)**: Sprawdzenie in-memory cache dla szybkiego dostępu
4. **Request Deduplication**: Sprawdzenie, czy identyczne żądanie jest już w trakcie przetwarzania
5. **Rate Limiting Check**: Weryfikacja limitów dla danego API endpoint
6. **Cache Check (L2)**: Jeśli L1 miss, sprawdzenie Redis cache
7. **Circuit Breaker Check**: Weryfikacja stanu circuit breakera dla API
8. **Wykonanie**: Narzędzie wykonuje zapytanie do zewnętrznego API (z retry logic)
9. **Przetwarzanie**: Odpowiedź API jest parsowana i normalizowana
10. **Caching**: Wynik jest cachowany w L1 i L2 (z TTL i tagami)
11. **Odpowiedź**: Znormalizowany wynik jest zwracany do klienta AI
12. **Metrics**: Aktualizacja metryk (cache hit/miss, response time, error rate)
### Obsługa Błędów
- **Walidacja Parametrów**: Błędy walidacji są zwracane przed wykonaniem
- **API Errors**: Błędy zewnętrznych API są przechwytywane i konwertowane na format MCP
- **Timeout Protection**: Wszystkie żądania mają timeouty, aby uniknąć zawieszenia
- **Retry Logic**: Automatyczne ponawianie z exponential backoff i jitter (axios-retry)
- **Circuit Breaker**: Automatyczne wyłączanie usługi przy wysokim wskaźniku błędów
- **Fallback to Cache**: W przypadku błędów API, zwracanie danych z cache (jeśli dostępne)
- **Graceful Degradation**: Stopniowe obniżanie funkcjonalności zamiast całkowitego błędu
---
## 🛠️ Tech Stack
### Core Technologies
- **Runtime**: Node.js 20+ - Najnowsze funkcje ES2023, wydajność i stabilność
- **Language**: TypeScript 5.7+ - Type safety, lepsze IDE support, refactoring
- **MCP SDK**: `@modelcontextprotocol/sdk` - Oficjalne SDK dla protokołu MCP
### Validation & Schema
- **Zod**: Walidacja schematów JSON Schema dla parametrów narzędzi
- **Type Safety**: Pełne typowanie TypeScript dla wszystkich komponentów
### HTTP & Networking
- **Axios**: HTTP client z interceptors, retry logic i error handling
- **axios-retry**: Automatyczne ponawianie żądań z konfigurowalnymi strategiami
- **axios-cache-interceptor**: Cache interceptor dla Axios z obsługą HTTP cache headers
- **Cheerio**: Server-side HTML parsing (jQuery-like API) dla web scraping
- **undici**: Wysokowydajny HTTP client (alternatywa dla Axios, natywny w Node.js 18+)
### Data Processing
- **xml2js**: Parsowanie XML do obiektów JavaScript
- **js-yaml**: Parsowanie i generowanie YAML
- **csv-parse**: Parsowanie plików CSV
### Performance & Caching
- **keyv**: Uniwersalny key-value store z adapterami dla Redis, Memcached, MongoDB, PostgreSQL, SQLite
- **cache-manager**: Elastyczny system cache'owania z wieloma backendami (Redis, Memcached, memory)
- **node-cache**: In-memory caching dla wyników wyszukiwań (lightweight alternative)
- **ioredis**: Zaawansowany Redis client z cluster support, pub/sub, pipeline
- **lru-cache**: Wysokowydajna implementacja LRU cache z TypeScript support
- **p-limit**: Kontrola współbieżności dla równoległych operacji API
- **bottleneck**: Zaawansowany rate limiter z queue management
- **axios-retry**: Automatyczne ponawianie żądań z exponential backoff
### Development Tools
- **Jest**: Framework testowy z coverage reports
- **ESLint**: Linting kodu z regułami TypeScript
- **Prettier**: Automatyczne formatowanie kodu
- **ts-node**: TypeScript execution environment dla development
### Security & Rate Limiting
- **dotenv**: Zarządzanie zmiennymi środowiskowymi
- **helmet**: (Planowane) Security headers dla HTTP transport
- **bottleneck**: Rate limiting z queue management i priority support
- **p-limit**: Kontrola współbieżności i rate limiting dla równoległych operacji
- **express-rate-limit**: Rate limiting middleware (dla HTTP transport)
---
## 📖 Zasoby
### MCP Protocol - Oficjalne Źródła
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - Oficjalna dokumentacja MCP
- [MCP SDK GitHub](https://github.com/modelcontextprotocol/sdk) - Oficjalne SDK dla różnych języków
- [MCP Specification](https://spec.modelcontextprotocol.io/) - Pełna specyfikacja protokołu
- [Cursor AI MCP Integration](https://docs.cursor.com/mcp) - Integracja MCP z Cursor AI
- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp) - Przewodnik integracji z Claude Desktop
- [OpenAI MCP Server Documentation](https://developers.openai.com/apps-sdk/concepts/mcp-server/) - Dokumentacja OpenAI dotycząca MCP Server
### Open-Source Repozytoria MCP Server
#### TypeScript/Node.js Implementacje
- [MCP SDK TypeScript](https://github.com/modelcontextprotocol/sdk-typescript) - Oficjalne SDK TypeScript
- [Learn MCP by Building](https://mcp.so/ja/server/learn-mcp-by-building) - Przewodnik krok po kroku z przykładami
- [OPNsense MCP Server](https://github.com/floriangrousset/opnsense-mcp-server) - Przykład integracji z OPNsense API
#### Flutter/Dart Implementacje (dla integracji z AI Code Box)
- [flutter_mcp_server](https://github.com/Centinol-alt/flutter_mcp_server) - Open-source implementacja MCP dla Flutter/Dart
- [mcp_dart](https://github.com/leehack/mcp_dart) - SDK MCP w Dart, umożliwiające tworzenie serwerów i klientów
- [mcp_flutter](https://github.com/Arenukvern/mcp_flutter) - MCP Server i Toolkit dla Flutter z dynamiczną rejestracją narzędzi
- [figma-flutter-mcp](https://github.com/mhmzdev/figma-flutter-mcp) - MCP Server konwertujący projekty Figma na kod Flutter
- [Flutter MCP Server Documentation](https://docs.flutter.dev/ai/mcp-server) - Oficjalna dokumentacja Flutter dotycząca MCP
#### Integracja z Flutter/Dart (AI Code Box)
Dla projektu **AI Code Box** w Flutter, możesz zintegrować ten MCP Server na kilka sposobów:
**Opcja 1: HTTP/SSE Transport**
Uruchom Node.js MCP Server jako osobny proces i połącz się przez HTTP+SSE używając `mcp_dart`:
```dart
import 'package:mcp_dart/mcp_dart.dart';
final client = MCPClient(
transport: StreamableHTTPTransport(url: 'http://localhost:3000/mcp'),
);
await client.connect();
```
**Opcja 2: Native Dart MCP Server**
Użyj biblioteki `mcp_dart` do stworzenia natywnego serwera MCP w Dart, portując narzędzia z tego projektu.
**Opcja 3: Bridge Pattern**
Stwórz bridge między Node.js MCP Server a Flutter aplikacją przez REST API.
**Zalecane biblioteki:**
- [mcp_dart](https://github.com/leehack/mcp_dart) - Pełne SDK MCP dla Dart
- [mcp_flutter](https://github.com/Arenukvern/mcp_flutter) - Flutter-specific MCP toolkit
- [dio](https://pub.dev/packages/dio) - HTTP client dla komunikacji z Node.js serverem
#### Inne Implementacje
- [Java MCP Server](https://modelcontextprotocol.io/sdk/java/mcp-server) - Implementacja w Javie
- [Python MCP Examples](https://github.com/modelcontextprotocol/python-sdk) - Przykłady w Pythonie
### Artykuły i Najlepsze Praktyki
#### Podstawowe Wprowadzenie do MCP
- [MCP Explained: The New Standard Connecting AI to Everything](https://medium.com/@elisowski/mcp-explained-the-new-standard-connecting-ai-to-everything-79c5a1c98288) - **Polecany!** Kompleksowe wyjaśnienie MCP, jego architektury, komponentów (tools, resources, prompts) oraz jak MCP standaryzuje integrację AI z zewnętrznymi systemami. Artykuł zawiera praktyczne przykłady i case studies.
- [Model Context Protocol (MCP) in AI](https://blog.stackademic.com/model-context-protocol-mcp-in-ai-9858b5ecd9ce) - **Polecany!** Szczegółowe omówienie MCP jako otwartego standardu łączącego AI z systemami danych. Artykuł opisuje założenia projektowe, architekturę i praktyczne zastosowania MCP w ekosystemie AI.
#### Zaawansowane Implementacje
- [Advanced MCP Implementation and Best Practices for Scaling AI Systems](https://medium.com/@cloudelligent_/advanced-mcp-implementation-and-best-practices-for-scaling-ai-systems-part-2-794f975746c6) - Zaawansowane techniki implementacji i skalowania systemów AI z MCP
- [MCP Security: Best Practices & Implementation Guide](https://vulnerablemcp.info/security.html) - Wytyczne dotyczące zabezpieczania serwera MCP
- [MCP Security Best Practices](https://mcp.harishgarg.com/learn/mcp-security-best-practices) - Najlepsze praktyki bezpieczeństwa
#### Przeglądy i Analizy
- [The Future of AI Applications: MCP Servers](https://www.techradar.com/pro/the-future-of-ai-applications-mcp-servers) - Przegląd przyszłości aplikacji AI z MCP
- [What is Model Context Protocol (MCP)?](https://www.itpro.com/technology/artificial-intelligence/what-is-model-context-protocol-mcp) - Wprowadzenie do MCP
- [Model Context Protocol - Wikipedia](https://en.wikipedia.org/wiki/Model_Context_Protocol) - Ogólne informacje o protokole
### Badania i Benchmarki
- [MCP-Bench: Benchmarking LLM Agents with MCP](https://arxiv.org/abs/2508.20453) - Narzędzie do benchmarkingu agentów LLM wykorzystujących MCP
- [MCP Safety Audit](https://arxiv.org/abs/2504.03767) - Analiza bezpieczeństwa LLM korzystających z MCP
### Cache'owanie i Optymalizacja API - Najnowsze Źródła (2024-2025)
#### Biblioteki i Narzędzia
- **[keyv](https://github.com/jaredwray/keyv)** - Uniwersalny key-value store z adapterami dla Redis, Memcached, MongoDB, PostgreSQL, SQLite. Idealny do multi-layer caching.
- **[cache-manager](https://github.com/node-cache-manager/node-cache-manager)** - Elastyczny system cache'owania z wieloma backendami i strategiami TTL.
- **[ioredis](https://github.com/redis/ioredis)** - Zaawansowany Redis client z cluster support, pub/sub, pipeline i TypeScript support.
- **[lru-cache](https://github.com/isaacs/node-lru-cache)** - Wysokowydajna implementacja LRU cache z TypeScript, idealna dla in-memory caching.
- **[axios-cache-interceptor](https://github.com/arthurfioretto/axios-cache-interceptor)** - Cache interceptor dla Axios z obsługą HTTP cache headers (ETag, Last-Modified, Cache-Control).
- **[axios-retry](https://github.com/softonic/axios-retry)** - Automatyczne ponawianie żądań z exponential backoff i konfigurowalnymi strategiami.
- **[bottleneck](https://github.com/SGrondin/bottleneck)** - Zaawansowany rate limiter z queue management, priority support i distributed rate limiting.
- **[p-limit](https://github.com/sindresorhus/p-limit)** - Kontrola współbieżności dla równoległych operacji API z Promise-based API.
#### Wzorce i Strategie Cache'owania
- **[Stale-While-Revalidate Pattern](https://web.dev/stale-while-revalidate/)** - Strategia cache'owania zapewniająca szybkie odpowiedzi przy jednoczesnej aktualizacji danych w tle.
- **[Cache-Aside Pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/cache-aside)** - Wzorzec cache'owania, gdzie aplikacja zarządza cache'em niezależnie od źródła danych.
- **[HTTP Caching Best Practices](https://web.dev/http-cache/)** - Najlepsze praktyki wykorzystania HTTP cache headers (Cache-Control, ETag, Last-Modified).
- **[Redis Caching Patterns](https://redis.io/docs/manual/patterns/)** - Oficjalne wzorce cache'owania w Redis z przykładami użycia.
#### Rate Limiting i Circuit Breaker
- **[Rate Limiting Strategies](https://www.cloudflare.com/learning/bots/what-is-rate-limiting/)** - Przegląd strategii rate limiting (Token Bucket, Sliding Window, Fixed Window).
- **[Circuit Breaker Pattern](https://martinfowler.com/bliki/CircuitBreaker.html)** - Wzorzec projektowy dla odporności na błędy w systemach rozproszonych.
- **[Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)** - Strategie ponawiania żądań z losowym opóźnieniem.
#### Optymalizacja Zapytań API
- **[Request Deduplication](https://www.patterns.dev/posts/request-deduplication-pattern/)** - Wzorzec eliminujący duplikaty równoległych żądań.
- **[API Batching Best Practices](https://www.apollographql.com/blog/query-batching-in-graphql/)** - Najlepsze praktyki grupowania zapytań (GraphQL, REST).
- **[Pagination Strategies](https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/)** - Strategie paginacji i filtrowania w API.
#### Monitoring i Performance
- **[Node.js Performance Best Practices](https://nodejs.org/en/docs/guides/simple-profiling/)** - Oficjalne wytyczne optymalizacji wydajności Node.js.
- **[Redis Performance Optimization](https://redis.io/docs/manual/optimization/)** - Optymalizacja wydajności Redis dla cache'owania.
- **[Application Performance Monitoring](https://www.datadoghq.com/knowledge-center/application-monitoring/)** - Monitorowanie wydajności aplikacji i identyfikacja wąskich gardeł.
#### Artykuły i Przewodniki (2024-2025)
- **[Node.js Caching Strategies: A Complete Guide](https://blog.logrocket.com/node-js-caching-complete-guide/)** - Kompleksowy przewodnik po strategiach cache'owania w Node.js.
- **[Building Resilient APIs with Rate Limiting](https://www.twilio.com/blog/building-resilient-apis-rate-limiting-node-js)** - Budowanie odpornych API z rate limiting w Node.js.
- **[Optimizing External API Calls in Node.js](https://www.digitalocean.com/community/tutorials/node-js-optimizing-external-api-calls)** - Optymalizacja wywołań zewnętrznych API w Node.js.
- **[Redis vs Memcached: Which Caching Solution is Right for You?](https://www.alibabacloud.com/blog/redis-vs-memcached-which-caching-solution-is-right-for-you_595820)** - Porównanie rozwiązań cache'owania.
### Firecrawl Integration - Analiza i Rekomendacje
#### 🔥 Czym jest Firecrawl?
[Firecrawl](https://github.com/firecrawl/firecrawl) to zaawansowany serwis API do konwersji całych stron internetowych na czysty markdown lub strukturalne dane gotowe dla LLM. Projekt ma **68.6k gwiazdek** na GitHub i jest aktywnie rozwijany.
**Kluczowe funkcjonalności:**
- 🔍 **Crawling całych stron** - Automatyczne przechodzenie przez wszystkie dostępne podstrony
- 📄 **Markdown conversion** - Konwersja HTML do czystego markdown
- 🤖 **LLM Extraction** - Ekstrakcja strukturalnych danych z użyciem LLM (Zod/Pydantic schemas)
- 🎯 **Actions support** - Interakcje z dynamicznymi stronami (kliknięcia, wpisywanie tekstu, screenshoty)
- 📦 **Batch scraping** - Równoległe przetwarzanie wielu URL
- 🔄 **MCP Support** - Oficjalne wsparcie dla Model Context Protocol
#### ⚖️ Self-Hosted vs Cloud - Analiza
**Status Self-Hosted (2024-2025):**
> ⚠️ **Ważne:** Według oficjalnego README: *"This repository is in development, and we're still integrating custom modules into the mono repo. It's not fully ready for self-hosted deployment yet, but you can run it locally."*
**Self-Hosted - Zalety:**
- ✅ **Kontrola nad danymi** - Wszystkie dane pozostają w Twojej infrastrukturze
- ✅ **Brak limitów API** - Nieograniczone użycie (zależne od zasobów)
- ✅ **Customizacja** - Możliwość modyfikacji kodu pod własne potrzeby
- ✅ **Koszty** - Brak opłat za użycie (tylko koszty infrastruktury)
- ✅ **AGPL-3.0 License** - Open source, możliwość modyfikacji
**Self-Hosted - Wady:**
- ❌ **Nie gotowy do produkcji** - Projekt wciąż w development
- ❌ **Wymaga zasobów** - Większe zapotrzebowanie na CPU/RAM niż prosty WebFetch
- ❌ **Maintenance** - Wymaga własnej konserwacji i aktualizacji
- ❌ **Brak niektórych funkcji** - Cloud wersja ma więcej funkcji (Actions, advanced extraction)
- ❌ **Kompleksowość** - Większa złożoność niż obecny WebFetch z Cheerio
**Cloud Offering - Zalety:**
- ✅ **Gotowe do użycia** - Natychmiastowa dostępność
- ✅ **Więcej funkcji** - Actions, advanced extraction, lepsze wsparcie dla dynamicznych stron
- ✅ **Maintenance** - Brak konieczności utrzymywania infrastruktury
- ✅ **Skalowalność** - Automatyczne skalowanie
- ✅ **MCP Server** - Gotowy MCP server dostępny
**Cloud Offering - Wady:**
- ❌ **Koszty** - Płatne API (z darmowym tierem)
- ❌ **Limity** - Ograniczenia w darmowym planie
- ❌ **Zależność zewnętrzna** - Zależność od zewnętrznego serwisu
- ❌ **Dane poza infrastrukturą** - URL są wysyłane do zewnętrznego API
#### 🎯 Rekomendacja dla MCP Server
**Dla obecnego projektu MCP Server:**
1. **Krótkoterminowo (Faza 1-2):**
- ✅ **Zostań przy WebFetch + Cheerio** - Prostsze, lżejsze, wystarczające dla większości przypadków
- ✅ **Dodaj Firecrawl jako opcjonalną integrację** - Dla zaawansowanych przypadków użycia
2. **Średnioterminowo (Faza 3-4):**
- 🔄 **Rozważ Firecrawl Cloud API** - Jako uzupełnienie dla:
- Crawling całych stron (nie tylko pojedyncze URL)
- LLM extraction (strukturalne dane)
- Dynamiczne strony wymagające interakcji
- 🔄 **Monitoruj rozwój self-hosted** - Gdy będzie gotowy do produkcji, rozważ migrację
3. **Długoterminowo:**
- 🎯 **Hybrid approach** - WebFetch dla prostych przypadków, Firecrawl dla zaawansowanych
- 🎯 **Self-hosted Firecrawl** - Gdy będzie stabilny, rozważ jako alternatywę
#### 💡 Proponowana Implementacja
**Opcja 1: Firecrawl jako opcjonalne narzędzie**
```typescript
// src/tools/webfetch-firecrawl.ts
import Firecrawl from '@mendable/firecrawl-js';
export class FirecrawlTool extends BaseTool {
name = 'firecrawl_scrape';
description = 'Advanced web scraping with Firecrawl (crawling, LLM extraction)';
async execute(params: {
url: string;
crawl?: boolean; // Crawl entire site vs single page
formats?: ('markdown' | 'html' | 'json')[];
schema?: ZodSchema; // For LLM extraction
}) {
const firecrawl = new Firecrawl({
apiKey: process.env.FIRECRAWL_API_KEY
});
if (params.crawl) {
return await firecrawl.crawl(params.url, {
limit: 100,
scrapeOptions: { formats: params.formats || ['markdown'] }
});
}
return await firecrawl.scrape(params.url, {
formats: params.formats || ['markdown'],
...(params.schema && {
formats: [{ type: 'json', schema: params.schema }]
})
});
}
}
```
**Opcja 2: Integracja z istniejącym WebFetch**
- WebFetch używa prostego Cheerio (szybkie, lekkie)
- Firecrawl jako fallback dla trudnych przypadków (dynamiczne strony, crawling)
#### 📚 Zasoby Firecrawl
- **[Firecrawl GitHub](https://github.com/firecrawl/firecrawl)** - Oficjalne repozytorium (68.6k ⭐)
- **[Firecrawl Documentation](https://docs.firecrawl.dev/)** - Kompleksowa dokumentacja API
- **[Firecrawl Cloud](https://firecrawl.dev/)** - Hosted version z playground
- **[Firecrawl MCP](https://github.com/firecrawl/firecrawl-mcp)** - Oficjalny MCP server dla Firecrawl
- **[Node.js SDK](https://www.npmjs.com/package/@mendable/firecrawl-js)** - `@mendable/firecrawl-js`
- **[Python SDK](https://pypi.org/project/firecrawl-py/)** - `firecrawl-py`
#### ⚠️ Uwagi Prawne
> **Ważne:** Firecrawl domyślnie respektuje `robots.txt`. Użytkownicy są odpowiedzialni za przestrzeganie polityk stron internetowych podczas scrapingu. Zawsze sprawdzaj Terms of Service i robots.txt przed crawlingiem.
### API Documentation
- [Amazon Product Advertising API](https://webservices.amazon.com/paapi5/documentation/)
- [eBay API](https://developer.ebay.com/)
- [Allegro API](https://developer.allegro.pl/)
- [arXiv API](https://arxiv.org/help/api/)
- [PubMed API](https://www.ncbi.nlm.nih.gov/home/develop/api/)
- [GitHub API](https://docs.github.com/en/rest)
- [Twitter API](https://developer.twitter.com/en/docs/twitter-api)
- [Reddit API](https://www.reddit.com/dev/api/)
---
## 🔒 Bezpieczeństwo
### Najlepsze Praktyki
Implementacja serwera MCP wymaga szczególnej uwagi na bezpieczeństwo, ponieważ serwer może mieć dostęp do wrażliwych danych i zewnętrznych systemów.
#### 1. Uwierzytelnianie i Autoryzacja
- **API Keys**: Przechowuj klucze API w zmiennych środowiskowych, nigdy w kodzie
- **Szyfrowanie**: Używaj szyfrowania dla wrażliwych danych (np. `flutter_secure_storage` dla Flutter)
- **Role-Based Access Control (RBAC)**: Implementuj kontrolę dostępu do narzędzi i zasobów
- **Rate Limiting**: Ogranicz liczbę żądań na użytkownika/IP, aby zapobiec nadużyciom
#### 2. Walidacja Danych
- **Input Validation**: Waliduj wszystkie dane wejściowe używając Zod lub podobnych narzędzi
- **Sanitization**: Oczyszczaj dane przed przetwarzaniem (szczególnie dla web scraping)
- **Schema Validation**: Używaj silnych schematów walidacji dla wszystkich parametrów narzędzi
#### 3. Bezpieczeństwo API
- **HTTPS Only**: Wymuszaj połączenia HTTPS dla wszystkich zewnętrznych API calls
- **Timeout Protection**: Ustaw rozsądne timeouty dla wszystkich żądań zewnętrznych
- **Error Handling**: Nie ujawniaj wrażliwych informacji w komunikatach błędów
- **Request Signing**: Podpisuj żądania do zewnętrznych API (np. Amazon Product Advertising API)
#### 4. Ochrona przed Atakami
- **Prompt Injection**: Waliduj i filtruj dane przed wysłaniem do LLM
- **SQL Injection**: Używaj parametryzowanych zapytań (jeśli używasz bazy danych)
- **XSS Protection**: Sanityzuj dane HTML przed wyświetleniem
- **CSRF Protection**: Implementuj tokeny CSRF dla operacji modyfikujących dane
#### 5. Monitoring i Logging
- **Audit Logs**: Loguj wszystkie operacje na wrażliwych danych
- **Error Tracking**: Monitoruj błędy i nieprawidłowe próby dostępu
- **Performance Monitoring**: Śledź wydajność i wykrywaj anomalie
#### 6. Konfiguracja Środowiska
- **Environment Variables**: Używaj `.env` dla konfiguracji, dodaj `.env` do `.gitignore`
- **Secrets Management**: Rozważ użycie narzędzi do zarządzania sekretami (np. AWS Secrets Manager, HashiCorp Vault)
- **Least Privilege**: Nadawaj minimalne wymagane uprawnienia
### Zasoby Bezpieczeństwa
- [MCP Security Best Practices](https://mcp.harishgarg.com/learn/mcp-security-best-practices) - Kompleksowy przewodnik
- [MCP Safety Audit Research](https://arxiv.org/abs/2504.03767) - Analiza luk bezpieczeństwa
- [OpenAI Platform Security](https://platform.openai.com/docs/mcp/) - Wytyczne bezpieczeństwa OpenAI
> [!WARNING]
> Zawsze testuj swoje narzędzia w środowisku izolowanym przed wdrożeniem produkcyjnym. Nie ufaj danym wejściowym i zawsze waliduj parametry przed wykonaniem operacji.
---
## 🚧 Roadmap
### Faza 1: Core Infrastructure ✅
- [x] Struktura projektu
- [x] Bazowa klasa narzędzi
- [x] System walidacji
- [x] Logging
### Faza 2: Basic Search Tools (W trakcie)
- [ ] General web search (Google, Bing)
- [ ] WebFetch tool
- [ ] Type conversion tools
- [ ] MCP server setup
### Faza 3: Specialized Search
- [ ] E-commerce search (Amazon, eBay, Allegro)
- [ ] Scientific publications (arXiv, PubMed)
- [ ] Code repositories (GitHub, npm, PyPI)
- [ ] Social media (Twitter, Reddit, YouTube)
### Faza 4: Advanced Features (W trakcie)
- [ ] **Multi-layer caching system**
- [ ] L1: In-memory cache (lru-cache/node-cache)
- [ ] L2: Redis cache dla współdzielonych danych
- [ ] L3: HTTP cache headers (ETag, Cache-Control)
- [ ] Cache invalidation strategies (TTL, tag-based, manual)
- [ ] **Request optimization**
- [ ] Request deduplication dla równoległych żądań
- [ ] Batching zapytań (gdy API wspiera)
- [ ] Intelligent pagination
- [ ] Field filtering
- [ ] **Rate limiting & circuit breaker**
- [ ] Token bucket rate limiter (bottleneck)
- [ ] Per-API rate limit tracking
- [ ] Circuit breaker pattern
- [ ] Queue management dla throttled requests
- [ ] **Data aggregation**
- [ ] Równoległe wyszukiwanie w wielu platformach
- [ ] Deduplikacja wyników
- [ ] Normalizacja formatów odpowiedzi
- [ ] Ranking i sortowanie zagregowanych wyników
- [ ] **Advanced filtering**
- [ ] Composite filters
- [ ] Full-text search optimization
- [ ] Faceted search
- [ ] **Error recovery & resilience**
- [ ] Exponential backoff retry strategy
- [ ] Fallback to cache on API errors
- [ ] Graceful degradation
- [ ] Health checks dla zewnętrznych API
### Faza 5: Polish & Optimization
- [ ] Comprehensive tests
- [ ] Performance optimization
- [ ] Documentation
- [ ] Example integrations
---
## 📄 Licencja
MIT License - możesz swobodnie używać i modyfikować ten projekt.
---
## 🤝 Contributing
Contributions are welcome! Jeśli chcesz dodać nowe źródło wyszukiwania lub poprawić istniejące:
1. Fork projektu
2. Utwórz branch (`git checkout -b feature/new-search-source`)
3. Commit zmian (`git commit -m 'Add new search source'`)
4. Push do brancha (`git push origin feature/new-search-source`)
5. Otwórz Pull Request
---
## 💡 Use Cases
### Research Assistant
```
Agent: Znajdź najnowsze publikacje o "quantum computing" na arXiv,
następnie wyszukaj implementacje na GitHub i podsumuj stan badań.
```
### Product Comparison
```
Agent: Porównaj ceny iPhone 15 Pro na Amazon, eBay i Allegro,
pokaż najlepsze oferty z dobrymi ocenami.
```
### Developer Tools Discovery
```
Agent: Znajdź popularne biblioteki TypeScript do walidacji danych,
sprawdź ich dokumentację i przykłady użycia.
```
### Trend Analysis
```
Agent: Sprawdź co jest teraz popularne na Reddit i Twitter w temacie AI,
znajdź powiązane artykuły naukowe i projekty na GitHub.
```
---
## 📦 Instalacja i Konfiguracja
> [!NOTE]
> Ta sekcja zawiera podstawowe informacje o instalacji. Szczegółowa dokumentacja funkcjonalności znajduje się w sekcjach powyżej.
### Wymagania
- **Node.js** 20.x lub wyższy
- **npm** lub **yarn**
- **API Keys** (opcjonalne, w zależności od używanych narzędzi)
- **Redis** (opcjonalne, dla L2 cache - zalecane dla produkcji)
### Szybki Start
```bash
# Klonowanie i instalacja
git clone <repo-url>
cd mcp-server
npm install
# Konfiguracja (opcjonalna)
cp .env.example .env
# Edytuj .env i dodaj API keys
# Instalacja zależności cache'owania (opcjonalne)
npm install keyv @keyv/redis ioredis lru-cache bottleneck axios-retry axios-cache-interceptor p-limit
# Build i uruchomienie
npm run build
npm start
```
### Konfiguracja Cache'owania i Optymalizacji
#### Przykładowy plik `.env`
```bash
# Redis Configuration (opcjonalne, dla L2 cache)
REDIS_URL=redis://localhost:6379
REDIS_TTL=1800000 # 30 minut w milisekundach
# Cache Configuration
CACHE_ENABLED=true
CACHE_L1_MAX_SIZE=500
CACHE_L1_TTL=300000 # 5 minut
CACHE_L2_TTL=1800000 # 30 minut
# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_CONCURRENT=5
RATE_LIMIT_MIN_TIME=1000 # minimum time between requests (ms)
# Circuit Breaker
CIRCUIT_BREAKER_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60000 # 1 minute
# Retry Configuration
RETRY_ENABLED=true
RETRY_ATTEMPTS=3
RETRY_DELAY=1000 # initial delay (ms)
```
#### Przykładowe zależności w `package.json`
```json
{
"dependencies": {
"@modelcontextprotocol/sdk": "^0.5.0",
"axios": "^1.6.0",
"axios-retry": "^4.0.0",
"axios-cache-interceptor": "^1.5.0",
"bottleneck": "^2.19.5",
"cheerio": "^1.0.0",
"keyv": "^4.5.0",
"@keyv/redis": "^2.8.0",
"ioredis": "^5.3.0",
"lru-cache": "^10.0.0",
"p-limit": "^5.0.0",
"zod": "^3.22.0"
}
}
```
### Integracja z Klientami AI
**Cursor AI**: Dodaj do `~/.cursor/config.json`:
```json
{
"mcpServers": {
"specialized-search": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"]
}
}
}
```
**Claude Desktop**: Edytuj plik konfiguracyjny (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`)
**Flutter/Dart**: Zobacz sekcję [Integracja z Flutter/Dart](#integracja-z-flutterdart-ai-code-box) w dokumentacji zasobów.
> [!TIP]
> Większość narzędzi ma darmowe tier API. Serwer działa z dostępnymi narzędziami - narzędzia bez skonfigurowanych kluczy są automatycznie wyłączone.
---
**Status projektu:** 🚧 W trakcie implementacji - Faza 1 & 2
Projekt jest aktywnie rozwijany. Podstawowa infrastruktura gotowa, implementacja narzędzi wyszukiwania w toku!
### ✨ Najnowsze Aktualizacje (2024-2025)
**Cache'owanie i Optymalizacja:**
- ✅ Dokumentacja multi-layer caching (L1: in-memory, L2: Redis)
- ✅ Strategie cache'owania: Cache-Aside, Stale-While-Revalidate, Tag-Based Invalidation
- ✅ Request deduplication i batching
- ✅ Rate limiting z bottleneck i p-limit
- ✅ Circuit breaker pattern dla odporności na błędy
- ✅ Przykłady implementacji z keyv, ioredis, lru-cache
- ✅ Integracja z axios-retry i axios-cache-interceptor
- ✅ Kompleksowa dokumentacja zasobów i najlepszych praktyk
**Zasoby:**
- 📚 20+ nowych źródeł dotyczących cache'owania i optymalizacji API
- 🔧 Przykłady kodu dla wszystkich wzorców projektowych
- 📖 Konfiguracja środowiska i zależności
- 🎯 Roadmap z szczegółowym planem implementacji