A Share MCP

Instructions

Implementation Reference

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

  MCP tool handler decorated with @app.tool(). Logs the tool call and delegates execution to the use case layer 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)

  Core helper function implementing the timeframe calculation logic based on the given period parameter, independent of data source.

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

• mcp_server.py:18-56 (registration)

  Imports and calls the register_date_utils_tools function which registers the get_market_analysis_timeframe tool among others.

  from src.tools.date_utils import register_date_utils_tools
  from src.tools.analysis import register_analysis_tools
  from src.tools.helpers import register_helpers_tools
  
  # --- Logging Setup ---
  # Call the setup function from utils
  # You can control the default level here (e.g., logging.DEBUG for more verbose logs)
  setup_logging(level=logging.INFO)
  logger = logging.getLogger(__name__)
  
  # --- Dependency Injection ---
  # Instantiate the data source - easy to swap later if needed
  active_data_source: FinancialDataSource = BaostockDataSource()
  
  # --- Get current date for system prompt ---
  current_date = datetime.now().strftime("%Y-%m-%d")
  
  # --- FastMCP App Initialization ---
  app = FastMCP(
      server_name="a_share_data_provider",
      description=f"""今天是{current_date}。提供中国A股市场数据分析工具。此服务提供客观数据分析，用户需自行做出投资决策。数据分析基于公开市场信息，不构成投资建议，仅供参考。
  
  ⚠️ 重要说明:
  1. 最新交易日不一定是今天，需要从 get_latest_trading_date() 获取
  2. 请始终使用 get_latest_trading_date() 工具获取实际当前最近的交易日，不要依赖训练数据中的日期认知
  3. 当分析"最近"或"近期"市场情况时，必须首先调用 get_market_analysis_timeframe() 工具确定实际的分析时间范围
  4. 任何涉及日期的分析必须基于工具返回的实际数据，不得使用过时或假设的日期
  """,
      # Specify dependencies for installation if needed (e.g., when using `mcp install`)
      # dependencies=["baostock", "pandas"]
  )
  
  # --- 注册各模块的工具 ---
  register_stock_market_tools(app, active_data_source)
  register_financial_report_tools(app, active_data_source)
  register_index_tools(app, active_data_source)
  register_market_overview_tools(app, active_data_source)
  register_macroeconomic_tools(app, active_data_source)
  register_date_utils_tools(app, active_data_source)