A-Share MCP Server

Instructions

Implementation Reference

• src/tools/macroeconomic.py:41-49 (handler)

  MCP tool handler function implementing the tool logic, decorated with @app.tool() for registration, wraps use case execution with standardized error handling.
  @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: """Required reserve ratio data.""" return run_tool_with_handling( lambda: fetch_required_reserve_ratio_data( active_data_source, start_date=start_date, end_date=end_date, year_type=year_type, limit=limit, format=format ), context="get_required_reserve_ratio_data", )
• src/use_cases/macroeconomic.py:23-28 (helper)

  Use case orchestrator that validates inputs, fetches raw data from FinancialDataSource, and formats the output as markdown table.
  def fetch_required_reserve_ratio_data(data_source: FinancialDataSource, *, start_date: Optional[str], end_date: Optional[str], year_type: str, limit: int, format: str) -> str: validate_output_format(format) validate_year_type_reserve(year_type) df = data_source.get_required_reserve_ratio_data(start_date=start_date, end_date=end_date, year_type=year_type) meta = {"dataset": "required_reserve_ratio", "start_date": start_date, "end_date": end_date, "year_type": year_type} return format_table_output(df, format=format, max_rows=limit, meta=meta)
• src/data_source_interface.py:108-111 (schema)

  Interface definition (schema) for the data source method, specifying expected parameters and return type (pd.DataFrame).
  @abstractmethod 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.""" pass
• src/baostock_data_source.py:672-676 (helper)

  Baostock-specific implementation of the data source method, delegating to shared _fetch_macro_data helper which calls baostock.query_required_reserve_ratio_data.
  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)
• src/tools/macroeconomic.py:22-70 (registration)

  Registration function that defines and registers all macroeconomic tools including get_required_reserve_ratio_data using FastMCP @app.tool() decorators.
  def register_macroeconomic_tools(app: FastMCP, active_data_source: FinancialDataSource): """Register macroeconomic tools.""" @app.tool() def get_deposit_rate_data(start_date: Optional[str] = None, end_date: Optional[str] = None, limit: int = 250, format: str = "markdown") -> str: """Benchmark deposit rates.""" return run_tool_with_handling( lambda: fetch_deposit_rate_data(active_data_source, start_date=start_date, end_date=end_date, limit=limit, format=format), context="get_deposit_rate_data", ) @app.tool() def get_loan_rate_data(start_date: Optional[str] = None, end_date: Optional[str] = None, limit: int = 250, format: str = "markdown") -> str: """Benchmark loan rates.""" return run_tool_with_handling( lambda: fetch_loan_rate_data(active_data_source, start_date=start_date, end_date=end_date, limit=limit, format=format), context="get_loan_rate_data", ) @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: """Required reserve ratio data.""" return run_tool_with_handling( lambda: fetch_required_reserve_ratio_data( active_data_source, start_date=start_date, end_date=end_date, year_type=year_type, limit=limit, format=format ), context="get_required_reserve_ratio_data", ) @app.tool() def get_money_supply_data_month(start_date: Optional[str] = None, end_date: Optional[str] = None, limit: int = 250, format: str = "markdown") -> str: """Monthly money supply data.""" return run_tool_with_handling( lambda: fetch_money_supply_data_month( active_data_source, start_date=start_date, end_date=end_date, limit=limit, format=format ), context="get_money_supply_data_month", ) @app.tool() def get_money_supply_data_year(start_date: Optional[str] = None, end_date: Optional[str] = None, limit: int = 250, format: str = "markdown") -> str: """Yearly money supply data.""" return run_tool_with_handling( lambda: fetch_money_supply_data_year( active_data_source, start_date=start_date, end_date=end_date, limit=limit, format=format ), context="get_money_supply_data_year", )