A-Share MCP Server

Instructions

Implementation Reference

• src/tools/macroeconomic.py:64-90 (handler)

  MCP tool handler for 'get_required_reserve_ratio_data'. Validates year_type parameter and delegates to call_macro_data_tool helper which fetches from data source and formats output.
  @app.tool() def get_required_reserve_ratio_data(start_date: Optional[str] = None, end_date: Optional[str] = None, year_type: str = '0', limit: int = 250, format: str = "markdown") -> str: """ Fetches required reserve ratio data (存款准备金率) within a date range. Args: start_date: Optional. Start date in 'YYYY-MM-DD' format. end_date: Optional. End date in 'YYYY-MM-DD' format. year_type: Optional. Year type for date filtering. '0' for announcement date (公告日期, default), '1' for effective date (生效日期). Returns: Markdown table with required reserve ratio data or an error message. """ # Basic validation for year_type if year_type not in ['0', '1']: logger.warning(f"Invalid year_type requested: {year_type}") return "Error: Invalid year_type '{year_type}'. Valid options are '0' (announcement date) or '1' (effective date)." return call_macro_data_tool( "get_required_reserve_ratio_data", active_data_source.get_required_reserve_ratio_data, "Required Reserve Ratio", start_date, end_date, limit=limit, format=format, yearType=year_type # Pass the extra arg correctly named for Baostock )
• mcp_server.py:55-55 (registration)

  Registers the macroeconomic tools, including 'get_required_reserve_ratio_data', by calling the register_macroeconomic_tools function with the FastMCP app instance and active data source.
  register_macroeconomic_tools(app, active_data_source)
• src/tools/base.py:76-124 (helper)

  Shared helper function that wraps data source calls for macro tools: logs, invokes data source method with date range and kwargs (e.g., yearType), formats pandas DataFrame to markdown table, and handles all errors uniformly.
  def call_macro_data_tool( tool_name: str, data_source_method: Callable, data_type_name: str, start_date: Optional[str] = None, end_date: Optional[str] = None, *, limit: int = 250, format: str = "markdown", **kwargs # For extra params like year_type ) -> str: """ Helper function for macroeconomic data tools Args: tool_name: Name of the tool for logging data_source_method: Method to call on the data source data_type_name: Type of data (for logging) start_date: Optional start date end_date: Optional end date **kwargs: Additional keyword arguments to pass to data_source_method Returns: Markdown formatted string with results or error message """ date_range_log = f"from {start_date or 'default'} to {end_date or 'default'}" kwargs_log = f", extra_args={kwargs}" if kwargs else "" logger.info(f"Tool '{tool_name}' called {date_range_log}{kwargs_log}") try: # Call the appropriate method on the active_data_source df = data_source_method(start_date=start_date, end_date=end_date, **kwargs) logger.info(f"Successfully retrieved {data_type_name} data.") meta = {"dataset": data_type_name, "start_date": start_date, "end_date": end_date} | ({"extra": kwargs} if kwargs else {}) return format_table_output(df, format=format, max_rows=limit, meta=meta) except NoDataFoundError as e: logger.warning(f"NoDataFoundError: {e}") return f"Error: {e}" except LoginError as e: logger.error(f"LoginError: {e}") return f"Error: Could not connect to data source. {e}" except DataSourceError as e: logger.error(f"DataSourceError: {e}") return f"Error: An error occurred while fetching data. {e}" except ValueError as e: logger.warning(f"ValueError: {e}") return f"Error: Invalid input parameter. {e}" except Exception as e: logger.exception(f"Unexpected Exception processing {tool_name}: {e}") return f"Error: An unexpected error occurred: {e}"
• src/baostock_data_source.py:672-675 (helper)

  BaostockDataSource implementation that calls Baostock's query_required_reserve_ratio_data via shared _fetch_macro_data helper.
  def get_required_reserve_ratio_data(self, start_date: Optional[str] = None, end_date: Optional[str] = None, year_type: str = '0') -> pd.DataFrame: """Fetches required reserve ratio data using Baostock.""" # Note the extra yearType parameter handled by kwargs return _fetch_macro_data(bs.query_required_reserve_ratio_data, "Required Reserve Ratio", start_date, end_date, yearType=year_type)