GovBR DS MCP

Open-Source-Server für das Model Context Protocol (MCP) für das Design System der brasilianischen Bundesregierung (GovBR-DS).

govbr-ds-mcp bietet KI-Agenten strukturierten Zugriff auf die Dokumentation des GovBR-DS, seine Komponenten, Barrierefreiheitsrichtlinien, Suche, Resources und wiederverwendbare Workflows für die Entwicklung.

Ziel ist es, Tools wie Codex, Claude Code, Kiro und andere MCP-kompatible Clients in die Lage zu versetzen, das GovBR Design System auf der Grundlage seiner synchronisierten offiziellen Dokumentation zu verstehen und zu nutzen, anstatt sich nur auf das Vorwissen des Modells zu verlassen.

Das Paket ist auf npm als govbr-ds-mcp veröffentlicht und kann direkt mit dem folgenden Befehl ausgeführt werden:

npx -y govbr-ds-mcp

Dies ist ein unabhängiges Community-Projekt. Es ist kein offizielles Projekt der brasilianischen Bundesregierung oder des für das GovBR-DS verantwortlichen Teams.

Warum dieses Projekt?

KI-Agenten können schnell Frontend-Code erzeugen, wissen aber nicht immer:

• welche GovBR-DS-Komponente verwendet werden soll;

• wie sich eine bestimmte Komponente verhalten soll;

• welche Barrierefreiheitsempfehlungen gelten;

• welche Nutzungsmuster empfohlen werden;

• wo sich eine bestimmte Information in der GovBR-DS-Dokumentation befindet.

govbr-ds-mcp versucht, dieses Problem zu lösen, indem es die GovBR-DS-Dokumentation über das Model Context Protocol bereitstellt.

Agente de IA
    │
    ▼
govbr-ds-mcp
    │
    ├── Tools
    ├── Resources
    ├── Prompts
    └── Busca
          │
          ▼
   Dados estruturados locais
          ▲
          │
   Sincronização da documentação
          ▲
          │
 Repositório oficial GovBR-DS

Der MCP-Server verwendet intern kein LLM und führt während des normalen Betriebs keine externen Anfragen durch.

Related MCP server: PortOne Global MCP Server

Funktionen

Synchronisierung der Dokumentation

Die Dokumentation wird aus dem offiziellen GovBR-DS-Repository abgerufen und in lokale strukturierte Daten umgewandelt.

GitLab GovBR-DS
      │
      ▼
   GitLab API
      │
      ▼
 Parser Markdown
      │
      ▼
Componentes estruturados
      │
      ▼
components.generated.ts

Die erzeugten Daten werden lokal gespeichert, sodass der MCP-Server nach der Synchronisierung ohne Internetzugang funktionieren kann.

Derzeit synchronisiert das Projekt 37 dokumentierte Komponenten des GovBR-DS.

MCP-Tools

list_components

Listet die im lokalen Dokumentationsindex verfügbaren GovBR-DS-Komponenten auf.

Beispiel:

{}

Antwort:

[
  {
    "name": "Button",
    "slug": "button",
    "description": "..."
  },
  {
    "name": "Input",
    "slug": "input",
    "description": "..."
  }
]

get_component

Gibt die vollständige strukturierte Dokumentation einer bestimmten GovBR-DS-Komponente zurück.

Beispiel:

{
  "name": "button"
}

Die Suche unterscheidet nicht zwischen Groß- und Kleinschreibung.

Die folgenden Aufrufe sind äquivalent:

button
Button
BUTTON

search_docs

Durchsucht die lokal synchronisierte GovBR-DS-Dokumentation.

Beispiel:

{
  "query": "como usar um botão",
  "limit": 5
}

Die Suchmaschine unterstützt:

• case-insensitive Suche;

• Suche ohne Unterscheidung von Akzenten;

• Entfernung portugiesischer Stoppwörter;

• Komponenten-Aliase;

• Kanonisierung morphologischer Varianten;

• Priorisierung der identifizierten Komponente;

• Ranking nach Abschnittsrelevanz;

• Erzeugung relevanter Snippets;

• Filter nach Komponente.

Beispiel:

{
  "query": "acessibilidade aria",
  "component": "button",
  "limit": 5
}

Die Suche findet vollständig im Speicher statt.

Es werden nicht verwendet:

• Embeddings;

• Vektordatenbank;

• Elasticsearch;

• LLM;

• externe Suchdienste.

MCP-Resources

Die GovBR-DS-Dokumentation wird auch über MCP-Resources bereitgestellt.

Komponentenkatalog

govbr-ds://catalog

Stellt einen Index aller synchronisierten Komponenten bereit.

Komponentendokumentation

govbr-ds://components/{slug}

Beispiel:

govbr-ds://components/button

Gibt die vollständige Dokumentation der Komponente im Markdown-Format zurück.

Barrierefreiheitsdokumentation

govbr-ds://components/{slug}/accessibility

Beispiel:

govbr-ds://components/button/accessibility

Gibt die für die Komponente verfügbaren Barrierefreiheitsrichtlinien zurück.

Nicht alle GovBR-DS-Komponenten verfügen über eine spezifische Barrierefreiheitsdokumentation.

Die Resources werden vollständig aus den lokal synchronisierten Daten erzeugt.

MCP-Prompts

Der Server stellt wiederverwendbare Prompts für häufige Entwicklungsworkflows mit GovBR-DS bereit.

implement_govbr_component

Stellt die synchronisierte offizielle Dokumentation einer Komponente sowie Anweisungen zur Unterstützung ihrer Implementierung bereit.

Beispiel:

{
  "component": "button",
  "requirements": "Preciso de uma ação principal para confirmar o formulário."
}

Der Prompt stellt dem Modell die relevante Dokumentation der Komponente bereit, damit die Implementierung auf dem GovBR-DS basiert.

review_govbr_component

Stellt die Komponentendokumentation zusammen mit einem Codeausschnitt bereit, der überprüft werden soll.

Beispiel:

{
  "component": "button",
  "code": "<button class=\"br-button\">Enviar</button>"
}

Die Überprüfung kann dann die bereitgestellte Implementierung mit den in der synchronisierten Dokumentation verfügbaren Richtlinien vergleichen.

check_govbr_accessibility

Stellt die Barrierefreiheitsrichtlinien einer Komponente bereit, um die Überprüfung einer Implementierung zu unterstützen.

Beispiel:

{
  "component": "button",
  "code": "<button class=\"br-button circle\"><i class=\"fas fa-plus\"></i></button>"
}

Der MCP-Server führt den empfangenen Code weder aus noch interpretiert er ihn.

Der Code wird ausschließlich als Text behandelt und dem verbundenen Modell als Kontext bereitgestellt.

Architektur

src/
├── data/
│   ├── components.ts
│   └── components.generated.ts
│
├── ingestion/
│   ├── gitlab-client.ts
│   ├── component-parser.ts
│   └── component-sync.ts
│
├── services/
│   ├── component.service.ts
│   └── search.service.ts
│
├── tools/
│   ├── list-components.ts
│   ├── get-component.ts
│   └── search-docs.ts
│
├── resources/
│   ├── register-resources.ts
│   ├── component.resource.ts
│   └── accessibility.resource.ts
│
├── prompts/
│   ├── register-prompts.ts
│   ├── implement-component.prompt.ts
│   ├── review-component.prompt.ts
│   └── accessibility-review.prompt.ts
│
├── formatters/
│   └── component-markdown.ts
│
├── types/
│
└── index.ts

scripts/
└── sync-components.ts

Der Hauptablauf der Anwendung ist:

                    Cliente MCP
                        │
                        ▼
                  govbr-ds-mcp
                        │
          ┌─────────────┼─────────────┐
          │             │             │
        Tools       Resources       Prompts
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                 Services locais
                        │
                        ▼
              Dados sincronizados
                        ▲
                        │
               sync:components
                        ▲
                        │
               GovBR-DS oficial

Schnellstart

• Node.js 22+

• npm

Es ist nicht erforderlich, das Paket zu klonen oder global zu installieren. MCP-Clients können den veröffentlichten Server direkt über npx starten:

npx -y govbr-ds-mcp

Der Server verwendet den MCP-Transport stdio und arbeitet mit den im Paket enthaltenen GovBR-DS-Daten, ohne HTTP-Aufrufe während der Abfragen.

Konfiguration in MCP-Clients

Claude Desktop

Fügen Sie den Server zur Konfigurationsdatei von Claude Desktop hinzu:

{
  "mcpServers": {
    "govbr-ds": {
      "command": "npx",
      "args": ["-y", "govbr-ds-mcp"]
    }
  }
}

Nach dem Speichern der Datei starten Sie Claude Desktop neu.

Siehe auch die MCP-Dokumentation von Claude.

Claude Code

Registrieren Sie den Server über das Terminal:

claude mcp add govbr-ds -- npx -y govbr-ds-mcp

Verwenden Sie claude mcp list, um die Registrierung zu bestätigen.

Codex

Fügen Sie Folgendes zur Datei ~/.codex/config.toml hinzu:

[mcp_servers.govbr-ds]
command = "npx"
args = ["-y", "govbr-ds-mcp"]

Sie können die Registrierung auch über das Terminal vornehmen:

codex mcp add govbr-ds -- npx -y govbr-ds-mcp

Starten Sie Codex neu, nachdem Sie die Konfiguration manuell geändert haben.

Siehe auch die MCP-Dokumentation von Codex.

Kiro

Öffnen oder erstellen Sie in Kiro .kiro/settings/mcp.json im Workspace. Um den Server global verfügbar zu machen, verwenden Sie ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "govbr-ds": {
      "command": "npx",
      "args": ["-y", "govbr-ds-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Öffnen Sie nach dem Speichern das MCP-Panel von Kiro und bestätigen Sie, dass govbr-ds verbunden ist.

Siehe auch die MCP-Dokumentation von Kiro.

Lokale Entwicklung

Klonen Sie das Repository und installieren Sie die Abhängigkeiten:

git clone https://github.com/FelipeVergaraChico/govbr-ds-mcp.git
cd govbr-ds-mcp
npm install

Ausführen des MCP-Servers

Starten Sie den Server im Entwicklungsmodus:

npm run dev

Der Server verwendet den MCP-Transport stdio.

Da stdout für die Kommunikation des MCP-Protokolls reserviert ist, müssen Anwendungsprotokolle an stderr gesendet werden.

Vermeiden Sie:

console.log("Servidor iniciado");

Bevorzugen Sie:

console.error("Servidor iniciado");

MCP Inspector

Das Projekt kann mit dem MCP Inspector getestet werden.

Führen Sie aus:

npx @modelcontextprotocol/inspector npx -y govbr-ds-mcp

Im Inspector können die verfügbaren Funktionen getestet werden.

Tools

list_components
get_component
search_docs

Resources

govbr-ds://catalog
govbr-ds://components/{slug}
govbr-ds://components/{slug}/accessibility

Prompts

implement_govbr_component
review_govbr_component
check_govbr_accessibility

Synchronisieren der GovBR-DS-Dokumentation

Um den lokalen Index zu aktualisieren:

npx tsx scripts/sync-components.ts

Der Synchronisierungsprozess:

1. greift über die GitLab-API auf das öffentliche GovBR-DS-Repository zu;

2. identifiziert die dokumentierten Komponenten;

3. lädt die Markdown-Dateien jeder Komponente herunter;

4. lädt die Barrierefreiheitsdokumentation herunter, sofern verfügbar;

5. interpretiert die Markdown-Dateien;

6. normalisiert die Daten;

7. erzeugt den lokalen Datensatz, der vom MCP verwendet wird.

Die erzeugten Daten werden gespeichert unter:

src/data/components.generated.ts

Die Datei wird automatisch erzeugt und darf nicht manuell bearbeitet werden.

Während des normalen Betriebs fragt der MCP-Server GitLab nicht ab.

Dadurch können die Tools, Resources, Prompts und die Suche auch ohne Internetverbindung genutzt werden.

Ausführen der Tests

Führen Sie aus:

npm test

Die Testsuite deckt Bereiche ab wie:

• Markdown-Parsing;

• Komponentensuche;

• case-insensitive Suche;

• Normalisierung von Akzenten;

• Aliase;

• Kanonisierung;

• Suchranking;

• Snippet-Generierung;

• MCP-Tools;

• MCP-Resources;

• MCP-Prompts;

• Formatierung der Dokumentation;

• Behandlung nicht vorhandener Komponenten.

Die Unit-Tests hängen nicht von der Verfügbarkeit von GitLab ab.

Entwicklung

Installieren Sie die Abhängigkeiten:

npm install

Führen Sie den Server aus:

npm run dev

Führen Sie die Tests aus:

npm test

Aktualisieren Sie die lokale Dokumentation:

npx tsx scripts/sync-components.ts

Öffnen Sie den MCP Inspector:

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Datenquelle

Die in diesem Projekt verwendete Dokumentation stammt aus dem offiziellen Repository des GovBR Design Systems:

GovBR-DS

Der aktuelle Erfassungsprozess verwendet hauptsächlich:

ds/componentes/

Die Komponentendokumentation weist normalerweise eine ähnliche Struktur auf wie:

ds/componentes/button/
├── button.md
├── button-access.md
└── imagens/

Die Hauptdatei enthält in der Regel Informationen wie:

• Beschreibung;

• Verwendung;

• Anatomie;

• Typen;

• Verhalten;

• Spezifikationen.

Sofern verfügbar, enthält die Datei *-access.md die spezifischen Barrierefreiheitsrichtlinien.

Nicht alle Komponenten besitzen exakt denselben Dateisatz.

Der Synchronisierungsprozess wurde entwickelt, um mit diesen Unterschieden umzugehen, ohne die Erzeugung des Datensatzes zu unterbrechen.

Projektprinzipien

Offizielle Dokumentation zuerst

Wann immer möglich, sollten die vom MCP bereitgestellten Informationen auf der synchronisierten offiziellen Dokumentation des GovBR-DS basieren.

Das Ziel ist es, Situationen zu reduzieren, in denen ein KI-Agent eine Regel oder ein Verhalten erfindet, das es im Design System nicht gibt.

LLM-unabhängig

Der MCP-Server ist nicht abhängig von:

• OpenAI;

• Anthropic;

• Google;

• lokalen Modellen;

• einem anderen KI-Anbieter.

Das Modell liegt in der Verantwortung des verbundenen MCP-Clients.

Lokale Laufzeit

Externe Anfragen werden während der Synchronisierung der Dokumentation verwendet, nicht bei normalen MCP-Abfragen.

npx tsx scripts/sync-components.ts
        │
        └── Internet necessária

npm run dev
        │
        └── Documentação local

Einfache Suche vor komplexer Infrastruktur

Die aktuelle Suche verwendet ein deterministisches Textranking.

Das Projekt ist nicht abhängig von:

• Embeddings;

• Vektordatenbank;

• RAG-Infrastruktur;

• externem Suchdienst.

Für die aktuelle Dokumentationsmenge hält eine gut strukturierte lokale Suche das Projekt einfacher, vorhersehbarer und schlanker.

Kleine Antworten

Das Tool search_docs gibt relevante Snippets zurück, anstatt ganze Dokumente an das Modell zu senden.

Das hilft, Folgendes zu reduzieren:

• Kontextmenge;

• Token-Verbrauch;

• irrelevante Informationen;

• übermäßig große Antworten.

Wenn das vollständige Dokument benötigt wird, kann der Agent get_component oder die MCP-Resources verwenden.

Roadmap

Abgeschlossen

• MCP-Server mit stdio-Transport

• Auflistung der Komponenten

• Einzelabfrage von Komponenten

• Synchronisierung der GovBR-DS-Dokumentation

• strukturierter Markdown-Parser

• automatische Erzeugung des lokalen Datensatzes

• lokale Suche in der Dokumentation

• Relevanzranking

• Normalisierung portugiesischer Abfragen

• MCP-Resources

• Barrierefreiheits-Resources

• Komponentenkatalog

• MCP-Prompts

• Autovervollständigung von Komponenten in den Prompts

Geplant

• offizielle HTML- und CSS-Implementierungsbeispiele

• Integration mit @govbr-ds/core

• Dokumentation der GovBR-Webkomponenten

• Dokumentation der GovBR-React-Komponenten

• Implementierungsbeispiele pro Komponente

• Validierung von GovBR-DS-Code

• Hilfsfunktionen für die Barrierefreiheitsvalidierung

• Veröffentlichung auf npm

• Veröffentlichung im MCP-Registry

• HTTP-Transport

Verwandtes Projekt

Dieses MCP wurde entwickelt, um die Skill govbr-design-system zu ergänzen.

Die beiden Projekte haben unterschiedliche Verantwortlichkeiten:

govbr-design-system
        │
        └── Instruções, regras e boas práticas
            para orientar agentes de IA

govbr-ds-mcp
        │
        └── Documentação, busca, Resources,
            Tools e Prompts

Sie können zusammen von kompatiblen Agenten verwendet werden.

Konzeptionell:

                    Agente de IA
                         │
             ┌───────────┴───────────┐
             │                       │
           Skill                    MCP
             │                       │
     Como se comportar       O que a documentação diz
     Boas práticas           Componentes
     Regras de uso           Acessibilidade
     Orientações             Busca
                             Resources

So können Sie beitragen

Beiträge sind willkommen.

Einige interessante Bereiche für Beiträge:

• Verbesserung des Dokumentationsparsers;

• Verbesserung der Suchrelevanz;

• Erstellung neuer Tests;

• Unterstützung neuer offizieller GovBR-DS-Quellen;

• Verbesserung der Kompatibilität mit MCP-Clients;

• Unterstützung der offiziellen Bibliotheken;

• Identifizierung nicht dokumentierter Komponenten;

• Korrektur falsch interpretierter Daten.

Bevor Sie einen Pull Request senden:

npm test

Stellen Sie außerdem sicher, dass das Projekt weiterhin den im Repository verwendeten Typecheck/Build besteht.

Hinweis

govbr-ds-mcp ist ein unabhängiges Open-Source-Projekt.

Es wird nicht von der brasilianischen Bundesregierung oder dem für das GovBR Design System verantwortlichen Team gewartet, befürwortet oder offiziell unterstützt.

Die Dokumentation und die Ressourcen von GovBR-DS, die vom Projekt verwendet werden, unterliegen weiterhin den Lizenzen und Bedingungen ihrer jeweiligen Originalprojekte.

Lizenz

Siehe die Datei LICENSE für Informationen zur Lizenz dieses Projekts.