A Share MCP

Instructions

Implementation Reference

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

  The MCP tool handler function for 'normalize_index_code'. It is decorated with @app.tool() for registration, logs the tool call, and delegates execution to the core logic via run_tool_with_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 implementing the normalization logic, mapping common index names/codes to Baostock standard format (sh.000300 etc.). Includes input 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)

  Registers the helper tools, including 'normalize_index_code', by calling the register_helpers_tools function.

  register_helpers_tools(app)

• src/tools/helpers.py:15-76 (registration)

  The registration function for helper tools. It defines and registers 'normalize_index_code' (and others) using @app.tool() decorators when called.

  def register_helpers_tools(app: FastMCP):
      """Register helper/utility tools with the MCP app."""
  
      @app.tool()
      def normalize_stock_code(code: str) -> str:
          """Normalize a stock code to Baostock format."""
          logger.info("Tool 'normalize_stock_code' called with input=%s", code)
          return run_tool_with_handling(
              lambda: normalize_stock_code_logic(code),
              context="normalize_stock_code",
          )
  
      @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",
          )
  
      @app.tool()
      def list_tool_constants(kind: Optional[str] = None) -> str:
          """
          List valid constants for tool parameters.
  
          Args:
              kind: Optional filter: 'frequency' | 'adjust_flag' | 'year_type' | 'index'. If None, show all.
          """
          logger.info("Tool 'list_tool_constants' called kind=%s", kind or "all")
          freq = [
              ("d", "daily"), ("w", "weekly"), ("m", "monthly"),
              ("5", "5 minutes"), ("15", "15 minutes"), ("30", "30 minutes"), ("60", "60 minutes"),
          ]
          adjust = [("1", "forward adjusted"), ("2", "backward adjusted"), ("3", "unadjusted")]
          year_type = [("report", "announcement year"), ("operate", "ex-dividend year")]
          index = [("hs300", "CSI 300"), ("sz50", "SSE 50"), ("zz500", "CSI 500")]
  
          sections = []
  
          def as_md(title: str, rows):
              if not rows:
                  return ""
              header = f"### {title}\n\n| value | meaning |\n|---|---|\n"
              lines = [f"| {v} | {m} |" for (v, m) in rows]
              return header + "\n".join(lines) + "\n"
  
          k = (kind or "").strip().lower()
          if k in ("", "frequency"):
              sections.append(as_md("frequency", freq))
          if k in ("", "adjust_flag"):
              sections.append(as_md("adjust_flag", adjust))
          if k in ("", "year_type"):
              sections.append(as_md("year_type", year_type))
          if k in ("", "index"):
              sections.append(as_md("index", index))
  
          out = "\n".join(s for s in sections if s)
          if not out:
              return "Error: Invalid kind. Use one of 'frequency', 'adjust_flag', 'year_type', 'index'."
          return out