market-data-analyzer 2.0.0

package/src/tools/market_overview.ts

@@ -0,0 +1,236 @@
+/**
+ * market_overview -- Current market snapshot.
+ *
+ * Fetches live data for major indices, sector ETFs, and VIX
+ * from Yahoo Finance to build a comprehensive market summary.
+ */
+
+import { yahooQuote } from "../utils/api.js";
+import { formatCurrency, formatVolume } from "../utils/math.js";
+
+/** Index/ETF symbols to track */
+const INDEX_SYMBOLS = [
+  "^GSPC",   // S&P 500
+  "^IXIC",   // NASDAQ Composite
+  "^DJI",    // Dow Jones
+  "^RUT",    // Russell 2000
+  "^VIX",    // VIX
+  "^TNX",    // 10-Year Treasury Yield
+];
+
+/** Sector ETFs (SPDR Select Sector) */
+const SECTOR_ETFS = [
+  { symbol: "XLK", name: "Technology" },
+  { symbol: "XLV", name: "Healthcare" },
+  { symbol: "XLF", name: "Financials" },
+  { symbol: "XLY", name: "Consumer Discretionary" },
+  { symbol: "XLP", name: "Consumer Staples" },
+  { symbol: "XLE", name: "Energy" },
+  { symbol: "XLI", name: "Industrials" },
+  { symbol: "XLU", name: "Utilities" },
+  { symbol: "XLRE", name: "Real Estate" },
+  { symbol: "XLB", name: "Materials" },
+  { symbol: "XLC", name: "Communication Services" },
+];
+
+/** Other reference symbols */
+const OTHER_SYMBOLS = [
+  "BTC-USD",  // Bitcoin
+  "ETH-USD",  // Ethereum
+  "GC=F",     // Gold futures
+  "CL=F",     // Crude oil WTI
+];
+
+export async function handleMarketOverview(): Promise<string> {
+  // Fetch all data in parallel
+  const allSymbols = [
+    ...INDEX_SYMBOLS,
+    ...SECTOR_ETFS.map((s) => s.symbol),
+    ...OTHER_SYMBOLS,
+  ];
+
+  const quotes = await yahooQuote(allSymbols);
+  const quoteMap = new Map(quotes.map((q) => [q.symbol, q]));
+
+  const lines: string[] = [];
+
+  lines.push("# Market Overview");
+  lines.push("");
+  lines.push(`*Live data as of ${new Date().toISOString().slice(0, 16)} UTC*`);
+  lines.push("");
+
+  // Major Indices
+  lines.push("## Major Indices");
+  lines.push("");
+  lines.push("| Index | Value | Change | Change % |");
+  lines.push("|-------|-------|--------|----------|");
+
+  const indexNames: Record<string, string> = {
+    "^GSPC": "S&P 500",
+    "^IXIC": "NASDAQ Composite",
+    "^DJI": "Dow Jones Industrial",
+    "^RUT": "Russell 2000",
+    "^VIX": "CBOE Volatility (VIX)",
+    "^TNX": "10-Year Treasury Yield",
+  };
+
+  for (const sym of INDEX_SYMBOLS) {
+    const q = quoteMap.get(sym);
+    if (!q || q.regularMarketPrice == null) continue;
+    const name = indexNames[sym] ?? q.shortName ?? sym;
+    const price = q.regularMarketPrice;
+    const change = q.regularMarketChange ?? 0;
+    const changePct = q.regularMarketChangePercent ?? 0;
+    const sign = change >= 0 ? "+" : "";
+    const fmtPrice = price > 100
+      ? price.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+      : price.toFixed(2);
+    lines.push(`| ${name} | ${fmtPrice} | ${sign}${change.toFixed(2)} | ${sign}${changePct.toFixed(2)}% |`);
+  }
+  lines.push("");
+
+  // VIX interpretation
+  const vix = quoteMap.get("^VIX");
+  if (vix?.regularMarketPrice != null) {
+    const vixVal = vix.regularMarketPrice;
+    lines.push("### VIX Interpretation");
+    lines.push("");
+    if (vixVal < 15) {
+      lines.push(`VIX at ${vixVal.toFixed(2)} -- **Low volatility.** Market complacency; conditions are calm.`);
+    } else if (vixVal < 20) {
+      lines.push(`VIX at ${vixVal.toFixed(2)} -- **Normal.** Typical market conditions.`);
+    } else if (vixVal < 25) {
+      lines.push(`VIX at ${vixVal.toFixed(2)} -- **Elevated.** Increasing uncertainty and hedging activity.`);
+    } else if (vixVal < 30) {
+      lines.push(`VIX at ${vixVal.toFixed(2)} -- **High.** Significant fear in the market.`);
+    } else {
+      lines.push(`VIX at ${vixVal.toFixed(2)} -- **Very high.** Extreme fear; possible market stress event.`);
+    }
+    lines.push("");
+  }
+
+  // Sector Performance
+  lines.push("## Sector Performance");
+  lines.push("");
+  lines.push("| Sector | ETF | Price | Change % |");
+  lines.push("|--------|-----|-------|----------|");
+
+  const sectorData: Array<{ name: string; symbol: string; changePct: number }> = [];
+  for (const etf of SECTOR_ETFS) {
+    const q = quoteMap.get(etf.symbol);
+    if (!q || q.regularMarketPrice == null) continue;
+    const changePct = q.regularMarketChangePercent ?? 0;
+    const sign = changePct >= 0 ? "+" : "";
+    lines.push(`| ${etf.name} | ${etf.symbol} | $${q.regularMarketPrice.toFixed(2)} | ${sign}${changePct.toFixed(2)}% |`);
+    sectorData.push({ name: etf.name, symbol: etf.symbol, changePct });
+  }
+  lines.push("");
+
+  // Sector breadth
+  if (sectorData.length > 0) {
+    const positive = sectorData.filter((s) => s.changePct > 0).length;
+    const negative = sectorData.filter((s) => s.changePct < 0).length;
+    const bestSector = [...sectorData].sort((a, b) => b.changePct - a.changePct)[0];
+    const worstSector = [...sectorData].sort((a, b) => a.changePct - b.changePct)[0];
+
+    lines.push("### Sector Breadth");
+    lines.push("");
+    lines.push(`- Sectors advancing: ${positive}/${sectorData.length}`);
+    lines.push(`- Sectors declining: ${negative}/${sectorData.length}`);
+    lines.push(`- Best: **${bestSector.name}** (${bestSector.changePct >= 0 ? "+" : ""}${bestSector.changePct.toFixed(2)}%)`);
+    lines.push(`- Worst: **${worstSector.name}** (${worstSector.changePct >= 0 ? "+" : ""}${worstSector.changePct.toFixed(2)}%)`);
+    lines.push("");
+  }
+
+  // Crypto & Commodities
+  lines.push("## Crypto & Commodities");
+  lines.push("");
+  lines.push("| Asset | Price | Change % |");
+  lines.push("|-------|-------|----------|");
+
+  const otherNames: Record<string, string> = {
+    "BTC-USD": "Bitcoin",
+    "ETH-USD": "Ethereum",
+    "GC=F": "Gold",
+    "CL=F": "Crude Oil WTI",
+  };
+
+  for (const sym of OTHER_SYMBOLS) {
+    const q = quoteMap.get(sym);
+    if (!q || q.regularMarketPrice == null) continue;
+    const name = otherNames[sym] ?? q.shortName ?? sym;
+    const changePct = q.regularMarketChangePercent ?? 0;
+    const sign = changePct >= 0 ? "+" : "";
+    lines.push(`| ${name} | $${q.regularMarketPrice.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })} | ${sign}${changePct.toFixed(2)}% |`);
+  }
+  lines.push("");
+
+  // Market Breadth / Sentiment estimate
+  lines.push("## Market Sentiment");
+  lines.push("");
+
+  const spx = quoteMap.get("^GSPC");
+  const spxChange = spx?.regularMarketChangePercent ?? 0;
+  const vixVal = vix?.regularMarketPrice ?? 20;
+
+  let sentimentScore = 50;
+
+  // SPX contribution
+  if (spxChange > 1) sentimentScore += 15;
+  else if (spxChange > 0.5) sentimentScore += 10;
+  else if (spxChange > 0) sentimentScore += 5;
+  else if (spxChange < -1) sentimentScore -= 15;
+  else if (spxChange < -0.5) sentimentScore -= 10;
+  else if (spxChange < 0) sentimentScore -= 5;
+
+  // VIX contribution
+  if (vixVal < 15) sentimentScore += 10;
+  else if (vixVal < 20) sentimentScore += 5;
+  else if (vixVal > 30) sentimentScore -= 15;
+  else if (vixVal > 25) sentimentScore -= 10;
+  else if (vixVal > 20) sentimentScore -= 5;
+
+  // Sector breadth
+  if (sectorData.length > 0) {
+    const posRatio = sectorData.filter((s) => s.changePct > 0).length / sectorData.length;
+    if (posRatio > 0.7) sentimentScore += 10;
+    else if (posRatio > 0.5) sentimentScore += 5;
+    else if (posRatio < 0.3) sentimentScore -= 10;
+  }
+
+  sentimentScore = Math.max(0, Math.min(100, sentimentScore));
+  const sentiment = sentimentScore >= 60 ? "BULLISH" : sentimentScore <= 40 ? "BEARISH" : "NEUTRAL";
+
+  lines.push(`**Sentiment: ${sentiment}** (Score: ${sentimentScore}/100)`);
+  lines.push("");
+
+  // Key observations
+  lines.push("## Key Observations");
+  lines.push("");
+
+  if (spx) {
+    const val = spx.regularMarketPrice?.toLocaleString("en-US", { minimumFractionDigits: 2 }) ?? "N/A";
+    lines.push(`- S&P 500 at ${val} (${spxChange >= 0 ? "+" : ""}${spxChange.toFixed(2)}%).`);
+  }
+
+  const btc = quoteMap.get("BTC-USD");
+  if (btc && btc.regularMarketChangePercent != null && Math.abs(btc.regularMarketChangePercent) > 2) {
+    lines.push(`- Crypto ${btc.regularMarketChangePercent > 0 ? "rallying" : "selling off"}: Bitcoin ${btc.regularMarketChangePercent >= 0 ? "+" : ""}${btc.regularMarketChangePercent.toFixed(1)}%.`);
+  }
+
+  const oil = quoteMap.get("CL=F");
+  if (oil && oil.regularMarketChangePercent != null && Math.abs(oil.regularMarketChangePercent) > 1) {
+    lines.push(`- Oil ${oil.regularMarketChangePercent > 0 ? "rising" : "falling"} (${oil.regularMarketChangePercent >= 0 ? "+" : ""}${oil.regularMarketChangePercent.toFixed(1)}%).`);
+  }
+
+  const gold = quoteMap.get("GC=F");
+  if (gold && gold.regularMarketChangePercent != null && gold.regularMarketChangePercent > 0.5) {
+    lines.push(`- Gold up ${gold.regularMarketChangePercent.toFixed(1)}% -- possible flight to safety.`);
+  }
+
+  if (vixVal > 25) {
+    lines.push("- Elevated VIX suggests caution; hedging demand is high.");
+  }
+
+  return lines.join("\n");
+}

package/src/tools/screen_stocks.ts

@@ -0,0 +1,154 @@
+/**
+ * screen_stocks -- Screen stocks by criteria using Yahoo Finance data.
+ *
+ * Fetches live quotes for a universe of popular stocks and filters
+ * by market cap, P/E ratio, sector, volume, etc.
+ */
+
+import { yahooScreener, POPULAR_SYMBOLS } from "../utils/api.js";
+import { formatCurrency, formatVolume } from "../utils/math.js";
+import type { YahooQuote } from "../types.js";
+
+export interface ScreenCriteria {
+  min_market_cap?: number;
+  max_market_cap?: number;
+  min_pe?: number;
+  max_pe?: number;
+  sector?: string;
+  min_volume?: number;
+  min_price?: number;
+  max_price?: number;
+  limit?: number;
+}
+
+export async function handleScreenStocks(criteria: ScreenCriteria): Promise<string> {
+  // Fetch quotes for the full symbol universe
+  let quotes = await yahooScreener(POPULAR_SYMBOLS);
+
+  // Apply filters
+  if (criteria.min_market_cap !== undefined) {
+    quotes = quotes.filter((q) => (q.marketCap ?? 0) >= criteria.min_market_cap!);
+  }
+  if (criteria.max_market_cap !== undefined) {
+    quotes = quotes.filter((q) => (q.marketCap ?? Infinity) <= criteria.max_market_cap!);
+  }
+  if (criteria.min_pe !== undefined) {
+    quotes = quotes.filter((q) => q.trailingPE != null && q.trailingPE >= criteria.min_pe!);
+  }
+  if (criteria.max_pe !== undefined) {
+    quotes = quotes.filter((q) => q.trailingPE != null && q.trailingPE <= criteria.max_pe!);
+  }
+  if (criteria.sector !== undefined) {
+    const sectorLower = criteria.sector.toLowerCase();
+    quotes = quotes.filter((q) =>
+      (q.sector ?? "").toLowerCase().includes(sectorLower) ||
+      (q.industry ?? "").toLowerCase().includes(sectorLower)
+    );
+  }
+  if (criteria.min_volume !== undefined) {
+    quotes = quotes.filter((q) => (q.regularMarketVolume ?? 0) >= criteria.min_volume!);
+  }
+  if (criteria.min_price !== undefined) {
+    quotes = quotes.filter((q) => (q.regularMarketPrice ?? 0) >= criteria.min_price!);
+  }
+  if (criteria.max_price !== undefined) {
+    quotes = quotes.filter((q) => (q.regularMarketPrice ?? Infinity) <= criteria.max_price!);
+  }
+
+  // Sort by market cap descending
+  quotes.sort((a, b) => (b.marketCap ?? 0) - (a.marketCap ?? 0));
+
+  // Limit results
+  const limit = criteria.limit ?? 25;
+  const total = quotes.length;
+  quotes = quotes.slice(0, limit);
+
+  return formatScreenResults(quotes, criteria, total);
+}
+
+function formatScreenResults(
+  quotes: YahooQuote[],
+  criteria: ScreenCriteria,
+  totalMatches: number,
+): string {
+  const lines: string[] = [];
+
+  lines.push("# Stock Screener Results");
+  lines.push("");
+
+  // Filters applied
+  const filters: string[] = [];
+  if (criteria.min_market_cap) filters.push(`Min Mkt Cap: ${formatCurrency(criteria.min_market_cap)}`);
+  if (criteria.max_market_cap) filters.push(`Max Mkt Cap: ${formatCurrency(criteria.max_market_cap)}`);
+  if (criteria.min_pe) filters.push(`Min P/E: ${criteria.min_pe}`);
+  if (criteria.max_pe) filters.push(`Max P/E: ${criteria.max_pe}`);
+  if (criteria.sector) filters.push(`Sector: ${criteria.sector}`);
+  if (criteria.min_volume) filters.push(`Min Volume: ${formatVolume(criteria.min_volume)}`);
+  if (criteria.min_price) filters.push(`Min Price: $${criteria.min_price}`);
+  if (criteria.max_price) filters.push(`Max Price: $${criteria.max_price}`);
+
+  if (filters.length > 0) {
+    lines.push(`**Filters:** ${filters.join(" | ")}`);
+  } else {
+    lines.push("**Filters:** None (showing full universe)");
+  }
+  lines.push(`**Matches:** ${totalMatches} stocks (showing top ${quotes.length})`);
+  lines.push("");
+
+  if (quotes.length === 0) {
+    lines.push("_No stocks match the specified criteria. Try broadening your filters._");
+    return lines.join("\n");
+  }
+
+  // Results table
+  lines.push("| Symbol | Name | Price | Chg% | Volume | Mkt Cap | P/E | Sector |");
+  lines.push("|--------|------|-------|------|--------|---------|-----|--------|");
+
+  for (const q of quotes) {
+    const price = q.regularMarketPrice?.toFixed(2) ?? "N/A";
+    const changePct = q.regularMarketChangePercent != null
+      ? `${q.regularMarketChangePercent >= 0 ? "+" : ""}${q.regularMarketChangePercent.toFixed(2)}%`
+      : "N/A";
+    const vol = q.regularMarketVolume ? formatVolume(q.regularMarketVolume) : "N/A";
+    const cap = q.marketCap ? formatCurrency(q.marketCap) : "N/A";
+    const pe = q.trailingPE?.toFixed(1) ?? "N/A";
+    const name = (q.shortName ?? q.longName ?? q.symbol).slice(0, 25);
+    const sector = q.sector ?? "--";
+
+    lines.push(`| ${q.symbol} | ${name} | $${price} | ${changePct} | ${vol} | ${cap} | ${pe} | ${sector} |`);
+  }
+
+  lines.push("");
+
+  // Quick stats
+  const withPE = quotes.filter((q) => q.trailingPE != null);
+  if (withPE.length > 0) {
+    const avgPE = withPE.reduce((s, q) => s + q.trailingPE!, 0) / withPE.length;
+    const minPE = Math.min(...withPE.map((q) => q.trailingPE!));
+    const maxPE = Math.max(...withPE.map((q) => q.trailingPE!));
+    lines.push("## P/E Statistics");
+    lines.push("");
+    lines.push(`- Average P/E: ${avgPE.toFixed(1)}`);
+    lines.push(`- P/E Range: ${minPE.toFixed(1)} - ${maxPE.toFixed(1)}`);
+    lines.push("");
+  }
+
+  // Top gainers/losers in results
+  const sorted = [...quotes].filter((q) => q.regularMarketChangePercent != null);
+  if (sorted.length >= 3) {
+    sorted.sort((a, b) => (b.regularMarketChangePercent ?? 0) - (a.regularMarketChangePercent ?? 0));
+    const top3 = sorted.slice(0, 3);
+    const bottom3 = sorted.slice(-3).reverse();
+
+    lines.push("## Notable Movers (within results)");
+    lines.push("");
+    lines.push("**Top gainers:** " + top3.map((q) =>
+      `${q.symbol} (${q.regularMarketChangePercent! >= 0 ? "+" : ""}${q.regularMarketChangePercent!.toFixed(2)}%)`
+    ).join(", "));
+    lines.push("**Top losers:** " + bottom3.map((q) =>
+      `${q.symbol} (${q.regularMarketChangePercent!.toFixed(2)}%)`
+    ).join(", "));
+  }
+
+  return lines.join("\n");
+}

package/src/types.ts

@@ -0,0 +1,175 @@
+/**
+ * Shared types for the Market Data Analyzer MCP server.
+ */
+
+// ---------------------------------------------------------------------------
+// Yahoo Finance response shapes (partial -- only what we use)
+// ---------------------------------------------------------------------------
+
+export interface YahooQuote {
+  symbol: string;
+  shortName?: string;
+  longName?: string;
+  regularMarketPrice?: number;
+  regularMarketChange?: number;
+  regularMarketChangePercent?: number;
+  regularMarketVolume?: number;
+  regularMarketDayHigh?: number;
+  regularMarketDayLow?: number;
+  regularMarketOpen?: number;
+  regularMarketPreviousClose?: number;
+  fiftyTwoWeekHigh?: number;
+  fiftyTwoWeekLow?: number;
+  fiftyDayAverage?: number;
+  twoHundredDayAverage?: number;
+  marketCap?: number;
+  trailingPE?: number;
+  forwardPE?: number;
+  priceToBook?: number;
+  trailingAnnualDividendYield?: number;
+  sector?: string;
+  industry?: string;
+  averageDailyVolume3Month?: number;
+}
+
+export interface YahooChartPoint {
+  date: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+}
+
+// ---------------------------------------------------------------------------
+// CoinGecko response shapes (partial)
+// ---------------------------------------------------------------------------
+
+export interface CoinGeckoMarketData {
+  id: string;
+  symbol: string;
+  name: string;
+  current_price: number;
+  market_cap: number;
+  market_cap_rank: number;
+  total_volume: number;
+  high_24h: number;
+  low_24h: number;
+  price_change_24h: number;
+  price_change_percentage_24h: number;
+  price_change_percentage_7d_in_currency?: number;
+  price_change_percentage_30d_in_currency?: number;
+  market_cap_change_percentage_24h: number;
+  circulating_supply: number;
+  total_supply: number | null;
+  max_supply: number | null;
+  ath: number;
+  ath_change_percentage: number;
+  ath_date: string;
+  atl: number;
+  atl_change_percentage: number;
+  atl_date: string;
+}
+
+export interface CoinGeckoGlobalData {
+  total_market_cap: Record<string, number>;
+  total_volume: Record<string, number>;
+  market_cap_percentage: Record<string, number>;
+  market_cap_change_percentage_24h_usd: number;
+  active_cryptocurrencies: number;
+}
+
+// ---------------------------------------------------------------------------
+// Tool output shapes
+// ---------------------------------------------------------------------------
+
+export interface StockAnalysis {
+  symbol: string;
+  name: string;
+  price: number;
+  change: number;
+  changePercent: number;
+  volume: number;
+  marketCap: number;
+  peRatio: number | null;
+  high52w: number;
+  low52w: number;
+  sma20: number | null;
+  sma50: number | null;
+  sma200: number | null;
+  rsi14: number | null;
+  macd: { line: number; signal: number; histogram: number } | null;
+  supportLevels: number[];
+  resistanceLevels: number[];
+  priceHistory: YahooChartPoint[];
+}
+
+export interface PortfolioPosition {
+  symbol: string;
+  shares: number;
+  avgCost: number;
+  currentPrice: number;
+  marketValue: number;
+  costBasis: number;
+  pnl: number;
+  pnlPercent: number;
+  allocationPercent: number;
+}
+
+export interface PortfolioAnalysis {
+  totalValue: number;
+  totalCost: number;
+  totalPnl: number;
+  totalPnlPercent: number;
+  positions: PortfolioPosition[];
+  diversificationScore: number;
+  riskMetrics: {
+    concentrationRisk: string;
+    largestPosition: string;
+    largestPositionPct: number;
+    sectorBreakdown: Record<string, number>;
+  };
+  warnings: string[];
+}
+
+export interface ScreenerResult {
+  symbol: string;
+  name: string;
+  price: number;
+  changePercent: number;
+  marketCap: number;
+  peRatio: number | null;
+  volume: number;
+  sector?: string;
+}
+
+export interface AssetComparison {
+  symbol: string;
+  name: string;
+  totalReturn: number;
+  annualizedReturn: number;
+  volatility: number;
+  sharpeRatio: number;
+  maxDrawdown: number;
+  currentPrice: number;
+}
+
+export interface CryptoAnalysisResult {
+  id: string;
+  symbol: string;
+  name: string;
+  price: number;
+  change24h: number;
+  changePct24h: number;
+  volume24h: number;
+  marketCap: number;
+  marketCapRank: number;
+  circulatingSupply: number;
+  totalSupply: number | null;
+  maxSupply: number | null;
+  ath: number;
+  athChangePct: number;
+  athDate: string;
+  dominance: number | null;
+  fearGreedApprox: string;
+}