Search Charity Commission Register

Instructions

Implementation Reference

• charity.py:66-115 (handler)

  The async function that executes the charity_search tool logic. It calls the Charity Commission API at /searchCharityName/{query}, applies client-side pagination (offset/limit), maps the response into CharitySearchItem objects, and returns a CharitySearchResult.

  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,
      )

• charity.py:56-65 (registration)

  The @mcp.tool decorator that registers 'charity_search' with FastMCP, including annotations for title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

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

• models.py:464-516 (schema)

  Pydantic models CharitySearchItem and CharitySearchResult defining the input/output schema for the charity_search tool.

  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)."
      )
  
  
  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.",
      )

• server.py:154-159 (registration)

  Top-level server registration: imports the charity module and calls charity.register_tools(mcp), which triggers the @mcp.tool decorator for charity_search.

  import companies_house, charity, disqualified, land_registry, gazette, hmrc_vat, search_fetch
  import prompts as prompts_module
  from fastmcp.server.transforms import PromptsAsTools
  
  companies_house.register_tools(mcp)
  charity.register_tools(mcp)

• prompts.py:30-39 (helper)

  Prompt template that references charity_search as step 1 in a due diligence workflow.

  def charity_due_diligence(charity_name: str) -> str:
      return (
          f"Run a due diligence check on UK charity '{charity_name}'. "
          "Use the available tools:\n"
          "1. charity_search — find the charity and confirm the charity number\n"
          "2. charity_profile — fetch the full record including trustees, "
          "income/expenditure, and insolvency flags\n"
          "3. gazette_insolvency — search by the charity name for any insolvency notices\n"
          "Summarise findings including financial health and governance flags."
      )