kospi-kosdaq

Instructions

Implementation Reference

• kospi_kosdaq_stock_server.py:237-302 (handler)

  The core handler function for the 'get_stock_market_cap' tool, decorated with @mcp.tool() for registration. It validates dates and ticker, fetches market cap data using pykrx.get_market_cap, converts DataFrame to sorted dict, and handles errors.
  @mcp.tool() def get_stock_market_cap(fromdate: Union[str, int], todate: Union[str, int], ticker: Union[str, int]) -> Dict[str, Any]: """Retrieves market capitalization data for a specific stock. Args: fromdate (str): Start date for retrieval (YYYYMMDD) todate (str): End date for retrieval (YYYYMMDD) ticker (str): Stock ticker symbol Returns: DataFrame: >> get_stock_market_cap("20150720", "20150724", "005930") Market Cap Volume Trading Value Listed Shares Date 2015-07-24 181030885173000 196584 241383636000 147299337 2015-07-23 181767381858000 208965 259446564000 147299337 2015-07-22 184566069261000 268323 333813094000 147299337 2015-07-21 186039062631000 194055 244129106000 147299337 2015-07-20 187806654675000 128928 165366199000 147299337 """ # Validate and convert date format def validate_date(date_str: Union[str, int]) -> str: try: if isinstance(date_str, int): date_str = str(date_str) # Convert if in YYYY-MM-DD format if '-' in date_str: parsed_date = datetime.strptime(date_str, '%Y-%m-%d') return parsed_date.strftime('%Y%m%d') # Validate if in YYYYMMDD format datetime.strptime(date_str, '%Y%m%d') return date_str except ValueError: raise ValueError(f"Date must be in YYYYMMDD format. Input value: {date_str}") def validate_ticker(ticker_str: Union[str, int]) -> str: if isinstance(ticker_str, int): return str(ticker_str) return ticker_str try: fromdate = validate_date(fromdate) todate = validate_date(todate) ticker = validate_ticker(ticker) logging.debug(f"Retrieving stock market capitalization data: {ticker}, {fromdate}-{todate}") # Call get_market_cap df = get_market_cap(fromdate, todate, ticker) # Convert DataFrame to dictionary result = df.to_dict(orient='index') # Convert datetime index to string and sort in reverse sorted_items = sorted( ((k.strftime('%Y-%m-%d'), v) for k, v in result.items()), reverse=True ) result = dict(sorted_items) return result except Exception as e: error_message = f"Data retrieval failed: {str(e)}" logging.error(error_message) return {"error": error_message}
• kospi_kosdaq_stock_server.py:237-237 (registration)

  The @mcp.tool() decorator registers the get_stock_market_cap function as an MCP tool.
  @mcp.tool()
• kospi_kosdaq_stock_server.py:238-256 (schema)

  Input schema defined by type hints (Union[str, int] for dates/ticker, returns Dict[str, Any]) and detailed docstring describing parameters and return format.
  def get_stock_market_cap(fromdate: Union[str, int], todate: Union[str, int], ticker: Union[str, int]) -> Dict[str, Any]: """Retrieves market capitalization data for a specific stock. Args: fromdate (str): Start date for retrieval (YYYYMMDD) todate (str): End date for retrieval (YYYYMMDD) ticker (str): Stock ticker symbol Returns: DataFrame: >> get_stock_market_cap("20150720", "20150724", "005930") Market Cap Volume Trading Value Listed Shares Date 2015-07-24 181030885173000 196584 241383636000 147299337 2015-07-23 181767381858000 208965 259446564000 147299337 2015-07-22 184566069261000 268323 333813094000 147299337 2015-07-21 186039062631000 194055 244129106000 147299337 2015-07-20 187806654675000 128928 165366199000 147299337 """
• kospi_kosdaq_stock_server.py:82-126 (helper)

  The search_stock_data_prompt includes instructions and examples for using get_stock_market_cap.
  @mcp.prompt() def search_stock_data_prompt() -> str: """Prompt template for searching stock data.""" return """ Step-by-step guide for searching stock data by stock name: 1. First, load the ticker information for all stocks: load_all_tickers() 2. Check the code of the desired stock from the loaded ticker information: Refer to the stock://tickers resource to find the ticker corresponding to the stock name. 3. Retrieve the desired data using the found ticker: Retrieve OHLCV (Open/High/Low/Close/Volume) data: get_stock_ohlcv("start_date", "end_date", "ticker", adjusted=True) Retrieve market capitalization data: get_stock_market_cap("start_date", "end_date", "ticker") Retrieve fundamental indicators (PER/PBR/Dividend Yield): get_stock_fundamental("start_date", "end_date", "ticker") Retrieve trading volume by investor type: get_stock_trading_volume("start_date", "end_date", "ticker") Retrieve index OHLCV data (KOSPI, KOSDAQ, etc.): get_index_ohlcv("start_date", "end_date", "ticker", freq="d") - ticker: 1001 for KOSPI, 2001 for KOSDAQ - freq: "d" for daily, "m" for monthly, "y" for yearly Example) To retrieve data for Samsung Electronics in January 2024: 1. load_all_tickers() # Load all tickers 2. Refer to stock://tickers # Check Samsung Electronics = 005930 3. get_stock_ohlcv("20240101", "20240131", "005930") # Retrieve OHLCV data or get_stock_market_cap("20240101", "20240131", "005930") # Retrieve market cap data or get_stock_fundamental("20240101", "20240131", "005930") # Retrieve fundamental data or get_stock_trading_volume("20240101", "20240131", "005930") # Retrieve trading volume Example) To retrieve KOSPI index data for January 2021: get_index_ohlcv("20210101", "20210131", "1001", freq="d") # Daily KOSPI data """