Search Gazette Corporate Insolvency Notices

Instructions

Implementation Reference

• gazette.py:186-262 (handler)

  The gazette_insolvency async handler function. Searches The Gazette's /insolvency/notice/data.json endpoint by entity name, parses and filters the feed entries, sorts by severity/date, caps the results, and returns a GazetteInsolvencyResult Pydantic model.

  async def gazette_insolvency(
      entity_name: Annotated[str, Field(description="Company or individual name to search for in Gazette insolvency notices", min_length=2, max_length=200)],
      notice_type: Annotated[str | None, Field(description="Filter by notice code (e.g. '2441' winding-up petition, '2443' winding-up order, '2448' administration order, '2460' striking-off). Omit to search all.")] = None,
      start_date: Annotated[str | None, Field(description="Filter notices from this date (YYYY-MM-DD)")] = None,
      end_date: Annotated[str | None, Field(description="Filter notices up to this date (YYYY-MM-DD)")] = None,
      max_notices: Annotated[int, Field(description="Cap on notices returned, applied after severity/date sort. Default 20. The Gazette insolvency feed returns up to 100 results per search — raise to 100 to see the full set.", ge=1, le=100)] = 20,
  ) -> GazetteInsolvencyResult:
      """Search The Gazette's insolvency notice index by entity name.
  
      Searches the Gazette's insolvency endpoint which covers corporate
      notice codes: winding-up orders (2443), administration orders (2448),
      liquidator appointments (2452), striking-off notices (2460), and more.
      Results are sorted by severity — winding-up orders and administration
      orders appear first.
  
      Each result includes a notice_numeric_id. Read the full legal wording
      via the notice://{notice_numeric_id} resource.
  
      The Gazette is the official UK public record. A notice here means
      the event has been formally published and is legally effective.
      """
      qs: dict[str, Any] = {
          "text": entity_name,
          "results-page-size": 100,
      }
      if start_date:
          qs["start-publish-date"] = start_date
      if end_date:
          qs["end-publish-date"] = end_date
  
      all_notices: list[dict[str, Any]] = []
  
      async with gazette_client() as client:
          try:
              resp = await _request_with_retry(
                  client, "GET", "/insolvency/notice/data.json", params=qs
              )
              raw = resp.json()
              entries = raw.get("entry", []) if isinstance(raw, dict) else []
              if isinstance(entries, dict):
                  entries = [entries]
              all_notices = _extract_notices(entries)
          except Exception:
              pass
  
      # Filter by specific notice type if requested
      if notice_type:
          all_notices = [n for n in all_notices if n["notice_code"] == notice_type]
  
      # Apply global cap (already sorted by _extract_notices)
      all_notices = all_notices[:max_notices]
  
      notice_models: list[GazetteNotice] = []
      for n in all_notices:
          code = n.get("notice_code")
          notice_models.append(
              GazetteNotice(
                  notice_id=n.get("notice_id"),
                  notice_numeric_id=n.get("notice_numeric_id"),
                  notice_code=code,
                  notice_type=n.get("notice_type"),
                  severity=SEVERITY.get(code or "", 0),
                  date=n.get("date"),
                  title=n.get("title"),
                  content=n.get("content"),
              )
          )
  
      return GazetteInsolvencyResult(
          entity_name=entity_name,
          notice_type_filter=notice_type,
          start_date=start_date,
          end_date=end_date,
          total_notices=len(notice_models),
          max_notices_cap=max_notices,
          notices=notice_models,
      )

• gazette.py:176-178 (registration)

  The @mcp.tool decorator registering 'gazette_insolvency' as a FastMCP tool, called via gazette.register_tools(mcp) in server.py line 162.

  @mcp.tool(
      name="gazette_insolvency",
      annotations={

• gazette.py:106-131 (helper)

  Helper function that extracts structured insolvency notice records from the Gazette feed entry array, filters by corporate insolvency codes, and sorts by severity descending then date descending.

  def _extract_notices(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
      """Pull structured insolvency notice records from the Gazette feed entry array."""
      notices = []
      for entry in entries:
          code = str(entry.get("f:notice-code", ""))
          if code not in ALL_CORPORATE_INSOLVENCY_CODES:
              continue
          notice_uri = entry.get("id", "")
          raw_content = entry.get("content", "")
          notices.append(
              {
                  "notice_id": notice_uri,
                  "notice_numeric_id": _notice_numeric_id(notice_uri) if notice_uri else None,
                  "notice_code": code,
                  "notice_type": NOTICE_LABELS.get(code, "Corporate Notice"),
                  "date": (entry.get("published") or "")[:10] or None,
                  "title": entry.get("title") or None,
                  "content": _strip_html(raw_content) if raw_content else None,
              }
          )
      # Sort by severity descending, then date descending
      notices.sort(
          key=lambda n: (SEVERITY.get(n["notice_code"], 0), n["date"] or ""),
          reverse=True,
      )
      return notices

• models.py:731-758 (schema)

  Pydantic output model for gazette_insolvency — returns entity_name, filters, total_notices, max_notices_cap, and a list of GazetteNotice items.

  class GazetteInsolvencyResult(BaseModel):
      """Aggregated Gazette insolvency notice search result."""
  
      model_config = BASE_CFG
  
      entity_name: str = Field(..., description="Entity name that was searched.")
      notice_type_filter: str | None = Field(
          None,
          description="Notice code filter applied, or null if all codes searched.",
      )
      start_date: str | None = Field(
          None, description="Lower bound of the date range filter, if any."
      )
      end_date: str | None = Field(
          None, description="Upper bound of the date range filter, if any."
      )
      total_notices: int = Field(
          ..., description="Total notices returned after deduplication, sorting, and cap."
      )
      max_notices_cap: int = Field(
          ..., description="The max_notices cap applied. Upstream may have more matching notices."
      )
      notices: list[GazetteNotice] = Field(
          default_factory=list,
          description=(
              "Matching notices, sorted by severity (desc) then date (desc)."
          ),
      )

• gazette.py:45-69 (helper)

  Taxonomy of corporate insolvency notice codes and their human-readable labels, used by the gazette_insolvency handler to filter/classify notices.

  ALL_CORPORATE_INSOLVENCY_CODES = {
      "2431", "2432", "2433",  # older corporate winding-up / liquidator codes
      "2441", "2442", "2443", "2444", "2445", "2446",
      "2447", "2448", "2449", "2450", "2452", "2455", "2456", "2460",
  }
  
  NOTICE_LABELS: dict[str, str] = {
      "2431": "Resolutions for Winding-Up",
      "2432": "Appointment of Liquidators",
      "2433": "Notice to Creditors / Contributories",
      "2441": "Winding-Up Petition",
      "2442": "Dismissal of Winding-Up Petition",
      "2443": "Winding-Up Order",
      "2444": "Stay of Winding-Up Order",
      "2445": "Appointment of Provisional Liquidator",
      "2446": "Notice to Creditors",
      "2447": "Notice to Contributories",
      "2448": "Administration Order",
      "2449": "Appointment of Administrative Receiver",
      "2450": "Moratorium",
      "2452": "Appointment of Liquidator",
      "2455": "Notice of Voluntary Winding-Up Resolution",
      "2456": "Creditors' Voluntary Liquidation",
      "2460": "Striking-Off Notice",
  }