Stock MCP Server

Instructions

Implementation Reference

• src/index.ts:273-284 (handler)

  The MCP tool handler for 'stock_get' that processes tool requests, validates input using GetStockSchema, calls fetchStock, and returns formatted JSON response

  if (name === 'stock_get') {
    const params = GetStockSchema.parse(args);
    const data = await fetchStock(params.code, params.market as Market);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }

• src/index.ts:102-119 (registration)

  Tool registration in the ListToolsRequestSchema handler that defines the 'stock_get' tool metadata and input schema including code and market parameters

    name: 'stock_get',
    description: '获取单只股票实时行情数据',
    inputSchema: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          description: '股票代码，如 000858',
        },
        market: {
          type: 'string',
          enum: ['sh', 'sz', 'hk', 'us'],
          description: '市场: sh=上海, sz=深圳, hk=港股, us=美股',
        },
      },
      required: ['code', 'market'],
    },
  },

• src/index.ts:14-17 (schema)

  Zod validation schema for stock_get input parameters that validates code (string) and market (enum: 'sh'|'sz'|'hk'|'us')

  const GetStockSchema = z.object({
    code: z.string().describe('股票代码，如 000858'),
    market: z.enum(['sh', 'sz', 'hk', 'us']).describe('市场: sh=上海, sz=深圳, hk=港股, us=美股'),
  });

• src/stock.ts:16-33 (handler)

  Core implementation of fetchStock that constructs API URL based on market prefix, fetches data from Tencent's stock API, and parses the response into structured StockData

  export async function fetchStock(code: string, market: Market): Promise<StockData> {
    const prefix = getPrefix(market);
    const url = `${BASE_URL}/?q=${prefix}${code}`;
  
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Failed to fetch stock data: ${response.statusText}`);
    }
  
    const text = await response.text();
    const rawData = parseRawResponse(text);
  
    if (!rawData) {
      throw new Error(`No data returned for ${prefix}${code}`);
    }
  
    return parseStockData(rawData, market);
  }

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

  Type definitions for stock_get including Market type, StockData union type (AStockData, HKStockData, USStockData), and their respective interfaces defining the structure of returned stock data

  // 股票市场类型
  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;