MCP server per il Design system .italia

Non perdere il filo.

<img src="docs/assets/imgs/filo-illustration-hero.png" alt="Tenere il filo blu Italia." width="400">

⚠️ 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

---

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.

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.

---

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.

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.
• 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.
• tokens_find_components(variable) — componenti Bootstrap Italia impattati da una variabile, incluso l'impatto indiretto tracciato lungo la catena. Utile per capire cosa cambia sovrascrivendo una variabile.
• tokens_search(query) — ricerca per sottostringa nel nome della variabile, su token BSI e Design Tokens Italia globali.

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).

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, la risposta lo segnala in warnings invece di sceglierne uno 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 un