split_japanese_name

Instructions

Implementation Reference

• src/japan_utils_mcp/server.py:502-545 (handler)

  The @mcp.tool() decorated function that implements the split_japanese_name tool. It cleans the input, uses a BasicNameDivider (from namedivider-python) to perform the split, and returns a dict with input, family, given, confidence, and algorithm keys.

  @mcp.tool()
  def split_japanese_name(full_name: str) -> dict[str, Any]:
      """Split a Japanese full name into surname (姓) and given name (名).
  
      Uses a kanji-feature-based statistical model (`namedivider-python`).
  
      Args:
          full_name: Japanese full name written in kanji, with no separator
              (e.g. '山田太郎', '長谷川健太'). Names with existing separators
              (space, comma) are also accepted — the separator will be re-detected.
  
      Returns:
          dict with keys:
              - input: str
              - family: str (姓 — surname)
              - given: str (名 — given name)
              - confidence: float (0.0–1.0; higher = more confident split)
              - algorithm: str (which underlying algorithm produced the split)
  
      Examples:
          split_japanese_name("山田太郎") → {"family": "山田", "given": "太郎", ...}
          split_japanese_name("長谷川健太") → {"family": "長谷川", "given": "健太", ...}
          split_japanese_name("佐藤花子") → {"family": "佐藤", "given": "花子", ...}
  
      Caveats:
          - Statistical model — not 100% accurate, especially for unusual names
            or non-traditional name compositions.
          - Confidence < 0.5 indicates an ambiguous split; treat with caution.
          - Single-kanji surnames + single-kanji given names (e.g. '林修') are
            fundamentally ambiguous without external context.
      """
      cleaned = full_name.strip().replace(" ", "").replace("　", "").replace(",", "")
      if not cleaned:
          raise ValueError("full_name cannot be empty.")
  
      divider = _get_name_divider()
      result = divider.divide_name(cleaned)
      return {
          "input": full_name,
          "family": result.family,
          "given": result.given,
          "confidence": float(result.score),
          "algorithm": result.algorithm,
      }

• src/japan_utils_mcp/server.py:488-500 (helper)

  Helper area: module-level _name_divider variable and lazy-initialization function _get_name_divider() that creates a BasicNameDivider instance.

  # ──────────────────────────────────────────────────────────────────────
  # Name splitting
  # ──────────────────────────────────────────────────────────────────────
  
  _name_divider: BasicNameDivider | None = None
  
  
  def _get_name_divider() -> BasicNameDivider:
      global _name_divider
      if _name_divider is None:
          _name_divider = BasicNameDivider()
      return _name_divider

• src/japan_utils_mcp/server.py:12-12 (registration)

  Tool registration at module level: the tool description listed in the module docstring and the @mcp.tool() decorator on line 502 registers it with the FastMCP server.

  - split_japanese_name: split a Japanese full name into surname + given name

• src/japan_utils_mcp/server.py:503-531 (schema)

  Full function signature and docstring defining the schema: accepts a string full_name, returns a dict with input, family, given, confidence (0.0-1.0), and algorithm.

  def split_japanese_name(full_name: str) -> dict[str, Any]:
      """Split a Japanese full name into surname (姓) and given name (名).
  
      Uses a kanji-feature-based statistical model (`namedivider-python`).
  
      Args:
          full_name: Japanese full name written in kanji, with no separator
              (e.g. '山田太郎', '長谷川健太'). Names with existing separators
              (space, comma) are also accepted — the separator will be re-detected.
  
      Returns:
          dict with keys:
              - input: str
              - family: str (姓 — surname)
              - given: str (名 — given name)
              - confidence: float (0.0–1.0; higher = more confident split)
              - algorithm: str (which underlying algorithm produced the split)
  
      Examples:
          split_japanese_name("山田太郎") → {"family": "山田", "given": "太郎", ...}
          split_japanese_name("長谷川健太") → {"family": "長谷川", "given": "健太", ...}
          split_japanese_name("佐藤花子") → {"family": "佐藤", "given": "花子", ...}
  
      Caveats:
          - Statistical model — not 100% accurate, especially for unusual names
            or non-traditional name compositions.
          - Confidence < 0.5 indicates an ambiguous split; treat with caution.
          - Single-kanji surnames + single-kanji given names (e.g. '林修') are
            fundamentally ambiguous without external context.