era_to_western

Instructions

Implementation Reference

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

  Era data definitions (_ERAS list, _ERA_KANJI_TO_INFO and _ERA_LETTER_TO_INFO lookup dicts) used by era_to_western

  # ──────────────────────────────────────────────────────────────────────
  # Era conversion
  # ──────────────────────────────────────────────────────────────────────
  
  # Era → (start_year, kanji_name, english_name, single_letter_alias)
  # Year-of-era 1 starts in start_year. e.g. 令和1 = 2019, 令和元年 = same.
  _ERAS: list[tuple[int, str, str, str]] = [
      (2019, "令和", "Reiwa", "R"),
      (1989, "平成", "Heisei", "H"),
      (1926, "昭和", "Showa", "S"),
      (1912, "大正", "Taisho", "T"),
      (1868, "明治", "Meiji", "M"),
  ]
  
  _ERA_KANJI_TO_INFO: dict[str, tuple[int, str, str, str]] = {
      e[1]: e for e in _ERAS
  }
  _ERA_LETTER_TO_INFO: dict[str, tuple[int, str, str, str]] = {
      e[3]: e for e in _ERAS
  }

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

  _parse_era_year helper function that parses various era-year string formats (kanji, single-letter alias, English name) into (era_kanji, year_of_era)

  def _parse_era_year(text: str) -> tuple[str, int]:
      """Parse an era-year string into (era_kanji, year_of_era).
  
      Accepts: '令和8年', '令和8', '令和元年', 'R8', 'reiwa 8', 'Reiwa8'.
      Raises ValueError on failure.
      """
      s = text.strip()
  
      # Match '令和元年' or '令和8年' or '令和8'
      m = re.match(r"^(明治|大正|昭和|平成|令和)\s*(元|\d+)\s*年?$", s)
      if m:
          era_kanji = m.group(1)
          year_str = m.group(2)
          year_of_era = 1 if year_str == "元" else int(year_str)
          return era_kanji, year_of_era
  
      # Match 'R8', 'H30', 'S64', 'T15', 'M45' (single-letter alias)
      m = re.match(r"^([RHSTMrhstm])\s*(\d+)$", s)
      if m:
          letter = m.group(1).upper()
          info = _ERA_LETTER_TO_INFO.get(letter)
          if info is None:
              raise ValueError(f"Unknown era letter: {letter}")
          return info[1], int(m.group(2))
  
      # Match 'Reiwa 8', 'Heisei30', 'showa 64' (English name)
      m = re.match(r"^([A-Za-z]+)\s*(\d+)$", s)
      if m:
          name_lower = m.group(1).lower()
          for _start, kanji, english, _letter in _ERAS:
              if english.lower() == name_lower:
                  return kanji, int(m.group(2))
          raise ValueError(f"Unknown era name: {m.group(1)}")
  
      raise ValueError(
          f"Could not parse era-year from {text!r}. "
          "Examples: '令和8年', '令和元年', 'R8', 'Reiwa 8'."
      )

• src/japan_utils_mcp/server.py:92-122 (handler)

  era_to_western MCP tool handler: converts a Japanese era year string to a Western (Gregorian) year using the decorator @mcp.tool()

  @mcp.tool()
  def era_to_western(era_year: str) -> dict[str, Any]:
      """Convert a Japanese era year to a Western (Gregorian) year.
  
      Args:
          era_year: An era-year string. Accepts kanji form ('令和8年', '令和8',
              '令和元年'), single-letter alias ('R8', 'H30'), or English alias
              ('Reiwa 8', 'Heisei 30').
  
      Returns:
          dict with keys:
              - western_year: int (Gregorian year)
              - era_kanji: str (e.g. '令和')
              - era_english: str (e.g. 'Reiwa')
              - year_of_era: int
  
      Examples:
          era_to_western("令和8年")  → {"western_year": 2026, ...}
          era_to_western("R8")      → {"western_year": 2026, ...}
          era_to_western("Reiwa 8") → {"western_year": 2026, ...}
      """
      era_kanji, year_of_era = _parse_era_year(era_year)
      info = _ERA_KANJI_TO_INFO[era_kanji]
      start_year, _kanji, english, _letter = info
      western = start_year + year_of_era - 1
      return {
          "western_year": western,
          "era_kanji": era_kanji,
          "era_english": english,
          "year_of_era": year_of_era,
      }

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

  MCP server registration via FastMCP('japan-utils'), which implicitly registers all @mcp.tool()-decorated functions including era_to_western

  mcp = FastMCP("japan-utils")