GovBR DS MCP

M8ven Score npm version npm license

Servidor Model Context Protocol (MCP) open source para o Design System do Governo Federal Brasileiro (GovBR-DS).

O govbr-ds-mcp fornece a agentes de IA acesso estruturado à documentação do GovBR-DS, seus componentes, orientações de acessibilidade, busca, Resources e workflows reutilizáveis para desenvolvimento.

O objetivo é permitir que ferramentas como Codex, Claude Code, Kiro e outros clientes compatíveis com MCP compreendam e utilizem o GovBR Design System com base em sua documentação oficial sincronizada, em vez de depender apenas do conhecimento prévio do modelo.

O pacote está publicado no npm como govbr-ds-mcp e pode ser executado diretamente com:

npx -y govbr-ds-mcp

Este é um projeto comunitário e independente. Não é um projeto oficial do Governo Federal Brasileiro nem da equipe responsável pelo GovBR-DS.

Por que este projeto?

Agentes de IA conseguem gerar código de frontend rapidamente, mas nem sempre sabem:

qual componente GovBR-DS deve ser utilizado;
como determinado componente deve se comportar;
quais recomendações de acessibilidade se aplicam;
quais padrões de uso são recomendados;
onde uma informação específica está localizada na documentação do GovBR-DS.

O govbr-ds-mcp busca resolver esse problema disponibilizando a documentação do GovBR-DS por meio do 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

O servidor MCP não utiliza um LLM internamente e não realiza requisições externas durante sua execução normal.

Funcionalidades

Sincronização da documentação

A documentação é obtida do repositório oficial do GovBR-DS e transformada em dados estruturados locais.

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

Os dados gerados são armazenados localmente, permitindo que o servidor MCP funcione sem acesso à internet depois da sincronização.

Atualmente, o projeto sincroniza 37 componentes documentados do GovBR-DS.

Tools MCP

`list_components`

Lista os componentes GovBR-DS disponíveis no índice local da documentação.

Exemplo:

{}

Resposta:

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

`get_component`

Retorna a documentação estruturada completa de um componente específico do GovBR-DS.

Exemplo:

{
  "name": "button"
}

A busca não diferencia letras maiúsculas e minúsculas.

As chamadas abaixo são equivalentes:

button
Button
BUTTON

`search_docs`

Pesquisa dentro da documentação GovBR-DS sincronizada localmente.

Exemplo:

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

O mecanismo de busca possui suporte a:

busca case-insensitive;
busca sem diferenciação de acentos;
remoção de stopwords em português;
aliases de componentes;
canonicalização de variações morfológicas;
priorização do componente identificado;
ranking por relevância de seções;
geração de snippets relevantes;
filtro por componente.

Exemplo:

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

A busca acontece inteiramente em memória.

Não são utilizados:

embeddings;
banco vetorial;
Elasticsearch;
LLM;
serviços externos de busca.

Resources MCP

A documentação do GovBR-DS também é disponibilizada através de MCP Resources.

Catálogo de componentes

govbr-ds://catalog

Disponibiliza um índice de todos os componentes sincronizados.

Documentação de componente

govbr-ds://components/{slug}

Exemplo:

govbr-ds://components/button

Retorna a documentação completa do componente em Markdown.

Documentação de acessibilidade

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

Exemplo:

govbr-ds://components/button/accessibility

Retorna as orientações de acessibilidade disponíveis para o componente.

Nem todos os componentes do GovBR-DS possuem documentação específica de acessibilidade.

Os Resources são gerados inteiramente a partir dos dados sincronizados localmente.

Prompts MCP

O servidor disponibiliza Prompts reutilizáveis para workflows comuns de desenvolvimento com GovBR-DS.

`implement_govbr_component`

Fornece a documentação oficial sincronizada de um componente e instruções para auxiliar sua implementação.

Exemplo:

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

O Prompt fornece ao modelo a documentação relevante do componente para que a implementação seja fundamentada no GovBR-DS.

`review_govbr_component`

Fornece a documentação do componente juntamente com um trecho de código que deve ser revisado.

Exemplo:

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

A revisão pode então comparar a implementação fornecida com as orientações disponíveis na documentação sincronizada.

`check_govbr_accessibility`

Fornece as orientações de acessibilidade de um componente para auxiliar na revisão de uma implementação.

Exemplo:

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

O servidor MCP não executa nem interpreta o código recebido.

O código é tratado somente como texto e disponibilizado como contexto para o modelo conectado.

Arquitetura

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

O fluxo principal da aplicação é:

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

Uso rápido

Node.js 22+
npm

Não é necessário clonar ou instalar o pacote globalmente. Clientes MCP podem iniciar o servidor publicado diretamente via npx:

npx -y govbr-ds-mcp

O servidor utiliza o transporte MCP stdio e funciona com os dados GovBR-DS incluídos no pacote, sem chamadas HTTP durante as consultas.

Configuração nos clientes MCP

Claude Desktop

Adicione o servidor ao arquivo de configuração do Claude Desktop:

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

Depois de salvar o arquivo, reinicie o Claude Desktop.

Consulte também a documentação MCP do Claude.

Claude Code

Registre o servidor pelo terminal:

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

Use claude mcp list para confirmar o registro.

Codex

Adicione ao arquivo ~/.codex/config.toml:

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

Também é possível registrar pelo terminal:

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

Reinicie o Codex depois de alterar manualmente a configuração.

Consulte também a documentação MCP do Codex.

Kiro

No Kiro, abra ou crie .kiro/settings/mcp.json no workspace. Para disponibilizar o servidor globalmente, use ~/.kiro/settings/mcp.json:

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

Após salvar, abra o painel MCP do Kiro e confirme que govbr-ds está conectado.

Consulte também a documentação MCP do Kiro.

Desenvolvimento local

Clone o repositório e instale as dependências:

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

Executando o servidor MCP

Inicie o servidor em modo de desenvolvimento:

npm run dev

O servidor utiliza o transporte MCP stdio.

Como o stdout é reservado para a comunicação do protocolo MCP, logs da aplicação devem ser enviados para stderr.

Evite:

console.log("Servidor iniciado");

Prefira:

console.error("Servidor iniciado");

MCP Inspector

O projeto pode ser testado utilizando o MCP Inspector.

Execute:

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

No Inspector é possível testar as funcionalidades disponíveis.

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 a documentação do GovBR-DS

Para atualizar o índice local:

npx tsx scripts/sync-components.ts

O processo de sincronização:

acessa o repositório público do GovBR-DS através da API do GitLab;
identifica os componentes documentados;
baixa os arquivos Markdown de cada componente;
baixa a documentação de acessibilidade quando disponível;
interpreta os arquivos Markdown;
normaliza os dados;
gera o dataset local utilizado pelo MCP.

Os dados gerados são armazenados em:

src/data/components.generated.ts

O arquivo é gerado automaticamente e não deve ser editado manualmente.

Durante a execução normal, o servidor MCP não consulta o GitLab.

Isso permite utilizar as Tools, Resources, Prompts e busca mesmo sem conexão com a internet.

Executando os testes

Execute:

npm test

A suíte de testes cobre áreas como:

parsing de Markdown;
busca de componentes;
busca case-insensitive;
normalização de acentos;
aliases;
canonicalização;
ranking da busca;
geração de snippets;
MCP Tools;
MCP Resources;
MCP Prompts;
formatação da documentação;
tratamento de componentes inexistentes.

Os testes unitários não dependem da disponibilidade do GitLab.

Desenvolvimento

Instale as dependências:

npm install

Execute o servidor:

npm run dev

Execute os testes:

npm test

Atualize a documentação local:

npx tsx scripts/sync-components.ts

Abra o MCP Inspector:

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

Fonte dos dados

A documentação utilizada por este projeto é obtida do repositório oficial do GovBR Design System:

GovBR-DS

O processo atual de ingestão utiliza principalmente:

ds/componentes/

A documentação dos componentes normalmente possui uma estrutura semelhante a:

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

O arquivo principal geralmente contém informações como:

descrição;
uso;
anatomia;
tipos;
comportamento;
especificações.

Quando disponível, o arquivo *-access.md contém as orientações específicas de acessibilidade.

Nem todos os componentes possuem exatamente o mesmo conjunto de arquivos.

O processo de sincronização foi desenvolvido para lidar com essas diferenças sem interromper a geração do dataset.

Princípios do projeto

Documentação oficial primeiro

Sempre que possível, as informações fornecidas pelo MCP devem estar fundamentadas na documentação oficial sincronizada do GovBR-DS.

O objetivo é reduzir situações em que um agente de IA inventa uma regra ou comportamento que não existe no Design System.

Independente de LLM

O servidor MCP não depende de:

OpenAI;
Anthropic;
Google;
modelos locais;
qualquer outro fornecedor de IA.

O modelo é responsabilidade do cliente MCP conectado.

Runtime local

Requisições externas são utilizadas durante a sincronização da documentação, e não durante consultas normais ao MCP.

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

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

Busca simples antes de infraestrutura complexa

A busca atual utiliza ranking textual determinístico.

O projeto não depende de:

embeddings;
banco vetorial;
infraestrutura de RAG;
serviço externo de pesquisa.

Para a quantidade atual de documentação, uma busca local bem estruturada mantém o projeto mais simples, previsível e leve.

Respostas pequenas

A Tool search_docs retorna snippets relevantes em vez de enviar documentos inteiros para o modelo.

Isso ajuda a reduzir:

quantidade de contexto;
consumo de tokens;
informações irrelevantes;
respostas excessivamente grandes.

Quando o documento completo for necessário, o agente pode utilizar get_component ou os MCP Resources.

Roadmap

Concluído

servidor MCP com transporte stdio
listagem de componentes
consulta individual de componentes
sincronização da documentação GovBR-DS
parser estruturado de Markdown
geração automática do dataset local
busca local na documentação
ranking de relevância
normalização de consultas em português
MCP Resources
Resources de acessibilidade
catálogo de componentes
MCP Prompts
autocomplete de componentes nos Prompts

Planejado

exemplos oficiais de implementação HTML e CSS
integração com @govbr-ds/core
documentação dos GovBR Web Components
documentação dos GovBR React Components
exemplos de implementação por componente
validação de código GovBR-DS
helpers para validação de acessibilidade
publicação no npm
publicação no MCP Registry
transporte HTTP

Projeto relacionado

Este MCP foi desenvolvido para complementar a skill govbr-design-system.

Os dois projetos possuem 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

Eles podem ser utilizados juntos por agentes compatíveis.

Conceitualmente:

                    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

Como contribuir

Contribuições são bem-vindas.

Algumas áreas interessantes para contribuição:

melhoria do parser de documentação;
melhoria da relevância da busca;
criação de novos testes;
suporte a novas fontes oficiais do GovBR-DS;
melhoria da compatibilidade com clientes MCP;
suporte às bibliotecas oficiais;
identificação de componentes não documentados;
correção de dados interpretados incorretamente.

Antes de enviar um Pull Request:

npm test

Também confirme que o projeto continua passando pelo typecheck/build utilizado no repositório.

Aviso

O govbr-ds-mcp é um projeto open source independente.

Ele não é mantido, endossado ou oficialmente suportado pelo Governo Federal Brasileiro ou pela equipe responsável pelo GovBR Design System.

A documentação e os recursos do GovBR-DS utilizados pelo projeto continuam sujeitos às licenças e termos de seus respectivos projetos originais.

Licença

Consulte o arquivo LICENSE para informações sobre a licença deste projeto.