Get Company Profile

Instructions

Implementation Reference

• companies_house.py:296-306 (handler)

  The company_profile tool handler function that fetches a full Companies House profile for a company number. Calls _fetch_company_profile with the normalised company number and returns a CompanyProfile object.

  async def company_profile(
      company_number: Annotated[str, Field(description="Companies House company number (8 digits, e.g. '03782379'). Returned by company_search.", min_length=1, max_length=10)],
  ) -> CompanyProfile:
      """Fetch the full Companies House profile for a company number.
  
      Returns status, registered address, SIC codes, filing compliance
      (overdue accounts and confirmation statement flags), and whether
      the company has outstanding charges. Use company_search first to
      find the company number.
      """
      return await _fetch_company_profile(_normalise_company_number(company_number))

• companies_house.py:74-117 (helper)

  Shared fetch helper that calls the Companies House API for company profile and charges data, constructing and returning a CompanyProfile Pydantic model.

  async def _fetch_company_profile(company_number: str) -> CompanyProfile:
      async with companies_house_client() as client:
          resp = await _request_with_retry(client, "GET", f"/company/{company_number}")
          data = resp.json()
  
          has_charges = False
          try:
              charges_resp = await _request_with_retry(
                  client, "GET", f"/company/{company_number}/charges",
                  params={"items_per_page": 1},
              )
              charges_data = charges_resp.json()
              charges_items = charges_data.get("items") or []
              has_charges = any(
                  item.get("status") == "outstanding" for item in charges_items
              ) or (
                  charges_data.get("total_count", 0) > 0
                  and not charges_items
              )
          except Exception:
              pass
  
      accs_raw = data.get("accounts") or {}
      conf_raw = data.get("confirmation_statement") or {}
  
      return CompanyProfile(
          company_number=str(data.get("company_number") or company_number),
          company_name=data.get("company_name"),
          company_status=data.get("company_status"),
          company_type=data.get("company_type"),
          date_of_creation=data.get("date_of_creation"),
          sic_codes=list(data.get("sic_codes") or []),
          registered_office_address=data.get("registered_office_address") or {},
          has_charges=has_charges,
          accounts=CompanyAccountsSummary(
              overdue=bool(accs_raw.get("overdue", False)),
              last_accounts_made_up_to=(accs_raw.get("last_accounts") or {}).get("made_up_to"),
              next_due=accs_raw.get("next_due"),
          ),
          confirmation_statement=CompanyConfirmationStatementSummary(
              overdue=bool(conf_raw.get("overdue", False)),
              next_due=conf_raw.get("next_due"),
          ),
      )

• models.py:129-167 (schema)

  CompanyProfile Pydantic model defining the output schema for the company_profile tool, including company_number, company_name, status, type, SIC codes, address, charges flag, accounts, and confirmation statement summaries.

  class CompanyProfile(BaseModel):
      """Full Companies House profile for a single company number."""
  
      model_config = BASE_CFG
  
      company_number: str = Field(..., description="Companies House company number.")
      company_name: str | None = Field(None, description="Registered company name.")
      company_status: str | None = Field(
          None, description="Current status (active, dissolved, in liquidation, etc.)."
      )
      company_type: str | None = Field(
          None, description="Companies House company type code."
      )
      date_of_creation: str | None = Field(
          None, description="Incorporation date (ISO YYYY-MM-DD)."
      )
      sic_codes: list[str] = Field(
          default_factory=list,
          description="Standard Industrial Classification codes.",
      )
      registered_office_address: dict[str, Any] = Field(
          default_factory=dict,
          description="Registered office address as returned by Companies House.",
      )
      has_charges: bool = Field(
          False,
          description=(
              "True if the company has outstanding registered charges (secured debt), "
              "derived from the /charges endpoint. A due diligence signal."
          ),
      )
      accounts: CompanyAccountsSummary = Field(
          default_factory=CompanyAccountsSummary,
          description="Accounts filing status and due dates.",
      )
      confirmation_statement: CompanyConfirmationStatementSummary = Field(
          default_factory=CompanyConfirmationStatementSummary,
          description="Confirmation statement filing status and next due date.",
      )

• companies_house.py:283-295 (registration)

  MCP tool registration for company_profile using @mcp.tool decorator with name='company_profile' and annotations (readOnlyHint, etc.). Registered inside register_tools(mcp).

  # ------------------------------------------------------------------ #
  # 2. company_profile
  # ------------------------------------------------------------------ #
  @mcp.tool(
      name="company_profile",
      annotations={
          "title": "Get Company Profile",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )

• server.py:158-164 (registration)

  Top-level server registration: companies_house.register_tools(mcp) is called in server.py's main() setup, which registers the company_profile tool along with other Companies House tools.

  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)