xstock-mcp 1.0.0

package/src/tools/crypto.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import axios from "axios";
+import { fetchGlobalMarket, fetchTopCoins, fetchFearGreed, fetchCategories } from "../data/coingecko";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+export const getCryptoOverviewTool: ToolDef = {
+  tool: {
+    name: "get_crypto_overview",
+    description:
+      "获取加密货币市场全局概况：总市值、24h成交量、BTC/ETH占比、市值变化，以及恐惧贪婪指数。",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  handler: async () => {
+    try {
+      const [market, fg] = await Promise.all([fetchGlobalMarket(), fetchFearGreed()]);
+      return ok({ market, fearGreed: fg });
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+const TopCoinsInput = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+});
+
+export const getCryptoTopTool: ToolDef = {
+  tool: {
+    name: "get_crypto_top",
+    description: "按市值排名获取 Top N 加密货币，含价格、涨跌幅、市值、24h成交量。默认 Top 20。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "返回数量，默认20，最大100",
+        },
+      },
+      required: [],
+    },
+  },
+  handler: async (input) => {
+    const parsed = TopCoinsInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { limit = 20 } = parsed.data;
+
+    try {
+      return ok(await fetchTopCoins(limit));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+export const getCryptoCatsTool: ToolDef = {
+  tool: {
+    name: "get_crypto_categories",
+    description: "获取加密货币赛道分类数据（DeFi、Layer1、AI、GameFi等），含各赛道市值和24h涨跌幅。",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  handler: async () => {
+    try {
+      const cats = await fetchCategories();
+      const sorted = cats.sort((a, b) => (b.marketCap ?? 0) - (a.marketCap ?? 0));
+      return ok(sorted);
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+const FundingInput = z.object({
+  symbols: z.array(z.string()).min(1).max(20),
+});
+
+interface FundingRate {
+  symbol: string;
+  markPrice: string;
+  indexPrice: string;
+  lastFundingRate: string;
+  nextFundingTime: number;
+}
+
+export const getCryptoFundingTool: ToolDef = {
+  tool: {
+    name: "get_funding_rate",
+    description:
+      "获取 Binance 永续合约资金费率。symbols 传币种代码，如 ['BTC','ETH']，自动补全 USDT 后缀。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbols: {
+          type: "array",
+          items: { type: "string" },
+          description: "币种代码列表，如 ['BTC','ETH','SOL']",
+          minItems: 1,
+          maxItems: 20,
+        },
+      },
+      required: ["symbols"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = FundingInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { symbols } = parsed.data;
+
+    try {
+      const results = await Promise.all(
+        symbols.map(async (raw) => {
+          const sym = raw.toUpperCase().endsWith("USDT") ? raw.toUpperCase() : raw.toUpperCase() + "USDT";
+          try {
+            const res = await axios.get<FundingRate>(
+              `https://fapi.binance.com/fapi/v1/premiumIndex?symbol=${sym}`,
+              { timeout: 5000 }
+            );
+            const d = res.data;
+            return {
+              symbol: sym,
+              markPrice: parseFloat(d.markPrice),
+              indexPrice: parseFloat(d.indexPrice),
+              fundingRate: parseFloat(d.lastFundingRate),
+              fundingRatePct: (parseFloat(d.lastFundingRate) * 100).toFixed(4) + "%",
+              nextFundingTime: new Date(d.nextFundingTime).toISOString(),
+            };
+          } catch {
+            return { symbol: sym, error: "not found or not a perpetual contract" };
+          }
+        })
+      );
+      return ok(results);
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};

package/src/tools/index.ts

@@ -0,0 +1,24 @@
+import type { ToolDef } from "./types";
+import { getQuoteTool } from "./quotes";
+import { getKlineTool } from "./kline";
+import { searchStockTool } from "./search";
+import { getUsIndicesTool, getStockProfileTool } from "./us-market";
+import { getCryptoOverviewTool, getCryptoTopTool, getCryptoCatsTool, getCryptoFundingTool } from "./crypto";
+
+export * from "./types";
+
+export const tools: ToolDef[] = [
+  getQuoteTool,
+  getKlineTool,
+  searchStockTool,
+  getUsIndicesTool,
+  getStockProfileTool,
+  getCryptoOverviewTool,
+  getCryptoTopTool,
+  getCryptoCatsTool,
+  getCryptoFundingTool,
+];
+
+export const toolMap = new Map<string, ToolDef>(
+  tools.map((t) => [t.tool.name, t])
+);

package/src/tools/kline.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { fetchAShareKline, fetchHKKline } from "../data/tencent";
+import { fetchUSKlines } from "../data/yahoo";
+import { fetchCryptoKlines } from "../data/binance";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+const periodToYahoo: Record<string, "1d" | "1wk" | "1mo"> = {
+  daily: "1d",
+  weekly: "1wk",
+  monthly: "1mo",
+};
+
+const Input = z.object({
+  market: z.enum(["a-share", "hk", "us", "crypto"]),
+  code: z.string(),
+  period: z.enum(["daily", "weekly", "monthly"]).optional(),
+  start: z.string().optional(),
+  end: z.string().optional(),
+  interval: z.string().optional(),
+  limit: z.number().int().min(1).max(500).optional(),
+});
+
+export const getKlineTool: ToolDef = {
+  tool: {
+    name: "get_kline",
+    description:
+      "获取K线数据（OHLCV）。股票支持 daily/weekly/monthly；加密货币支持 1m/5m/15m/1h/4h/1d/1w 等 Binance 标准周期。" +
+      "美股可指定 start/end 日期（YYYY-MM-DD）；加密可指定 limit（最多500条）。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        market: {
+          type: "string",
+          enum: ["a-share", "hk", "us", "crypto"],
+          description: "市场类型",
+        },
+        code: {
+          type: "string",
+          description: "代码，如 AAPL、600519、00700、BTC",
+        },
+        period: {
+          type: "string",
+          enum: ["daily", "weekly", "monthly"],
+          description: "周期（股票市场），默认 daily",
+        },
+        start: {
+          type: "string",
+          description: "开始日期 YYYY-MM-DD（仅美股，默认近90天）",
+        },
+        end: {
+          type: "string",
+          description: "结束日期 YYYY-MM-DD（仅美股，默认今天）",
+        },
+        interval: {
+          type: "string",
+          description: "加密货币周期，如 1d、4h、1h、15m，默认 1d",
+        },
+        limit: {
+          type: "number",
+          description: "加密货币返回条数，最大500，默认100",
+        },
+      },
+      required: ["market", "code"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = Input.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { market, code, period, start, end, interval, limit } = parsed.data;
+
+    try {
+      if (market === "a-share") {
+        return ok(await fetchAShareKline(code, period ?? "daily"));
+      }
+      if (market === "hk") {
+        return ok(await fetchHKKline(code, period ?? "daily"));
+      }
+      if (market === "us") {
+        const endDate = end ?? new Date().toISOString().slice(0, 10);
+        const startDate = start ?? new Date(Date.now() - 90 * 86400_000).toISOString().slice(0, 10);
+        const yInterval = periodToYahoo[period ?? "daily"] ?? "1d";
+        return ok(await fetchUSKlines(code, startDate, endDate, yInterval));
+      }
+      // crypto
+      return ok(await fetchCryptoKlines(code, interval ?? "1d", limit ?? 100));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};

package/src/tools/quotes.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { fetchAShareQuotes, fetchHKQuotes } from "../data/tencent";
+import { fetchUSQuotes } from "../data/yahoo";
+import { fetchCryptoTickers } from "../data/binance";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+const Input = z.object({
+  market: z.enum(["a-share", "hk", "us", "crypto"]),
+  codes: z.array(z.string()).min(1).max(20),
+});
+
+export const getQuoteTool: ToolDef = {
+  tool: {
+    name: "get_quote",
+    description:
+      "获取股票或加密货币实时行情。支持美股（us）、A股（a-share）、港股（hk）、加密货币（crypto）。" +
+      "美股示例：codes=['AAPL','NVDA']；A股：codes=['600519','000858']；港股：codes=['00700','09988']；加密：codes=['BTC','ETH']。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        market: {
+          type: "string",
+          enum: ["a-share", "hk", "us", "crypto"],
+          description: "市场类型：a-share=A股, hk=港股, us=美股, crypto=加密货币",
+        },
+        codes: {
+          type: "array",
+          items: { type: "string" },
+          description: "股票/币种代码列表，最多20个",
+          minItems: 1,
+          maxItems: 20,
+        },
+      },
+      required: ["market", "codes"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = Input.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { market, codes } = parsed.data;
+
+    try {
+      if (market === "a-share") return ok(await fetchAShareQuotes(codes));
+      if (market === "hk") return ok(await fetchHKQuotes(codes));
+      if (market === "us") return ok(await fetchUSQuotes(codes));
+      return ok(await fetchCryptoTickers(codes));
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};

package/src/tools/search.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { default as YahooFinance } from "yahoo-finance2";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+const yf = new YahooFinance({ suppressNotices: ["yahooSurvey"] });
+
+const Input = z.object({
+  query: z.string().min(1),
+  limit: z.number().int().min(1).max(20).optional(),
+});
+
+export const searchStockTool: ToolDef = {
+  tool: {
+    name: "search_stock",
+    description:
+      "按关键词搜索股票或ETF，返回匹配的股票列表（含代码、名称、交易所、类型）。适用于不知道确切代码时查找标的。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "搜索关键词，如公司名或代码，如 'Apple'、'TSLA'、'nvidia'",
+        },
+        limit: {
+          type: "number",
+          description: "最多返回条数，默认10，最大20",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = Input.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { query, limit = 10 } = parsed.data;
+
+    try {
+      const res = await yf.search(query);
+      const items = (res.quotes ?? []).slice(0, limit).map((q) => {
+        const r = q as Record<string, unknown>;
+        return {
+          symbol: r.symbol,
+          name: r.longname ?? r.shortname ?? "",
+          exchange: r.exchange ?? "",
+          type: r.typeDisp ?? r.quoteType ?? "",
+        };
+      });
+      return ok(items);
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};

package/src/tools/types.ts

@@ -0,0 +1,44 @@
+// MCP-compatible types for tools layer
+
+export interface ToolInputSchema {
+  type: "object";
+  properties?: Record<string, object>;
+  required?: string[];
+  [key: string]: unknown;
+}
+
+export interface MCPTool {
+  name: string;
+  description?: string;
+  inputSchema: ToolInputSchema;
+}
+
+export interface TextContent {
+  type: "text";
+  text: string;
+}
+
+export interface CallToolResult {
+  content: TextContent[];
+  isError?: boolean;
+}
+
+export type ToolHandler = (input: Record<string, unknown>) => Promise<CallToolResult>;
+
+export interface ToolDef {
+  tool: MCPTool;
+  handler: ToolHandler;
+}
+
+export function ok(data: unknown): CallToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+export function err(message: string): CallToolResult {
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true,
+  };
+}

package/src/tools/us-market.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { fetchUSQuotes, fetchStockProfile } from "../data/yahoo";
+import type { ToolDef } from "./types";
+import { ok, err } from "./types";
+
+// 主要美股指数 ETF + 直接指数代码
+const US_INDICES = ["^GSPC", "^IXIC", "^DJI", "^RUT", "^VIX"];
+const INDEX_NAMES: Record<string, string> = {
+  "^GSPC": "S&P 500",
+  "^IXIC": "Nasdaq Composite",
+  "^DJI": "Dow Jones",
+  "^RUT": "Russell 2000",
+  "^VIX": "VIX 恐慌指数",
+};
+
+export const getUsIndicesTool: ToolDef = {
+  tool: {
+    name: "get_us_indices",
+    description:
+      "获取美股主要指数实时行情，包括标普500、纳斯达克、道琼斯、罗素2000、VIX恐慌指数。",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  handler: async () => {
+    try {
+      const quotes = await fetchUSQuotes(US_INDICES);
+      const result = quotes.map((q) => ({
+        ...q,
+        indexName: INDEX_NAMES[q.symbol] ?? q.symbol,
+      }));
+      return ok(result);
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};
+
+const ProfileInput = z.object({
+  symbol: z.string().min(1),
+});
+
+export const getStockProfileTool: ToolDef = {
+  tool: {
+    name: "get_stock_profile",
+    description:
+      "获取美股上市公司基本面信息：行业、市值、PE、EPS、Beta、52周高低点、员工数、公司简介等。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        symbol: {
+          type: "string",
+          description: "美股代码，如 AAPL、TSLA、NVDA",
+        },
+      },
+      required: ["symbol"],
+    },
+  },
+  handler: async (input) => {
+    const parsed = ProfileInput.safeParse(input);
+    if (!parsed.success) return err(parsed.error.message);
+    const { symbol } = parsed.data;
+
+    try {
+      const profile = await fetchStockProfile(symbol);
+      return ok(profile);
+    } catch (e) {
+      return err((e as Error).message);
+    }
+  },
+};

package/test/data-binance.ts

@@ -0,0 +1,68 @@
+/**
+ * 测试 data/binance.ts
+ * 运行：npx ts-node test/data-binance.ts
+ */
+import { fetchCryptoTickers, fetchCryptoKlines, normalizeSymbol } from "../src/data/binance";
+
+function section(title: string) {
+  console.log(`\n${"─".repeat(50)}`);
+  console.log(`  ${title}`);
+  console.log("─".repeat(50));
+}
+
+async function main() {
+  // ── 1. Symbol 标准化 ──────────────────────────────
+  section("normalizeSymbol");
+  const cases = ["BTC", "btc", "ETHUSDT", "solUsdt", "PEPE"];
+  for (const s of cases) {
+    console.log(`  ${s.padEnd(10)} → ${normalizeSymbol(s)}`);
+  }
+
+  // ── 2. 多币种行情 ─────────────────────────────────
+  section("fetchCryptoTickers — BTC / ETH / SOL");
+  try {
+    const tickers = await fetchCryptoTickers(["BTC", "ETH", "SOL"]);
+    for (const t of tickers) {
+      console.log(
+        `  ${t.symbol.padEnd(10)}  价格=$${t.price.toLocaleString()}` +
+        `  涨跌幅=${t.changePercent}  成交量=${t.volume.toFixed(2)}`
+      );
+    }
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 3. 错误 symbol ────────────────────────────────
+  section("fetchCryptoTickers — 不存在的 symbol");
+  try {
+    const tickers = await fetchCryptoTickers(["NOTEXIST123"]);
+    console.log("  返回:", tickers.length === 0 ? "空数组（符合预期）" : JSON.stringify(tickers));
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 4. BTC 日K ────────────────────────────────────
+  section("fetchCryptoKlines — BTC 日K 最近 10 条");
+  try {
+    const bars = await fetchCryptoKlines("BTC", "1d", 10);
+    console.log(`  共 ${bars.length} 条`);
+    for (const b of bars) {
+      console.log(`  ${b.date}  open=${b.open}  close=${b.close}  vol=${b.volume.toFixed(2)}`);
+    }
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 5. ETH 4h K 线 ───────────────────────────────
+  section("fetchCryptoKlines — ETH 4h 最近 5 条");
+  try {
+    const bars = await fetchCryptoKlines("ETH", "4h", 5);
+    const last = bars[bars.length - 1];
+    console.log(`  共 ${bars.length} 条`);
+    console.log(`  最新: date=${last?.date}  close=${last?.close}`);
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+}
+
+main().catch(console.error);

package/test/data-coingecko.ts

@@ -0,0 +1,71 @@
+/**
+ * 测试 data/coingecko.ts
+ * 运行：npx ts-node test/data-coingecko.ts
+ *
+ * 注意：CoinGecko 免费接口有频率限制，测试时请勿频繁运行
+ */
+import { fetchGlobalMarket, fetchTopCoins, fetchCategories, fetchFearGreed } from "../src/data/coingecko";
+
+function section(title: string) {
+  console.log(`\n${"─".repeat(50)}`);
+  console.log(`  ${title}`);
+  console.log("─".repeat(50));
+}
+
+async function main() {
+  // ── 1. 全市场概况 ─────────────────────────────────
+  section("fetchGlobalMarket");
+  try {
+    const g = await fetchGlobalMarket();
+    console.log(`  总市值:    $${(g.totalMarketCapUsd / 1e12).toFixed(2)}T`);
+    console.log(`  24h 成交量: $${(g.totalVolumeUsd / 1e9).toFixed(2)}B`);
+    console.log(`  BTC 占比:  ${g.btcDominance}%`);
+    console.log(`  ETH 占比:  ${g.ethDominance}%`);
+    console.log(`  24h 涨跌:  ${g.marketCapChangePercent24h}%`);
+    console.log(`  活跃币种:  ${g.activeCryptos}`);
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 2. 市值 Top 10 ───────────────────────────────
+  section("fetchTopCoins — Top 10");
+  try {
+    const coins = await fetchTopCoins(10);
+    for (const c of coins) {
+      const cap = (c.marketCap / 1e9).toFixed(1);
+      console.log(
+        `  #${String(c.rank).padEnd(3)} ${c.symbol.padEnd(8)} $${c.price.toFixed(4).padStart(12)}` +
+        `  ${c.changePercent24h >= 0 ? "+" : ""}${c.changePercent24h}%  市值=$${cap}B`
+      );
+    }
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 3. 恐惧贪婪指数 ───────────────────────────────
+  section("fetchFearGreed");
+  try {
+    const fg = await fetchFearGreed();
+    console.log(`  指数值: ${fg.value}  状态: ${fg.label}  日期: ${fg.timestamp}`);
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+
+  // ── 4. 赛道分类（前 10 条）────────────────────────
+  section("fetchCategories — 前 10 个赛道");
+  try {
+    const cats = await fetchCategories();
+    const top10 = cats
+      .sort((a, b) => (b.marketCap ?? 0) - (a.marketCap ?? 0))
+      .slice(0, 10);
+    for (const c of top10) {
+      const cap = c.marketCap ? `$${(c.marketCap / 1e9).toFixed(1)}B` : "N/A";
+      const chg = c.marketCapChange24h >= 0 ? `+${c.marketCapChange24h}%` : `${c.marketCapChange24h}%`;
+      console.log(`  ${c.name.padEnd(30)} 市值=${cap.padStart(10)}  24h=${chg}`);
+    }
+  } catch (e) {
+    console.error("  ERROR:", e);
+  }
+}
+
+main().catch(console.error);