normattiva-mcp 0.1.3 → 0.1.4

package/README.md

@@ -12,11 +12,11 @@ It wraps the synchronous read endpoints (search, article detail, recent updates)
 
 | 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). |
+| `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). To find acts **newly published** in Gazzetta Ufficiale within a window, set `data_pubblicazione_da` / `data_pubblicazione_a` — this is the right tool for "what was published recently?", not `recent_updates`. |
 | `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. |
+| `recent_updates` | Lists atti normativi whose **consolidated text was amended** within a date window (max 12 months) — i.e. the in-force version changed because another act modified it. Does **not** list acts newly published in Gazzetta Ufficiale; for those, use `search_acts` with `data_pubblicazione_da` / `data_pubblicazione_a`. |
 
 ### Resources
 
@@ -32,7 +32,7 @@ It wraps the synchronous read endpoints (search, article detail, recent updates)
 | 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. |
+| `monitoraggio-modifiche` | `giorni` (default `7`) | Summarize amendments to the consolidated text of existing acts in the last *N* days (uses `recent_updates`; for newly published acts use `search_acts` with `data_pubblicazione_da/a`). |
 
 ## Installation & client configuration
 
@@ -78,6 +78,38 @@ The server always talks to Normattiva's **production OpenData API** (`https://ap
 
 The OpenData API is open and does not require authentication.
 
+## HTTP transport
+
+In addition to the npm-published stdio binary, this repo also ships `packages/http-server/` — a Vercel deployment of the same MCP server over the Streamable HTTP transport. Useful for clients that need a remote endpoint instead of a local subprocess.
+
+**Hosted endpoint:** `https://normattiva-mcp.adellorto.com/api/mcp` — free, no signup, no auth.
+
+Client config:
+
+```json
+{
+  "mcpServers": {
+    "normattiva": {
+      "url": "https://normattiva-mcp.adellorto.com/api/mcp"
+    }
+  }
+}
+```
+
+### Self-hosting
+
+To run your own copy on a Vercel account:
+
+```bash
+git clone https://github.com/adellorto/normattiva-mcp.git
+cd normattiva-mcp
+pnpm install
+cd packages/http-server
+npx vercel deploy
+```
+
+The handler exposes only Streamable HTTP (SSE is removed from the 2025-03-26 MCP spec). No authentication by default — anyone with the URL can call it.
+
 ## Building from source
 
 Requires Node.js ≥ 20.

package/dist/index.js

@@ -15,7 +15,7 @@ var 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.2 (+https://www.npmjs.com/package/normattiva-mcp)"
+  "User-Agent": "normattiva-mcp/0.1.4 (+https://www.npmjs.com/package/normattiva-mcp)"
 };
 var REQUEST_TIMEOUT_MS = 2e4;
 async function request(path, init) {
@@ -165,7 +165,7 @@ function jsonContent(data) {
 function registerTools(server, _ctx) {
   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' \u2014 see resource normattiva://tipologiche/denominazioni for the full list.",
+    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' \u2014 see resource normattiva://tipologiche/denominazioni for the full list. To find acts newly published in Gazzetta Ufficiale within a window, set data_pubblicazione_da and data_pubblicazione_a (this is the right tool for 'what was published recently?', not recent_updates).",
     inputSchema: {
       testo: z.string().optional().describe("Keywords searched in the act body."),
       titolo: z.string().optional().describe("Keywords searched in the act title."),
@@ -176,8 +176,8 @@ function registerTools(server, _ctx) {
       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(),
+      data_pubblicazione_da: dateString.optional().describe("Start of the publication window in Gazzetta Ufficiale (YYYY-MM-DD). Use this (with data_pubblicazione_a) to answer 'which acts were published recently'."),
+      data_pubblicazione_a: dateString.optional().describe("End of the publication window in Gazzetta Ufficiale (YYYY-MM-DD)."),
       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."),
@@ -456,11 +456,11 @@ function registerTools(server, _ctx) {
     });
   });
   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.",
+    title: "Atti whose consolidated text was amended on Normattiva",
+    description: "Lists Italian normative acts whose consolidated text was amended within a date window (i.e. the in-force version changed because another act modified it). Does NOT return acts newly published in Gazzetta Ufficiale \u2014 for 'what was published recently', call search_acts with data_pubblicazione_da / data_pubblicazione_a instead. Useful for monitoring how existing legislation evolves. 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.")
+      data_inizio: dateString.describe("Start of the amendment window (YYYY-MM-DD). Refers to the date the consolidated text changed, not to publication in Gazzetta Ufficiale."),
+      data_fine: dateString.describe("End of the amendment window (YYYY-MM-DD), max 12 months after data_inizio.")
     }
   }, async ({ data_inizio, data_fine }) => {
     const data = await ricercaAggiornati({
@@ -698,8 +698,8 @@ Procedi cos\xEC:
     ]
   }));
   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.",
+    title: "Monitora modifiche al testo consolidato di atti esistenti",
+    description: "Recupera gli atti normativi italiani il cui testo consolidato \xE8 stato modificato negli ultimi N giorni e ne fornisce un riepilogo. Per gli atti pubblicati di recente in Gazzetta Ufficiale usa invece search_acts con data_pubblicazione_da/a.",
     argsSchema: {
       giorni: z2.string().regex(/^\d+$/, "Numero di giorni come stringa intera").default("7").describe("Quanti giorni indietro guardare (default 7).")
     }
@@ -714,7 +714,7 @@ Procedi cos\xEC:
           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\xF9 rilevanti, evidenziando gli atti modificanti principali.`
+            text: `Recupera con recent_updates gli atti normativi italiani il cui testo consolidato \xE8 stato modificato tra il ${fmt(inizio)} e il ${fmt(oggi)} (non si tratta di nuove pubblicazioni in Gazzetta Ufficiale: per quelle usa search_acts con data_pubblicazione_da/a). Raggruppa i risultati per tipologia di atto e fornisci un riepilogo delle modifiche pi\xF9 rilevanti, evidenziando gli atti modificanti principali.`
           }
         }
       ]
@@ -726,7 +726,7 @@ Procedi cos\xEC:
 async function main() {
   const server = new McpServer({
     name: "normattiva-mcp",
-    version: "0.1.2"
+    version: "0.1.4"
   });
   const ctx = {};
   registerTools(server, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "normattiva-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MCP server wrapping the Normattiva OpenData API for Italian legislation (search, read articles, monitor recent updates).",
   "type": "module",
   "main": "./dist/index.js",