validate_invoice_be

Instructions

Implementation Reference

• src/mcp_einvoicing_be/tools/validation.py:72-90 (handler)

  The main tool handler function 'validate_invoice_be' — an async method on BEDocumentValidator that validates a UBL 2.1 XML invoice against the selected Belgian profile (peppol-bis-3, pint-be, or mercurius). Calls _validate_with_profile which evaluates XPath-based business rules and returns a structured result dict.

  async def validate_invoice_be(
      self,
      xml: Annotated[str, "Raw UBL 2.1 XML invoice content"],
      profile: Annotated[
          ProfileLiteral,
          "Validation profile: 'peppol-bis-3' (default), 'pint-be', or 'mercurius'",
      ] = "peppol-bis-3",
  ) -> dict[str, object]:
      """Validate a UBL 2.1 XML invoice against Belgian business rules.
  
      Applies EN 16931 syntax and semantic checks plus the selected Belgian
      profile overlay (Peppol BIS Billing 3.0, PINT-BE, or Mercurius).
      Returns a structured result with per-rule error and warning messages.
      """
      try:
          result = self._validate_with_profile(xml, profile)
          return cast(dict[str, object], result.to_dict())
      except ValidationError as exc:
          return {"valid": False, "profile": profile, "errors": [str(exc)], "warnings": []}

• src/mcp_einvoicing_be/tools/validation.py:16-22 (schema)

  ProfileLiteral type and _PROFILE_RULES mapping: defines the three allowed profiles ('peppol-bis-3', 'pint-be', 'mercurius') and maps them to their respective rule sets imported from the standards modules.

  ProfileLiteral = Literal["peppol-bis-3", "pint-be", "mercurius"]
  
  _PROFILE_RULES: dict[str, list[dict[str, str]]] = {
      "peppol-bis-3": PEPPOL_BIS3_RULES,
      "pint-be": PINT_BE_RULES,
      "mercurius": MERCURIUS_RULES,
  }

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

  Tool registration: BEDocumentValidator is instantiated and validate_invoice_be is registered via mcp.tool()(_validator.validate_invoice_be) on the FastMCP instance in _register_be_tools.

  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)
  
  
  mcp = EInvoicingMCPServer(
      "mcp-einvoicing-be",
      instructions=(
          "Tools for Belgian electronic invoicing: validation, generation, and lookups "
          "for Peppol BIS Billing 3.0, PINT-BE (NBB), UBL 2.1, and Mercurius."
      ),
  )
  mcp.register_plugin(_register_be_tools, "be")

• src/mcp_einvoicing_be/utils/helpers.py:37-42 (helper)

  Helper function 'parse_ubl_xml' used by the validator to parse raw XML string into an ElementTree. Returns (root, None) on success or (None, error_str) on ParseError.

  def parse_ubl_xml(xml: str) -> tuple[Element | None, str | None]:
      """Parse a UBL XML string and return ``(root_element, None)`` or ``(None, error_str)``."""
      try:
          return fromstring(xml.strip()), None
      except ParseError as exc:
          return None, f"XML parse error: {exc}"

• src/mcp_einvoicing_be/standards/peppol_bis_3.py:20-30 (helper)

  PEPPOL_BIS3_RULES definition — the base business rules (BR-01, BR-02) used by the default 'peppol-bis-3' profile and extended by PINT-BE and Mercurius.

  PEPPOL_BIS3_RULES: list[dict[str, str]] = [
      {
          "id": "BR-01",
          "severity": "error",
          "xpath": "/Invoice/cbc:CustomizationID",
          "message": "An Invoice shall have a Specification identifier (BT-24).",
      },
      {
          "id": "BR-02",
          "severity": "error",
          "xpath": "/Invoice/cbc:ProfileID",