Stock MCP Server

Instructions

Implementation Reference

• src/index.ts:286-301 (handler)

  Handler for stock_get_batch tool: validates input using GetStocksSchema, maps the stocks array, calls fetchStocks, and returns JSON-formatted stock data

  if (name === 'stock_get_batch') {
    const params = GetStocksSchema.parse(args);
    const stocks = params.stocks.map(s => ({
      code: s.code,
      market: s.market as Market
    }));
    const data = await fetchStocks(stocks);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/index.ts:19-24 (schema)

  GetStocksSchema: Zod validation schema defining the input structure for batch stock fetching (array of stock objects with code and market)

  const GetStocksSchema = z.object({
    stocks: z.array(z.object({
      code: z.string(),
      market: z.enum(['sh', 'sz', 'hk', 'us']),
    })).min(1).describe('股票列表'),
  });

• src/index.ts:121-141 (registration)

  Tool registration: Registers stock_get_batch in the MCP server's tool list with description and input schema definition

    name: 'stock_get_batch',
    description: '批量获取多只股票实时行情数据',
    inputSchema: {
      type: 'object',
      properties: {
        stocks: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              code: { type: 'string' },
              market: { type: 'string', enum: ['sh', 'sz', 'hk', 'us'] },
            },
            required: ['code', 'market'],
          },
          description: '股票列表',
        },
      },
      required: ['stocks'],
    },
  },

• src/stock.ts:189-202 (handler)

  fetchStocks implementation: Iterates through stock codes, fetches each stock individually using fetchStock, and returns array of StockData (continues on error for individual stocks)

  export async function fetchStocks(codes: Array<{ code: string; market: Market }>): Promise<StockData[]> {
    const results: StockData[] = [];
  
    for (const { code, market } of codes) {
      try {
        const data = await fetchStock(code, market);
        results.push(data);
      } catch (error) {
        console.error(`Failed to fetch ${market}${code}:`, error);
      }
    }
  
    return results;
  }

• src/types.ts:1-78 (schema)

  Type definitions: Market type, StockPrefix, AStockData, HKStockData, USStockData, and unified StockData type used by fetchStocks

  // 股票市场类型
  export type Market = 'sh' | 'sz' | 'hk' | 'us';
  
  // 股票代码前缀
  export type StockPrefix = 'sh' | 'sz' | 'r_hk' | 's_us';
  
  // A股解析后的数据
  export interface AStockData {
    market: 'sh' | 'sz';
    name: string;
    code: string;
    currentPrice: number;
    yesterdayClose: number;
    open: number;
    volume: number;
    outside: number;
    inside: number;
    datetime: string;
    change: number;
    changePercent: number;
    high: number;
    low: number;
    amount: number;
    turnoverRate: number;    // 38 换手率
    peTtm: number;           // 39 市盈率TTM
    amplitude: number;      // 43 振幅
    totalMarketCap: number; // 44 总市值(亿)
    floatMarketCap: number;  // 45 流通市值(亿)
    volumeRatio: number;     // 49 量比
    avgPrice: number;        // 51 均价
    peDynamic: number;       // 52 市盈率(动)
    peStatic: number;        // 53 市盈率(静)
    floatingShares: number;  // 72 流通股
    totalShares: number;     // 73 总股本
    currency: string;       // 82 货币
    bidAsk?: {
      asks: Array<{ price: number; volume: number }>;
      bids: Array<{ price: number; volume: number }>;
    };
  }
  
  // 港股解析后的数据
  export interface HKStockData {
    market: 'hk';
    name: string;
    code: string;
    currentPrice: number;
    yesterdayClose: number;
    open: number;
    volume: number;
    datetime: string;
    change: number;
    changePercent: number;
    high: number;
    low: number;
    amount: number;
    pe: number;
    floatingShares: number;
    totalShares: number;
    currency: string;
  }
  
  // 美股解析后的数据
  export interface USStockData {
    market: 'us';
    name: string;
    code: string;
    currentPrice: number;
    change: number;
    changePercent: number;
    volume: number;
    amount: number;
    marketCap?: number;
    currency: string;
  }
  
  // 统一返回类型
  export type StockData = AStockData | HKStockData | USStockData;