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}",
          )