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