add_allegato

Instructions

Implementation Reference

• tools/body_tools.py:592-663 (handler)

  The add_allegato tool handler: accepts nome_allegato, attachment_base64, optional formato_allegato and descrizione_allegato; validates base64 decodability and name length <=60; returns {'Allegati': {...}} on success or {'error': '...'} on failure.

  @mcp.tool()
  def add_allegato(
      nome_allegato: Annotated[
          str,
          Field(
              description=(
                  "Attachment file name (NomeAllegato), max 60 chars. "
                  "Include the extension (e.g. 'contract.pdf', 'ddt_001.pdf')."
              )
          ),
      ],
      attachment_base64: Annotated[
          str,
          Field(
              description=(
                  "Base64-encoded content of the attachment. "
                  "Any binary file is accepted; common formats: PDF, XML, JPG, ZIP."
              )
          ),
      ],
      formato_allegato: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "MIME type or format description (FormatoAllegato), max 10 chars. "
                  "Examples: 'PDF', 'XML', 'ZIP'. Optional but recommended."
              ),
          ),
      ] = None,
      descrizione_allegato: Annotated[
          Optional[str],
          Field(
              default=None,
              description="Short description of the attachment content, max 100 chars. Optional.",
          ),
      ] = None,
  ) -> dict:
      """Build an Allegati (attachment) entry to include in a FatturaPA document.
  
      Use this when you need to attach supporting documents (e.g. DDT, contract, PDF)
      to the invoice. Call once per file, collect results in a list, and pass it to
      generate_fattura_xml() as the allegati parameter.
  
      attachment_base64 must be valid standard base64 (RFC 4648); the tool verifies
      decodability. nome_allegato must include the file extension (e.g. 'contract.pdf').
      formato_allegato (e.g. 'PDF', 'XML', 'ZIP') is optional but recommended for
      recipients to identify the content without decoding.
  
      On success returns {'Allegati': {'NomeAllegato', 'Attachment', 'size_bytes', ...}}.
      On failure returns {'error': '<reason>'} (invalid base64 or name > 60 chars).
      """
      try:
          decoded = base64.b64decode(attachment_base64)
      except Exception as exc:
          return {"error": f"Invalid base64 content: {exc}"}
  
      if len(nome_allegato) > 60:
          return {"error": "nome_allegato must not exceed 60 characters."}
  
      allegato: dict = {
          "NomeAllegato": nome_allegato,
          "Attachment": attachment_base64,
          "size_bytes": len(decoded),
      }
  
      if formato_allegato:
          allegato["FormatoAllegato"] = formato_allegato[:10]
      if descrizione_allegato:
          allegato["DescrizioneAllegato"] = descrizione_allegato[:100]
  
      return {"Allegati": allegato}

• tools/body_tools.py:593-628 (schema)

  Input schema for add_allegato — four parameters: nome_allegato (str, max 60), attachment_base64 (str, base64 encoded), formato_allegato (Optional[str], max 10), descrizione_allegato (Optional[str], max 100).

  def add_allegato(
      nome_allegato: Annotated[
          str,
          Field(
              description=(
                  "Attachment file name (NomeAllegato), max 60 chars. "
                  "Include the extension (e.g. 'contract.pdf', 'ddt_001.pdf')."
              )
          ),
      ],
      attachment_base64: Annotated[
          str,
          Field(
              description=(
                  "Base64-encoded content of the attachment. "
                  "Any binary file is accepted; common formats: PDF, XML, JPG, ZIP."
              )
          ),
      ],
      formato_allegato: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "MIME type or format description (FormatoAllegato), max 10 chars. "
                  "Examples: 'PDF', 'XML', 'ZIP'. Optional but recommended."
              ),
          ),
      ] = None,
      descrizione_allegato: Annotated[
          Optional[str],
          Field(
              default=None,
              description="Short description of the attachment content, max 100 chars. Optional.",
          ),
      ] = None,

• server.py:83-84 (registration)

  add_allegato is registered via register_body_tools(mcp) at server startup (line 84), which calls @mcp.tool() decorator on the add_allegato function inside tools/body_tools.py.

  register_header_tools(mcp)
  register_body_tools(mcp)

• tools/body_tools.py:113-114 (registration)

  The register_body_tools function that registers add_allegato (and 6 other body tools) via @mcp.tool() decorators.

  def register_body_tools(mcp: FastMCP) -> None:
      """Register the 7 FatturaElettronicaBody tools on the FastMCP instance."""