is_holiday

Instructions

Implementation Reference

• src/japan_utils_mcp/server.py:300-337 (handler)

  The main handler function for the 'is_holiday' tool. Decorated with @mcp.tool(), accepts a date string (YYYY-MM-DD, YYYY/MM/DD, or YYYYMMDD), parses it via _parse_date helper, checks against the jpholiday library, and returns a dict with is_holiday, name_jp, weekday_jp, weekday_en.

  @mcp.tool()
  def is_holiday(date_str: str) -> dict[str, Any]:
      """Check whether a date is a Japanese national holiday (祝日).
  
      Args:
          date_str: Date in 'YYYY-MM-DD', 'YYYY/MM/DD', or 'YYYYMMDD' format.
  
      Returns:
          dict with keys:
              - date: str (normalized 'YYYY-MM-DD')
              - is_holiday: bool
              - name_jp: str | None (holiday name in Japanese, if applicable)
              - weekday_jp: str (e.g. '月', '火', ...)
              - weekday_en: str (e.g. 'Monday')
  
      Examples:
          is_holiday("2026-05-03") → {"is_holiday": True, "name_jp": "憲法記念日", ...}
          is_holiday("2026-05-04") → {"is_holiday": True, "name_jp": "みどりの日", ...}
          is_holiday("2026-05-08") → {"is_holiday": False, "name_jp": None, ...}
  
      Notes:
          - Covers national holidays only (祝日 designated by the 国民の祝日に関する法律).
            Does not cover company-specific or regional observances.
          - 振替休日 (substitute holidays) are correctly identified.
      """
      d = _parse_date(date_str)
      name = jpholiday.is_holiday_name(d)
      weekday_jp = "月火水木金土日"[d.weekday()]
      weekday_en = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"][
          d.weekday()
      ]
      return {
          "date": d.isoformat(),
          "is_holiday": name is not None,
          "name_jp": name,
          "weekday_jp": weekday_jp,
          "weekday_en": weekday_en,
      }

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

  Registration of the 'is_holiday' tool via the @mcp.tool() decorator on line 300. FastMCP automatically registers tool functions decorated with @mcp.tool().

  @mcp.tool()
  def is_holiday(date_str: str) -> dict[str, Any]:

• src/japan_utils_mcp/server.py:309-337 (schema)

  Return schema for is_holiday: dict with keys 'date' (str), 'is_holiday' (bool), 'name_jp' (str | None), 'weekday_jp' (str), 'weekday_en' (str).

          - date: str (normalized 'YYYY-MM-DD')
          - is_holiday: bool
          - name_jp: str | None (holiday name in Japanese, if applicable)
          - weekday_jp: str (e.g. '月', '火', ...)
          - weekday_en: str (e.g. 'Monday')
  
  Examples:
      is_holiday("2026-05-03") → {"is_holiday": True, "name_jp": "憲法記念日", ...}
      is_holiday("2026-05-04") → {"is_holiday": True, "name_jp": "みどりの日", ...}
      is_holiday("2026-05-08") → {"is_holiday": False, "name_jp": None, ...}
  
  Notes:
      - Covers national holidays only (祝日 designated by the 国民の祝日に関する法律).
        Does not cover company-specific or regional observances.
      - 振替休日 (substitute holidays) are correctly identified.
  """
  d = _parse_date(date_str)
  name = jpholiday.is_holiday_name(d)
  weekday_jp = "月火水木金土日"[d.weekday()]
  weekday_en = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"][
      d.weekday()
  ]
  return {
      "date": d.isoformat(),
      "is_holiday": name is not None,
      "name_jp": name,
      "weekday_jp": weekday_jp,
      "weekday_en": weekday_en,
  }

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

  Helper function _parse_date used by is_holiday to parse date strings in YYYY-MM-DD, YYYY/MM/DD, or YYYYMMDD formats into a datetime.date object.

  def _parse_date(text: str) -> date:
      """Accept 'YYYY-MM-DD', 'YYYY/MM/DD', or 'YYYYMMDD'."""
      s = text.strip()
      for fmt in ("%Y-%m-%d", "%Y/%m/%d", "%Y%m%d"):
          try:
              return datetime.strptime(s, fmt).date()
          except ValueError:
              continue
      raise ValueError(
          f"Could not parse date {text!r}. Use YYYY-MM-DD, YYYY/MM/DD, or YYYYMMDD."
      )