Filo — MCP server per il Design System .italia

Di cosa parliamo?

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:

Bootstrap Italia (componenti e stili HTML, CSS)
Dev Kit Italia (web component it-*)
Design Tokens Italia (variabili CSS e SCSS globali)
designers.italia.it (documentazione e linee guida d'uso)

Filo raccoglie e organizza le informazioni utili da queste sorgenti ogni notte e le espone via MCP. È un'interfaccia per assistenti AI che offre strumenti per consultare e usare le risorse del design system in modo semplice e verificato. È da notare che Filo fa riferimento alle future v3 di Bootstrap Italia e v1 di Dev Kit Italia, attualmente in alpha.

Perché Filo?

Un progetto sperimentale con alcune idee precise:

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 documentazione, risorse e repository
Supportare persone e assistenti AI nella progettazione di interfacce, nell'esplorazione della documentazione, nella generazione di codice e nella validazione di scelte e risultati
Realizzare un server MCP read-only e open source che espone strumenti per interrogare dati verificati e riproducibili, con versioni delle risorse sempre esplicite e note
Fare un esperimento sulle possibilità di sviluppare software utile per le persone, anche mentre litighi con qualche LLM

In roadmap: strumenti per setup progetti e lettura fondamenti del design system, ottimizzazione dell'uso di token LLM e risorse. Futuribile: test uso combinato con server MCP per tool di design

Installa Filo

Avvia il server MCP in un comando

npx @fupete/design-system-italia-mcp

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

git clone https://github.com/fupete/design-system-italia-mcp.git
cd design-system-italia-mcp
npm install && npm run dev

GITHUB_TOKEN (opzionale ma consigliato) per get_component_issues. Senza: 60 richieste/ora per IP. Con token scopo pubblico read-only: 5000/ora.

Client

In ~/Library/Application Support/Claude/claude_desktop_config.json

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

In .vscode/mcp.json

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

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

{
  "mcpServers": {
    "design-system-italia": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

System prompt

## 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 tool restituisce un sottoinsieme dei dati (es. 3 varianti su 13), segnalalo all'utente.

## 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 tool returns a subset of available data (e.g. 3 variants out of 13), flag this to the user.

Scopri gli strumenti

Approfondisci i tool a disposizione del tuo assistente AI

Scopri

list_components Elenca tutti i componenti con stato per libreria (Bootstrap Italia, UI Kit…) e stato accessibilità. Punto di partenza per una panoramica completa.
search_components Cerca componenti per nome o feature. Supporta alias IT/EN e tag Dev Kit (es. a11y-ok, alpha, web-component).
list_by_status Filtra i componenti per stato in una libreria specifica. Stati possibili: PRONTO, DA RIVEDERE A11Y, DA FARE, NON PRESENTE…
list_accessibility_issues Elenca i componenti con note di accessibilità aperte o verifiche incomplete.

Componenti

get_component Markup HTML varianti Bootstrap Italia e props web component it-* Dev Kit Italia. Punto di partenza per markup e varianti.
get_component_variant Markup completo di una variante specifica per nome, da BSI o Dev Kit in modo trasparente.
get_component_full Risposta aggregata: markup + token CSS con valori risolti + linee guida + stato + props it-* + issue GitHub. Da usare quando servono dati da più sorgenti in una sola chiamata.
get_component_guidelines Linee guida d'uso da Designers Italia: quando usarlo, come usarlo, alternative consigliate, note accessibilità.
get_component_issues Issue GitHub aperte per un componente sui 4 repository del Design system .italia.

Token

get_component_tokens Variabili CSS --bsi-* personalizzabili per componente con descrizione semantica e valore risolto (es. var(--bsi-spacing-m) → 1.5rem).
find_token Cerca un token CSS per nome variabile o descrizione semantica. Copre sia --bsi-* che --it-* di Design Tokens Italia.

Esplora i dati

Verifica i dati aggregati dalle sorgenti originali del Design system .italia

Caricamento...

Componente	Bootstrap Italia	UI Kit Italia	Dev Kit Italia

Con Filo attivo il tuo assistente AI può accedere a varianti e markup dei componenti

Prova

Componente

Esempio — --bsi-accordion-padding

--bsi-accordion-padding → var(--bsi-spacing-m) → var(--it-spacing-m) → 1.5rem

get_component_tokens("accordion")

caricamento…

Con Filo attivo il tuo assistente AI riceve la catena di risoluzione completa — --bsi-* → Design Tokens Italia --it-* → valore concreto

Prova

Componente

Istantanea salvata ogni notte nel ramo data-fetched del repository

MCP server per il Design system .italia

Di cosa parliamo?

Perché Filo?

Installa Filo

Client

System prompt

Scopri gli strumenti

Scopri

Componenti

Token

Meta

Esplora i dati

MCP server per il Design system .italia

Di cosa parliamo?

Perché Filo?

Installa Filo

Client

Claude Desktop

Cursor / VS Code

Claude Code

HTTP remoto (Docker / VPS)

System prompt

Scopri gli strumenti

Scopri

Componenti

Token

Meta

Esplora i dati