GovBR DS MCP

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:

1. acessa o repositório público do GovBR-DS através da API do GitLab;
2. identifica os componentes documentados;
3. baixa os arquivos Markdown de cada componente;
4. baixa a documentação de acessibilidade quando disponível;
5. interpreta os arquivos Markdown;
6. normaliza os dados;
7. 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

• [x] servidor MCP com transporte stdio
• [x] listagem de componentes
• [x] consulta individual de componentes
• [x] sincronização da documentação GovBR-DS
• [x] parser estruturado de Markdown
• [x] geração automática do dataset local
• [x] busca local na documentação
• [x] ranking de relevância
• [x] normalização de consultas em português
• [x] MCP Resources
• [x] Resources de acessibilidade
• [x] catálogo de componentes
• [x] MCP Prompts
• [x] 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
• [x] 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.