A-Share MCP Server

Instructions

Implementation Reference

• src/tools/macroeconomic.py:92-111 (handler)

  The primary MCP tool handler function, decorated with @app.tool(). It validates inputs implicitly via types, calls the shared helper call_macro_data_tool which invokes the data source method and formats the output as markdown table.
  @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: """ Fetches monthly money supply data (M0, M1, M2) within a date range. Args: start_date: Optional. Start date in 'YYYY-MM' format. end_date: Optional. End date in 'YYYY-MM' format. Returns: Markdown table with monthly money supply data or an error message. """ # Add specific validation for YYYY-MM format if desired return call_macro_data_tool( "get_money_supply_data_month", active_data_source.get_money_supply_data_month, "Monthly Money Supply", start_date, end_date, limit=limit, format=format )
• mcp_server.py:55-55 (registration)

  The call to register_macroeconomic_tools which defines and registers the get_money_supply_data_month tool (along with other macro tools) to the FastMCP app instance.
  register_macroeconomic_tools(app, active_data_source)
• src/tools/base.py:76-125 (helper)

  Shared helper function used by macro tools to call the data source method, handle exceptions, and format the pandas DataFrame output as a markdown table.
  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:677-681 (helper)

  Implementation of the data source method called by the tool handler, using Baostock's query_money_supply_data_month API via the shared _fetch_macro_data helper.
  def get_money_supply_data_month(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame: """Fetches monthly money supply data (M0, M1, M2) using Baostock.""" # Baostock expects YYYY-MM format for dates here return _fetch_macro_data(bs.query_money_supply_data_month, "Monthly Money Supply", start_date, end_date)
• src/data_source_interface.py:113-116 (schema)

  Abstract method in the FinancialDataSource interface defining the expected signature and return type for money supply data retrieval.
  @abstractmethod def get_money_supply_data_month(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame: """Fetches monthly money supply data (M0, M1, M2).""" pass