lookup_vat_be

Instructions

Implementation Reference

• src/mcp_einvoicing_be/tools/lookup.py:30-70 (handler)

  The async function lookup_vat_be that implements the tool logic. It normalizes a Belgian VAT number, calls the BCE/KBO API at /enterprises/{digits}, and returns legal name, address, legal form, status, NACE codes, and start date. Handles 404 with a structured not-found response.

  async def lookup_vat_be(
      vat_number: Annotated[
          str,
          "Belgian VAT/enterprise number, e.g. 'BE0123456789' or '0123456789'",
      ],
  ) -> dict[str, object]:
      """Look up a Belgian enterprise number against the BCE/KBO public database.
  
      Accepts the number with or without the 'BE' prefix and with or without
      dots/spaces. Returns the enterprise's legal name, registered address,
      legal form, status, and NACE activity codes.
  
      Optionally set the ``BCE_API_KEY`` environment variable for authenticated
      access to the full BCE dataset.
      """
      normalized = normalize_vat_be(vat_number)
      digits = normalized[2:]  # strip 'BE' for the path segment
  
      client = _bce_client()
      try:
          response = await client._request("GET", f"/enterprises/{digits}")
      except PlatformError as exc:
          if exc.status_code == 404:
              return {
                  "found": False,
                  "vat_number": normalized,
                  "error": "Enterprise number not found",
              }  # noqa: E501
          raise
  
      data: dict[str, object] = response.json()
      return {
          "found": True,
          "vat_number": normalized,
          "name": data.get("name"),
          "legal_form": data.get("legalForm"),
          "status": data.get("status"),
          "address": data.get("address"),
          "nace_codes": data.get("activities", []),
          "start_date": data.get("startDate"),
      }

• src/mcp_einvoicing_be/tools/lookup.py:1-12 (schema)

  Module-level imports and constants, including the BCE API base URL and type annotations. The input schema is defined inline via Annotated[str, ...] on the vat_number parameter (lines 31-34).

  """Lookup tools: lookup_vat_be, check_peppol_participant_be, get_invoice_types_be."""
  
  import os
  from typing import Annotated
  
  from mcp_einvoicing_core import AuthMode, BaseEInvoicingClient, PlatformError
  
  from mcp_einvoicing_be.standards.peppol_bis_3 import INVOICE_TYPES
  from mcp_einvoicing_be.utils.helpers import normalize_vat_be
  
  _BCE_API_BASE = "https://api.kbo-bce.be/v1"
  _PEPPOL_SML_BASE = "https://edelivery.tech.ec.europa.eu/edelivery-smp"

• src/mcp_einvoicing_be/server.py:20-28 (registration)

  Registration of lookup_vat_be on the MCP server via mcp.tool()(lookup_vat_be) at line 26. The function is imported from tools.lookup at line 11.

  def _register_be_tools(mcp: Any) -> None:
      """Register all Belgian e-invoicing tools onto the shared FastMCP instance."""
      mcp.tool()(_validator.validate_invoice_be)
      mcp.tool()(_validator.validate_pint_be)
      mcp.tool()(_generator.generate_invoice_be)
      mcp.tool()(transform_to_ubl)
      mcp.tool()(lookup_vat_be)
      mcp.tool()(check_peppol_participant_be)
      mcp.tool()(get_invoice_types_be)

• src/mcp_einvoicing_be/utils/helpers.py:14-34 (helper)

  Helper function normalize_vat_be used by lookup_vat_be. Normalizes a Belgian VAT number to 'BE' + 10 digits, stripping spaces, dots, dashes and optional BE prefix.

  def normalize_vat_be(vat_number: str) -> str:
      """Normalize a Belgian VAT/enterprise number to 'BE' + 10-digit format.
  
      Accepts:
      - ``BE0123456789``
      - ``0123456789``
      - ``BE 0123.456.789``
      - ``0123.456.789``
  
      Raises ``ValueError`` if the result is not exactly 10 digits.
      """
      cleaned = re.sub(r"[\s.\-]", "", vat_number.upper())
      digits = cleaned[2:] if cleaned.startswith("BE") else cleaned
  
      if not re.fullmatch(r"\d{10}", digits):
          raise ValueError(
              f"Invalid Belgian VAT/enterprise number: {vat_number!r}. "
              "Expected 10 digits (with optional 'BE' prefix)."
          )
  
      return f"BE{digits}"

• src/mcp_einvoicing_be/tools/lookup.py:15-23 (helper)

  Helper _bce_client() that constructs an HTTP client for the BCE API, optionally using a BEARER_TOKEN auth mode if BCE_API_KEY environment variable is set.

  def _bce_client() -> BaseEInvoicingClient:
      api_key = os.environ.get("BCE_API_KEY", "")
      if api_key:
          return BaseEInvoicingClient(
              base_url=_BCE_API_BASE,
              auth_mode=AuthMode.BEARER_TOKEN,
              static_bearer_token=api_key,
          )
      return BaseEInvoicingClient(base_url=_BCE_API_BASE, auth_mode=AuthMode.NONE)