data-aggregator-mcp 1.0.0

package/src/types.ts

@@ -0,0 +1,184 @@
+// ─── Shared Types ──────────────────────────────────────────────────────────
+
+/** Generic API response wrapper */
+export interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  cached?: boolean;
+  timestamp: string;
+}
+
+// ─── Stock / Crypto Types ──────────────────────────────────────────────────
+
+export interface StockQuote {
+  symbol: string;
+  name?: string;
+  price: number;
+  currency: string;
+  change: number;
+  changePercent: number;
+  volume?: number;
+  marketCap?: number;
+  high?: number;
+  low?: number;
+  open?: number;
+  previousClose?: number;
+  timestamp: string;
+  source: string;
+}
+
+export interface CryptoQuote {
+  symbol: string;
+  name: string;
+  price: number;
+  currency: string;
+  change24h: number;
+  changePercent24h: number;
+  volume24h: number;
+  marketCap: number;
+  high24h?: number;
+  low24h?: number;
+  timestamp: string;
+  source: string;
+}
+
+// ─── Weather Types ─────────────────────────────────────────────────────────
+
+export interface CurrentWeather {
+  temperature: number;
+  feelsLike: number;
+  humidity: number;
+  windSpeed: number;
+  windDirection: number;
+  precipitation: number;
+  weatherCode: number;
+  weatherDescription: string;
+  isDay: boolean;
+  timestamp: string;
+}
+
+export interface DailyForecast {
+  date: string;
+  temperatureMax: number;
+  temperatureMin: number;
+  precipitationSum: number;
+  precipitationProbability: number;
+  windSpeedMax: number;
+  weatherCode: number;
+  weatherDescription: string;
+  sunrise: string;
+  sunset: string;
+}
+
+export interface WeatherData {
+  location: string;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  current: CurrentWeather;
+  forecast: DailyForecast[];
+  source: string;
+}
+
+// ─── News Types ────────────────────────────────────────────────────────────
+
+export interface NewsArticle {
+  title: string;
+  description: string;
+  url: string;
+  source: string;
+  publishedAt: string;
+  author?: string;
+  imageUrl?: string;
+}
+
+// ─── Exchange Rate Types ───────────────────────────────────────────────────
+
+export interface ExchangeRate {
+  base: string;
+  target: string;
+  rate: number;
+  timestamp: string;
+  source: string;
+}
+
+export interface CurrencyConversion {
+  from: string;
+  to: string;
+  amount: number;
+  convertedAmount: number;
+  rate: number;
+  timestamp: string;
+}
+
+// ─── Web Scraping Types ────────────────────────────────────────────────────
+
+export interface ScrapedPage {
+  url: string;
+  title: string;
+  metaDescription: string;
+  headings: { level: number; text: string }[];
+  mainContent: string;
+  links: { text: string; href: string }[];
+  selectedContent?: string;
+  timestamp: string;
+}
+
+// ─── Public Data Types ─────────────────────────────────────────────────────
+
+export interface WikipediaSummary {
+  title: string;
+  extract: string;
+  url: string;
+  thumbnail?: string;
+  timestamp: string;
+}
+
+export interface IpGeolocation {
+  ip: string;
+  country: string;
+  countryCode: string;
+  region: string;
+  city: string;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  isp: string;
+}
+
+export interface DnsRecord {
+  domain: string;
+  type: string;
+  records: string[];
+  ttl?: number;
+}
+
+export interface UrlInfo {
+  originalUrl: string;
+  expandedUrl: string;
+  statusCode: number;
+  contentType?: string;
+}
+
+// ─── Cache & Rate Limiting ─────────────────────────────────────────────────
+
+export interface CacheEntry<T> {
+  data: T;
+  expiresAt: number;
+  createdAt: number;
+}
+
+export interface RateLimitConfig {
+  maxRequests: number;
+  windowMs: number;
+  source: string;
+}
+
+// ─── Tool Result Helper ────────────────────────────────────────────────────
+
+export interface ToolResult {
+  [key: string]: unknown;
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}

package/src/utils/cache.ts

@@ -0,0 +1,103 @@
+import type { CacheEntry } from "../types.js";
+
+/**
+ * In-memory cache with per-key TTL support.
+ *
+ * TTL defaults (in milliseconds):
+ *   - Market data:    5 minutes   (300_000)
+ *   - Exchange rates: 30 minutes  (1_800_000)
+ *   - Weather:        1 hour      (3_600_000)
+ *   - News:           15 minutes  (900_000)
+ *   - Web scraping:   10 minutes  (600_000)
+ *   - Public data:    1 hour      (3_600_000)
+ */
+
+export const TTL = {
+  MARKET: 5 * 60 * 1000,
+  EXCHANGE: 30 * 60 * 1000,
+  WEATHER: 60 * 60 * 1000,
+  NEWS: 15 * 60 * 1000,
+  SCRAPE: 10 * 60 * 1000,
+  PUBLIC: 60 * 60 * 1000,
+} as const;
+
+export class Cache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private cleanupInterval: ReturnType<typeof setInterval>;
+
+  constructor(cleanupIntervalMs = 60_000) {
+    // Periodic sweep to evict expired entries
+    this.cleanupInterval = setInterval(() => this.evictExpired(), cleanupIntervalMs);
+    // Allow the process to exit even if the interval is still running
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  /** Retrieve a cached value, or undefined if missing / expired. */
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.data as T;
+  }
+
+  /** Store a value with a TTL (milliseconds). */
+  set<T>(key: string, data: T, ttlMs: number): void {
+    this.store.set(key, {
+      data,
+      expiresAt: Date.now() + ttlMs,
+      createdAt: Date.now(),
+    });
+  }
+
+  /** Check whether a non-expired entry exists. */
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  /** Remove a single key. */
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  /** Remove all entries. */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Number of entries (including possibly-expired ones until next sweep). */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Build a deterministic cache key from parts. */
+  static key(...parts: (string | number | boolean | undefined | null)[]): string {
+    return parts
+      .map((p) => (p === undefined || p === null ? "_" : String(p).toLowerCase()))
+      .join(":");
+  }
+
+  /** Remove all expired entries. */
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /** Tear down the cleanup interval (for graceful shutdown). */
+  destroy(): void {
+    clearInterval(this.cleanupInterval);
+  }
+}
+
+/** Singleton cache instance shared across the server. */
+export const cache = new Cache();

package/src/utils/http.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared HTTP client with:
+ *   - Automatic retries with exponential back-off
+ *   - User-Agent rotation (for scraping)
+ *   - Timeout support
+ *   - JSON convenience helpers
+ */
+
+const USER_AGENTS = [
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+  "Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0",
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36 Edg/124.0.0.0",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+];
+
+export interface HttpOptions {
+  /** Request timeout in milliseconds (default: 15 000). */
+  timeoutMs?: number;
+  /** Maximum number of attempts (default: 3). */
+  maxRetries?: number;
+  /** Additional headers to merge in. */
+  headers?: Record<string, string>;
+  /** Use a rotating browser-like User-Agent (default: false). */
+  rotateUserAgent?: boolean;
+  /** HTTP method (default: GET). */
+  method?: string;
+  /** Request body (for POST/PUT). */
+  body?: string;
+}
+
+function pickUserAgent(): string {
+  return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)]!;
+}
+
+/**
+ * Fetch with retries, timeouts, and optional UA rotation.
+ * Returns the raw `Response` object on success.
+ */
+export async function httpFetch(
+  url: string,
+  opts: HttpOptions = {}
+): Promise<Response> {
+  const {
+    timeoutMs = 15_000,
+    maxRetries = 3,
+    headers = {},
+    rotateUserAgent = false,
+    method = "GET",
+    body,
+  } = opts;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const finalHeaders: Record<string, string> = {
+        Accept: "application/json, text/html, */*",
+        ...headers,
+      };
+
+      if (rotateUserAgent) {
+        finalHeaders["User-Agent"] = pickUserAgent();
+      }
+
+      const response = await fetch(url, {
+        method,
+        headers: finalHeaders,
+        body,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timer);
+
+      // Retry on server errors (5xx), not on client errors (4xx)
+      if (response.status >= 500 && attempt < maxRetries) {
+        lastError = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        await backoff(attempt);
+        continue;
+      }
+
+      return response;
+    } catch (err) {
+      clearTimeout(timer);
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      if (attempt < maxRetries) {
+        await backoff(attempt);
+        continue;
+      }
+    }
+  }
+
+  throw lastError ?? new Error(`Failed to fetch ${url}`);
+}
+
+/**
+ * Convenience: fetch and parse JSON.
+ */
+export async function httpGetJson<T = unknown>(
+  url: string,
+  opts: HttpOptions = {}
+): Promise<T> {
+  const resp = await httpFetch(url, {
+    ...opts,
+    headers: { Accept: "application/json", ...opts.headers },
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(
+      `HTTP ${resp.status} from ${url}: ${body.slice(0, 300)}`
+    );
+  }
+
+  return resp.json() as Promise<T>;
+}
+
+/**
+ * Convenience: fetch and return text.
+ */
+export async function httpGetText(
+  url: string,
+  opts: HttpOptions = {}
+): Promise<string> {
+  const resp = await httpFetch(url, opts);
+
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(
+      `HTTP ${resp.status} from ${url}: ${body.slice(0, 300)}`
+    );
+  }
+
+  return resp.text();
+}
+
+/** Exponential back-off: 500ms, 1s, 2s, ... */
+async function backoff(attempt: number): Promise<void> {
+  const ms = Math.min(500 * 2 ** (attempt - 1), 5_000);
+  await new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Format an error into a user-friendly string for tool results.
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    if (err.name === "AbortError") return "Request timed out. The API may be slow or unreachable.";
+    return err.message;
+  }
+  return String(err);
+}

package/src/utils/rate-limiter.ts

@@ -0,0 +1,114 @@
+/**
+ * Sliding-window rate limiter keyed by source name.
+ *
+ * Default limits per source (requests / window):
+ *   - CoinGecko:      30 req / 60 s
+ *   - Open-Meteo:     60 req / 60 s
+ *   - ExchangeRate:   60 req / 60 s
+ *   - NewsAPI:        50 req / 60 s  (free tier is tight)
+ *   - Google News RSS: 60 req / 60 s
+ *   - Wikipedia:      100 req / 60 s
+ *   - Generic HTTP:   120 req / 60 s
+ */
+
+interface Window {
+  timestamps: number[];
+  maxRequests: number;
+  windowMs: number;
+}
+
+const DEFAULT_LIMITS: Record<string, { maxRequests: number; windowMs: number }> = {
+  coingecko:    { maxRequests: 30,  windowMs: 60_000 },
+  "open-meteo": { maxRequests: 60,  windowMs: 60_000 },
+  exchangerate: { maxRequests: 60,  windowMs: 60_000 },
+  newsapi:      { maxRequests: 50,  windowMs: 60_000 },
+  googlenews:   { maxRequests: 60,  windowMs: 60_000 },
+  wikipedia:    { maxRequests: 100, windowMs: 60_000 },
+  generic:      { maxRequests: 120, windowMs: 60_000 },
+  dns:          { maxRequests: 120, windowMs: 60_000 },
+  ipgeo:        { maxRequests: 45,  windowMs: 60_000 },
+};
+
+export class RateLimiter {
+  private windows = new Map<string, Window>();
+
+  /** Register or update limits for a source. */
+  configure(source: string, maxRequests: number, windowMs: number): void {
+    const existing = this.windows.get(source);
+    if (existing) {
+      existing.maxRequests = maxRequests;
+      existing.windowMs = windowMs;
+    } else {
+      this.windows.set(source, { timestamps: [], maxRequests, windowMs });
+    }
+  }
+
+  /**
+   * Try to acquire a permit for `source`.
+   * Returns `true` if the request is allowed, `false` if rate-limited.
+   */
+  tryAcquire(source: string): boolean {
+    const win = this.getOrCreate(source);
+    const now = Date.now();
+
+    // Slide the window: drop timestamps older than the window
+    win.timestamps = win.timestamps.filter((t) => now - t < win.windowMs);
+
+    if (win.timestamps.length >= win.maxRequests) {
+      return false;
+    }
+
+    win.timestamps.push(now);
+    return true;
+  }
+
+  /**
+   * Acquire a permit, waiting if necessary. Throws after `timeoutMs`.
+   */
+  async acquire(source: string, timeoutMs = 10_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+
+    while (!this.tryAcquire(source)) {
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Rate limit exceeded for "${source}". Try again in a few seconds.`
+        );
+      }
+      // Wait a short interval before retrying
+      await new Promise((r) => setTimeout(r, 250));
+    }
+  }
+
+  /** How many requests remain in the current window. */
+  remaining(source: string): number {
+    const win = this.getOrCreate(source);
+    const now = Date.now();
+    const active = win.timestamps.filter((t) => now - t < win.windowMs).length;
+    return Math.max(0, win.maxRequests - active);
+  }
+
+  /** Milliseconds until the next permit becomes available (0 if available now). */
+  retryAfterMs(source: string): number {
+    const win = this.getOrCreate(source);
+    if (win.timestamps.length < win.maxRequests) return 0;
+
+    const now = Date.now();
+    const oldest = win.timestamps.find((t) => now - t < win.windowMs);
+    if (!oldest) return 0;
+
+    return Math.max(0, oldest + win.windowMs - now);
+  }
+
+  private getOrCreate(source: string): Window {
+    let win = this.windows.get(source);
+    if (!win) {
+      const defaults = DEFAULT_LIMITS[source] ?? DEFAULT_LIMITS.generic!;
+      win = { timestamps: [], ...defaults };
+      this.windows.set(source, win);
+    }
+    return win;
+  }
+}
+
+/** Singleton rate limiter shared across the server. */
+export const rateLimiter = new RateLimiter();

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}