get_natura_codes

Instructions

Implementation Reference

• tools/body_tools.py:467-482 (handler)

  The tool handler function that returns the complete list of Natura exemption codes (N1–N7 and sub-codes) with legal references. Reads from the NATURA_CODES dictionary and returns a dict with 'codes' (list of code/description/legal_ref objects) and 'total' count.

  @mcp.tool()
  def get_natura_codes() -> dict:
      """Return the complete list of Natura exemption codes (N1–N7 and sub-codes) with legal references.
  
      Call this when add_linea_dettaglio() requires a Natura code (i.e. aliquota_iva is 0.0).
      Common codes: N1 (excluded, art. 15), N2.1 (out-of-scope, territoriality),
      N3.1 (exports), N3.2 (intra-EU supplies), N4 (VAT-exempt), N6.x (reverse charge),
      N7 (OSS/IOSS — VAT paid in another EU state).
  
      Always succeeds. Returns {'codes': [{'code', 'description', 'legal_ref'}, ...], 'total': int}.
      """
      codes = [
          {"code": code, "description": info["description"], "legal_ref": info["legal_ref"]}
          for code, info in NATURA_CODES.items()
      ]
      return {"codes": codes, "total": len(codes)}

• tools/body_tools.py:55-80 (schema)

  Static reference dictionary defining all 23 Natura exemption codes (N1–N7 with sub-codes) with descriptions and legal references. This is the data source for the get_natura_codes tool.

  NATURA_CODES: dict[str, dict] = {
      "N1": {"description": "Escluse ex art. 15", "legal_ref": "Art. 15 DPR 633/72"},
      "N2": {"description": "Non soggette", "legal_ref": "Various exclusions from VAT scope"},
      "N2.1": {"description": "Non soggette ad IVA ai sensi degli artt. da 7 a 7-septies del DPR 633/72", "legal_ref": "Art. 7–7-septies DPR 633/72 (territoriality)"},
      "N2.2": {"description": "Non soggette — altri casi", "legal_ref": "Other out-of-scope cases"},
      "N3": {"description": "Non imponibili", "legal_ref": "Zero-rated supplies"},
      "N3.1": {"description": "Non imponibili — esportazioni", "legal_ref": "Art. 8 DPR 633/72 (exports)"},
      "N3.2": {"description": "Non imponibili — cessioni intracomunitarie", "legal_ref": "Art. 41 DL 331/93 (intra-EU)"},
      "N3.3": {"description": "Non imponibili — cessioni verso San Marino", "legal_ref": "Art. 71 DPR 633/72"},
      "N3.4": {"description": "Non imponibili — operazioni assimilate alle cessioni all'esportazione", "legal_ref": "Art. 8-bis DPR 633/72"},
      "N3.5": {"description": "Non imponibili — a seguito di dichiarazioni d'intento", "legal_ref": "Habitual exporter declaration (lettera d'intento)"},
      "N3.6": {"description": "Non imponibili — altre operazioni che non concorrono alla formazione del plafond", "legal_ref": "Other zero-rated not forming VAT ceiling"},
      "N4": {"description": "Esenti", "legal_ref": "Art. 10 DPR 633/72 (VAT-exempt supplies)"},
      "N5": {"description": "Regime del margine / IVA non esposta in fattura", "legal_ref": "Art. 36 DL 41/95 (margin scheme)"},
      "N6": {"description": "Inversione contabile (reverse charge)", "legal_ref": "Various reverse charge provisions"},
      "N6.1": {"description": "Inversione contabile — cessione di rottami e altri materiali di recupero", "legal_ref": "Art. 74 c. 7-8 DPR 633/72"},
      "N6.2": {"description": "Inversione contabile — cessione di oro e argento puro", "legal_ref": "Art. 17 c. 5 DPR 633/72"},
      "N6.3": {"description": "Inversione contabile — subappalto nel settore edile", "legal_ref": "Art. 17 c. 6 lett. a DPR 633/72"},
      "N6.4": {"description": "Inversione contabile — cessione di fabbricati", "legal_ref": "Art. 17 c. 6 lett. a-bis DPR 633/72"},
      "N6.5": {"description": "Inversione contabile — cessione di telefoni cellulari", "legal_ref": "Art. 17 c. 6 lett. b DPR 633/72"},
      "N6.6": {"description": "Inversione contabile — cessione di prodotti elettronici", "legal_ref": "Art. 17 c. 6 lett. c DPR 633/72"},
      "N6.7": {"description": "Inversione contabile — prestazioni comparto edile e settori connessi", "legal_ref": "Art. 17 c. 6 lett. a-ter DPR 633/72"},
      "N6.8": {"description": "Inversione contabile — operazioni settore energetico", "legal_ref": "Art. 17 c. 6 lett. d-bis/d-ter/d-quater DPR 633/72"},
      "N6.9": {"description": "Inversione contabile — altri casi", "legal_ref": "Other reverse charge cases"},
      "N7": {"description": "IVA assolta in altro stato UE (one stop shop)", "legal_ref": "OSS / IOSS — VAT paid in another EU member state"},
  }

• tools/body_tools.py:467-484 (registration)

  The @mcp.tool() decorator registers get_natura_codes as an MCP tool. This happens inside register_body_tools() which is called from server.py line 84.

  @mcp.tool()
  def get_natura_codes() -> dict:
      """Return the complete list of Natura exemption codes (N1–N7 and sub-codes) with legal references.
  
      Call this when add_linea_dettaglio() requires a Natura code (i.e. aliquota_iva is 0.0).
      Common codes: N1 (excluded, art. 15), N2.1 (out-of-scope, territoriality),
      N3.1 (exports), N3.2 (intra-EU supplies), N4 (VAT-exempt), N6.x (reverse charge),
      N7 (OSS/IOSS — VAT paid in another EU state).
  
      Always succeeds. Returns {'codes': [{'code', 'description', 'legal_ref'}, ...], 'total': int}.
      """
      codes = [
          {"code": code, "description": info["description"], "legal_ref": info["legal_ref"]}
          for code, info in NATURA_CODES.items()
      ]
      return {"codes": codes, "total": len(codes)}
  
  @mcp.tool()

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

  The registration function that contains the @mcp.tool() decorated get_natura_codes handler. Called from server.py line 84.

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

• server.py:84-90 (helper)

  Entry point where register_body_tools is called to register all body tools including get_natura_codes on the FastMCP server instance.

  register_body_tools(mcp)
  register_global_tools(mcp)
  
  logger.info(
      "MCP server 'mcp-fattura-elettronica-it' initialised — "
      "7 Header tools + 7 Body tools + 7 Global tools = 21 tools"
  )