generate_progressivo_invio

Instructions

Implementation Reference

• tools/header_tools.py:430-481 (handler)

  The actual handler function for generate_progressivo_invio. Implements the logic: validates prefix (1-3 alphabetic chars), generates a sequence number (explicit or random 5-digit), pads to max 10 chars, and returns the ProgressivoInvio string with its length.

  @mcp.tool()
  def generate_progressivo_invio(
      prefix: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Optional alphabetic prefix (max 3 chars) to prepend to the sequence number. "
                  "E.g. 'INV' → 'INV00001'. Total length must not exceed 10 chars."
              ),
          ),
      ] = None,
      sequence: Annotated[
          Optional[int],
          Field(
              default=None,
              ge=1,
              le=9999999,
              description=(
                  "Explicit sequence number (1–9999999). If omitted, a random 5-digit "
                  "number is generated. Callers should track their own sequence in production."
              ),
          ),
      ] = None,
  ) -> dict:
      """Generate a ProgressivoInvio identifier for the DatiTrasmissione block.
  
      Use this as step 2 in the invoice generation workflow, before
      build_transmission_header(). The SDI requires each ProgressivoInvio to be unique
      per transmitter Partita IVA — in production, pass an explicit monotonically
      increasing sequence number; use the random default only for testing.
  
      prefix (optional): alphabetic 1–3 char prefix, e.g. 'INV' → 'INV00001'.
      sequence (optional): integer 1–9999999; random 5-digit value if omitted.
      Total length must not exceed 10 characters.
  
      On success returns {'progressivo_invio': str, 'length': int}.
      On failure (invalid prefix) returns {'error': '<reason>'}.
      """
      if prefix and not re.match(r"^[A-Za-z]{1,3}$", prefix):
          return {"error": "prefix must be 1–3 alphabetic characters."}
  
      seq_num = sequence if sequence is not None else random.randint(1, 99999)
      prefix_str = prefix.upper() if prefix else ""
  
      # Pad sequence to fill remaining width up to 10 chars
      remaining = 10 - len(prefix_str)
      seq_str = str(seq_num).zfill(min(remaining, 5))
  
      progressivo = (prefix_str + seq_str)[:10]
  
      return {"progressivo_invio": progressivo, "length": len(progressivo)}

• tools/header_tools.py:431-453 (schema)

  Input parameter definitions (prefix and sequence) using Pydantic Field with validation constraints: prefix optional 1-3 alpha, sequence optional int 1-9999999.

  def generate_progressivo_invio(
      prefix: Annotated[
          Optional[str],
          Field(
              default=None,
              description=(
                  "Optional alphabetic prefix (max 3 chars) to prepend to the sequence number. "
                  "E.g. 'INV' → 'INV00001'. Total length must not exceed 10 chars."
              ),
          ),
      ] = None,
      sequence: Annotated[
          Optional[int],
          Field(
              default=None,
              ge=1,
              le=9999999,
              description=(
                  "Explicit sequence number (1–9999999). If omitted, a random 5-digit "
                  "number is generated. Callers should track their own sequence in production."
              ),
          ),
      ] = None,

• tools/header_tools.py:51-53 (registration)

  The register_header_tools function that registers all header tools on the FastMCP instance. The @mcp.tool() decorator on line 430 registers generate_progressivo_invio.

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

• server.py:83-85 (registration)

  Call to register_header_tools(mcp) in the main server entry point, which triggers registration of generate_progressivo_invio among other header tools.

  register_header_tools(mcp)
  register_body_tools(mcp)
  register_global_tools(mcp)

• tools/header_tools.py:10-16 (helper)

  Imports used by the handler: random for random sequence generation, re for prefix validation.

  import random
  import re
  from typing import Annotated, Optional
  
  from fastmcp import FastMCP
  from pydantic import Field