A-Share MCP Server

Instructions

Implementation Reference

• src/tools/date_utils.py:28-35 (handler)

  The MCP tool handler for 'get_market_analysis_timeframe', decorated with @app.tool(). It logs the call and delegates execution to the use_cases.date_utils implementation via run_tool_with_handling.
  @app.tool() def get_market_analysis_timeframe(period: str = "recent") -> str: """Return a human-friendly timeframe label.""" logger.info(f"Tool 'get_market_analysis_timeframe' called with period={period}") return run_tool_with_handling( lambda: uc_date.get_market_analysis_timeframe(period=period), context="get_market_analysis_timeframe", )
• src/use_cases/date_utils.py:28-53 (helper)

  The core business logic implementation that computes a human-readable timeframe string (e.g., '2024-11-01 至 2024-12-10') based on the 'period' parameter and current date.
  def get_market_analysis_timeframe(period: str = "recent") -> str: now = datetime.now() end_date = now if period == "recent": if now.day < 15: if now.month == 1: start_date = datetime(now.year - 1, 11, 1) else: prev_month = now.month - 1 start_month = prev_month if prev_month > 0 else 12 start_year = now.year if prev_month > 0 else now.year - 1 start_date = datetime(start_year, start_month, 1) else: start_date = datetime(now.year, now.month, 1) elif period == "quarter": quarter = (now.month - 1) // 3 + 1 start_month = (quarter - 1) * 3 + 1 start_date = datetime(now.year, start_month, 1) elif period == "half_year": start_month = 1 if now.month <= 6 else 7 start_date = datetime(now.year, start_month, 1) elif period == "year": start_date = datetime(now.year, 1, 1) else: raise ValueError("Invalid period. Use 'recent', 'quarter', 'half_year', or 'year'.") return f"{start_date.strftime('%Y-%m-%d')} 至 {end_date.strftime('%Y-%m-%d')}"
• src/tools/date_utils.py:16-84 (registration)

  The registration function that defines and registers the 'get_market_analysis_timeframe' tool (along with other date tools) using FastMCP's @app.tool() decorator. Called from mcp_server.py.
  def register_date_utils_tools(app: FastMCP, active_data_source: FinancialDataSource): """Register date utility tools.""" @app.tool() def get_latest_trading_date() -> str: """Get the latest trading date up to today.""" logger.info("Tool 'get_latest_trading_date' called") return run_tool_with_handling( lambda: uc_date.get_latest_trading_date(active_data_source), context="get_latest_trading_date", ) @app.tool() def get_market_analysis_timeframe(period: str = "recent") -> str: """Return a human-friendly timeframe label.""" logger.info(f"Tool 'get_market_analysis_timeframe' called with period={period}") return run_tool_with_handling( lambda: uc_date.get_market_analysis_timeframe(period=period), context="get_market_analysis_timeframe", ) @app.tool() def is_trading_day(date: str) -> str: """Check if a specific date is a trading day.""" return run_tool_with_handling( lambda: uc_date.is_trading_day(active_data_source, date=date), context=f"is_trading_day:{date}", ) @app.tool() def previous_trading_day(date: str) -> str: """Get the previous trading day before the given date.""" return run_tool_with_handling( lambda: uc_date.previous_trading_day(active_data_source, date=date), context=f"previous_trading_day:{date}", ) @app.tool() def next_trading_day(date: str) -> str: """Get the next trading day after the given date.""" return run_tool_with_handling( lambda: uc_date.next_trading_day(active_data_source, date=date), context=f"next_trading_day:{date}", ) @app.tool() def get_last_n_trading_days(days: int = 5) -> str: """Return the last N trading dates.""" return run_tool_with_handling( lambda: uc_date.get_last_n_trading_days(active_data_source, days=days), context=f"get_last_n_trading_days:{days}", ) @app.tool() def get_recent_trading_range(days: int = 5) -> str: """Return a date range string covering the recent N trading days.""" return run_tool_with_handling( lambda: uc_date.get_recent_trading_range(active_data_source, days=days), context=f"get_recent_trading_range:{days}", ) @app.tool() def get_month_end_trading_dates(year: int) -> str: """Return month-end trading dates for a given year.""" return run_tool_with_handling( lambda: uc_date.get_month_end_trading_dates(active_data_source, year=year), context=f"get_month_end_trading_dates:{year}", )