get_latest_date

Instructions

Implementation Reference

• servers/ecfr-mcp/src/ecfr_mcp/server.py:510-546 (handler)

  The main tool handler for 'get_latest_date'. Defined as an MCP tool via @mcp.tool decorator. Accepts a title_number (default 48=FAR) and returns the latest available date from the eCFR titles API. Validates the title number, fetches /api/versioner/v1/titles.json, and returns title metadata including up_to_date_as_of, latest_amended_on, and latest_issue_date. Raises ValueError for reserved/not-found titles.

  @mcp.tool(annotations={"title": "Get Latest Date", "readOnlyHint": True, "destructiveHint": False})
  async def get_latest_date(title_number: int = 48) -> dict[str, Any]:
      """Get the most recent available date for a CFR title.
  
      CRITICAL: eCFR lags 1-2 business days behind the Federal Register.
      Using today's date on versioner endpoints causes 404 errors. Call this
      first to get the safe date, then pass it to other tools.
  
      Default title 48 = Federal Acquisition Regulations System (FAR, DFARS,
      and all agency supplements). Other common titles: 2 (Grants/Agreements),
      5 (Administrative Personnel), 29 (Labor), 41 (Public Contracts).
  
      Raises ValueError for titles 1-50 that are reserved (no content).
      """
      title_number = _validate_title_number(title_number)
      data = await _get_json("/api/versioner/v1/titles.json")
      titles = _as_list(_safe_dict(data).get("titles"))
      for title in titles:
          t = _safe_dict(title)
          if _safe_int(t.get("number")) == title_number:
              utd = t.get("up_to_date_as_of")
              if not isinstance(utd, str) or not utd.strip():
                  reserved = t.get("reserved")
                  raise ValueError(
                      f"Title {title_number} has no available content "
                      f"(reserved={reserved}). Reserved titles are placeholders "
                      f"in the CFR numbering scheme without published regulations."
                  )
              return {
                  "title": title_number,
                  "name": t.get("name"),
                  "up_to_date_as_of": utd,
                  "latest_amended_on": t.get("latest_amended_on"),
                  "latest_issue_date": t.get("latest_issue_date"),
                  "reserved": bool(t.get("reserved", False)),
              }
      raise ValueError(f"Title {title_number} not found.")

• servers/ecfr-mcp/src/ecfr_mcp/server.py:510-510 (registration)

  Tool registration via the @mcp.tool decorator with annotations including title 'Get Latest Date', readOnlyHint=True, and destructiveHint=False.

  @mcp.tool(annotations={"title": "Get Latest Date", "readOnlyHint": True, "destructiveHint": False})

• servers/ecfr-mcp/src/ecfr_mcp/server.py:478-503 (helper)

  Internal helper _resolve_date() that shares the same core logic (fetching titles.json and extracting up_to_date_as_of) but returns only the date string. Called by other tools (not get_latest_date itself) to auto-resolve dates before making versioner API calls.

  async def _resolve_date(title_number: int) -> str:
      """Resolve the latest available date for a CFR title.
  
      Called before any versioner endpoint. Using today's date often returns
      404 because eCFR lags 1-2 business days.
  
      Raises ValueError with an actionable message for reserved titles
      (which have null up_to_date_as_of) rather than building a URL with
      'None' in it.
      """
      data = await _get_json("/api/versioner/v1/titles.json")
      titles = _as_list(_safe_dict(data).get("titles"))
      for title in titles:
          t = _safe_dict(title)
          if _safe_int(t.get("number")) == title_number:
              utd = t.get("up_to_date_as_of")
              if not isinstance(utd, str) or not utd.strip():
                  reason = "this title is marked 'reserved'" if t.get("reserved") else (
                      "the API did not return up_to_date_as_of"
                  )
                  raise ValueError(
                      f"Cannot resolve a date for title {title_number}: {reason}. "
                      f"Reserved or un-issued titles have no published content."
                  )
              return utd
      raise ValueError(f"Title {title_number} not found in eCFR titles list.")

• servers/ecfr-mcp/src/ecfr_mcp/server.py:166-179 (helper)

  Validation helper _validate_title_number() used by get_latest_date to ensure title_number is an integer between 1 and 50.

  def _validate_title_number(value: Any, *, field: str = "title_number") -> int:
      """CFR titles are 1-50."""
      if value is None:
          raise ValueError(f"{field} is required.")
      if isinstance(value, bool):
          raise ValueError(f"{field} must be an int 1-50, not bool.")
      try:
          n = int(value)
      except (TypeError, ValueError, OverflowError) as exc:
          # OverflowError catches inf/nan float coercion. Round 6 fix.
          raise ValueError(f"{field} must be an int 1-50. Got {value!r}.") from exc
      if n < 1 or n > 50:
          raise ValueError(f"{field} must be between 1 and 50. Got {n}.")
      return n

• servers/ecfr-mcp/src/ecfr_mcp/server.py:275-285 (helper)

  Error formatting helper that references get_latest_date() in its 404 error message, directing users to call get_latest_date() first if a date exceeds a title's up_to_date_as_of value.

  def _format_error(status: int, body: Any) -> str:
      """Translate common eCFR errors into actionable messages."""
      cleaned = _clean_error_body(body)
      low = cleaned.lower() if isinstance(cleaned, str) else ""
      if status == 404:
          return (
              "HTTP 404: Resource not found. Common causes: (1) the date exceeds "
              "the title's up_to_date_as_of value -- use get_latest_date() first; "
              "(2) the section/part does not exist at the requested date; "
              "(3) 'current' is not a valid date keyword -- use a specific YYYY-MM-DD date. "
              f"API response: {cleaned}"