convert_kana

Instructions

Implementation Reference

• src/japan_utils_mcp/server.py:385-431 (handler)

  The `convert_kana` function — the actual handler implementation of the 'convert_kana' MCP tool. Uses jaconv to convert between hiragana, katakana, and half-width/full-width katakana based on the 'to' parameter.

  @mcp.tool()
  def convert_kana(text: str, to: str) -> dict[str, Any]:
      """Convert between hiragana, katakana, and half-width katakana.
  
      Args:
          text: Input string. Mix of hiragana, katakana, kanji, ASCII is fine —
              non-target characters pass through unchanged.
          to: Target script. One of:
              - 'hiragana'  : ひらがな (e.g. ヤマダ → やまだ)
              - 'katakana'  : カタカナ (full-width) (e.g. やまだ → ヤマダ)
              - 'half_kana' : ﾊﾝｶｸｶﾀｶﾅ (half-width katakana) (e.g. ヤマダ → ﾔﾏﾀﾞ)
              - 'full_kana' : ヤマダ (half-width → full-width katakana)
  
      Returns:
          dict with keys:
              - input: str
              - output: str
              - to: str
  
      Examples:
          convert_kana("ヤマダタロウ", "hiragana") → "やまだたろう"
          convert_kana("やまだたろう", "katakana") → "ヤマダタロウ"
          convert_kana("ヤマダ", "half_kana") → "ﾔﾏﾀﾞ"
          convert_kana("ﾔﾏﾀﾞ", "full_kana") → "ヤマダ"
      """
      target = to.strip().lower()
  
      if target in ("hiragana", "hira", "h"):
          # Half-width katakana → full-width katakana → hiragana
          normalized = jaconv.h2z(text, kana=True)
          out = jaconv.kata2hira(normalized)
      elif target in ("katakana", "kata", "k", "full_katakana"):
          normalized = jaconv.h2z(text, kana=True)
          out = jaconv.hira2kata(normalized)
      elif target in ("half_kana", "halfwidth_kana", "hankaku"):
          # Convert hiragana → katakana → half-width
          full = jaconv.hira2kata(text)
          out = jaconv.z2h(full, kana=True, digit=False, ascii=False)
      elif target in ("full_kana", "fullwidth_kana", "zenkaku"):
          out = jaconv.h2z(text, kana=True, digit=False, ascii=False)
      else:
          raise ValueError(
              f"Unknown 'to' value: {to!r}. "
              "Use 'hiragana', 'katakana', 'half_kana', or 'full_kana'."
          )
  
      return {"input": text, "output": out, "to": target}

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

  The `@mcp.tool()` decorator on the `convert_kana` function — this registers the tool with the FastMCP server instance, making it available as an MCP tool named 'convert_kana'.

  @mcp.tool()

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

  The `jaconv` library import — this is the third-party helper used by the convert_kana function to perform kana conversions (hiragana/katakana, half-width/full-width).

  import jaconv  # type: ignore[import-untyped]

• src/japan_utils_mcp/server.py:386-398 (schema)

  The type annotations and docstring for the convert_kana function act as the schema — defining the parameter types (text: str, to: str) and return type (dict[str, Any]) with documented valid values for 'to'.

  def convert_kana(text: str, to: str) -> dict[str, Any]:
      """Convert between hiragana, katakana, and half-width katakana.
  
      Args:
          text: Input string. Mix of hiragana, katakana, kanji, ASCII is fine —
              non-target characters pass through unchanged.
          to: Target script. One of:
              - 'hiragana'  : ひらがな (e.g. ヤマダ → やまだ)
              - 'katakana'  : カタカナ (full-width) (e.g. やまだ → ヤマダ)
              - 'half_kana' : ﾊﾝｶｸｶﾀｶﾅ (half-width katakana) (e.g. ヤマダ → ﾔﾏﾀﾞ)
              - 'full_kana' : ヤマダ (half-width → full-width katakana)
  
      Returns: