xstock-mcp 1.2.0 → 1.3.0

package/README.md

@@ -11,17 +11,44 @@
 
 ## 工具列表
 
+### 美股
+
 | 工具 | 说明 |
 |------|------|
-| `get_quote` | 实时报价（美股 / 加密货币 / A股 / 港股） |
+| `get_quote` | 实时行情 |
 | `get_kline` | K线数据，支持日线 / 周线 / 月线 |
-| `search_stock` | 按关键词搜索股票和加密货币 |
-| `get_us_indices` | 美国主要市场指数 |
-| `get_stock_profile` | 公司基本面信息 |
-| `get_crypto_overview` | 全球加密市场总市值 + 恐惧贪婪指数 |
+| `get_kline_with_indicators` | K线 + MA5/10/20/60、RSI14、MACD、布林带（精确计算） |
+| `get_us_indices` | 主要指数：标普500、纳斯达克、道琼斯、罗素2000、VIX |
+| `get_us_sector_heatmap` | 11大行业板块今日涨跌（SPDR ETF） |
+| `get_stock_profile` | 公司基本面：市值、PE、行业、简介 |
+| `get_financials` | 财务数据：营收、毛利率、净利润、自由现金流、负债率（年报/季报） |
+| `get_analyst_rating` | 分析师评级分布、目标价、近期评级变动 |
+| `get_earnings_calendar` | 下次财报日期 + 近4季度 EPS 历史 |
+| `get_stock_news` | 个股最新新闻（近7天） |
+| `get_insider_activity` | 高管/内部人买卖记录（SEC Form 4） |
+| `get_market_movers` | 当日涨幅榜 / 跌幅榜 / 成交量异动榜 |
+| `get_dividend_history` | 分红历史、股息率、除息日 |
+| `get_institutional_holders` | 前10大机构持仓比例及变动 |
+| `get_similar_stocks` | 同行业可比公司估值对比 |
+| `get_stock_full_overview` | 复合工具：行情 + 基本面 + 评级 + 新闻，一次返回 |
+| `search_stock` | 按名称或代码搜索 |
+
+### 加密货币
+
+| 工具 | 说明 |
+|------|------|
+| `get_crypto_overview` | 全球市值 + 恐惧贪婪指数 |
 | `get_crypto_top` | 按市值排名的 Top N 币种 |
-| `get_crypto_categories` | 加密货币赛道分类（DeFi、Layer1、AI、GameFi…） |
+| `get_crypto_categories` | 赛道分类（DeFi、Layer1、AI、GameFi…） |
 | `get_funding_rate` | Binance 永续合约资金费率 |
+| `get_crypto_liquidation` | 合约市场情绪：OI、多空比、吃单比 |
+
+### A股 / 港股
+
+| 工具 | 说明 |
+|------|------|
+| `get_quote` | 实时行情（腾讯财经） |
+| `get_kline` | K线数据 |
 
 ## 使用方法
 

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_types7 = require("@modelcontextprotocol/sdk/types.js");
+var import_types8 = require("@modelcontextprotocol/sdk/types.js");
 
 // src/tools/quotes.ts
 var import_zod = require("zod");
@@ -368,6 +368,93 @@ async function fetchInsiderActivity(symbol) {
     sharesAfter: tx.shareholderAfter ?? null
   }));
 }
+function mapQuoteToMover(q) {
+  return {
+    symbol: String(q.symbol ?? ""),
+    name: String(q.longName ?? q.shortName ?? q.symbol ?? ""),
+    price: Number(q.regularMarketPrice ?? 0),
+    change: Number(q.regularMarketChange ?? 0),
+    changePercent: Number(q.regularMarketChangePercent ?? 0).toFixed(2) + "%",
+    volume: Number(q.regularMarketVolume ?? 0),
+    marketCap: q.marketCap != null ? Number(q.marketCap) : null
+  };
+}
+async function fetchMarketMovers(type, count = 20) {
+  process.stderr.write(`[yahoo] fetchMarketMovers type=${type} count=${count}
+`);
+  let result;
+  if (type === "gainers") {
+    result = await yf.dailyGainers({ count, region: "US" });
+  } else if (type === "losers") {
+    result = await yf.dailyLosers({ count, region: "US" });
+  } else {
+    result = await yf.mostActives({ count, region: "US" });
+  }
+  const quotes = result.quotes ?? [];
+  return quotes.map(mapQuoteToMover);
+}
+async function fetchDividendHistory(symbol) {
+  process.stderr.write(`[yahoo] fetchDividendHistory symbol=${symbol}
+`);
+  const fiveYearsAgo = new Date(Date.now() - 5 * 365 * 864e5).toISOString().slice(0, 10);
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const [summaryResult, histResult] = await Promise.allSettled([
+    yf.quoteSummary(symbol, { modules: ["summaryDetail", "defaultKeyStatistics"] }),
+    yf.historical(symbol, { period1: fiveYearsAgo, period2: today, events: "dividends" })
+  ]);
+  const detail = summaryResult.status === "fulfilled" ? summaryResult.value.summaryDetail : void 0;
+  const history = histResult.status === "fulfilled" ? histResult.value.filter((r) => r.dividends != null).map((r) => ({ date: r.date.toISOString().slice(0, 10), amount: r.dividends })).reverse() : [];
+  const consecutiveYears = history.length > 0 ? new Set(history.map((h) => h.date.slice(0, 4))).size : null;
+  return {
+    symbol,
+    currentYield: detail?.dividendYield ?? null,
+    annualDividend: detail?.dividendRate ?? null,
+    exDividendDate: detail?.exDividendDate instanceof Date ? detail.exDividendDate.toISOString().slice(0, 10) : null,
+    consecutiveYears,
+    history
+  };
+}
+async function fetchInstitutionalHolders(symbol) {
+  process.stderr.write(`[yahoo] fetchInstitutionalHolders symbol=${symbol}
+`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["institutionOwnership"]
+  });
+  const ownership = summary.institutionOwnership;
+  const holders = ownership?.ownershipList ?? [];
+  return holders.slice(0, 10).map((h) => ({
+    organization: String(h.organization ?? ""),
+    pctHeld: h.pctHeld != null ? Math.round(Number(h.pctHeld) * 1e4) / 100 : null,
+    shares: h.position != null ? Number(h.position) : null,
+    value: h.value != null ? Number(h.value) : null,
+    reportDate: h.reportDate instanceof Date ? h.reportDate.toISOString().slice(0, 10) : null
+  }));
+}
+async function fetchSimilarStocks(symbol) {
+  process.stderr.write(`[yahoo] fetchSimilarStocks symbol=${symbol}
+`);
+  const recs = await yf.recommendedSymbols(symbol);
+  const symbols = (recs.recommendedSymbols ?? []).slice(0, 8).map((r) => String(r.symbol ?? "")).filter(Boolean);
+  if (symbols.length === 0) return [];
+  const quotes = await fetchUSQuotes(symbols);
+  const profiles = await Promise.allSettled(
+    symbols.map((s) => yf.quoteSummary(s, { modules: ["price", "summaryProfile"] }))
+  );
+  return quotes.map((q, i) => {
+    const p = profiles[i];
+    const profile = p.status === "fulfilled" ? p.value.summaryProfile : void 0;
+    const price = p.status === "fulfilled" ? p.value.price : void 0;
+    return {
+      symbol: q.symbol,
+      name: q.name,
+      price: q.price,
+      changePercent: q.changePercent,
+      marketCap: price?.marketCap != null ? Number(price.marketCap) : q.marketCap,
+      pe: price?.trailingPE != null ? Number(price.trailingPE) : null,
+      sector: profile?.sector ? String(profile.sector) : null
+    };
+  });
+}
 async function fetchStockProfile(symbol) {
   process.stderr.write(`[yahoo] fetchStockProfile symbol=${symbol}
 `);
@@ -1412,6 +1499,110 @@ var getStockFullOverviewTool = {
   }
 };
 
+// src/tools/us-market-b.ts
+var import_zod7 = require("zod");
+var MoversInput = import_zod7.z.object({
+  type: import_zod7.z.enum(["gainers", "losers", "actives"]).optional(),
+  count: import_zod7.z.number().int().min(1).max(50).optional()
+});
+var getMarketMoversTool = {
+  tool: {
+    name: "get_market_movers",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u5F53\u65E5\u699C\u5355\uFF1A\u6DA8\u5E45\u699C\uFF08gainers\uFF09\u3001\u8DCC\u5E45\u699C\uFF08losers\uFF09\u3001\u6210\u4EA4\u91CF\u5F02\u52A8\u699C\uFF08actives\uFF09\u3002\u9ED8\u8BA4\u8FD4\u56DE\u6DA8\u5E45\u699C Top 20\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["gainers", "losers", "actives"],
+          description: "\u699C\u5355\u7C7B\u578B\uFF1Againers=\u6DA8\u5E45\u699C\uFF0Closers=\u8DCC\u5E45\u699C\uFF0Cactives=\u6210\u4EA4\u91CF\u699C\uFF0C\u9ED8\u8BA4 gainers"
+        },
+        count: {
+          type: "number",
+          description: "\u8FD4\u56DE\u6570\u91CF\uFF0C\u9ED8\u8BA420\uFF0C\u6700\u592750"
+        }
+      },
+      required: []
+    }
+  },
+  handler: async (input) => {
+    const parsed = MoversInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchMarketMovers(parsed.data.type ?? "gainers", parsed.data.count ?? 20));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var SymbolInput3 = import_zod7.z.object({ symbol: import_zod7.z.string().min(1) });
+var getDividendHistoryTool = {
+  tool: {
+    name: "get_dividend_history",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u5206\u7EA2\u6570\u636E\uFF1A\u5F53\u524D\u80A1\u606F\u7387\u3001\u5E74\u5316\u5206\u7EA2\u989D\u3001\u9664\u606F\u65E5\u3001\u8FD15\u5E74\u5206\u7EA2\u5386\u53F2\u8BB0\u5F55\u3002\u9002\u5408\u5224\u65AD\u516C\u53F8\u662F\u5426\u7A33\u5B9A\u6D3E\u606F\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001JNJ\u3001KO" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput3.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchDividendHistory(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var getInstitutionalHoldersTool = {
+  tool: {
+    name: "get_institutional_holders",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u524D10\u5927\u673A\u6784\u6301\u4ED3\uFF1A\u673A\u6784\u540D\u79F0\u3001\u6301\u80A1\u6BD4\u4F8B\u3001\u6301\u80A1\u6570\u91CF\u3001\u6301\u4ED3\u5E02\u503C\u3001\u6700\u65B0\u62A5\u544A\u65E5\u671F\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 AAPL\u3001NVDA" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput3.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchInstitutionalHolders(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+var getSimilarStocksTool = {
+  tool: {
+    name: "get_similar_stocks",
+    description: "\u83B7\u53D6\u4E0E\u6307\u5B9A\u80A1\u7968\u540C\u884C\u4E1A\u7684\u53EF\u6BD4\u516C\u53F8\u5217\u8868\uFF0C\u542B\u5B9E\u65F6\u4EF7\u683C\u3001\u6DA8\u8DCC\u5E45\u3001\u5E02\u503C\u3001PE\u3001\u884C\u4E1A\u5206\u7C7B\u3002\u9002\u5408\u6A2A\u5411\u4F30\u503C\u5BF9\u6BD4\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 NVDA\u3001TSLA\u3001AAPL" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput3.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchSimilarStocks(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
+
 // src/tools/index.ts
 var tools = [
   getQuoteTool,
@@ -1431,7 +1622,11 @@ var tools = [
   getAnalystRatingTool,
   getStockNewsTool,
   getInsiderActivityTool,
-  getStockFullOverviewTool
+  getStockFullOverviewTool,
+  getMarketMoversTool,
+  getDividendHistoryTool,
+  getInstitutionalHoldersTool,
+  getSimilarStocksTool
 ];
 var toolMap = new Map(
   tools.map((t) => [t.tool.name, t])
@@ -1442,10 +1637,10 @@ var server = new import_server.Server(
   { name: "stock-mcp", version: "1.0.0" },
   { capabilities: { tools: {} } }
 );
-server.setRequestHandler(import_types7.ListToolsRequestSchema, async () => ({
+server.setRequestHandler(import_types8.ListToolsRequestSchema, async () => ({
   tools: tools.map((t) => t.tool)
 }));
-server.setRequestHandler(import_types7.CallToolRequestSchema, async (request) => {
+server.setRequestHandler(import_types8.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.2.0",
+  "version": "1.3.0",
   "description": "Stock & Crypto analysis MCP Server",
   "main": "dist/index.js",
   "bin": {

package/src/data/yahoo.ts

@@ -340,6 +340,164 @@ export async function fetchInsiderActivity(symbol: string): Promise<InsiderTrans
   }));
 }
 
+// ─── Market Movers ────────────────────────────────────────────────────────────
+
+export interface MoverItem {
+  symbol: string;
+  name: string;
+  price: number;
+  change: number;
+  changePercent: string;
+  volume: number;
+  marketCap: number | null;
+}
+
+function mapQuoteToMover(q: Record<string, unknown>): MoverItem {
+  return {
+    symbol: String(q.symbol ?? ""),
+    name: String(q.longName ?? q.shortName ?? q.symbol ?? ""),
+    price: Number(q.regularMarketPrice ?? 0),
+    change: Number(q.regularMarketChange ?? 0),
+    changePercent: (Number(q.regularMarketChangePercent ?? 0).toFixed(2)) + "%",
+    volume: Number(q.regularMarketVolume ?? 0),
+    marketCap: q.marketCap != null ? Number(q.marketCap) : null,
+  };
+}
+
+export async function fetchMarketMovers(type: "gainers" | "losers" | "actives", count = 20): Promise<MoverItem[]> {
+  process.stderr.write(`[yahoo] fetchMarketMovers type=${type} count=${count}\n`);
+  let result: Record<string, unknown>;
+  if (type === "gainers") {
+    result = await (yf as unknown as Record<string, (opts: unknown) => Promise<Record<string, unknown>>>)
+      .dailyGainers({ count, region: "US" });
+  } else if (type === "losers") {
+    result = await (yf as unknown as Record<string, (opts: unknown) => Promise<Record<string, unknown>>>)
+      .dailyLosers({ count, region: "US" });
+  } else {
+    result = await (yf as unknown as Record<string, (opts: unknown) => Promise<Record<string, unknown>>>)
+      .mostActives({ count, region: "US" });
+  }
+  const quotes = (result.quotes as Record<string, unknown>[]) ?? [];
+  return quotes.map(mapQuoteToMover);
+}
+
+// ─── Dividend History ─────────────────────────────────────────────────────────
+
+export interface DividendInfo {
+  symbol: string;
+  currentYield: number | null;
+  annualDividend: number | null;
+  exDividendDate: string | null;
+  consecutiveYears: number | null;
+  history: { date: string; amount: number }[];
+}
+
+export async function fetchDividendHistory(symbol: string): Promise<DividendInfo> {
+  process.stderr.write(`[yahoo] fetchDividendHistory symbol=${symbol}\n`);
+  const fiveYearsAgo = new Date(Date.now() - 5 * 365 * 86400_000).toISOString().slice(0, 10);
+  const today = new Date().toISOString().slice(0, 10);
+
+  const [summaryResult, histResult] = await Promise.allSettled([
+    yf.quoteSummary(symbol, { modules: ["summaryDetail", "defaultKeyStatistics"] }),
+    yf.historical(symbol, { period1: fiveYearsAgo, period2: today, events: "dividends" }),
+  ]);
+
+  const detail = summaryResult.status === "fulfilled"
+    ? summaryResult.value.summaryDetail as Record<string, unknown> | undefined : undefined;
+
+  const history = histResult.status === "fulfilled"
+    ? (histResult.value as unknown as { date: Date; dividends: number }[])
+        .filter((r) => r.dividends != null)
+        .map((r) => ({ date: r.date.toISOString().slice(0, 10), amount: r.dividends }))
+        .reverse()
+    : [];
+
+  const consecutiveYears = history.length > 0
+    ? new Set(history.map((h) => h.date.slice(0, 4))).size : null;
+
+  return {
+    symbol,
+    currentYield: detail?.dividendYield as number | null ?? null,
+    annualDividend: detail?.dividendRate as number | null ?? null,
+    exDividendDate: detail?.exDividendDate instanceof Date
+      ? detail.exDividendDate.toISOString().slice(0, 10) : null,
+    consecutiveYears,
+    history,
+  };
+}
+
+// ─── Institutional Holders ────────────────────────────────────────────────────
+
+export interface InstitutionalHolder {
+  organization: string;
+  pctHeld: number | null;
+  shares: number | null;
+  value: number | null;
+  reportDate: string | null;
+}
+
+export async function fetchInstitutionalHolders(symbol: string): Promise<InstitutionalHolder[]> {
+  process.stderr.write(`[yahoo] fetchInstitutionalHolders symbol=${symbol}\n`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["institutionOwnership"] as never[],
+  });
+  const ownership = summary.institutionOwnership as Record<string, unknown> | undefined;
+  const holders = (ownership?.ownershipList as Record<string, unknown>[]) ?? [];
+  return holders.slice(0, 10).map((h) => ({
+    organization: String(h.organization ?? ""),
+    pctHeld: h.pctHeld != null ? Math.round(Number(h.pctHeld) * 10000) / 100 : null,
+    shares: h.position != null ? Number(h.position) : null,
+    value: h.value != null ? Number(h.value) : null,
+    reportDate: h.reportDate instanceof Date ? h.reportDate.toISOString().slice(0, 10) : null,
+  }));
+}
+
+// ─── Similar Stocks ───────────────────────────────────────────────────────────
+
+export interface SimilarStock {
+  symbol: string;
+  name: string;
+  price: number;
+  changePercent: string;
+  marketCap: number | null;
+  pe: number | null;
+  sector: string | null;
+}
+
+export async function fetchSimilarStocks(symbol: string): Promise<SimilarStock[]> {
+  process.stderr.write(`[yahoo] fetchSimilarStocks symbol=${symbol}\n`);
+  const recs = await (yf as unknown as Record<string, (sym: string) => Promise<Record<string, unknown>>>)
+    .recommendedSymbols(symbol);
+  const symbols: string[] = ((recs.recommendedSymbols as Record<string, unknown>[]) ?? [])
+    .slice(0, 8)
+    .map((r) => String(r.symbol ?? ""))
+    .filter(Boolean);
+
+  if (symbols.length === 0) return [];
+
+  const quotes = await fetchUSQuotes(symbols);
+  const profiles = await Promise.allSettled(
+    symbols.map((s) => yf.quoteSummary(s, { modules: ["price", "summaryProfile"] }))
+  );
+
+  return quotes.map((q, i) => {
+    const p = profiles[i];
+    const profile = p.status === "fulfilled"
+      ? p.value.summaryProfile as Record<string, unknown> | undefined : undefined;
+    const price = p.status === "fulfilled"
+      ? p.value.price as Record<string, unknown> | undefined : undefined;
+    return {
+      symbol: q.symbol,
+      name: q.name,
+      price: q.price,
+      changePercent: q.changePercent,
+      marketCap: price?.marketCap != null ? Number(price.marketCap) : q.marketCap,
+      pe: price?.trailingPE != null ? Number(price.trailingPE) : null,
+      sector: profile?.sector ? String(profile.sector) : 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

@@ -5,6 +5,7 @@ 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";
+import { getMarketMoversTool, getDividendHistoryTool, getInstitutionalHoldersTool, getSimilarStocksTool } from "./us-market-b";
 
 export * from "./types";
 
@@ -27,6 +28,10 @@ export const tools: ToolDef[] = [
   getStockNewsTool,
   getInsiderActivityTool,
   getStockFullOverviewTool,
+  getMarketMoversTool,
+  getDividendHistoryTool,
+  getInstitutionalHoldersTool,
+  getSimilarStocksTool,
 ];
 
 export const toolMap = new Map<string, ToolDef>(

package/src/tools/us-market-b.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import {
+  fetchMarketMovers,
+  fetchDividendHistory,
+  fetchInstitutionalHolders,
+  fetchSimilarStocks,
+} from "../data/yahoo";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+// ─── get_market_movers ────────────────────────────────────────────────────────
+
+const MoversInput = z.object({
+  type: z.enum(["gainers", "losers", "actives"]).optional(),
+  count: z.number().int().min(1).max(50).optional(),
+});
+
+export const getMarketMoversTool: ToolDef = {
+  tool: {
+    name: "get_market_movers",
+    description:
+      "获取美股当日榜单：涨幅榜（gainers）、跌幅榜（losers）、成交量异动榜（actives）。默认返回涨幅榜 Top 20。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["gainers", "losers", "actives"],
+          description: "榜单类型：gainers=涨幅榜，losers=跌幅榜，actives=成交量榜，默认 gainers",
+        },
+        count: {
+          type: "number",
+          description: "返回数量，默认20，最大50",
+        },
+      },
+      required: [],
+    },
+  },
+  handler: async (input) => {
+    const parsed = MoversInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchMarketMovers(parsed.data.type ?? "gainers", parsed.data.count ?? 20));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_dividend_history ─────────────────────────────────────────────────────
+
+const SymbolInput = z.object({ symbol: z.string().min(1) });
+
+export const getDividendHistoryTool: ToolDef = {
+  tool: {
+    name: "get_dividend_history",
+    description:
+      "获取美股分红数据：当前股息率、年化分红额、除息日、近5年分红历史记录。适合判断公司是否稳定派息。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 AAPL、JNJ、KO" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchDividendHistory(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_institutional_holders ────────────────────────────────────────────────
+
+export const getInstitutionalHoldersTool: ToolDef = {
+  tool: {
+    name: "get_institutional_holders",
+    description:
+      "获取美股前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 fetchInstitutionalHolders(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+// ─── get_similar_stocks ───────────────────────────────────────────────────────
+
+export const getSimilarStocksTool: ToolDef = {
+  tool: {
+    name: "get_similar_stocks",
+    description:
+      "获取与指定股票同行业的可比公司列表，含实时价格、涨跌幅、市值、PE、行业分类。适合横向估值对比。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 NVDA、TSLA、AAPL" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchSimilarStocks(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};