GovBR-DS MCP

{"type": "text"}# GovBR DS MCP

Servidor Model Context Protocol (MCP) de código abierto para el Design System del Gobierno Federal Brasileño (GovBR-DS).

El govbr-ds-mcp proporciona a agentes de IA acceso estructurado a la documentación de GovBR-DS, sus componentes, orientaciones de accesibilidad, búsqueda, Resources y flujos de trabajo reutilizables para desarrollo.

El objetivo es permitir que herramientas como Codex, Claude Code, Kiro y otros clientes compatibles con MCP comprendan y utilicen el GovBR Design System basándose en su documentación oficial sincronizada, en lugar de depender únicamente del conocimiento previo del modelo.

El paquete está publicado en npm como govbr-ds-mcp y se puede ejecutar directamente con:

npx -y govbr-ds-mcp

Este es un proyecto comunitario e independiente. No es un proyecto oficial del Gobierno Federal Brasileño ni del equipo responsable de GovBR-DS.

¿Por qué este proyecto?

Los agentes de IA pueden generar código frontend rápidamente, pero no siempre saben:

• qué componente de GovBR-DS debe utilizarse;

• cómo debe comportarse un componente determinado;

• qué recomendaciones de accesibilidad se aplican;

• qué estándares de uso se recomiendan;

• dónde se encuentra una información específica en la documentación de GovBR-DS.

El govbr-ds-mcp busca resolver este problema poniendo a disposición la documentación de GovBR-DS a través del Model Context Protocol.

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

El servidor MCP no utiliza un LLM internamente y no realiza solicitudes externas durante su ejecución normal.

Related MCP server: PortOne Global MCP Server

Funcionalidades

Sincronización de la documentación

La documentación se obtiene del repositorio oficial de GovBR-DS y se transforma en datos estructurados locales.

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

Los datos generados se almacenan localmente, lo que permite que el servidor MCP funcione sin acceso a internet después de la sincronización.

Actualmente, el proyecto sincroniza 37 componentes documentados de GovBR-DS.

Tools MCP

list_components

Lista los componentes de GovBR-DS disponibles en el índice local de la documentación.

Ejemplo:

{}

Respuesta:

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

get_component

Devuelve la documentación estructurada completa de un componente específico de GovBR-DS.

Ejemplo:

{
  "name": "button"
}

La búsqueda no distingue entre mayúsculas y minúsculas.

Las siguientes llamadas son equivalentes:

button
Button
BUTTON

search_docs

Busca dentro de la documentación de GovBR-DS sincronizada localmente.

Ejemplo:

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

El mecanismo de búsqueda tiene soporte para:

• búsqueda sin distinción de mayúsculas y minúsculas;

• búsqueda sin diferenciación de acentos;

• eliminación de stopwords en portugués;

• alias de componentes;

• canonicalización de variaciones morfológicas;

• priorización del componente identificado;

• ranking por relevancia de secciones;

• generación de snippets relevantes;

• filtro por componente.

Ejemplo:

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

La búsqueda se realiza completamente en memoria.

No se utilizan:

• embeddings;

• base vectorial;

• Elasticsearch;

• LLM;

• servicios de búsqueda externos.

Resources MCP

La documentación de GovBR-DS también se pone a disposición a través de MCP Resources.

Catálogo de componentes

govbr-ds://catalog

Proporciona un índice de todos los componentes sincronizados.

Documentación de componente

govbr-ds://components/{slug}

Ejemplo:

govbr-ds://components/button

Devuelve la documentación completa del componente en Markdown.

Documentación de accesibilidad

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

Ejemplo:

govbr-ds://components/button/accessibility

Devuelve las orientaciones de accesibilidad disponibles para el componente.

No todos los componentes de GovBR-DS tienen documentación específica de accesibilidad.

Los Resources se generan íntegramente a partir de los datos sincronizados localmente.

Prompts MCP

El servidor pone a disposición Prompts reutilizables para flujos de trabajo comunes de desarrollo con GovBR-DS.

implement_govbr_component

Proporciona la documentación oficial sincronizada de un componente e instrucciones para ayudar en su implementación.

Ejemplo:

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

El Prompt proporciona al modelo la documentación relevante del componente para que la implementación se base en GovBR-DS.

review_govbr_component

Proporciona la documentación del componente junto con un fragmento de código que debe revisarse.

Ejemplo:

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

La revisión puede entonces comparar la implementación proporcionada con las orientaciones disponibles en la documentación sincronizada.

check_govbr_accessibility

Proporciona las orientaciones de accesibilidad de un componente para ayudar en la revisión de una implementación.

Ejemplo:

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

El servidor MCP no ejecuta ni interpreta el código recibido.

El código se trata solo como texto y se pone a disposición como contexto para el modelo conectado.

Arquitectura

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

El flujo principal de la aplicación es:

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

Uso rápido

• Node.js 22+

• npm

No es necesario clonar ni instalar el paquete globalmente. Los clientes MCP pueden iniciar el servidor publicado directamente vía npx:

npx -y govbr-ds-mcp

El servidor utiliza el transporte MCP stdio y funciona con los datos de GovBR-DS incluidos en el paquete, sin llamadas HTTP durante las consultas.

Configuración en los clientes MCP

Claude Desktop

Agregue el servidor al archivo de configuración de Claude Desktop:

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

Después de guardar el archivo, reinicie Claude Desktop.

Consulte también la documentación MCP de Claude.

Claude Code

Registre el servidor desde la terminal:

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

Use claude mcp list para confirmar el registro.

Codex

Agregue al archivo ~/.codex/config.toml:

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

También es posible registrarlo desde la terminal:

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

Reinicie Codex después de modificar manualmente la configuración.

Consulte también la documentación MCP de Codex.

Kiro

En Kiro, abra o cree .kiro/settings/mcp.json en el workspace. Para poner el servidor a disposición globalmente, use ~/.kiro/settings/mcp.json:

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

Después de guardar, abra el panel MCP de Kiro y confirme que govbr-ds está conectado.

Consulte también la documentación MCP de Kiro.

Desarrollo local

Clone el repositorio e instale las dependencias:

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

Ejecutando el servidor MCP

Inicie el servidor en modo de desarrollo:

npm run dev

El servidor utiliza el transporte MCP stdio.

Como el stdout está reservado para la comunicación del protocolo MCP, los registros de la aplicación deben enviarse a stderr.

Evite:

console.log("Servidor iniciado");

Prefiera:

console.error("Servidor iniciado");

MCP Inspector

El proyecto se puede probar utilizando el MCP Inspector.

Ejecute:

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

En el Inspector es posible probar las funcionalidades disponibles.

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

Sincronizando la documentación de GovBR-DS

Para actualizar el índice local:

npx tsx scripts/sync-components.ts

El proceso de sincronización:

1. accede al repositorio público de GovBR-DS a través de la API de GitLab;

2. identifica los componentes documentados;

3. descarga los archivos Markdown de cada componente;

4. descarga la documentación de accesibilidad cuando está disponible;

5. interpreta los archivos Markdown;

6. normaliza los datos;

7. genera el dataset local utilizado por el MCP.

Los datos generados se almacenan en:

src/data/components.generated.ts

El archivo se genera automáticamente y no debe editarse manualmente.

Durante la ejecución normal, el servidor MCP no consulta GitLab.

Esto permite utilizar las Tools, Resources, Prompts y la búsqueda incluso sin conexión a internet.

Ejecutando las pruebas

Ejecute:

npm test

La suite de pruebas cubre áreas como:

• análisis de Markdown;

• búsqueda de componentes;

• búsqueda sin distinción de mayúsculas y minúsculas;

• normalización de acentos;

• alias;

• canonicalización;

• ranking de búsqueda;

• generación de snippets;

• MCP Tools;

• MCP Resources;

• MCP Prompts;

• formato de la documentación;

• manejo de componentes inexistentes.

Las pruebas unitarias no dependen de la disponibilidad de GitLab.

Desarrollo

Instale las dependencias:

npm install

Ejecute el servidor:

npm run dev

Ejecute las pruebas:

npm test

Actualice la documentación local:

npx tsx scripts/sync-components.ts

Abra el MCP Inspector:

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

Fuente de datos

La documentación utilizada por este proyecto se obtiene del repositorio oficial del GovBR Design System:

GovBR-DS

El proceso actual de ingesta utiliza principalmente:

ds/componentes/

La documentación de los componentes normalmente tiene una estructura similar a:

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

El archivo principal generalmente contiene información como:

• descripción;

• uso;

• anatomía;

• tipos;

• comportamiento;

• especificaciones.

Cuando está disponible, el archivo *-access.md contiene las orientaciones específicas de accesibilidad.

No todos los componentes tienen exactamente el mismo conjunto de archivos.

El proceso de sincronización se desarrolló para manejar estas diferencias sin interrumpir la generación del dataset.

Principios del proyecto

Documentación oficial primero

Siempre que sea posible, la información proporcionada por el MCP debe basarse en la documentación oficial sincronizada de GovBR-DS.

El objetivo es reducir situaciones en las que un agente de IA inventa una regla o comportamiento que no existe en el Design System.

Independiente de LLM

El servidor MCP no depende de:

• OpenAI;

• Anthropic;

• Google;

• modelos locales;

• cualquier otro proveedor de IA.

El modelo es responsabilidad del cliente MCP conectado.

Runtime local

Las solicitudes externas se utilizan durante la sincronización de la documentación, y no durante las consultas normales al MCP.

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

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

Búsqueda simple antes que infraestructura compleja

La búsqueda actual utiliza ranking textual determinista.

El proyecto no depende de:

• embeddings;

• base vectorial;

• infraestructura RAG;

• servicio de búsqueda externo.

Para la cantidad actual de documentación, una búsqueda local bien estructurada mantiene el proyecto más simple, predecible y ligero.

Respuestas pequeñas

La Tool search_docs devuelve snippets relevantes en lugar de enviar documentos completos al modelo.

Esto ayuda a reducir:

• cantidad de contexto;

• consumo de tokens;

• información irrelevante;

• respuestas excesivamente grandes.

Cuando se necesita el documento completo, el agente puede utilizar get_component o los MCP Resources.

Roadmap

Completado

• servidor MCP con transporte stdio

• listado de componentes

• consulta individual de componentes

• sincronización de la documentación de GovBR-DS

• parser estructurado de Markdown

• generación automática del dataset local

• búsqueda local en la documentación

• ranking de relevancia

• normalización de consultas en portugués

• MCP Resources

• Resources de accesibilidad

• catálogo de componentes

• MCP Prompts

• autocompletado de componentes en los Prompts

Planificado

• ejemplos oficiales de implementación HTML y CSS

• integración con @govbr-ds/core

• documentación de los GovBR Web Components

• documentación de los GovBR React Components

• ejemplos de implementación por componente

• validación de código GovBR-DS

• helpers para validación de accesibilidad

• publicación en npm

• publicación en el MCP Registry

• transporte HTTP

Proyecto relacionado

Este MCP se desarrolló para complementar la skill govbr-design-system.

Los dos proyectos tienen responsabilidades diferentes:

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

Pueden utilizarse juntos por agentes compatibles.

Conceptualmente:

                    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

Cómo contribuir

Las contribuciones son bienvenidas.

Algunas áreas interesantes para contribuir:

• mejora del parser de documentación;

• mejora de la relevancia de la búsqueda;

• creación de nuevas pruebas;

• soporte para nuevas fuentes oficiales de GovBR-DS;

• mejora de la compatibilidad con clientes MCP;

• soporte para las bibliotecas oficiales;

• identificación de componentes no documentados;

• corrección de datos interpretados incorrectamente.

Antes de enviar un Pull Request:

npm test

También confirme que el proyecto continúa pasando el typecheck/build utilizado en el repositorio.

Aviso

El govbr-ds-mcp es un proyecto de código abierto independiente.

No está mantenido, respaldado ni soportado oficialmente por el Gobierno Federal Brasileño ni por el equipo responsable del GovBR Design System.

La documentación y los recursos de GovBR-DS utilizados por el proyecto siguen sujetos a las licencias y términos de sus respectivos proyectos originales.

Licencia

Consulte el archivo LICENSE para obtener información sobre la licencia de este proyecto.