normattiva-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 normattiva-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.it.md

@@ -0,0 +1,116 @@
+# normattiva-mcp
+
+[English](./README.md) · **Italiano**
+
+Server [Model Context Protocol](https://modelcontextprotocol.io) leggero che espone l'API OpenData di [Normattiva](https://www.normattiva.it) — il portale ufficiale della legislazione italiana gestito da IPZS — a client LLM come Claude Desktop, Cursor e Claude Code.
+
+Wrappa gli endpoint sincroni di lettura (ricerca, dettaglio atto, atti aggiornati) e i cataloghi delle tipologiche statiche come **tools**, **resources** e **prompts** MCP.
+
+## Funzionalità
+
+### Tools
+
+| Tool | Scopo |
+| --- | --- |
+| `search_acts` | Ricerca atti normativi italiani per testo libero, titolo, denominazione atto, anno/numero, intervallo di date, classe provvedimento o data di vigenza. Restituisce i metadati di ciascun atto trovato, incluso `codice_redazionale` e `data_gu` (necessari a `read_article`). |
+| `list_articles` | Scopre i numeri degli articoli di un atto sondando in sequenza `read_article` a partire da `articolo=1`. Per default trova solo gli articoli base; con `include_suffixes: true` sonda anche `bis`/`ter`/`quater`/… per ognuno. Ogni voce porta i flag opzionali `is_preamble` e `is_abrogated` (informativi; nessun filtro lato server). Gli articoli interni a gruppi strutturati (`id_gruppo != 0`) non vengono enumerati automaticamente. |
+| `read_article` | Recupera il testo di un singolo articolo di uno specifico atto a una data di vigenza. Per default ritorna testo semplice; con `format: "html"` restituisce il markup originale (preserva i marcatori di emendamento). In modalità testo i target dei link sono inlinati come `L. 5/2003 [urn:nir:stato:legge:2003-06-05;131]` così le citazioni URN sopravvivono alla conversione. Le risposte di successo includono `found: true`; articoli inesistenti (`sotto_articolo`, `id_gruppo` errato o `articolo` fuori range) ritornano `{ found: false, reason, richiesta }` senza sollevare eccezioni — il sondaggio è exception-free. L'LLM può chiamarlo in parallelo per più articoli dello stesso atto. |
+| `read_act` | Lettura aggregata di un intero atto: enumera internamente gli articoli e ne recupera ognuno, ritornandoli in ordine fino al limite `max_chars` (default 80 000 ≈ 20k token Claude). Onora `include_suffixes` e `id_gruppo` come `list_articles`. Quando il budget è esaurito la risposta include `truncated: true`, `truncated_reason` e `articolo_successivo` per riprendere con una chiamata successiva impostando `articolo_da` a quel valore. |
+| `recent_updates` | Elenca atti normativi modificati in una finestra temporale (max 12 mesi). Utile per monitorare le modifiche legislative. |
+
+### Resources
+
+| URI | Contenuto |
+| --- | --- |
+| `normattiva://tipologiche/denominazioni` | Codici di denominazione atto (es. `PLE` → `LEGGE`, `PDL` → `DECRETO-LEGGE`). Usa il value come argomento `denominazione` di `search_acts`. |
+| `normattiva://tipologiche/classi-provvedimento` | Codici classe provvedimento: `1` = atto normativo senza aggiornamenti, `2` = aggiornato, `3` = abrogato. |
+| `normattiva://collezioni-predefinite` | Collezioni preconfezionate di atti con il numero di elementi di ciascuna. |
+| `normattiva://ricerche-predefinite` | Ricerche predefinite con i relativi filtri preimpostati. |
+
+### Prompts
+
+| Nome | Argomenti | Scopo |
+| --- | --- | --- |
+| `ricerca-articolo` | `argomento` | Cerca la normativa italiana su un argomento e legge gli articoli più rilevanti. |
+| `monitoraggio-modifiche` | `giorni` (default `7`) | Riepiloga le modifiche normative degli ultimi *N* giorni. |
+
+## Installazione e configurazione del client
+
+Una volta pubblicato, eseguilo con `npx`:
+
+```bash
+npx normattiva-mcp
+```
+
+### Claude Desktop / Claude Code
+
+Aggiungi alla configurazione del tuo client MCP (`claude_desktop_config.json` per Claude Desktop, oppure `~/.claude.json` / `.mcp.json` per Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "normattiva": {
+      "command": "npx",
+      "args": ["-y", "normattiva-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+In `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "normattiva": {
+      "command": "npx",
+      "args": ["-y", "normattiva-mcp"]
+    }
+  }
+}
+```
+
+## Configurazione
+
+Il server dialoga sempre con l'**ambiente di esercizio dell'API OpenData** di Normattiva (`https://api.normattiva.it/t/normattiva.api`). L'endpoint è hard-coded — non c'è alcuna variabile d'ambiente per sovrascriverlo. L'ambiente di test (PRE) non è supportato di proposito perché protetto da mTLS.
+
+L'API OpenData è aperta e non richiede autenticazione.
+
+## Build da sorgente
+
+Richiede Node.js ≥ 20.
+
+```bash
+git clone <repo>
+cd normattiva-mcp
+npm install
+npm run build
+node dist/index.js  # parla MCP via stdio
+```
+
+Smoke test live (chiama l'API pubblica):
+
+```bash
+node tests/smoke.mjs
+```
+
+## Note e limitazioni
+
+- **Nessun endpoint di indice articoli.** Normattiva OpenData non espone un sommario sincrono. `list_articles` è un sondaggio best-effort: chiama `read_article` per `articolo=1,2,3,…` finché smette di trovare risultati. Per default scopre solo gli **articoli base**; `include_suffixes: true` estende il sondaggio a `bis`/`ter`/`quater`/… (round-by-round, fermando ciascuna catena al primo miss) ma non può trovare sotto-articoli il cui base manca, né articoli interni a gruppi strutturati (`id_gruppo != 0`).
+- **`id_gruppo` è opaco.** Alcuni atti — tipicamente codici strutturati (codici, testi unici, leggi articolate) — restituiscono contenuto solo quando `read_article` viene chiamato con un `id_gruppo` non zero. L'API OpenData non offre alcun modo sincrono per scoprire il valore corretto. Strategia pratica: provare prima con `id_gruppo=0`; se i risultati appaiono vuoti o errati, provare interi piccoli (1, 2, 3, …) finché l'articolo non torna.
+- **Un articolo per chiamata upstream.** L'endpoint `dettaglio-atto` di Normattiva serve un articolo alla volta. `read_article` lo espone direttamente (parallelizza dal client quando leggi più articoli); `read_act` nasconde l'orchestrazione e restituisce un payload aggregato unico, limitato da `max_chars` e ripristinabile via `articolo_successivo`.
+- **Stripping dell'HTML.** Il default `format: "text"` collassa il markup HTML di Normattiva ma preserva i marcatori italiani di emendamento `(( ... ))` (inserimenti) e `[ ... ]` (cancellazioni), che hanno valore semantico. I link verso altri atti normativi sono inlinati come `<testo> [urn:nir:…]` così l'URN Akoma Ntoso sopravvive in formato testo.
+- **Versioning degli articoli non scopribile.** Ogni chiamata `read_article` ritorna la versione dell'articolo in vigore alla `data_vigenza` (default `versione=0` dell'API). L'API OpenData non espone quante versioni storiche esistano per un articolo, quindi i testi precedenti possono essere recuperati solo variando `data_vigenza` (o tentando `versione=1, 2, …`).
+- **`is_abrogated` è euristico.** Il flag riconosce il marcatore canonico `((ARTICOLO ABROGATO …))` che gli emendamenti successivi inseriscono in testa a un articolo interamente abrogato. Articoli con singoli commi abrogati ma articolo nel complesso vivo (es. `((COMMA ABROGATO …))` in alcune sottosezioni) **non** vengono segnalati.
+- **Export asincrono e ambiente PRE** (protetto da mTLS) **non** sono wrappati — il server resta leggero e sincrono.
+- **`recent_updates`** tratta `data_fine` come fine giornata inclusiva (UTC). La finestra è limitata dall'API a 12 mesi e 7000 atti; entrambi i limiti emergono come codici di errore IPZS (`1501`, `1502`).
+
+## Licenza
+
+Il codice sorgente di questo server è MIT — vedi [LICENSE](./LICENSE).
+
+I contenuti normativi recuperati tramite questo server sono pubblicati da IPZS con licenza [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Il server è un pass-through e non rilicenzia il contenuto: qualunque uso o redistribuzione a valle deve attribuire Normattiva / IPZS come fonte.
+
+Normattiva è un marchio dell'Istituto Poligrafico e Zecca dello Stato Italiano (IPZS); questo progetto non è affiliato né sponsorizzato da IPZS.

package/README.md

@@ -0,0 +1,116 @@
+# normattiva-mcp
+
+**English** · [Italiano](./README.it.md)
+
+A lightweight [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the [Normattiva](https://www.normattiva.it) OpenData API — the official Italian legislation portal run by IPZS — to LLM clients like Claude Desktop, Cursor, and Claude Code.
+
+It wraps the synchronous read endpoints (search, article detail, recent updates) and the static reference catalogs as MCP **tools**, **resources**, and **prompts**.
+
+## Capabilities
+
+### Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `search_acts` | Search Italian legislation by free text, title, act type, year/number, date range, vigenza class, or in-force date. Returns metadata for each matching atto including `codice_redazionale` and `data_gu` (which `read_article` needs). |
+| `list_articles` | Discover the article numbers of an atto by sequentially probing `read_article` from `articolo=1`. Finds base articles by default; pass `include_suffixes: true` to also probe `bis`/`ter`/`quater`/… for each one. Each entry carries optional `is_preamble` and `is_abrogated` flags (informational; nothing is filtered server-side). Articles inside structured groups (`id_gruppo != 0`) are still not enumerated automatically. |
+| `read_article` | Fetch the text of a single article of a specific atto at a given date of vigenza. Returns plain text by default; pass `format: "html"` for the original markup (preserves amendment markers). In text mode, hyperlink targets are inlined as `L. 5/2003 [urn:nir:stato:legge:2003-06-05;131]` so URN citations survive the conversion. Successful responses include `found: true`; non-existent articles (wrong `sotto_articolo`, `id_gruppo`, or out-of-range `articolo`) return `{ found: false, reason, richiesta }` instead of throwing — so probing is exception-free. The LLM can call this in parallel for several articles of the same atto. |
+| `read_act` | Aggregate-read of an entire atto: internally enumerates articles and fetches each one, returning them in order capped by `max_chars` (default 80 000 ≈ 20k Claude tokens). Honors `include_suffixes` and `id_gruppo` like `list_articles`. When the budget is exhausted the response includes `truncated: true`, `truncated_reason`, and `articolo_successivo` for resuming via a follow-up call with `articolo_da` set to that value. |
+| `recent_updates` | Lists atti normativi modified within a date window (max 12 months). Useful for monitoring legislative changes. |
+
+### Resources
+
+| URI | Contents |
+| --- | --- |
+| `normattiva://tipologiche/denominazioni` | Act-type codes (e.g. `PLE` → `LEGGE`, `PDL` → `DECRETO-LEGGE`). Use the value as the `denominazione` argument of `search_acts`. |
+| `normattiva://tipologiche/classi-provvedimento` | Vigenza class codes: `1` = senza aggiornamenti, `2` = aggiornato, `3` = abrogato. |
+| `normattiva://collezioni-predefinite` | Predefined collections of acts with their item counts. |
+| `normattiva://ricerche-predefinite` | Predefined searches with their preset filters. |
+
+### Prompts
+
+| Name | Args | Purpose |
+| --- | --- | --- |
+| `ricerca-articolo` | `argomento` | Search Italian law on a topic and read the most relevant articles. |
+| `monitoraggio-modifiche` | `giorni` (default `7`) | Summarize legislative changes in the last *N* days. |
+
+## Installation & client configuration
+
+Once published, run via `npx`:
+
+```bash
+npx normattiva-mcp
+```
+
+### Claude Desktop / Claude Code
+
+Add to your MCP client config (`claude_desktop_config.json` for Claude Desktop, or `~/.claude.json` / `.mcp.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "normattiva": {
+      "command": "npx",
+      "args": ["-y", "normattiva-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+In `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "normattiva": {
+      "command": "npx",
+      "args": ["-y", "normattiva-mcp"]
+    }
+  }
+}
+```
+
+## Configuration
+
+The server always talks to Normattiva's **production OpenData API** (`https://api.normattiva.it/t/normattiva.api`). The endpoint is hard-coded — there is no environment variable to override it. The PRE/test environment is intentionally not supported because it is mTLS-protected.
+
+The OpenData API is open and does not require authentication.
+
+## Building from source
+
+Requires Node.js ≥ 20.
+
+```bash
+git clone <repo>
+cd normattiva-mcp
+npm install
+npm run build
+node dist/index.js  # speaks MCP on stdio
+```
+
+A live smoke test (hits the public API):
+
+```bash
+node tests/smoke.mjs
+```
+
+## Notes & limitations
+
+- **No table-of-contents endpoint.** Normattiva OpenData has no synchronous TOC. `list_articles` is a best-effort probe: it calls `read_article` for `articolo=1,2,3,…` until it stops finding results. By default it discovers **base articles** only; `include_suffixes: true` extends the probe to `bis`/`ter`/`quater`/… (round-by-round, stopping each chain at the first miss) but cannot find sub-articles whose base is missing, nor articles inside structured groups (`id_gruppo != 0`).
+- **`id_gruppo` is opaque.** Some atti — typically structured codes (codici, testi unici, leggi articolate) — return content only when `read_article` is called with a non-zero `id_gruppo`. The OpenData API offers no way to discover the right value synchronously. Practical strategy: try `id_gruppo=0` first; if results look empty or wrong, try small integers (1, 2, 3, …) until the article comes back.
+- **One article per call upstream.** Normattiva's `dettaglio-atto` endpoint serves one article at a time. `read_article` exposes that directly (parallelize from the client when reading several articles); `read_act` hides the orchestration and returns a single aggregated payload, capped by `max_chars` and resumable via `articolo_successivo`.
+- **HTML stripping.** The default `format: "text"` collapses Normattiva's HTML markup but preserves the Italian-law amendment markers `(( ... ))` (insertions) and `[ ... ]` (deletions), which carry semantic meaning. Hyperlinks to other normative acts are inlined as `<text> [urn:nir:…]` so the Akoma Ntoso URN survives in plain text.
+- **Article versioning is non-discoverable.** Each `read_article` call returns the version of the article in force on `data_vigenza` (the API's `versione=0` default). The OpenData API does not expose how many historical versions exist for an article, so previous texts can only be retrieved by varying `data_vigenza` (or by guessing `versione=1, 2, …`).
+- **`is_abrogated` is heuristic.** The flag matches the canonical `((ARTICOLO ABROGATO …))` marker that successive amendments insert at the head of a wholly-abrogated article. Articles where individual commi are abrogated but the article itself is alive (e.g. `((COMMA ABROGATO …))` in a few subsections) are **not** flagged.
+- **Async export and PRE environment** (mTLS-protected) are **not** wrapped — this server stays light and synchronous.
+- **`recent_updates`** treats `data_fine` as inclusive end-of-day (UTC). The window is capped at 12 months and 7000 atti by the API; both limits surface as IPZS error codes (`1501`, `1502`).
+
+## License
+
+This server's source code is MIT — see [LICENSE](./LICENSE).
+
+Legislative content retrieved through this server is published by IPZS under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The server is a pass-through and does not relicense the content: any downstream use or redistribution must attribute Normattiva / IPZS as the source.
+
+Normattiva is a trademark of the Istituto Poligrafico e Zecca dello Stato Italiano (IPZS); this project is not affiliated with or endorsed by IPZS.

package/dist/api.d.ts

@@ -0,0 +1,9 @@
+import type { RicercaAvanzataBody, RicercaResponse, DettaglioAttoBody, DettaglioAttoResponse, AggiornatiBody, DenominazioneItem, ClasseItem, CollezioneItem, RicerchePredefiniteResponse } from "./types.js";
+export declare const BASE_URL = "https://api.normattiva.it/t/normattiva.api";
+export declare function ricercaAvanzata(body: RicercaAvanzataBody): Promise<RicercaResponse>;
+export declare function dettaglioAtto(body: DettaglioAttoBody): Promise<DettaglioAttoResponse>;
+export declare function ricercaAggiornati(body: AggiornatiBody): Promise<RicercaResponse>;
+export declare const getDenominazioni: () => Promise<DenominazioneItem[]>;
+export declare const getClassiProvvedimento: () => Promise<ClasseItem[]>;
+export declare const getCollezioniPredefinite: () => Promise<CollezioneItem[]>;
+export declare const getRicerchePredefinite: () => Promise<RicerchePredefiniteResponse>;

package/dist/api.js

@@ -0,0 +1,92 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+// Hard-coded to the production OpenData environment. The PRE environment
+// requires mTLS and is intentionally unsupported here.
+export const BASE_URL = "https://api.normattiva.it/t/normattiva.api";
+const COMMON_HEADERS = {
+    Accept: "application/json, text/plain, */*",
+    "Accept-Language": "it-IT,it;q=0.9,en-US;q=0.8,en;q=0.7",
+    Origin: "https://dati.normattiva.it",
+    "User-Agent": "normattiva-mcp/0.1.0 (+https://www.npmjs.com/package/normattiva-mcp)",
+};
+const REQUEST_TIMEOUT_MS = 20_000;
+async function request(path, init) {
+    const url = BASE_URL + path;
+    let res;
+    try {
+        res = await fetch(url, {
+            ...init,
+            signal: init?.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: { ...COMMON_HEADERS, ...init?.headers },
+        });
+    }
+    catch (err) {
+        throw new McpError(ErrorCode.InternalError, `Network error contacting Normattiva: ${err.message}`);
+    }
+    if (!res.ok) {
+        let detail = "";
+        let apiCode;
+        try {
+            const body = (await res.json());
+            apiCode = body.code;
+            detail = body.message ?? body.description ?? body.error ?? JSON.stringify(body);
+        }
+        catch {
+            detail = await res.text().catch(() => "");
+        }
+        // IPZS-specific 4xx codes (per spec §1.3.x): 1003 invalid export format,
+        // 1005/1006 invalid input/vigenza, 1200 resource missing, 1204 token unknown,
+        // 1501 window > 12 months, 1502 > 7000 atti, 1503 inverted date range.
+        const isClientError = res.status === 400 ||
+            res.status === 404 ||
+            res.status === 422 ||
+            (apiCode !== undefined && /^1[0-9]{3}$/.test(apiCode));
+        const mcpCode = isClientError ? ErrorCode.InvalidRequest : ErrorCode.InternalError;
+        const codeTag = apiCode ? ` [code=${apiCode}]` : "";
+        throw new McpError(mcpCode, `Normattiva API ${res.status}${codeTag}: ${detail || res.statusText}`);
+    }
+    return (await res.json());
+}
+function postJson(path, body) {
+    return request(path, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+export function ricercaAvanzata(body) {
+    return postJson("/bff-opendata/v1/api/v1/ricerca/avanzata", body);
+}
+export async function dettaglioAtto(body) {
+    try {
+        return await postJson("/bff-opendata/v1/api/v1/atto/dettaglio-atto", body);
+    }
+    catch (err) {
+        // Soft-fail "not found" responses so callers can probe sotto_articolo / id_gruppo
+        // without try/catch: real bad-input or server errors still surface as exceptions.
+        if (err instanceof McpError &&
+            err.code === ErrorCode.InvalidRequest &&
+            /non\s+trovat[oa]/i.test(err.message)) {
+            return { success: false, message: err.message };
+        }
+        throw err;
+    }
+}
+export function ricercaAggiornati(body) {
+    return postJson("/bff-opendata/v1/api/v1/ricerca/aggiornati", body);
+}
+function memoize(fn) {
+    let cache;
+    return () => {
+        if (!cache) {
+            cache = fn().catch((err) => {
+                cache = undefined;
+                throw err;
+            });
+        }
+        return cache;
+    };
+}
+export const getDenominazioni = memoize(() => request("/bff-opendata/v1/api/v1/tipologiche/denominazione-atto"));
+export const getClassiProvvedimento = memoize(() => request("/bff-opendata/v1/api/v1/tipologiche/classe-provvedimento"));
+export const getCollezioniPredefinite = memoize(() => request("/bff-opendata/v1/api/v1/collections/collection-predefinite"));
+export const getRicerchePredefinite = memoize(() => request("/bff-opendata/v1/api/v1/ricerca/predefinita"));

package/dist/html.d.ts

@@ -0,0 +1 @@
+export declare function htmlToText(html: string): string;

package/dist/html.js

@@ -0,0 +1,81 @@
+const NAMED_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+    laquo: "«",
+    raquo: "»",
+    lsquo: "‘",
+    rsquo: "’",
+    ldquo: "“",
+    rdquo: "”",
+    hellip: "…",
+    ndash: "–",
+    mdash: "—",
+    bull: "•",
+    middot: "·",
+    euro: "€",
+    copy: "©",
+    reg: "®",
+    trade: "™",
+    agrave: "à",
+    egrave: "è",
+    eacute: "é",
+    igrave: "ì",
+    ograve: "ò",
+    ugrave: "ù",
+    Agrave: "À",
+    Egrave: "È",
+    Eacute: "É",
+    Igrave: "Ì",
+    Ograve: "Ò",
+    Ugrave: "Ù",
+    sect: "§",
+    para: "¶",
+    deg: "°",
+};
+function decodeEntity(entity) {
+    // Numeric: &#1234; or &#xAB;
+    const numeric = /^&#(x?)([0-9a-f]+);$/i.exec(entity);
+    if (numeric && numeric[2]) {
+        const code = parseInt(numeric[2], numeric[1] ? 16 : 10);
+        if (Number.isFinite(code) && code > 0 && code <= 0x10ffff) {
+            try {
+                return String.fromCodePoint(code);
+            }
+            catch {
+                return entity;
+            }
+        }
+        return entity;
+    }
+    // Named: &name;
+    const named = /^&([a-z]+);$/i.exec(entity);
+    if (named && named[1]) {
+        return NAMED_ENTITIES[named[1]] ?? entity;
+    }
+    return entity;
+}
+export function htmlToText(html) {
+    return html
+        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+        .replace(/<a\b[^>]*?\bhref=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, inner) => {
+        // Normattiva citations carry an Akoma-Ntoso URN (urn:nir:...) inside the
+        // href. Preserve it as an inline annotation so plain-text consumers can
+        // still resolve cross-references; for non-URN links keep just the text.
+        const urn = /urn:[a-z]+(?::[^\s"'&<>]+)+/i.exec(href);
+        return urn ? `${inner} [${urn[0]}]` : inner;
+    })
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<\/(p|div|h[1-6]|li|tr|article|section)>/gi, "\n")
+        .replace(/<div\b/gi, "\n<div")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&(?:#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, decodeEntity)
+        .replace(/[ \t]+/g, " ")
+        .replace(/\n[ \t]+/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+async function main() {
+    const server = new McpServer({
+        name: "normattiva-mcp",
+        version: "0.1.0",
+    });
+    registerTools(server);
+    registerResources(server);
+    registerPrompts(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("[normattiva-mcp] fatal:", err);
+    process.exit(1);
+});

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.registerPrompt("ricerca-articolo", {
+        title: "Cerca un articolo per argomento",
+        description: "Cerca atti normativi italiani su un argomento e legge gli articoli più rilevanti.",
+        argsSchema: {
+            argomento: z.string().describe("Argomento di interesse, es. 'protezione dei dati personali'."),
+        },
+    }, ({ argomento }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Voglio capire la normativa italiana su: ${argomento}.\n\n` +
+                        `Procedi così:\n` +
+                        `1. Usa lo strumento search_acts per individuare gli atti normativi più rilevanti sull'argomento.\n` +
+                        `2. Identifica l'atto (o gli atti) più pertinenti dai risultati.\n` +
+                        `3. Usa read_article per leggere gli articoli più probabilmente rilevanti — fino a circa 10 articoli, scelti in base ai titoli/descrizioni.\n` +
+                        `4. Fornisci una sintesi chiara con i riferimenti normativi (atto, articolo) per ogni punto.`,
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("monitoraggio-modifiche", {
+        title: "Monitora modifiche normative recenti",
+        description: "Recupera gli atti normativi italiani modificati negli ultimi N giorni e ne fornisce un riepilogo.",
+        argsSchema: {
+            giorni: z
+                .string()
+                .regex(/^\d+$/, "Numero di giorni come stringa intera")
+                .default("7")
+                .describe("Quanti giorni indietro guardare (default 7)."),
+        },
+    }, ({ giorni }) => {
+        const n = Number.parseInt(giorni ?? "7", 10);
+        const oggi = new Date();
+        const inizio = new Date(oggi.getTime() - n * 24 * 60 * 60 * 1000);
+        const fmt = (d) => d.toISOString().slice(0, 10);
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Recupera con recent_updates gli atti normativi italiani modificati ` +
+                            `tra il ${fmt(inizio)} e il ${fmt(oggi)}. ` +
+                            `Raggruppa i risultati per tipologia di atto e fornisci un riepilogo ` +
+                            `delle modifiche più rilevanti, evidenziando gli atti modificanti principali.`,
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,34 @@
+import { getDenominazioni, getClassiProvvedimento, getCollezioniPredefinite, getRicerchePredefinite, } from "./api.js";
+function jsonResource(uri, data) {
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function registerResources(server) {
+    server.registerResource("denominazioni", "normattiva://tipologiche/denominazioni", {
+        title: "Codici denominazione atto",
+        description: "List of valid act-type codes accepted by Normattiva (label = code, value = full Italian description). Use the value (e.g. 'LEGGE') for the denominazione parameter of search_acts.",
+        mimeType: "application/json",
+    }, async (uri) => jsonResource(uri, await getDenominazioni()));
+    server.registerResource("classi-provvedimento", "normattiva://tipologiche/classi-provvedimento", {
+        title: "Classi di provvedimento (vigenza)",
+        description: "Vigenza class codes: 1 = atto senza aggiornamenti, 2 = aggiornato, 3 = abrogato. Use the label as the classe parameter of search_acts.",
+        mimeType: "application/json",
+    }, async (uri) => jsonResource(uri, await getClassiProvvedimento()));
+    server.registerResource("collezioni-predefinite", "normattiva://collezioni-predefinite", {
+        title: "Collezioni preconfezionate Normattiva",
+        description: "Predefined collections of acts available on Normattiva, with the number of acts in each.",
+        mimeType: "application/json",
+    }, async (uri) => jsonResource(uri, await getCollezioniPredefinite()));
+    server.registerResource("ricerche-predefinite", "normattiva://ricerche-predefinite", {
+        title: "Ricerche predefinite Normattiva",
+        description: "Predefined searches with their preset filters (date ranges, classe, etc.).",
+        mimeType: "application/json",
+    }, async (uri) => jsonResource(uri, await getRicerchePredefinite()));
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTools(server: McpServer): void;

package/dist/tools.js

@@ -0,0 +1,584 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { ricercaAvanzata, dettaglioAtto, ricercaAggiornati, } from "./api.js";
+import { htmlToText } from "./html.js";
+const dateString = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Use ISO date YYYY-MM-DD");
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+function jsonContent(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function registerTools(server) {
+    server.registerTool("search_acts", {
+        title: "Search Italian legislation (Normattiva)",
+        description: "Search Italian legislation on Normattiva by free text, title, act type, year/number, date range, or vigenza class. Returns metadata for each matching atto including codice_redazionale and data_gu, which are required to fetch article text via read_article. The denominazione parameter expects an Italian act-type label like 'LEGGE' or 'DECRETO LEGISLATIVO' — see resource normattiva://tipologiche/denominazioni for the full list.",
+        inputSchema: {
+            testo: z.string().optional().describe("Keywords searched in the act body."),
+            titolo: z.string().optional().describe("Keywords searched in the act title."),
+            denominazione: z
+                .string()
+                .optional()
+                .describe("Italian act-type label, e.g. 'LEGGE', 'DECRETO LEGISLATIVO', 'DECRETO DEL PRESIDENTE DELLA REPUBBLICA'."),
+            anno: z.number().int().optional().describe("Year of the provvedimento."),
+            numero: z.string().optional().describe("Number of the provvedimento."),
+            mese: z.number().int().min(1).max(12).optional(),
+            giorno: z.number().int().min(1).max(31).optional(),
+            data_emanazione_da: dateString.optional(),
+            data_emanazione_a: dateString.optional(),
+            data_pubblicazione_da: dateString.optional(),
+            data_pubblicazione_a: dateString.optional(),
+            classe: z
+                .enum(["1", "2", "3"])
+                .optional()
+                .describe("Vigenza class: 1=senza aggiornamenti (single-version atto), 2=aggiornato, 3=abrogato."),
+            codice_tipo: z
+                .string()
+                .optional()
+                .describe("Faceted filter: act-type code (e.g. 'PLE' for LEGGE)."),
+            data_vigenza: dateString
+                .optional()
+                .describe("Restrict results to atti in force on this date (YYYY-MM-DD). Maps to the spec's 'vigenza' field."),
+            page: z.number().int().min(1).default(1),
+            per_page: z.number().int().min(1).max(50).default(5),
+            order: z.enum(["recente", "vecchio"]).default("recente"),
+        },
+    }, async (args) => {
+        const body = {
+            orderType: args.order,
+            paginazione: {
+                paginaCorrente: args.page,
+                numeroElementiPerPagina: args.per_page,
+            },
+        };
+        if (args.testo)
+            body.testoRicerca = args.testo;
+        if (args.titolo)
+            body.titoloRicerca = args.titolo;
+        if (args.denominazione)
+            body.denominazioneAtto = args.denominazione;
+        if (args.anno !== undefined)
+            body.annoProvvedimento = String(args.anno);
+        if (args.numero)
+            body.numeroProvvedimento = args.numero;
+        if (args.mese !== undefined)
+            body.meseProvvedimento = String(args.mese);
+        if (args.giorno !== undefined)
+            body.giornoProvvedimento = String(args.giorno);
+        if (args.data_emanazione_da)
+            body.dataInizioEmanazione = args.data_emanazione_da;
+        if (args.data_emanazione_a)
+            body.dataFineEmanazione = args.data_emanazione_a;
+        if (args.data_pubblicazione_da)
+            body.dataInizioPubProvvedimento = args.data_pubblicazione_da;
+        if (args.data_pubblicazione_a)
+            body.dataFinePubProvvedimento = args.data_pubblicazione_a;
+        if (args.classe)
+            body.classeProvvedimento = args.classe;
+        if (args.data_vigenza)
+            body.vigenza = args.data_vigenza;
+        if (args.codice_tipo)
+            body.filtriMap = { codice_tipo_provvedimento: args.codice_tipo };
+        const data = await ricercaAvanzata(body);
+        return jsonContent({
+            totale_atti: data.numeroAttiTrovati ?? 0,
+            pagine_totali: data.numeroPagine ?? 0,
+            pagina_corrente: data.paginaCorrente ?? args.page,
+            atti: (data.listaAtti ?? []).map((a) => ({
+                anno: a.annoProvvedimento,
+                numero: a.numeroProvvedimento,
+                denominazione: a.denominazioneAtto,
+                descrizione: a.descrizioneAtto,
+                titolo: a.titoloAtto,
+                codice_redazionale: a.codiceRedazionale,
+                data_gu: a.dataGU,
+                data_emanazione: a.dataEmanazione,
+                data_pubblicazione: a.dataPubblicazione,
+                classe: a.classeProvvedimento,
+            })),
+        });
+    });
+    server.registerTool("read_article", {
+        title: "Read one article of an Italian act",
+        description: "Fetches the text of a single article of a specific atto, at a given date of vigenza. Prefer calling search_acts first to obtain codice_redazionale and data_gu, then list_articles to discover which article numbers exist, and finally read_article on the relevant ones (you may call it in parallel for multiple articles of the same atto). Returns plain text by default; pass format='html' for the original markup (which preserves amendment markers). The text format inlines URN citations as 'L. 5/2003 [urn:nir:stato:legge:2003-06-05;131]'. When the article does not exist (wrong sotto_articolo, id_gruppo or articolo number) the tool returns {found:false, reason, ...} instead of throwing — successful responses include {found:true}. Note: 'bis'/'ter' suffixes require sotto_articolo (1=base, 2=bis, 3=ter, ...), and some atti (e.g. structured codes) require a non-zero id_gruppo whose value is not synchronously discoverable.",
+        inputSchema: {
+            data_gu: dateString.describe("Publication date in Gazzetta Ufficiale (from search_acts)."),
+            codice_redazionale: z.string().describe("Editorial code of the atto (from search_acts)."),
+            articolo: z.number().int().describe("Article number."),
+            sotto_articolo: z
+                .number()
+                .int()
+                .min(1)
+                .default(1)
+                .describe("Article suffix index. 1 = base article (e.g. 'art. 13'), 2 = bis, 3 = ter, 4 = quater, ..."),
+            sotto_articolo_1: z.number().int().default(0),
+            data_vigenza: dateString
+                .default(todayIso)
+                .describe("Date at which to read the article (defaults to today)."),
+            id_gruppo: z.number().int().default(0),
+            progressivo: z.number().int().default(0),
+            versione: z
+                .number()
+                .int()
+                .default(0)
+                .describe("Version selector. 0 (default) is the standard choice and pairs with data_vigenza to return the in-force text on that date."),
+            format: z.enum(["text", "html"]).default("text"),
+        },
+    }, async (args) => {
+        const data = await dettaglioAtto({
+            dataGU: args.data_gu,
+            codiceRedazionale: args.codice_redazionale,
+            idArticolo: args.articolo,
+            sottoArticolo: args.sotto_articolo,
+            sottoArticolo1: args.sotto_articolo_1,
+            dataVigenza: args.data_vigenza,
+            idGruppo: args.id_gruppo,
+            progressivo: args.progressivo,
+            versione: args.versione,
+        });
+        if (!data.success || !data.data?.atto) {
+            return jsonContent({
+                found: false,
+                reason: "no-such-article",
+                message: data.message ?? null,
+                richiesta: {
+                    articolo: args.articolo,
+                    sotto_articolo: args.sotto_articolo,
+                    codice_redazionale: args.codice_redazionale,
+                    data_gu: args.data_gu,
+                    data_vigenza: args.data_vigenza,
+                    id_gruppo: args.id_gruppo,
+                },
+            });
+        }
+        const atto = data.data.atto;
+        const html = atto.articoloHtml ?? "";
+        const articolo_testo = args.format === "html" ? html : htmlToText(html);
+        return jsonContent({
+            found: true,
+            titolo: atto.titolo,
+            tipo: atto.tipoProvvedimentoDescrizione,
+            codice_tipo: atto.tipoProvvedimentoCodice,
+            format: args.format,
+            articolo: articolo_testo,
+            data_inizio_vigenza: atto.articoloDataInizioVigenza,
+            data_fine_vigenza: atto.articoloDataFineVigenza,
+        });
+    });
+    server.registerTool("list_articles", {
+        title: "List articles of an Italian act (sequential probe)",
+        description: "Discovers which articles exist in an atto by probing dettaglio-atto sequentially from articolo=1. Normattiva OpenData has no synchronous table-of-contents endpoint, so this is a best-effort enumeration. By default only base articles (sotto_articolo=1) are discovered; pass include_suffixes=true to also probe bis/ter/quater/... for each base article (extra round-trips, stops at the first miss per article). Articles inside structured groups (id_gruppo!=0) are not discovered automatically. Each probe is a real API call. The base probe stops early once a full chunk yields no results after at least one article has been found. Use this before read_article when you need to know the article range.",
+        inputSchema: {
+            data_gu: dateString.describe("Publication date in Gazzetta Ufficiale (from search_acts)."),
+            codice_redazionale: z.string().describe("Editorial code of the atto (from search_acts)."),
+            data_vigenza: dateString
+                .default(todayIso)
+                .describe("Date at which to test article existence (defaults to today)."),
+            max_articoli: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(30)
+                .describe("Hard cap on the highest article number to probe."),
+            id_gruppo: z
+                .number()
+                .int()
+                .default(0)
+                .describe("Article-group id (default 0). Non-zero values target a specific group inside a structured atto."),
+            include_suffixes: z
+                .boolean()
+                .default(false)
+                .describe("If true, after finding base articles also probe sotto_articolo=2,3,... for each one until the first miss, discovering bis/ter/quater/... Adds 1-N extra calls per base article."),
+        },
+    }, async (args) => {
+        const CHUNK = 5;
+        // Whole-article abrogation marker: '((ARTICOLO ABROGATO ...))' inserted by
+        // a successive amendment. Distinct from '((COMMA ABROGATO ...))' which only
+        // tags individual commi inside an otherwise-live article.
+        const ABROGATED_RE = /\(\(\s*ARTICOLO\s+ABROGATO/i;
+        const SUFFIX_LABELS = [
+            "base",
+            "bis",
+            "ter",
+            "quater",
+            "quinquies",
+            "sexies",
+            "septies",
+            "octies",
+            "novies",
+            "decies",
+        ];
+        const MAX_SUFFIX_INDEX = SUFFIX_LABELS.length;
+        const found = [];
+        let probedUpTo = 0;
+        let stoppedEarly = false;
+        for (let start = 1; start <= args.max_articoli; start += CHUNK) {
+            const end = Math.min(start + CHUNK - 1, args.max_articoli);
+            const batch = await Promise.all(Array.from({ length: end - start + 1 }, (_, i) => start + i).map(async (n) => {
+                try {
+                    const data = await dettaglioAtto({
+                        dataGU: args.data_gu,
+                        codiceRedazionale: args.codice_redazionale,
+                        idArticolo: n,
+                        sottoArticolo: 1,
+                        sottoArticolo1: 0,
+                        dataVigenza: args.data_vigenza,
+                        idGruppo: args.id_gruppo,
+                        progressivo: 0,
+                        versione: 0,
+                    });
+                    if (!data.success || !data.data?.atto?.articoloHtml) {
+                        return { articolo: n, ok: false };
+                    }
+                    const html = data.data.atto.articoloHtml;
+                    // Detect the canonical "Art. N" header. Atti often expose the
+                    // promulgation preamble at idArticolo=1 with no article header.
+                    const isArticle = /<h2[^>]*class="[^"]*article-num-akn[^"]*"[^>]*>\s*Art\.\s/i.test(html);
+                    const text = htmlToText(html);
+                    const preview = text
+                        .split("\n")
+                        .map((l) => l.trim())
+                        .filter((l) => l.length > 0)
+                        .slice(0, 4)
+                        .join(" — ")
+                        .slice(0, 200);
+                    return {
+                        articolo: n,
+                        ok: true,
+                        titolo: preview,
+                        is_preamble: !isArticle,
+                        is_abrogated: ABROGATED_RE.test(text),
+                    };
+                }
+                catch (err) {
+                    // Treat "article not found" (client-error) as a miss; let
+                    // network/5xx errors surface so the caller sees the failure
+                    // instead of getting a silently truncated list.
+                    if (err instanceof McpError && err.code === ErrorCode.InvalidRequest) {
+                        return { articolo: n, ok: false };
+                    }
+                    throw err;
+                }
+            }));
+            probedUpTo = end;
+            const hits = batch.filter((b) => b.ok);
+            for (const h of hits) {
+                if (h.ok) {
+                    const entry = {
+                        articolo: h.articolo,
+                        titolo: h.titolo,
+                    };
+                    if (h.is_preamble)
+                        entry.is_preamble = true;
+                    if (h.is_abrogated)
+                        entry.is_abrogated = true;
+                    found.push(entry);
+                }
+            }
+            if (hits.length === 0 && found.length > 0) {
+                stoppedEarly = true;
+                break;
+            }
+        }
+        const suffixHits = [];
+        if (args.include_suffixes && found.length > 0) {
+            // Round-by-round probing: at sa=2 probe every base article, then at sa=3
+            // only those that hit at sa=2, etc. Stops at the first miss per article,
+            // which matches how bis/ter/quater are densely numbered in practice.
+            let live = found
+                .filter((f) => !f.is_preamble)
+                .map((f) => f.articolo);
+            for (let sa = 2; sa <= MAX_SUFFIX_INDEX && live.length > 0; sa++) {
+                const round = await Promise.all(live.map(async (n) => {
+                    try {
+                        const data = await dettaglioAtto({
+                            dataGU: args.data_gu,
+                            codiceRedazionale: args.codice_redazionale,
+                            idArticolo: n,
+                            sottoArticolo: sa,
+                            sottoArticolo1: 0,
+                            dataVigenza: args.data_vigenza,
+                            idGruppo: args.id_gruppo,
+                            progressivo: 0,
+                            versione: 0,
+                        });
+                        if (!data.success || !data.data?.atto?.articoloHtml) {
+                            return { articolo: n, hit: false };
+                        }
+                        const text = htmlToText(data.data.atto.articoloHtml);
+                        const preview = text
+                            .split("\n")
+                            .map((l) => l.trim())
+                            .filter((l) => l.length > 0)
+                            .slice(0, 4)
+                            .join(" — ")
+                            .slice(0, 200);
+                        return {
+                            articolo: n,
+                            hit: true,
+                            titolo: preview,
+                            is_abrogated: ABROGATED_RE.test(text),
+                        };
+                    }
+                    catch (err) {
+                        if (err instanceof McpError && err.code === ErrorCode.InvalidRequest) {
+                            return { articolo: n, hit: false };
+                        }
+                        throw err;
+                    }
+                }));
+                const nextLive = [];
+                for (const r of round) {
+                    if (r.hit) {
+                        const sx = {
+                            articolo: r.articolo,
+                            sotto_articolo: sa,
+                            suffisso: SUFFIX_LABELS[sa - 1] ?? `sotto_articolo_${sa}`,
+                            titolo: r.titolo,
+                        };
+                        if (r.is_abrogated)
+                            sx.is_abrogated = true;
+                        suffixHits.push(sx);
+                        nextLive.push(r.articolo);
+                    }
+                }
+                live = nextLive;
+            }
+        }
+        const articoli = [];
+        for (const base of found) {
+            articoli.push(base);
+            const itsSuffixes = suffixHits
+                .filter((s) => s.articolo === base.articolo)
+                .sort((a, b) => (a.sotto_articolo ?? 0) - (b.sotto_articolo ?? 0));
+            for (const sx of itsSuffixes)
+                articoli.push(sx);
+        }
+        return jsonContent({
+            codice_redazionale: args.codice_redazionale,
+            data_gu: args.data_gu,
+            data_vigenza: args.data_vigenza,
+            id_gruppo: args.id_gruppo,
+            probed_up_to: probedUpTo,
+            stopped_early: stoppedEarly,
+            truncated: !stoppedEarly && probedUpTo === args.max_articoli,
+            include_suffixes: args.include_suffixes,
+            articoli_trovati: articoli.length,
+            articoli,
+        });
+    });
+    server.registerTool("recent_updates", {
+        title: "Atti recently modified on Normattiva",
+        description: "Lists Italian normative acts whose text was modified within a date window. Useful for monitoring legislative changes. The window must be at most 12 months wide and data_fine cannot precede data_inizio.",
+        inputSchema: {
+            data_inizio: dateString.describe("Start of the modification window (YYYY-MM-DD)."),
+            data_fine: dateString.describe("End of the modification window (YYYY-MM-DD), max 12 months after data_inizio."),
+        },
+    }, async ({ data_inizio, data_fine }) => {
+        const data = await ricercaAggiornati({
+            dataInizioAggiornamento: `${data_inizio}T00:00:00.000Z`,
+            dataFineAggiornamento: `${data_fine}T23:59:59.999Z`,
+        });
+        return jsonContent({
+            numero_atti: data.numeroAttiTrovati ?? 0,
+            atti: (data.listaAtti ?? []).map((a) => ({
+                descrizione: a.descrizioneAtto,
+                titolo: a.titoloAtto,
+                codice_redazionale: a.codiceRedazionale,
+                data_gu: a.dataGU,
+                data_ultima_modifica: a.dataUltimaModifica,
+                ultimi_atti_modificanti: a.ultimiAttiModificanti
+                    ? a.ultimiAttiModificanti.trim().split(/\s+/)
+                    : [],
+            })),
+        });
+    });
+    server.registerTool("read_act", {
+        title: "Read an entire Italian act in one call",
+        description: "Fetches every article of an atto sequentially and returns them aggregated, capped by max_chars (default 80000 ≈ 20k Claude tokens). Useful when you want the whole law text without orchestrating list_articles + N parallel read_article calls. Probes from articolo_da onward, includes bis/ter when include_suffixes=true, and stops at the first empty chunk or when adding the next unit would exceed max_chars. Truncation is reported via {truncated, truncated_reason, articolo_successivo} so the caller can resume by re-invoking with articolo_da set to that value. Each article entry mirrors read_article output (testo + vigenza dates + is_abrogated flag).",
+        inputSchema: {
+            data_gu: dateString.describe("Publication date in Gazzetta Ufficiale (from search_acts)."),
+            codice_redazionale: z.string().describe("Editorial code of the atto (from search_acts)."),
+            data_vigenza: dateString
+                .default(todayIso)
+                .describe("Date at which to read the atto (defaults to today)."),
+            format: z.enum(["text", "html"]).default("text"),
+            max_chars: z
+                .number()
+                .int()
+                .min(1000)
+                .max(500_000)
+                .default(80_000)
+                .describe("Soft cap on the total number of characters across all aggregated articles. Checked before adding each unit. Default ≈ 20k Claude tokens."),
+            max_articoli: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .default(50)
+                .describe("Hard cap on how many base article numbers to probe past articolo_da."),
+            articolo_da: z
+                .number()
+                .int()
+                .min(1)
+                .default(1)
+                .describe("Starting article number. Set to articolo_successivo from a previous truncated response to resume."),
+            include_suffixes: z
+                .boolean()
+                .default(false)
+                .describe("If true, after each base article also fetch its bis/ter/quater/... chain. Each suffix counts against max_chars. If the budget runs out mid-chain, the remaining suffixes of that article are skipped — fetch them with read_article if needed."),
+            id_gruppo: z
+                .number()
+                .int()
+                .default(0)
+                .describe("Article-group id. Non-zero values target a specific group inside a structured atto."),
+        },
+    }, async (args) => {
+        const CHUNK = 5;
+        const SUFFIX_LABELS = [
+            "base",
+            "bis",
+            "ter",
+            "quater",
+            "quinquies",
+            "sexies",
+            "septies",
+            "octies",
+            "novies",
+            "decies",
+        ];
+        const ABROGATED_RE = /\(\(\s*ARTICOLO\s+ABROGATO/i;
+        const articoli = [];
+        let totalChars = 0;
+        let attoTitolo;
+        let attoTipo;
+        let attoCodiceTipo;
+        let probedUpTo = args.articolo_da - 1;
+        let stoppedEarly = false;
+        let truncatedReason = null;
+        let articoloSuccessivo = null;
+        const fetchUnit = async (n, sa) => {
+            try {
+                const data = await dettaglioAtto({
+                    dataGU: args.data_gu,
+                    codiceRedazionale: args.codice_redazionale,
+                    idArticolo: n,
+                    sottoArticolo: sa,
+                    sottoArticolo1: 0,
+                    dataVigenza: args.data_vigenza,
+                    idGruppo: args.id_gruppo,
+                    progressivo: 0,
+                    versione: 0,
+                });
+                if (!data.success || !data.data?.atto?.articoloHtml)
+                    return null;
+                const atto = data.data.atto;
+                const html = atto.articoloHtml;
+                // Narrow for TS: the guard above already excluded undefined.
+                if (typeof html !== "string")
+                    return null;
+                attoTitolo ??= atto.titolo;
+                attoTipo ??= atto.tipoProvvedimentoDescrizione;
+                attoCodiceTipo ??= atto.tipoProvvedimentoCodice;
+                const isArticle = /<h2[^>]*class="[^"]*article-num-akn[^"]*"[^>]*>\s*Art\.\s/i.test(html);
+                const testo = args.format === "html" ? html : htmlToText(html);
+                return {
+                    testo,
+                    isArticle,
+                    // The '((ARTICOLO ABROGATO' marker is plain text in both formats —
+                    // test on the raw HTML to avoid an extra conversion when format=html.
+                    isAbrogated: ABROGATED_RE.test(html),
+                    atto,
+                };
+            }
+            catch (err) {
+                if (err instanceof McpError && err.code === ErrorCode.InvalidRequest)
+                    return null;
+                throw err;
+            }
+        };
+        const upperBound = args.articolo_da + args.max_articoli - 1;
+        outer: for (let start = args.articolo_da; start <= upperBound; start += CHUNK) {
+            const end = Math.min(start + CHUNK - 1, upperBound);
+            const numbers = Array.from({ length: end - start + 1 }, (_, i) => start + i);
+            const baseResults = await Promise.all(numbers.map((n) => fetchUnit(n, 1).then((r) => ({ n, r }))));
+            probedUpTo = end;
+            const hits = baseResults.filter((x) => x.r !== null);
+            if (hits.length === 0 && articoli.length > 0) {
+                stoppedEarly = true;
+                break;
+            }
+            for (const { n, r } of baseResults) {
+                if (!r)
+                    continue;
+                if (totalChars + r.testo.length > args.max_chars && articoli.length > 0) {
+                    truncatedReason = "max_chars";
+                    articoloSuccessivo = n;
+                    break outer;
+                }
+                const entry = {
+                    articolo: n,
+                    testo: r.testo,
+                    data_inizio_vigenza: r.atto.articoloDataInizioVigenza,
+                    data_fine_vigenza: r.atto.articoloDataFineVigenza,
+                };
+                if (!r.isArticle)
+                    entry.is_preamble = true;
+                if (r.isAbrogated)
+                    entry.is_abrogated = true;
+                articoli.push(entry);
+                totalChars += r.testo.length;
+                if (args.include_suffixes && r.isArticle) {
+                    for (let sa = 2; sa < SUFFIX_LABELS.length; sa++) {
+                        const sx = await fetchUnit(n, sa);
+                        if (!sx)
+                            break;
+                        if (totalChars + sx.testo.length > args.max_chars) {
+                            truncatedReason = "max_chars";
+                            articoloSuccessivo = n + 1;
+                            entry.suffixes_truncated = true;
+                            break outer;
+                        }
+                        const sxEntry = {
+                            articolo: n,
+                            sotto_articolo: sa,
+                            suffisso: SUFFIX_LABELS[sa - 1] ?? `sotto_articolo_${sa}`,
+                            testo: sx.testo,
+                            data_inizio_vigenza: sx.atto.articoloDataInizioVigenza,
+                            data_fine_vigenza: sx.atto.articoloDataFineVigenza,
+                        };
+                        if (sx.isAbrogated)
+                            sxEntry.is_abrogated = true;
+                        articoli.push(sxEntry);
+                        totalChars += sx.testo.length;
+                    }
+                }
+            }
+        }
+        const exhaustedRange = truncatedReason === null && probedUpTo >= upperBound && !stoppedEarly;
+        return jsonContent({
+            titolo: attoTitolo ?? null,
+            tipo: attoTipo ?? null,
+            codice_tipo: attoCodiceTipo ?? null,
+            codice_redazionale: args.codice_redazionale,
+            data_gu: args.data_gu,
+            data_vigenza: args.data_vigenza,
+            format: args.format,
+            articolo_da: args.articolo_da,
+            probed_up_to: probedUpTo,
+            stopped_early: stoppedEarly,
+            truncated: truncatedReason !== null || exhaustedRange,
+            truncated_reason: truncatedReason ?? (exhaustedRange ? "max_articoli" : null),
+            articolo_successivo: articoloSuccessivo ?? (exhaustedRange ? upperBound + 1 : null),
+            char_count: totalChars,
+            articoli_inclusi: articoli.length,
+            include_suffixes: args.include_suffixes,
+            articoli,
+        });
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+export interface AttoListItem {
+    annoProvvedimento?: number;
+    numeroProvvedimento?: string;
+    denominazioneAtto?: string;
+    descrizioneAtto?: string;
+    titoloAtto?: string;
+    codiceRedazionale?: string;
+    dataGU?: string;
+    dataEmanazione?: string;
+    dataPubblicazione?: string;
+    classeProvvedimento?: string;
+    dataUltimaModifica?: string;
+    ultimiAttiModificanti?: string;
+}
+export interface RicercaResponse {
+    numeroAttiTrovati?: number;
+    numeroPagine?: number;
+    paginaCorrente?: number;
+    listaAtti?: AttoListItem[];
+    facetMap?: Record<string, Array<{
+        descrizione: string;
+        valore: number;
+    }>>;
+}
+export interface DettaglioAttoBody {
+    dataGU: string;
+    codiceRedazionale: string;
+    idArticolo: number;
+    sottoArticolo: number;
+    sottoArticolo1: number;
+    dataVigenza: string;
+    idGruppo: number;
+    progressivo: number;
+    versione: number;
+}
+export interface DettaglioAttoResponse {
+    success?: boolean;
+    data?: {
+        atto?: {
+            titolo?: string;
+            tipoProvvedimentoDescrizione?: string;
+            tipoProvvedimentoCodice?: string;
+            articoloHtml?: string;
+            articoloDataInizioVigenza?: string;
+            articoloDataFineVigenza?: string;
+        };
+    };
+    message?: string;
+    code?: string | null;
+}
+export interface RicercaAvanzataBody {
+    testoRicerca?: string;
+    titoloRicerca?: string;
+    denominazioneAtto?: string;
+    annoProvvedimento?: string;
+    numeroProvvedimento?: string;
+    meseProvvedimento?: string;
+    giornoProvvedimento?: string;
+    dataInizioEmanazione?: string;
+    dataFineEmanazione?: string;
+    dataInizioPubProvvedimento?: string;
+    dataFinePubProvvedimento?: string;
+    vigenza?: string;
+    classeProvvedimento?: string;
+    orderType: "recente" | "vecchio";
+    paginazione: {
+        paginaCorrente: number;
+        numeroElementiPerPagina: number;
+    };
+    filtriMap?: Record<string, string | number>;
+}
+export interface AggiornatiBody {
+    dataInizioAggiornamento: string;
+    dataFineAggiornamento: string;
+}
+export interface DenominazioneItem {
+    label: string;
+    value: string;
+}
+export interface ClasseItem {
+    label: string;
+    value: string;
+}
+export interface CollezioneItem {
+    nomeCollezione: string;
+    numeroAtti: number;
+}
+export interface RicercaPredefinita {
+    nome: string;
+    dettagli: Array<{
+        nomeCampo: string;
+        valoreCampo: string;
+    }>;
+    dataCreazione: string;
+}
+export interface RicerchePredefiniteResponse {
+    ricerchePredefinite: RicercaPredefinita[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "normattiva-mcp",
+  "version": "0.1.0",
+  "description": "MCP server wrapping the Normattiva OpenData API for Italian legislation (search, read articles, monitor recent updates).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "normattiva-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "normattiva",
+    "italian-law",
+    "legislation",
+    "ipzs",
+    "ai",
+    "claude"
+  ],
+  "author": "adellorto (https://github.com/adellorto)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adellorto/normattiva-mcp.git"
+  },
+  "homepage": "https://github.com/adellorto/normattiva-mcp/tree/main",
+  "bugs": {
+    "url": "https://github.com/adellorto/normattiva-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
+  }
+}