xstock-mcp 1.3.0 → 1.4.0

package/README.md

@@ -30,6 +30,7 @@
 | `get_dividend_history` | 分红历史、股息率、除息日 |
 | `get_institutional_holders` | 前10大机构持仓比例及变动 |
 | `get_similar_stocks` | 同行业可比公司估值对比 |
+| `get_short_interest` | 做空比例、空头回补天数、与上月对比 |
 | `get_stock_full_overview` | 复合工具：行情 + 基本面 + 评级 + 新闻，一次返回 |
 | `search_stock` | 按名称或代码搜索 |
 

package/dist/index.js

@@ -368,6 +368,28 @@ async function fetchInsiderActivity(symbol) {
     sharesAfter: tx.shareholderAfter ?? null
   }));
 }
+async function fetchShortInterest(symbol) {
+  process.stderr.write(`[yahoo] fetchShortInterest symbol=${symbol}
+`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["defaultKeyStatistics"]
+  });
+  const stats = summary.defaultKeyStatistics;
+  const sharesShort = stats?.sharesShort != null ? Number(stats.sharesShort) : null;
+  const priorMonth = stats?.sharesShortPriorMonth != null ? Number(stats.sharesShortPriorMonth) : null;
+  const change = sharesShort !== null && priorMonth !== null && priorMonth !== 0 ? Math.round((sharesShort - priorMonth) / priorMonth * 1e4) / 100 : null;
+  return {
+    symbol,
+    sharesShort,
+    sharesShortPriorMonth: priorMonth,
+    shortRatio: stats?.shortRatio != null ? Number(stats.shortRatio) : null,
+    shortPercentOfFloat: stats?.shortPercentOfFloat != null ? Math.round(Number(stats.shortPercentOfFloat) * 1e4) / 100 : null,
+    floatShares: stats?.floatShares != null ? Number(stats.floatShares) : null,
+    sharesOutstanding: stats?.sharesOutstanding != null ? Number(stats.sharesOutstanding) : null,
+    settlementDate: stats?.dateShortInterest instanceof Date ? stats.dateShortInterest.toISOString().slice(0, 10) : null,
+    changeFromPriorMonth: change
+  };
+}
 function mapQuoteToMover(q) {
   return {
     symbol: String(q.symbol ?? ""),
@@ -1602,6 +1624,28 @@ var getSimilarStocksTool = {
     }
   }
 };
+var getShortInterestTool = {
+  tool: {
+    name: "get_short_interest",
+    description: "\u83B7\u53D6\u7F8E\u80A1\u505A\u7A7A\u6570\u636E\uFF1A\u7A7A\u5934\u80A1\u6570\u3001\u505A\u7A7A\u5360\u6D41\u901A\u76D8\u6BD4\u4F8B\u3001\u7A7A\u5934\u56DE\u8865\u5929\u6570\uFF08Short Ratio\uFF09\u3001\u4E0E\u4E0A\u6708\u5BF9\u6BD4\u53D8\u5316\u3002\u7A7A\u5934\u56DE\u8865\u5929\u6570\u8D8A\u9AD8\u4EE3\u8868\u903C\u7A7A\u98CE\u9669\u8D8A\u5927\u3002",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "\u7F8E\u80A1\u4EE3\u7801\uFF0C\u5982 GME\u3001TSLA\u3001NVDA" }
+      },
+      required: ["symbol"]
+    }
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput3.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchShortInterest(parsed.data.symbol));
+    } catch (e) {
+      return err(e.message);
+    }
+  }
+};
 
 // src/tools/index.ts
 var tools = [
@@ -1626,7 +1670,8 @@ var tools = [
   getMarketMoversTool,
   getDividendHistoryTool,
   getInstitutionalHoldersTool,
-  getSimilarStocksTool
+  getSimilarStocksTool,
+  getShortInterestTool
 ];
 var toolMap = new Map(
   tools.map((t) => [t.tool.name, t])

package/package.json

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

package/src/data/yahoo.ts

@@ -340,6 +340,48 @@ export async function fetchInsiderActivity(symbol: string): Promise<InsiderTrans
   }));
 }
 
+// ─── Short Interest ───────────────────────────────────────────────────────────
+
+export interface ShortInterest {
+  symbol: string;
+  sharesShort: number | null;
+  sharesShortPriorMonth: number | null;
+  shortRatio: number | null;
+  shortPercentOfFloat: number | null;
+  floatShares: number | null;
+  sharesOutstanding: number | null;
+  settlementDate: string | null;
+  changeFromPriorMonth: number | null;
+}
+
+export async function fetchShortInterest(symbol: string): Promise<ShortInterest> {
+  process.stderr.write(`[yahoo] fetchShortInterest symbol=${symbol}\n`);
+  const summary = await yf.quoteSummary(symbol, {
+    modules: ["defaultKeyStatistics"] as never[],
+  });
+  const stats = summary.defaultKeyStatistics as Record<string, unknown> | undefined;
+
+  const sharesShort = stats?.sharesShort != null ? Number(stats.sharesShort) : null;
+  const priorMonth = stats?.sharesShortPriorMonth != null ? Number(stats.sharesShortPriorMonth) : null;
+  const change = sharesShort !== null && priorMonth !== null && priorMonth !== 0
+    ? Math.round(((sharesShort - priorMonth) / priorMonth) * 10000) / 100
+    : null;
+
+  return {
+    symbol,
+    sharesShort,
+    sharesShortPriorMonth: priorMonth,
+    shortRatio: stats?.shortRatio != null ? Number(stats.shortRatio) : null,
+    shortPercentOfFloat: stats?.shortPercentOfFloat != null
+      ? Math.round(Number(stats.shortPercentOfFloat) * 10000) / 100 : null,
+    floatShares: stats?.floatShares != null ? Number(stats.floatShares) : null,
+    sharesOutstanding: stats?.sharesOutstanding != null ? Number(stats.sharesOutstanding) : null,
+    settlementDate: stats?.dateShortInterest instanceof Date
+      ? stats.dateShortInterest.toISOString().slice(0, 10) : null,
+    changeFromPriorMonth: change,
+  };
+}
+
 // ─── Market Movers ────────────────────────────────────────────────────────────
 
 export interface MoverItem {

package/src/tools/index.ts

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

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

@@ -4,6 +4,7 @@ import {
   fetchDividendHistory,
   fetchInstitutionalHolders,
   fetchSimilarStocks,
+  fetchShortInterest,
 } from "../data/yahoo";
 import type { ToolDef } from "./types";
 import { ok, err } from "./types";
@@ -126,3 +127,30 @@ export const getSimilarStocksTool: ToolDef = {
     }
   },
 };
+
+// ─── get_short_interest ───────────────────────────────────────────────────────
+
+export const getShortInterestTool: ToolDef = {
+  tool: {
+    name: "get_short_interest",
+    description:
+      "获取美股做空数据：空头股数、做空占流通盘比例、空头回补天数（Short Ratio）、与上月对比变化。" +
+      "空头回补天数越高代表逼空风险越大。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: { type: "string", description: "美股代码，如 GME、TSLA、NVDA" },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = SymbolInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    try {
+      return ok(await fetchShortInterest(parsed.data.symbol));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};