Search Companies House

Instructions

Implementation Reference

• companies_house.py:225-281 (handler)

  The async handler function for the company_search tool. Calls the Companies House /search/companies API, builds a list of CompanySearchItem objects, and returns a paginated CompanySearchResult.

  async def company_search(
      query: Annotated[str, Field(description="Company name or keyword to search for", min_length=2, max_length=200)],
      company_status: Annotated[str | None, Field(description="Filter by company status (e.g. 'active', 'dissolved'). Omit to search all.")] = None,
      company_type: Annotated[str | None, Field(description="Filter by company type (e.g. 'ltd', 'llp'). Omit to search all.")] = None,
      items_per_page: Annotated[int, Field(description="Number of results to return (max 100). Default 20.", ge=1, le=100)] = 20,
      start_index: Annotated[int, Field(description="Pagination offset. Default 0.", ge=0, le=10000)] = 0,
  ) -> CompanySearchResult:
      """Search the Companies House register by company name or keyword.
  
      Returns a paginated list of matching companies with name, number,
      status, SIC codes, incorporation date, and registered address.
      Use company_profile for the full record once you have the company
      number. Re-call with start_index=start_index+items_per_page to
      fetch the next page.
      """
      qs: dict[str, Any] = {
          "q": query,
          "items_per_page": items_per_page,
          "start_index": start_index,
      }
      if company_status:
          qs["status"] = company_status
      if company_type:
          qs["type"] = company_type
  
      async with companies_house_client() as client:
          resp = await _request_with_retry(client, "GET", "/search/companies", params=qs)
          data = resp.json()
  
      raw_items = data.get("items", []) or []
      total = int(data.get("total_results", 0) or 0)
  
      items = [
          CompanySearchItem(
              company_number=raw.get("company_number"),
              title=raw.get("title"),
              company_status=raw.get("company_status"),
              company_type=raw.get("company_type"),
              date_of_creation=raw.get("date_of_creation"),
              sic_codes=list(raw.get("sic_codes") or []),
              address=raw.get("registered_office_address") or {},
              description=raw.get("description"),
          )
          for raw in raw_items
      ]
  
      has_more = (start_index + len(items)) < total
  
      return CompanySearchResult(
          query=query,
          total_results=total,
          start_index=start_index,
          items_per_page=items_per_page,
          returned=len(items),
          has_more=has_more,
          items=items,
      )

• companies_house.py:210-224 (registration)

  The register_tools function in companies_house.py that registers the company_search tool via @mcp.tool(name="company_search", ...) with annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Called from server.py line 158.

  def register_tools(mcp: FastMCP) -> None:
  
      # ------------------------------------------------------------------ #
      # 1. company_search
      # ------------------------------------------------------------------ #
      @mcp.tool(
          name="company_search",
          annotations={
              "title": "Search Companies House",
              "readOnlyHint": True,
              "destructiveHint": False,
              "idempotentHint": True,
              "openWorldHint": True,
          },
      )

• models.py:26-59 (schema)

  CompanySearchItem Pydantic model — defines each search result item with fields: company_number, title, company_status, company_type, date_of_creation, sic_codes, address, description.

  class CompanySearchItem(BaseModel):
      """A single entry in a Companies House search result."""
  
      model_config = BASE_CFG
  
      company_number: str | None = Field(
          None, description="Companies House company number (e.g. '12345678')."
      )
      title: str | None = Field(
          None, description="Registered company name."
      )
      company_status: str | None = Field(
          None,
          description="Company status (e.g. 'active', 'dissolved', 'liquidation').",
      )
      company_type: str | None = Field(
          None,
          description="Companies House company type code (e.g. 'ltd', 'plc', 'llp').",
      )
      date_of_creation: str | None = Field(
          None, description="Incorporation date in ISO format (YYYY-MM-DD)."
      )
      sic_codes: list[str] = Field(
          default_factory=list,
          description="Standard Industrial Classification codes associated with the company.",
      )
      address: dict[str, Any] = Field(
          default_factory=dict,
          description="Registered office address as returned by the Companies House API.",
      )
      description: str | None = Field(
          None,
          description="Short upstream description (usually number + status + creation date).",
      )

• models.py:62-94 (schema)

  CompanySearchResult Pydantic model — defines the paginated search result with fields: query, total_results, start_index, items_per_page, returned, has_more, items (list of CompanySearchItem).

  class CompanySearchResult(BaseModel):
      """Paginated result of a Companies House company search."""
  
      model_config = BASE_CFG
  
      query: str = Field(..., description="The query string that was searched.")
      total_results: int = Field(
          ..., description="Total matching companies in Companies House (server-side)."
      )
      start_index: int = Field(
          ...,
          description="Number of results skipped before this page (upstream start_index).",
      )
      items_per_page: int = Field(
          ..., description="Page size requested from the API for this call."
      )
      returned: int = Field(
          ..., description="Number of items actually returned on this page."
      )
      has_more: bool = Field(
          ...,
          description=(
              "True if more results exist beyond this page. Re-call with "
              "start_index=start_index+items_per_page to fetch the next page."
          ),
      )
      items: list[CompanySearchItem] = Field(
          default_factory=list,
          description=(
              "Matching companies. Use the `company_number` field to call "
              "company_profile, company_officers, or company_psc for full detail."
          ),
      )

• server.py:158-164 (registration)

  Top-level registration call: companies_house.register_tools(mcp) in server.py which calls register_tools(mcp), registering the company_search tool on the MCP server.

  companies_house.register_tools(mcp)
  charity.register_tools(mcp)
  disqualified.register_tools(mcp)
  land_registry.register_tools(mcp)
  gazette.register_tools(mcp)
  hmrc_vat.register_tools(mcp)
  search_fetch.register_tools(mcp)