Get Company Profile

Instructions

Implementation Reference

• companies_house.py:283-306 (registration)

  Tool registration for 'company_profile' — annotated @mcp.tool decorator that defines the tool name, metadata, input parameter schema (company_number), return type (CompanyProfile), and docstring.

  # ------------------------------------------------------------------ #
  # 2. company_profile
  # ------------------------------------------------------------------ #
  @mcp.tool(
      name="company_profile",
      annotations={
          "title": "Get Company Profile",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  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:296-306 (handler)

  Handler function for the company_profile tool — normalizes the company number then delegates to _fetch_company_profile.

  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 (handler)

  Core fetch logic for company profiles — calls Companies House /company/{number} and /company/{number}/charges endpoints, then constructs and returns a CompanyProfile 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)

  Pydantic model CompanyProfile — defines the output schema with fields: company_number, company_name, company_status, company_type, date_of_creation, sic_codes, registered_office_address, has_charges, accounts, confirmation_statement.

  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:49-50 (helper)

  Helper function _normalise_company_number — pads numeric strings to 8 digits with leading zeros, uppercases alpha strings.

  def _normalise_company_number(v: str) -> str:
      return v.zfill(8) if v.isdigit() else v.upper()