yfinance_get_option_dates

Instructions

Returns JSON array of expiration dates in YYYY-MM-DD format.

Use these dates with the 'yfinance_get_option_chain' tool to fetch
the options chain for a specific date.

Implementation Reference

• src/yfmcp/server.py:970-1007 (handler)

  The async function `get_option_dates` (registered as 'yfinance_get_option_dates') fetches available option expiration dates for a stock ticker symbol. It creates a yfinance Ticker, retrieves the options dates via `ticker.options`, handles errors via `_create_option_dates_fetch_error`, and returns JSON using `dump_json`.

  @mcp.tool(
      name="yfinance_get_option_dates",
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
  )
  async def get_option_dates(
      symbol: Annotated[str, Field(description="Stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'MSFT')")],
  ) -> str:
      """Fetch available option expiration dates for a stock.
  
      Returns JSON array of expiration dates in YYYY-MM-DD format.
  
      Use these dates with the 'yfinance_get_option_chain' tool to fetch
      the options chain for a specific date.
      """
      try:
          ticker = await asyncio.to_thread(yf.Ticker, symbol)
          dates = await asyncio.to_thread(lambda: ticker.options)
      except Exception as exc:
          return _create_option_dates_fetch_error(
              symbol,
              exc,
              f"Failed to fetch option dates for '{symbol}'. Verify the symbol is correct.",
          )
  
      if not dates:
          return create_error_response(
              f"No options available for symbol '{symbol}'. "
              "This symbol may not have listed options (e.g., ETFs, stocks without options).",
              error_code="NO_DATA",
              details={"symbol": symbol},
          )
  
      return dump_json(dates)

• src/yfmcp/server.py:970-978 (registration)

  The tool is registered via the `@mcp.tool()` decorator with the name 'yfinance_get_option_dates', annotated as readOnlyHint=True, idempotentHint=True, openWorldHint=True.

  @mcp.tool(
      name="yfinance_get_option_dates",
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
  )

• src/yfmcp/server.py:60-68 (helper)

  Helper function `_create_option_dates_fetch_error` builds error responses for option dates fetching failures, distinguishing retryable errors (rate limits/network) from other API errors.

  def _create_option_dates_fetch_error(symbol: str, exc: Exception, api_message: str) -> str:
      if _is_retryable_yfinance_error(exc):
          return _create_retryable_error_response(f"fetching option dates for '{symbol}'", exc, {"symbol": symbol})
  
      return create_error_response(
          api_message,
          error_code="API_ERROR",
          details={"symbol": symbol, "exception": str(exc)},
      )

• src/yfmcp/utils.py:6-7 (helper)

  Utility function `dump_json` serializes payloads to JSON with `default=str` for non-serializable types.

  def dump_json(payload: object) -> str:
      return json.dumps(payload, ensure_ascii=False, default=str)

• src/yfmcp/utils.py:10-24 (helper)

  Utility function `create_error_response` builds a structured JSON error response with error message, error code, and optional details.

  def create_error_response(message: str, error_code: ErrorCode = "UNKNOWN_ERROR", details: dict | None = None) -> str:
      """Create a structured error response.
  
      Args:
          message: Human-readable error message
          error_code: Machine-readable error code for client handling
          details: Optional additional error details
  
      Returns:
          JSON string with error information
      """
      error_obj: dict[str, object] = {"error": message, "error_code": error_code}
      if details:
          error_obj["details"] = details
      return dump_json(error_obj)