A-Share MCP Server

Instructions

Implementation Reference

• src/tools/helpers.py:27-34 (handler)

  The main handler function for the 'normalize_index_code' tool. It is decorated with @app.tool() for MCP registration, logs the input, and delegates execution to the core logic via run_tool_with_handling for error handling.

  @app.tool()
  def normalize_index_code(code: str) -> str:
      """Normalize common index codes to Baostock format."""
      logger.info("Tool 'normalize_index_code' called with input=%s", code)
      return run_tool_with_handling(
          lambda: normalize_index_code_logic(code),
          context="normalize_index_code",
      )

• src/use_cases/helpers.py:30-39 (helper)

  Core helper function containing the exact normalization logic, mapping common index code strings to Baostock format codes (e.g., 'HS300' -> 'sh.000300') with validation.

  def normalize_index_code_logic(code: str) -> str:
      validate_non_empty_str(code, "code")
      raw = code.strip().upper()
      if raw in {"000300", "CSI300", "HS300"}:
          return "sh.000300"
      if raw in {"000016", "SSE50", "SZ50"}:
          return "sh.000016"
      if raw in {"000905", "ZZ500", "CSI500"}:
          return "sh.000905"
      raise ValueError("Unsupported index code. Examples: 000300/CSI300/HS300, 000016, 000905.")

• mcp_server.py:58-58 (registration)

  Top-level registration call in the main MCP server setup that invokes register_helpers_tools(app), thereby registering the 'normalize_index_code' tool.

  register_helpers_tools(app)