xstock-mcp 1.1.0 → 1.2.0

package/dist/index.js

@@ -26,7 +26,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/server.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
-var import_types6 = require("@modelcontextprotocol/sdk/types.js");
+var import_types7 = require("@modelcontextprotocol/sdk/types.js");
 
 // src/tools/quotes.ts
 var import_zod = require("zod");
@@ -169,6 +169,7 @@ async function fetchHKKline(code, period = "daily") {
 
 // src/data/yahoo.ts
 var import_yahoo_finance2 = __toESM(require("yahoo-finance2"));
+var import_axios2 = __toESM(require("axios"));
 var yf = new import_yahoo_finance2.default({ suppressNotices: ["yahooSurvey"] });
 async function fetchUSQuotes(symbols) {
   process.stderr.write(`[yahoo] fetchUSQuotes symbols=${symbols.join(",")}
@@ -254,6 +255,119 @@ async function fetchEarningsCalendar(symbol) {
     recentEPS
   };
 }
+async function fetchFinancials(symbol, quarterly = false) {
+  process.stderr.write(`[yahoo] fetchFinancials symbol=${symbol} quarterly=${quarterly}
+`);
+  const modules = quarterly ? ["incomeStatementHistoryQuarterly", "cashflowStatementHistoryQuarterly", "balanceSheetHistoryQuarterly"] : ["incomeStatementHistory", "cashflowStatementHistory", "balanceSheetHistory"];
+  const summary = await yf.quoteSummary(symbol, { modules });
+  const incomeKey = quarterly ? "incomeStatementHistoryQuarterly" : "incomeStatementHistory";
+  const cashKey = quarterly ? "cashflowStatementHistoryQuarterly" : "cashflowStatementHistory";
+  const balanceKey = quarterly ? "balanceSheetHistoryQuarterly" : "balanceSheetHistory";
+  const incomeArr = summary[incomeKey]?.incomeStatementHistory ?? [];
+  const cashArr = summary[cashKey]?.cashflowStatements ?? [];
+  const balanceArr = summary[balanceKey]?.balanceSheetStatements ?? [];
+  return incomeArr.slice(0, 4).map((inc, i) => {
+    const cash = cashArr[i] ?? {};
+    const bal = balanceArr[i] ?? {};
+    const date = inc.endDate instanceof Date ? inc.endDate.toISOString().slice(0, 10) : String(inc.endDate ?? "");
+    const revenue = inc.totalRevenue ?? null;
+    const gross = inc.grossProfit ?? null;
+    const net = inc.netIncome ?? null;
+    const opCash = cash.totalCashFromOperatingActivities ?? null;
+    const capex = cash.capitalExpenditures ?? null;
+    const debt = bal.totalDebt ?? (bal.longTermDebt ?? null);
+    const equity = bal.totalStockholderEquity ?? null;
+    return {
+      date,
+      totalRevenue: revenue,
+      grossProfit: gross,
+      grossMargin: revenue && gross ? Math.round(gross / revenue * 1e4) / 100 : null,
+      netIncome: net,
+      netMargin: revenue && net ? Math.round(net / revenue * 1e4) / 100 : null,
+      epsDiluted: inc.dilutedEPS ?? null,
+      operatingCashFlow: opCash,
+      freeCashFlow: opCash !== null && capex !== null ? opCash + capex : null,
+      totalDebt: debt,
+      stockholdersEquity: equity,
+      debtToEquity: debt !== null && equity !== null && equity !== 0 ? Math.round(debt / equity * 100) / 100 : null
+    };
+  });
+}
+async function fetchAnalystRating(symbol) {
+  process.stderr.write(`[yahoo] fetchAnalystRating symbol=${symbol}
+`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["financialData", "recommendationTrend", "upgradeDowngradeHistory"]
+  });
+  const fin = summary.financialData;
+  const trend = summary.recommendationTrend;
+  const history = summary.upgradeDowngradeHistory;
+  const trendArr = trend?.trend ?? [];
+  const latest = trendArr[0] ?? {};
+  const changes = (history?.history ?? []).slice(0, 10).map((h) => ({
+    date: h.epochGradeDate instanceof Date ? h.epochGradeDate.toISOString().slice(0, 10) : String(h.epochGradeDate ?? ""),
+    firm: String(h.firm ?? ""),
+    action: String(h.action ?? ""),
+    from: h.fromGrade ? String(h.fromGrade) : null,
+    to: h.toGrade ? String(h.toGrade) : null
+  }));
+  return {
+    symbol,
+    consensus: fin?.recommendationKey ?? null,
+    targetPriceMean: fin?.targetMeanPrice ?? null,
+    targetPriceHigh: fin?.targetHighPrice ?? null,
+    targetPriceLow: fin?.targetLowPrice ?? null,
+    distribution: {
+      strongBuy: Number(latest.strongBuy ?? 0),
+      buy: Number(latest.buy ?? 0),
+      hold: Number(latest.hold ?? 0),
+      sell: Number(latest.sell ?? 0),
+      strongSell: Number(latest.strongSell ?? 0)
+    },
+    recentChanges: changes
+  };
+}
+function extractXmlTag(xml, tag) {
+  const match = xml.match(new RegExp(`<${tag}[^>]*>(?:<!\\[CDATA\\[)?([\\s\\S]*?)(?:\\]\\]>)?</${tag}>`, "i"));
+  return match ? match[1].trim() : "";
+}
+async function fetchStockNews(symbol, limit = 20) {
+  process.stderr.write(`[yahoo] fetchStockNews symbol=${symbol}
+`);
+  const url = `https://feeds.finance.yahoo.com/rss/2.0/headline?s=${symbol}&region=US&lang=en-US`;
+  const res = await import_axios2.default.get(url, { timeout: 8e3, responseType: "text" });
+  const xml = res.data;
+  const items = [];
+  const itemMatches = xml.match(/<item>[\s\S]*?<\/item>/g) ?? [];
+  for (const item of itemMatches.slice(0, limit)) {
+    items.push({
+      title: extractXmlTag(item, "title"),
+      link: extractXmlTag(item, "link") || extractXmlTag(item, "guid"),
+      summary: extractXmlTag(item, "description").replace(/<[^>]+>/g, "").slice(0, 200),
+      pubDate: extractXmlTag(item, "pubDate")
+    });
+  }
+  process.stderr.write(`[yahoo] fetchStockNews \u8FD4\u56DE ${items.length} \u6761
+`);
+  return items;
+}
+async function fetchInsiderActivity(symbol) {
+  process.stderr.write(`[yahoo] fetchInsiderActivity symbol=${symbol}
+`);
+  const summary = await yf.quoteSummary(symbol, { modules: ["insiderTransactions"] });
+  const raw = summary.insiderTransactions;
+  const txArr = raw?.transactions ?? [];
+  return txArr.slice(0, 20).map((tx) => ({
+    date: tx.startDate instanceof Date ? tx.startDate.toISOString().slice(0, 10) : String(tx.startDate ?? ""),
+    name: String(tx.filerName ?? ""),
+    relation: String(tx.filerRelation ?? ""),
+    transactionType: String(tx.transactionDescription ?? ""),
+    shares: tx.shares ?? null,
+    value: tx.value ?? null,
+    sharesBefore: tx.shareholderBefore ?? null,
+    sharesAfter: tx.shareholderAfter ?? null
+  }));
+}
 async function fetchStockProfile(symbol) {
   process.stderr.write(`[yahoo] fetchStockProfile symbol=${symbol}
 `);
@@ -286,7 +400,7 @@ async function fetchStockProfile(symbol) {
 }
 
 // src/data/binance.ts
-var import_axios2 = __toESM(require("axios"));
+var import_axios3 = __toESM(require("axios"));
 function normalizeSymbol(symbol) {
   const s = symbol.toUpperCase();
   return s.endsWith("USDT") ? s : s + "USDT";
@@ -298,7 +412,7 @@ async function fetchCryptoTickers(symbols) {
     symbols.map(async (raw) => {
       const sym = normalizeSymbol(raw);
       try {
-        const res = await import_axios2.default.get(
+        const res = await import_axios3.default.get(
           `https://api.binance.com/api/v3/ticker/24hr?symbol=${sym}`,
           { timeout: 5e3 }
         );
@@ -331,11 +445,11 @@ async function fetchMarketSentiment(symbol, period = "1h") {
   const base = "https://fapi.binance.com";
   const params = `symbol=${sym}&period=${period}&limit=1`;
   const [oiRes, globalRes, topAccRes, topPosRes, takerRes] = await Promise.all([
-    import_axios2.default.get(`${base}/fapi/v1/openInterest?symbol=${sym}`, { timeout: 5e3 }),
-    import_axios2.default.get(`${base}/futures/data/globalLongShortAccountRatio?${params}`, { timeout: 5e3 }),
-    import_axios2.default.get(`${base}/futures/data/topLongShortAccountRatio?${params}`, { timeout: 5e3 }),
-    import_axios2.default.get(`${base}/futures/data/topLongShortPositionRatio?${params}`, { timeout: 5e3 }),
-    import_axios2.default.get(`${base}/futures/data/takerlongshortRatio?${params}`, { timeout: 5e3 })
+    import_axios3.default.get(`${base}/fapi/v1/openInterest?symbol=${sym}`, { timeout: 5e3 }),
+    import_axios3.default.get(`${base}/futures/data/globalLongShortAccountRatio?${params}`, { timeout: 5e3 }),
+    import_axios3.default.get(`${base}/futures/data/topLongShortAccountRatio?${params}`, { timeout: 5e3 }),
+    import_axios3.default.get(`${base}/futures/data/topLongShortPositionRatio?${params}`, { timeout: 5e3 }),
+    import_axios3.default.get(`${base}/futures/data/takerlongshortRatio?${params}`, { timeout: 5e3 })
   ]);
   const oi = oiRes.data;
   const global = globalRes.data[0] ?? {};
@@ -360,7 +474,7 @@ async function fetchCryptoKlines(symbol, interval = "1d", limit = 100) {
   const sym = normalizeSymbol(symbol);
   process.stderr.write(`[binance] fetchCryptoKlines symbol=${sym} interval=${interval} limit=${limit}
 `);
-  const res = await import_axios2.default.get(
+  const res = await import_axios3.default.get(
     `https://api.binance.com/api/v3/klines?symbol=${sym}&interval=${interval}&limit=${limit}`,
     { timeout: 5e3 }
   );
@@ -909,16 +1023,16 @@ var getStockProfileTool = {
 
 // src/tools/crypto.ts
 var import_zod5 = require("zod");
-var import_axios4 = __toESM(require("axios"));
+var import_axios5 = __toESM(require("axios"));
 
 // src/data/coingecko.ts
-var import_axios3 = __toESM(require("axios"));
+var import_axios4 = __toESM(require("axios"));
 var BASE = "https://api.coingecko.com/api/v3";
 var FEAR_GREED_URL = "https://api.alternative.me/fng/?limit=1";
 async function fetchGlobalMarket() {
   process.stderr.write(`[coingecko] fetchGlobalMarket
 `);
-  const res = await import_axios3.default.get(`${BASE}/global`, { timeout: 8e3 });
+  const res = await import_axios4.default.get(`${BASE}/global`, { timeout: 8e3 });
   const d = res.data.data;
   const result = {
     totalMarketCapUsd: d.total_market_cap?.usd ?? 0,
@@ -935,7 +1049,7 @@ async function fetchGlobalMarket() {
 async function fetchTopCoins(limit = 50) {
   process.stderr.write(`[coingecko] fetchTopCoins limit=${limit}
 `);
-  const res = await import_axios3.default.get(`${BASE}/coins/markets`, {
+  const res = await import_axios4.default.get(`${BASE}/coins/markets`, {
     timeout: 8e3,
     params: {
       vs_currency: "usd",
@@ -962,7 +1076,7 @@ async function fetchTopCoins(limit = 50) {
 async function fetchCategories() {
   process.stderr.write(`[coingecko] fetchCategories
 `);
-  const res = await import_axios3.default.get(`${BASE}/coins/categories`, { timeout: 8e3 });
+  const res = await import_axios4.default.get(`${BASE}/coins/categories`, { timeout: 8e3 });
   const categories = res.data.map((c) => ({
     id: c.id,
     name: c.name,
@@ -978,7 +1092,7 @@ async function fetchCategories() {
 async function fetchFearGreed() {
   process.stderr.write(`[coingecko] fetchFearGreed
 `);
-  const res = await import_axios3.default.get(FEAR_GREED_URL, { timeout: 5e3 });
+  const res = await import_axios4.default.get(FEAR_GREED_URL, { timeout: 5e3 });
   const d = res.data.data[0];
   const result = {
     value: parseInt(d.value),
@@ -1089,7 +1203,7 @@ var getCryptoFundingTool = {
         symbols.map(async (raw) => {
           const sym = raw.toUpperCase().endsWith("USDT") ? raw.toUpperCase() : raw.toUpperCase() + "USDT";
           try {
-            const res = await import_axios4.default.get(
+            const res = await import_axios5.default.get(
               `https://fapi.binance.com/fapi/v1/premiumIndex?symbol=${sym}`,
               { timeout: 5e3 }
             );
@@ -1161,6 +1275,143 @@ var getCryptoLiquidationTool = {
   }
 };
 
+// src/tools/us-fundamentals.ts
+var import_zod6 = require("zod");
+var SymbolInput2 = import_zod6.z.object({ symbol: import_zod6.z.string().min(1) });
+var FinancialsInput = import_zod6.z.object({
+  symbol: import_zod6.z.string().min(1),
+  quarterly: import_zod6.z.boolean().optional()
+});
+var getFinancialsTool = {
+  tool: {
+    name: "get_financials",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u8D22\u52A1\u6570\u636E\uFF1A\u8425\u6536\u3001\u6BDB\u5229\u7387\u3001\u51C0\u5229\u6DA6\u3001\u51C0\u5229\u7387\u3001EPS\u3001\u81EA\u7531\u73B0\u91D1\u6D41\u3001\u8D1F\u503A\u7387\u3002\u9ED8\u8BA4\u8FD4\u56DE\u8FD14\u5E74\u5E74\u62A5\uFF0Cquarterly=true \u8FD4\u56DE\u8FD14\u5B63\u5EA6\u5B63\u62A5\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA" },
+        quarterly: { type: "boolean", description: "true=\u5B63\u62A5\uFF0Cfalse=\u5E74\u62A5\uFF08\u9ED8\u8BA4\uFF09" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = FinancialsInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchFinancials(parsed.data.symbol, parsed.data.quarterly ?? false));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var getAnalystRatingTool = {
+  tool: {
+    name: "get_analyst_rating",
+    description: "\u83B7\u53D6\u534E\u5C14\u8857\u5206\u6790\u5E08\u8BC4\u7EA7\uFF1A\u5171\u8BC6\u8BC4\u7EA7\uFF08buy/hold/sell\uFF09\u3001\u5E73\u5747\u76EE\u6807\u4EF7\u3001\u9AD8\u4F4E\u76EE\u6807\u4EF7\u3001\u5F3A\u4E70/\u4E70/\u6301\u6709/\u5356/\u5F3A\u5356\u4EBA\u6570\u5206\u5E03\uFF0C\u4EE5\u53CA\u6700\u8FD110\u6761\u8BC4\u7EA7\u53D8\u52A8\u8BB0\u5F55\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput2.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchAnalystRating(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var NewsInput = import_zod6.z.object({
+  symbol: import_zod6.z.string().min(1),
+  limit: import_zod6.z.number().int().min(1).max(30).optional()
+});
+var getStockNewsTool = {
+  tool: {
+    name: "get_stock_news",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u4E2A\u80A1\u6700\u65B0\u65B0\u95FB\uFF08\u8FD17\u5929\uFF09\uFF0C\u542B\u6807\u9898\u3001\u6458\u8981\u3001\u94FE\u63A5\u3001\u53D1\u5E03\u65F6\u95F4\u3002\u6700\u591A30\u6761\uFF0C\u9ED8\u8BA415\u6761\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA" },
+        limit: { type: "number", description: "\u8FD4\u56DE\u6761\u6570\uFF0C\u9ED8\u8BA415\uFF0C\u6700\u592730" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = NewsInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchStockNews(parsed.data.symbol, parsed.data.limit ?? 15));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var getInsiderActivityTool = {
+  tool: {
+    name: "get_insider_activity",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u5185\u90E8\u4EBA\uFF08\u9AD8\u7BA1/\u8463\u4E8B\uFF09\u8FD1\u671F\u4E70\u5356\u8BB0\u5F55\uFF0C\u57FA\u4E8E SEC Form 4 \u516C\u5F00\u6570\u636E\u3002\u542B\u4EA4\u6613\u4EBA\u59D3\u540D\u3001\u804C\u4F4D\u3001\u4EA4\u6613\u7C7B\u578B\u3001\u80A1\u6570\u3001\u4EA4\u6613\u91D1\u989D\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput2.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchInsiderActivity(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var getStockFullOverviewTool = {
+  tool: {
+    name: "get_stock_full_overview",
+    description: "\u4E00\u6B21\u8C03\u7528\u83B7\u53D6\u7F8E\u80A1\u5B8C\u6574\u5206\u6790\u6570\u636E\uFF1A\u5B9E\u65F6\u884C\u60C5 + \u516C\u53F8\u57FA\u672C\u9762 + \u5206\u6790\u5E08\u8BC4\u7EA7 + \u8FD1\u671F\u65B0\u95FB\uFF08\u5E76\u884C\u83B7\u53D6\uFF09\u3002\u9002\u5408\u56DE\u7B54\u7EFC\u5408\u5206\u6790\u7C7B\u95EE\u9898\uFF08\u5982\uFF1A\u5E2E\u6211\u5206\u6790\u4E00\u4E0B NVDA\uFF09\uFF0C\u907F\u514D\u591A\u6B21\u8C03\u7528\u4E0D\u540C\u5DE5\u5177\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA\u3001TSLA" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput2.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { symbol } = parsed.data;
+    try {
+      const [quotes, profile, analyst, news] = await Promise.allSettled([
+        fetchUSQuotes([symbol]),
+        fetchStockProfile(symbol),
+        fetchAnalystRating(symbol),
+        fetchStockNews(symbol, 10)
+      ]);
+      return ok({
+        symbol,
+        quote: quotes.status === "fulfilled" ? quotes.value[0] ?? null : null,
+        profile: profile.status === "fulfilled" ? profile.value : null,
+        analyst: analyst.status === "fulfilled" ? analyst.value : null,
+        news: news.status === "fulfilled" ? news.value : []
+      });
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+
 // src/tools/index.ts
 var tools = [
   getQuoteTool,
@@ -1175,7 +1426,12 @@ var tools = [
   getCryptoTopTool,
   getCryptoCatsTool,
   getCryptoFundingTool,
-  getCryptoLiquidationTool
+  getCryptoLiquidationTool,
+  getFinancialsTool,
+  getAnalystRatingTool,
+  getStockNewsTool,
+  getInsiderActivityTool,
+  getStockFullOverviewTool
 ];
 var toolMap = new Map(
   tools.map((t) => [t.tool.name, t])
@@ -1186,10 +1442,10 @@ var server = new import_server.Server(
   { name: "stock-mcp", version: "1.0.0" },
   { capabilities: { tools: {} } }
 );
-server.setRequestHandler(import_types6.ListToolsRequestSchema, async () => ({
+server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
   tools: tools.map((t) => t.tool)
 }));
-server.setRequestHandler(import_types6.CallToolRequestSchema, async (request) => {
+server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   const def = toolMap.get(name);
   if (!def) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xstock-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Stock & Crypto analysis MCP Server",
   "main": "dist/index.js",
   "bin": {

package/src/data/yahoo.ts

@@ -1,4 +1,5 @@
 import { default as YahooFinance } from "yahoo-finance2";
+import axios from "axios";
 
 // v3 需要实例化
 const yf = new YahooFinance({ suppressNotices: ["yahooSurvey"] });
@@ -158,6 +159,187 @@ export async function fetchEarningsCalendar(symbol: string): Promise<EarningsCal
   };
 }
 
+// ─── Financials ───────────────────────────────────────────────────────────────
+
+export interface FinancialPeriod {
+  date: string;
+  totalRevenue: number | null;
+  grossProfit: number | null;
+  grossMargin: number | null;
+  netIncome: number | null;
+  netMargin: number | null;
+  epsDiluted: number | null;
+  operatingCashFlow: number | null;
+  freeCashFlow: number | null;
+  totalDebt: number | null;
+  stockholdersEquity: number | null;
+  debtToEquity: number | null;
+}
+
+export async function fetchFinancials(symbol: string, quarterly = false): Promise<FinancialPeriod[]> {
+  process.stderr.write(`[yahoo] fetchFinancials symbol=${symbol} quarterly=${quarterly}\n`);
+  const modules = quarterly
+    ? ["incomeStatementHistoryQuarterly", "cashflowStatementHistoryQuarterly", "balanceSheetHistoryQuarterly"]
+    : ["incomeStatementHistory", "cashflowStatementHistory", "balanceSheetHistory"];
+
+  const summary = await yf.quoteSummary(symbol, { modules: modules as never[] });
+
+  const incomeKey = quarterly ? "incomeStatementHistoryQuarterly" : "incomeStatementHistory";
+  const cashKey = quarterly ? "cashflowStatementHistoryQuarterly" : "cashflowStatementHistory";
+  const balanceKey = quarterly ? "balanceSheetHistoryQuarterly" : "balanceSheetHistory";
+
+  const incomeArr = ((summary[incomeKey as keyof typeof summary] as Record<string, unknown>)
+    ?.incomeStatementHistory as Record<string, unknown>[]) ?? [];
+  const cashArr = ((summary[cashKey as keyof typeof summary] as Record<string, unknown>)
+    ?.cashflowStatements as Record<string, unknown>[]) ?? [];
+  const balanceArr = ((summary[balanceKey as keyof typeof summary] as Record<string, unknown>)
+    ?.balanceSheetStatements as Record<string, unknown>[]) ?? [];
+
+  return incomeArr.slice(0, 4).map((inc, i) => {
+    const cash = cashArr[i] ?? {};
+    const bal = balanceArr[i] ?? {};
+    const date = inc.endDate instanceof Date ? inc.endDate.toISOString().slice(0, 10) : String(inc.endDate ?? "");
+    const revenue = inc.totalRevenue as number | null ?? null;
+    const gross = inc.grossProfit as number | null ?? null;
+    const net = inc.netIncome as number | null ?? null;
+    const opCash = cash.totalCashFromOperatingActivities as number | null ?? null;
+    const capex = cash.capitalExpenditures as number | null ?? null;
+    const debt = bal.totalDebt as number | null ?? (bal.longTermDebt as number | null ?? null);
+    const equity = bal.totalStockholderEquity as number | null ?? null;
+
+    return {
+      date,
+      totalRevenue: revenue,
+      grossProfit: gross,
+      grossMargin: revenue && gross ? Math.round((gross / revenue) * 10000) / 100 : null,
+      netIncome: net,
+      netMargin: revenue && net ? Math.round((net / revenue) * 10000) / 100 : null,
+      epsDiluted: inc.dilutedEPS as number | null ?? null,
+      operatingCashFlow: opCash,
+      freeCashFlow: opCash !== null && capex !== null ? opCash + capex : null,
+      totalDebt: debt,
+      stockholdersEquity: equity,
+      debtToEquity: debt !== null && equity !== null && equity !== 0
+        ? Math.round((debt / equity) * 100) / 100 : null,
+    };
+  });
+}
+
+// ─── Analyst Rating ───────────────────────────────────────────────────────────
+
+export interface AnalystRating {
+  symbol: string;
+  consensus: string | null;
+  targetPriceMean: number | null;
+  targetPriceHigh: number | null;
+  targetPriceLow: number | null;
+  distribution: { strongBuy: number; buy: number; hold: number; sell: number; strongSell: number };
+  recentChanges: { date: string; firm: string; action: string; from: string | null; to: string | null }[];
+}
+
+export async function fetchAnalystRating(symbol: string): Promise<AnalystRating> {
+  process.stderr.write(`[yahoo] fetchAnalystRating symbol=${symbol}\n`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["financialData", "recommendationTrend", "upgradeDowngradeHistory"],
+  });
+
+  const fin = summary.financialData as Record<string, unknown> | undefined;
+  const trend = summary.recommendationTrend as Record<string, unknown> | undefined;
+  const history = summary.upgradeDowngradeHistory as Record<string, unknown> | undefined;
+
+  const trendArr = (trend?.trend as Record<string, unknown>[]) ?? [];
+  const latest = trendArr[0] ?? {};
+
+  const changes = ((history?.history as Record<string, unknown>[]) ?? []).slice(0, 10).map((h) => ({
+    date: h.epochGradeDate instanceof Date ? h.epochGradeDate.toISOString().slice(0, 10) : String(h.epochGradeDate ?? ""),
+    firm: String(h.firm ?? ""),
+    action: String(h.action ?? ""),
+    from: h.fromGrade ? String(h.fromGrade) : null,
+    to: h.toGrade ? String(h.toGrade) : null,
+  }));
+
+  return {
+    symbol,
+    consensus: fin?.recommendationKey as string | null ?? null,
+    targetPriceMean: fin?.targetMeanPrice as number | null ?? null,
+    targetPriceHigh: fin?.targetHighPrice as number | null ?? null,
+    targetPriceLow: fin?.targetLowPrice as number | null ?? null,
+    distribution: {
+      strongBuy: Number(latest.strongBuy ?? 0),
+      buy: Number(latest.buy ?? 0),
+      hold: Number(latest.hold ?? 0),
+      sell: Number(latest.sell ?? 0),
+      strongSell: Number(latest.strongSell ?? 0),
+    },
+    recentChanges: changes,
+  };
+}
+
+// ─── News ─────────────────────────────────────────────────────────────────────
+
+export interface StockNewsItem {
+  title: string;
+  link: string;
+  summary: string;
+  pubDate: string;
+}
+
+function extractXmlTag(xml: string, tag: string): string {
+  const match = xml.match(new RegExp(`<${tag}[^>]*>(?:<!\\[CDATA\\[)?([\\s\\S]*?)(?:\\]\\]>)?</${tag}>`, "i"));
+  return match ? match[1].trim() : "";
+}
+
+export async function fetchStockNews(symbol: string, limit = 20): Promise<StockNewsItem[]> {
+  process.stderr.write(`[yahoo] fetchStockNews symbol=${symbol}\n`);
+  const url = `https://feeds.finance.yahoo.com/rss/2.0/headline?s=${symbol}&region=US&lang=en-US`;
+  const res = await axios.get<string>(url, { timeout: 8000, responseType: "text" });
+  const xml = res.data;
+
+  const items: StockNewsItem[] = [];
+  const itemMatches = xml.match(/<item>[\s\S]*?<\/item>/g) ?? [];
+  for (const item of itemMatches.slice(0, limit)) {
+    items.push({
+      title: extractXmlTag(item, "title"),
+      link: extractXmlTag(item, "link") || extractXmlTag(item, "guid"),
+      summary: extractXmlTag(item, "description").replace(/<[^>]+>/g, "").slice(0, 200),
+      pubDate: extractXmlTag(item, "pubDate"),
+    });
+  }
+  process.stderr.write(`[yahoo] fetchStockNews 返回 ${items.length} 条\n`);
+  return items;
+}
+
+// ─── Insider Activity ─────────────────────────────────────────────────────────
+
+export interface InsiderTransaction {
+  date: string;
+  name: string;
+  relation: string;
+  transactionType: string;
+  shares: number | null;
+  value: number | null;
+  sharesBefore: number | null;
+  sharesAfter: number | null;
+}
+
+export async function fetchInsiderActivity(symbol: string): Promise<InsiderTransaction[]> {
+  process.stderr.write(`[yahoo] fetchInsiderActivity symbol=${symbol}\n`);
+  const summary = await yf.quoteSummary(symbol, { modules: ["insiderTransactions"] });
+  const raw = summary.insiderTransactions as Record<string, unknown> | undefined;
+  const txArr = (raw?.transactions as Record<string, unknown>[]) ?? [];
+
+  return txArr.slice(0, 20).map((tx) => ({
+    date: tx.startDate instanceof Date ? tx.startDate.toISOString().slice(0, 10) : String(tx.startDate ?? ""),
+    name: String(tx.filerName ?? ""),
+    relation: String(tx.filerRelation ?? ""),
+    transactionType: String(tx.transactionDescription ?? ""),
+    shares: tx.shares as number | null ?? null,
+    value: tx.value as number | null ?? null,
+    sharesBefore: tx.shareholderBefore as number | null ?? null,
+    sharesAfter: tx.shareholderAfter as number | null ?? null,
+  }));
+}
+
 export async function fetchStockProfile(symbol: string): Promise<StockProfile> {
   process.stderr.write(`[yahoo] fetchStockProfile symbol=${symbol}\n`);
   const summary = await yf.quoteSummary(symbol, {

package/src/tools/index.ts

@@ -4,6 +4,7 @@ import { getKlineTool, getKlineWithIndicatorsTool } from "./kline";
 import { searchStockTool } from "./search";
 import { getUsIndicesTool, getStockProfileTool, getEarningsCalendarTool, getUsSectorHeatmapTool } from "./us-market";
 import { getCryptoOverviewTool, getCryptoTopTool, getCryptoCatsTool, getCryptoFundingTool, getCryptoLiquidationTool } from "./crypto";
+import { getFinancialsTool, getAnalystRatingTool, getStockNewsTool, getInsiderActivityTool, getStockFullOverviewTool } from "./us-fundamentals";
 
 export * from "./types";
 
@@ -21,6 +22,11 @@ export const tools: ToolDef[] = [
   getCryptoCatsTool,
   getCryptoFundingTool,
   getCryptoLiquidationTool,
+  getFinancialsTool,
+  getAnalystRatingTool,
+  getStockNewsTool,
+  getInsiderActivityTool,
+  getStockFullOverviewTool,
 ];
 
 export const toolMap = new Map<string, ToolDef>(

package/src/tools/us-fundamentals.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import {
+  fetchFinancials,
+  fetchAnalystRating,
+  fetchStockNews,
+  fetchInsiderActivity,
+  fetchUSQuotes,
+  fetchStockProfile,
+} from "../data/yahoo";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+const SymbolInput = z.object({ symbol: z.string().min(1) });
+
+// ─── get_financials ───────────────────────────────────────────────────────────
+
+const FinancialsInput = z.object({
+  symbol: z.string().min(1),
+  quarterly: z.boolean().optional(),
+});
+
+export const getFinancialsTool: ToolDef = {
+  tool: {
+    name: "get_financials",
+    description:
+      "获取美股财务数据：营收、毛利率、净利润、净利率、EPS、自由现金流、负债率。" +
+      "默认返回近4年年报，quarterly=true 返回近4季度季报。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、NVDA" },
+        quarterly: { type: "boolean", description: "true=季报，false=年报（默认）" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = FinancialsInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchFinancials(parsed.data.symbol, parsed.data.quarterly ?? false));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_analyst_rating ───────────────────────────────────────────────────────
+
+export const getAnalystRatingTool: ToolDef = {
+  tool: {
+    name: "get_analyst_rating",
+    description:
+      "获取华尔街分析师评级：共识评级（buy/hold/sell）、平均目标价、高低目标价、" +
+      "强买/买/持有/卖/强卖人数分布，以及最近10条评级变动记录。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、NVDA" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchAnalystRating(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_stock_news ───────────────────────────────────────────────────────────
+
+const NewsInput = z.object({
+  symbol: z.string().min(1),
+  limit: z.number().int().min(1).max(30).optional(),
+});
+
+export const getStockNewsTool: ToolDef = {
+  tool: {
+    name: "get_stock_news",
+    description:
+      "获取美股个股最新新闻（近7天），含标题、摘要、链接、发布时间。最多30条，默认15条。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、NVDA" },
+        limit: { type: "number", description: "返回条数，默认15，最大30" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = NewsInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchStockNews(parsed.data.symbol, parsed.data.limit ?? 15));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_insider_activity ─────────────────────────────────────────────────────
+
+export const getInsiderActivityTool: ToolDef = {
+  tool: {
+    name: "get_insider_activity",
+    description:
+      "获取美股内部人（高管/董事）近期买卖记录，基于 SEC Form 4 公开数据。" +
+      "含交易人姓名、职位、交易类型、股数、交易金额。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、NVDA" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchInsiderActivity(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_stock_full_overview ──────────────────────────────────────────────────
+
+export const getStockFullOverviewTool: ToolDef = {
+  tool: {
+    name: "get_stock_full_overview",
+    description:
+      "一次调用获取美股完整分析数据：实时行情 + 公司基本面 + 分析师评级 + 近期新闻（并行获取）。" +
+      "适合回答综合分析类问题（如：帮我分析一下 NVDA），避免多次调用不同工具。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、NVDA、TSLA" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { symbol } = parsed.data;
+
+    try {
+      const [quotes, profile, analyst, news] = await Promise.allSettled([
+        fetchUSQuotes([symbol]),
+        fetchStockProfile(symbol),
+        fetchAnalystRating(symbol),
+        fetchStockNews(symbol, 10),
+      ]);
+
+      return ok({
+        symbol,
+        quote: quotes.status === "fulfilled" ? quotes.value[0] ?? null : null,
+        profile: profile.status === "fulfilled" ? profile.value : null,
+        analyst: analyst.status === "fulfilled" ? analyst.value : null,
+        news: news.status === "fulfilled" ? news.value : [],
+      });
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};