MCP server per il Design system .italia

Non perdere il filo.

⚠️ Progetto personale non ufficiale e sperimentale - I dati sono forniti così come sono e potrebbero essere incompleti o non aggiornati. Utilizzare a proprio rischio. / ⚠️ Unofficial & experimental personal sandbox project - Data is provided as-is and may be outdated or incomplete. Use at your own risk.

Di cosa parliamo? / What are we talking about?

IT — Design system .italia è il sistema open source ufficiale per realizzare le interfacce della Pubblica Amministrazione. Una iniziativa del progetto Designers Italia, è distribuito in più repository indipendenti.

EN — Design System .italia is the official open source design system for Italian Public Administration interfaces. An initiative by Designers Italia, it is distributed across multiple independent repositories.

• Bootstrap Italia — componenti e stili HTML/CSS / HTML/CSS components and styles ⚠️ v3 beta

• Dev Kit Italia — web component it-* ⚠️ v1 beta

• Design Tokens Italia — variabili CSS e SCSS globali --it-* e $it- / global CSS and SCSS variables

• designers.italia.it — documentazione e linee guida d'uso / documentation and usage guidelines

Related MCP server: ds-pilot

Cos'è Filo / What is Filo

IT — Filo è un server MCP (Model Context Protocol) non ufficiale che espone a assistenti AI i dati strutturati del Design system .italia: componenti e markup HTML Bootstrap Italia v3 ⚠️ beta, web component e props Dev Kit Italia v1 ⚠️ beta, token CSS con valori risolti, linee guida per componente, stato di accessibilità e issue GitHub collegate. I dati sono aggiornati nightly tramite snapshot CI nel branch data-fetched quando upstream rilascia una nuova versione (al più tardi settimanalmente).

EN — Filo is an unofficial MCP (Model Context Protocol) server providing AI assistants with structured access to Italy's Design System resources: Bootstrap Italia v3 components and HTML markup ⚠️ beta, Dev Kit Italia web components and props v1 ⚠️ beta, CSS tokens with resolved values, per-component usage guidelines, accessibility status, and related GitHub issues. Data is refreshed nightly via CI snapshot into the data-fetched branch whenever upstream releases a new version (at least weekly).

Perché Filo / Why Filo

IT — Tenere il filo della qualità nell’epoca degli LLM e dell’AI come scorciatoia per tutto. Rendere interrogabile il Design system .italia e il suo vasto ecosistema di risorse. Supportare persone e assistenti AI nella progettazione, esplorazione, generazione e validazione su dati reali e verificati. Un server MCP read-only e open source. Un esperimento sulle possibilità di sviluppare software utile per le persone, anche mentre litighi con qualche LLM.

EN — Keep the thread of quality in the age of LLMs and AI as a shortcut for everything. Make Italy’s Design System and its vast ecosystem of resources queryable. Support people and AI assistants in design, exploration, code generation and validation — on real, verified data. A read-only, open source MCP server. An experiment in the possibilities of building software that is actually useful for people, even while arguing with a few LLMs.​​​​​​​​​​​​​​​​

Strumenti disponibili / Available tools

I tool sono organizzati per sorgente/namespace: dsi_ (inventario unificato componenti Design system .italia), bsi_ e devkit_ (markup/varianti/props da Bootstrap Italia e Dev Kit Italia — mirror solo dove le sorgenti producono artefatti distinti), tokens_ (design token e variabili CSS, asse sorgente unico), docs_ (da schede linee guida Designers Italia), github_ (issue dalle repo dell'ecosistema). Rispetto alle prime release, per un approccio di risparmio token, non esiste più un tool aggregatore full: combinare più fonti in un'unica risposta è responsabilità del client, componendo più chiamate mirate. Per lo stesso motivo, non tutti i tool espongono i dati anche in forma strutturata (structuredContent), solo dove il numero di risultati è naturalmente limitato dal parametro di input.

Componenti — dsi_

• dsi_list_components() — inventario unificato di tutti i componenti: una riga per componente con bsi:{status, accessibility} (null se non presente in Bootstrap Italia) e devkit:{tags, storybookUrl, componentType} (null se non presente in Dev Kit Italia). Un componente è un'unica entità con due possibili implementazioni. Punto di partenza prima di markup, token o props.

• dsi_search_components(query) — ricerca sulla stessa unione, per nome, slug, alias IT/EN o tag Dev Kit.

Markup e varianti — bsi_ / devkit_

• bsi_list_component_variants(component) — nomi di tutte le varianti Bootstrap Italia disponibili, senza markup.

• bsi_get_component_markup(component, variant?) — markup HTML completo di una variante specifica (variant omesso → prima variante).

• bsi_list_components_by_status(status, library?) — componenti filtrati per stato di implementazione (PRONTO, DA RIVEDERE, DA FARE, ...). library sceglie la colonna: bootstrapItalia (default) o devKitItalia — cambia anche a cosa punta docUrl nel risultato (documentazione BSI o pagina Storybook). uiKitItalia non è ancora filtrabile qui (vive solo su Figma).

• devkit_list_component_variants(component) — nomi di tutte le varianti Dev Kit Italia disponibili.

• devkit_get_component_markup(component, variant?) — markup HTML di una variante Dev Kit, estratto da Storybook via snapshot CI (variant omesso → prima variante).

• devkit_list_component_props(component) — attributi HTML it-* di un web component Dev Kit: nome, tipo, descrizione, default, opzioni — incluse le props dei subcomponenti (es. it-accordion-item).

Design tokens e variabili CSS — tokens_

• tokens_list_component_vars(component) — variabili CSS --bsi-* personalizzabili di un componente, con descrizione semantica, catena di risoluzione e valore risolto. I valori compositi (shorthand, calc()) sono risolti riferimento per riferimento; le variabili dichiarate più volte con valori diversi sono segnalate esplicitamente invece di apparire come righe duplicate.

• tokens_list_globals(match?) — coppie di token globali che Bootstrap Italia usa davvero: Design Token centrale (--it-*/$it-*, non sovrascrivibile per progetto) + --bsi-* corrispondente (sovrascrivibile a runtime), con valore risolto. match filtra per sottostringa nel nome, omesso restituisce tutti.

• tokens_resolve(variable) — risolve qualunque variabile (--bsi-*, --it-* o $it-*) al valore concreto, seguendo l'intera catena. Su un valore composito o su una dichiarazione ambigua, la risposta lo segnala invece di restituire un valore arbitrario.

• tokens_find_components(variable) — componenti Bootstrap Italia impattati da una variabile, incluso l'impatto indiretto tracciato lungo la catena — anche quando la variabile è solo uno dei riferimenti embedded in un valore composito di un altro componente.

• tokens_search(query) — ricerca per sottostringa su nome, descrizione e valore della variabile, su token BSI e Design Tokens Italia globali; per le variabili con dichiarazioni multiple, cerca anche in ciascun valore dichiarato.

Ogni token include resolvedVia: l'elenco degli hop intermedi della catena di risoluzione, ciascuno con role (bsi-component | bsi-global | dti) e overridable (true per le --bsi-* sovrascrivibili a runtime, false per i Design Token centrali --it-*/$it-*, definiti upstream). Un valore che incorpora più riferimenti in un'unica stringa (shorthand spacing, calc(), box-shadow) include anche composedOf: un riferimento risolto per elemento, oltre al valore finale già sostituito. Se lo stesso nome è dichiarato più volte con valori diversi nel sorgente del componente (breakpoint responsive, varianti di tema, stati dell'elemento), il token include declaredTimes/ambiguousValues invece di un valore unico silenzioso.

Linee guida componenti e stato accessibilità — docs_

• docs_get_component_guide(component) — linee guida d'uso da Designers Italia: descrizione, quando/come usarlo, stato verifiche accessibilità, stato libreria (Bootstrap Italia, UI Kit Italia, Dev Kit Italia). Lo stato accessibilità per-componente è disponibile anche in dsi_list_components (campo bsi.accessibility). Se l'URL Dev Kit registrato nella board diverge da quello reale su Storybook, o se il tab "Uso e accessibilità" non viene trovato per titolo su Designers Italia (contenuto preso dal primo tab come fallback), la risposta lo segnala in warnings invece di restare in silenzio.

Issue e stato progetto — github_

• github_get_component_issues(component) — issue GitHub aperte per componente sulle repository monitorate (bootstrap-italia, design-ui-kit, dev-kit-italia, design-tokens-italia), più le issue note già registrate in components_status.json.

• github_get_project_repo_links() — link alle issue aperte di ciascuna repository. Non include i dati live delle board GitHub Projects v2 (non ancora integrate).

Connessione e meta

• ping — verifica connessione al server, versione, timestamp e warning sulle sorgenti in beta. Da usare all'inizio della sessione per confermare i tool disponibili.

Query consigliata / Recommended Query

Il valore del server è la combinazione contestuale di sorgenti frammentate — componendo più chiamate mirate.

Esempi: "Quali varianti ha l'Accordion e quali token posso personalizzare?", "Quali variabili devo sovrascrivere nel mio CSS per cambiare i colori di header e footer?", "..."

Flusso tipico: dsi_list_components/dsi_search_components per orientarsi → bsi_list_component_variants/devkit_list_component_variants per i nomi delle varianti → bsi_get_component_markup/devkit_get_component_markup per il markup di una variante specifica → tokens_list_component_vars/tokens_resolve per i token.

Ogni risposta include le versioni delle risorse (Design system .italia, Bootstrap Italia, Dev Kit Italia, Design Tokens Italia), URL verificato della documentazione ufficiale e dataFetchedAt, la data dell'ultimo snapshot CI che avviene tendenzialmente* ogni notte, non il momento della richiesta. (* = laddove ci sono rilasci di nuove versioni upstream).

I tool bsi_get_component_markup/devkit_get_component_markup restituiscono sempre una sola variante per chiamata; usa prima bsi_list_component_variants/devkit_list_component_variants per scoprire i nomi delle varianti disponibili.

I nomi dei componenti funzionano in italiano e inglese: "fisarmonica", "dialog", "pulsante" trovano accordion, modal, button.

System prompt consigliato / Recommended system prompt

Per ridurre gli errori o allucinazioni, istruisci il tuo assistente AI a basarsi esclusivamente sui dati restituiti da Filo.

IT

## Regole dati Design System .italia (Filo MCP)

DATI VERIFICATI: usa esclusivamente i dati restituiti dagli strumenti MCP di Filo. Non integrare con conoscenza pregressa su Bootstrap Italia, Dev Kit Italia, Design Tokens Italia o altri framework CSS/web component.

QUANDO IL DATO MANCA: se un'informazione non è presente nelle risposte MCP, dillo esplicitamente. Scrivi "Questo dato non è disponibile nelle sorgenti MCP" anziché fornire una stima o inferenza. Non inventare valori numerici.

QUANDO COMPONI ELEMENTI: se combini markup MCP reale con HTML/CSS che aggiungi tu, segnala chiaramente cosa viene dai dati MCP e cosa è tua inferenza.

VERSIONI E FONTI: in ogni risposta che usa dati MCP, includi la versione delle sorgenti e il link alla documentazione ufficiale restituiti dal tool.

REGOLA D'ORO: se non sei sicuro che un dato provenga da MCP, trattalo come inferenza e segnalalo.

TOOL DISPONIBILI: all'inizio della sessione, usa il tool ping per verificare la connessione e leggi la lista dei tool disponibili. Non assumere quali tool esistono.

COMPLETEZZA DATI: se un componente non è presente in una sorgente (es. `devkit: null` in dsi_list_components/dsi_search_components), segnalalo all'utente invece di presumerne l'assenza totale.

EN

## Data rules — Design System .italia (Filo MCP)

VERIFIED DATA: use exclusively the data returned by Filo's MCP tools. Do not supplement with prior knowledge of Bootstrap Italia, Dev Kit Italia, Design Tokens Italia, or any other CSS/web component framework.

WHEN DATA IS MISSING: if information is not present in the MCP responses, say so explicitly. Never invent numeric values.

WHEN COMPOSING ELEMENTS: clearly indicate what comes from MCP data and what is your own inference.

VERSIONS AND SOURCES: in every response that uses MCP data, include the source versions and official documentation URL returned by the tool.

GOLDEN RULE: if you are unsure whether a piece of data comes from MCP, treat it as inference and label it as such.

AVAILABLE TOOLS: at the start of the session, use the ping tool to verify the connection and read the list of available tools. Do not assume which tools exist.

DATA COMPLETENESS: if a component is missing from one source (e.g. `devkit: null` in dsi_list_components/dsi_search_components), flag this to the user instead of assuming it doesn't exist at all.

Come connettersi / How to connect

Claude Desktop / Cursor / VS Code (via NPX — consigliato)

Non richiede installazione — npx scarica e avvia il server automaticamente.

Aggiungi al file di configurazione MCP del tuo client:

{
  "mcpServers": {
    "design-system-italia": {
      "command": "npx",
      "args": ["-y", "@fupete/design-system-italia-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

ℹ️ nvm su macOS — se npx risolve a una versione vecchia di Node ("You must supply a command" o "Cannot find module 'node:path'"), usa il path esplicito. Trova il path con nvm use 22 && which npx, poi:

{
  "mcpServers": {
    "design-system-italia": {
      "command": "/Users/tuonome/.nvm/versions/node/v22.12.0/bin/npx",
      "args": ["-y", "@fupete/design-system-italia-mcp"],
      "env": {
        "PATH": "/Users/tuonome/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/usr/bin:/bin",
        "TRANSPORT": "stdio",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Sostituisci tuonome e v22.12.0 con i tuoi valori.

Oppure via CLI (Claude Desktop):

claude mcp add design-system-italia \
  --command "npx -y @fupete/design-system-italia-mcp" \
  --env TRANSPORT=stdio \
  --env GITHUB_TOKEN=your_token

ℹ️ Problemi con nvm su macOS? Usa la configurazione JSON sopra con path esplicito.

Self-hosting con Docker (locale o VPS)

Funziona su qualsiasi macchina con Docker installato — locale, VPS personale, server aziendale.

docker pull ghcr.io/fupete/design-system-italia-mcp
docker run -e GITHUB_TOKEN=your_token -p 8080:8080 \
  ghcr.io/fupete/design-system-italia-mcp

⚠️ Docker multiarch — se docker pull scarica un'architettura incompatibile, fai una build locale: docker build -t design-system-italia-mcp .

ℹ️ GITHUB_TOKEN (opzionale ma consigliato) — serve per il tool github_get_component_issues. Senza token: 60 richieste/ora per IP. Con token: 5000 richieste/ora. Basta un token con scope pubblico read-only — nessun permesso speciale richiesto.

Sorgenti dati / Data sources

I dati sono aggiornati nightly tramite CI snapshot e serviti dal branch data-fetched. Solo le GitHub Issues sono fetchate live a runtime.

Le sorgenti 1–9 e 11 sono controllate ogni notte e aggiornate quando upstream rilascia una nuova versione (al più tardi settimanalmente), cached per 24h lato server. La sorgente 10 (GitHub Issues) è l'unica fetchata live a runtime (cache 15 min). dataFetchedAt nelle risposte riflette la data dell'ultimo snapshot CI.

⚠️ Layer token e web component in beta — Il server usa Bootstrap Italia 3.x (beta) e Dev Kit Italia (beta). Token CSS --bsi-* e web component it-* possono avere alcune breaking change prima della release stabile.

⚠️ Token and web component layer in beta — This server uses Bootstrap Italia 3.x (beta) and Dev Kit Italia (beta). CSS tokens --bsi-* and web components it-* may have some breaking changes before stable release.

Stack tecnico / Tech stack

• Node.js + TypeScript

• @modelcontextprotocol/sdk

• Streamable HTTP transport / stdio transport (via TRANSPORT=stdio)

• Docker (self-hosting — locale o VPS)

• Playwright (CI only — snapshot Dev Kit Storybook markup)

Sviluppo locale / Local development

git clone https://github.com/fupete/design-system-italia-mcp
cd design-system-italia-mcp
npm install
cp .env.example .env
# aggiungi GITHUB_TOKEN in .env
npm run dev

# Typecheck
npm run typecheck
# Test unitari
npm run test
# Verifica sorgenti upstream e freschezza snapshot
npm run canary

Server disponibile su http://localhost:8080/mcp

Testare con MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8080/mcp

Riferimenti / References

• dati-semantic-mcp progetto analogo per schema.gov.it iniziato da @mfortini, spunto iniziale

• MCP Protocol

• Design system .italia

• Bootstrap Italia

• Dev Kit Italia

• Design Tokens Italia

Provenienza dei dati e licenze / Data provenance & licenses

Il server recupera e serve dati da repository pubblici upstream. Le sorgenti includono Bootstrap Italia, Dev Kit Italia, Design Tokens Italia e Designers Italia — tutte BSD-3-Clause. I contenuti editoriali di Designers Italia (linee guida d'uso, note di accessibilità) sono licenziati sotto CC-BY-SA 4.0. I lavori derivati ereditano il requisito ShareAlike / This server fetches and serves data from public upstream repositories. Sources include Bootstrap Italia, Dev Kit Italia, Design Tokens Italia and Designers Italia — all BSD-3-Clause. Editorial content from Designers Italia (usage guidelines, accessibility notes) is licensed under CC-BY-SA 4.0. Derivatives of that content inherit the ShareAlike requirement.

Dettagli completi, link agli autori upstream e riferimenti alle licenze: / Full provenance details, upstream author links and license references: data-fetched branch README

Licenza / License

BSD 3-Clause — © 2026 Daniele Tabellini (Fupete) Documentazione: CC BY SA 4.0 I dati esposti mantengono la licenza delle rispettive sorgenti

Illustrazione hero: Open Doodles (remix)

Filo è un progetto sperimentale sviluppato da @Fupete anche litigando con qualche LLM. Issue benvenute. / Filo is an experimental project developed by @Fupete, partly by arguing with a few LLMs. Issues welcome.