Search Charity Commission Register

Instructions

Implementation Reference

• charity.py:66-115 (handler)

  Async handler for the charity_search tool. Calls the Charity Commission API /searchCharityName/{query}, applies client-side pagination (offset/limit), maps raw response items to CharitySearchItem models, and returns a CharitySearchResult with metadata.

  async def charity_search(
      query: Annotated[str, Field(description="Charity name or keyword to search for", min_length=2, max_length=200)],
      offset: Annotated[int, Field(description="Number of items to skip before this page. Default 0.", ge=0, le=10000)] = 0,
      limit: Annotated[int, Field(description="Max items to return in this page. Default 20; raise to 100 for bulk views.", ge=1, le=100)] = 20,
  ) -> CharitySearchResult:
      """Search the Charity Commission register of England and Wales by name or keyword.
  
      Returns matching charities with registration number, status, and
      registration date. Use charity_profile for full details once you
      have the charity number. The upstream `searchCharityName` endpoint
      returns the full list in one shot — pagination is applied
      client-side via offset/limit.
      """
      async with charity_client() as client:
          resp = await _request_with_retry(
              client, "GET",
              f"/searchCharityName/{query}",
          )
          data = resp.json()
  
      # API returns a list of charity objects directly
      all_charities = data if isinstance(data, list) else []
      total = len(all_charities)
  
      page_slice = all_charities[offset : offset + limit]
  
      items: list[CharitySearchItem] = []
      for raw in page_slice:
          raw_status = raw.get("reg_status")
          items.append(
              CharitySearchItem(
                  charity_number=str(raw.get("reg_charity_number")) if raw.get("reg_charity_number") is not None else None,
                  charity_name=raw.get("charity_name"),
                  reg_status=raw_status,
                  reg_status_label=_STATUS_LABELS.get(raw_status or "", raw_status),
                  date_of_registration=(raw.get("date_of_registration") or "")[:10] or None,
              )
          )
  
      has_more = (offset + len(items)) < total
  
      return CharitySearchResult(
          query=query,
          total=total,
          offset=offset,
          limit=limit,
          returned=len(items),
          has_more=has_more,
          charities=items,
      )

• models.py:464-490 (schema)

  Pydantic model for a single charity search result item, with fields for charity number, name, status code, status label, and registration date.

  class CharitySearchItem(BaseModel):
      """A single hit in a Charity Commission name search."""
  
      model_config = BASE_CFG
  
      charity_number: str | None = Field(
          None,
          description=(
              "Charity Commission registration number. Pass to charity_profile "
              "for the full record."
          ),
      )
      charity_name: str | None = Field(None, description="Registered charity name.")
      reg_status: str | None = Field(
          None,
          description=(
              "Registration status code as returned upstream: 'R' registered, "
              "'RM' removed."
          ),
      )
      reg_status_label: str | None = Field(
          None,
          description="Human-readable registration status ('Registered', 'Removed').",
      )
      date_of_registration: str | None = Field(
          None, description="Date of first registration (ISO YYYY-MM-DD)."
      )

• models.py:493-516 (schema)

  Pydantic model for the paginated charity search result, containing query metadata and a list of CharitySearchItem records.

  class CharitySearchResult(BaseModel):
      """Paginated result of a Charity Commission name search."""
  
      model_config = BASE_CFG
  
      query: str = Field(..., description="Search term applied.")
      total: int = Field(..., description="Total matches returned by upstream.")
      offset: int = Field(
          ..., description="Number of items skipped before this page (client-side)."
      )
      limit: int = Field(..., description="Max items requested for this page.")
      returned: int = Field(..., description="Items actually returned on this page.")
      has_more: bool = Field(
          ...,
          description=(
              "True if more items may exist beyond this page. Re-call with "
              "offset=offset+returned to continue."
          ),
      )
      charities: list[CharitySearchItem] = Field(
          default_factory=list,
          description="Matching charity records.",
      )

• charity.py:56-65 (registration)

  Registration of the charity_search tool via the @mcp.tool decorator with name and annotations. This is inside the register_tools() function which is called from server.py.

  @mcp.tool(
      name="charity_search",
      annotations={
          "title": "Search Charity Commission Register",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )

• charity.py:30-30 (helper)

  Helper dictionary mapping charity registration status codes to human-readable labels, used by the charity_search handler.

  _STATUS_LABELS = {"R": "Registered", "RM": "Removed"}