GovBR DS MCP

Open source Model Context Protocol (MCP) server for the Brazilian Federal Government Design System (GovBR-DS).

govbr-ds-mcp provides AI agents with structured access to GovBR-DS documentation, its components, accessibility guidelines, search, Resources, and reusable workflows for development.

The goal is to enable tools such as Codex, Claude Code, Kiro, and other MCP-compatible clients to understand and use the GovBR Design System based on its synchronized official documentation, rather than relying only on the model's prior knowledge.

The package is published on npm as govbr-ds-mcp and can be run directly with:

npx -y govbr-ds-mcp

This is a community and independent project. It is not an official project of the Brazilian Federal Government nor of the team responsible for GovBR-DS.

Why this project?

AI agents can generate frontend code quickly, but they don't always know:

• which GovBR-DS component should be used;

• how a given component should behave;

• which accessibility recommendations apply;

• which usage patterns are recommended;

• where a specific piece of information is located in the GovBR-DS documentation.

govbr-ds-mcp aims to solve this problem by making GovBR-DS documentation available through the 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

The MCP server does not use an LLM internally and does not make external requests during its normal operation.

Related MCP server: PortOne Global MCP Server

Features

Documentation synchronization

The documentation is fetched from the official GovBR-DS repository and transformed into local structured data.

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

The generated data is stored locally, allowing the MCP server to work without internet access after synchronization.

Currently, the project synchronizes 37 documented GovBR-DS components.

MCP Tools

list_components

Lists the GovBR-DS components available in the local documentation index.

Example:

{}

Response:

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

get_component

Returns the complete structured documentation of a specific GovBR-DS component.

Example:

{
  "name": "button"
}

The search is case-insensitive.

The calls below are equivalent:

button
Button
BUTTON

search_docs

Searches within the locally synchronized GovBR-DS documentation.

Example:

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

The search engine supports:

• case-insensitive search;

• accent-insensitive search;

• Portuguese stopword removal;

• component aliases;

• canonicalization of morphological variations;

• prioritization of the identified component;

• ranking by section relevance;

• generation of relevant snippets;

• filtering by component.

Example:

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

The search happens entirely in memory.

The following are not used:

• embeddings;

• vector database;

• Elasticsearch;

• LLM;

• external search services.

MCP Resources

GovBR-DS documentation is also made available through MCP Resources.

Component catalog

govbr-ds://catalog

Provides an index of all synchronized components.

Component documentation

govbr-ds://components/{slug}

Example:

govbr-ds://components/button

Returns the complete component documentation in Markdown.

Accessibility documentation

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

Example:

govbr-ds://components/button/accessibility

Returns the accessibility guidelines available for the component.

Not all GovBR-DS components have specific accessibility documentation.

The Resources are generated entirely from locally synchronized data.

MCP Prompts

The server provides reusable Prompts for common development workflows with GovBR-DS.

implement_govbr_component

Provides the synchronized official documentation of a component and instructions to assist its implementation.

Example:

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

The Prompt provides the model with the relevant component documentation so that the implementation is grounded in GovBR-DS.

review_govbr_component

Provides the component documentation along with a code snippet that should be reviewed.

Example:

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

The review can then compare the provided implementation with the guidelines available in the synchronized documentation.

check_govbr_accessibility

Provides the accessibility guidelines of a component to assist in reviewing an implementation.

Example:

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

The MCP server does not execute or interpret the received code.

The code is treated only as text and made available as context for the connected model.

Architecture

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

The main application flow is:

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

Quick start

• Node.js 22+

• npm

There is no need to clone or install the package globally. MCP clients can start the published server directly via npx:

npx -y govbr-ds-mcp

The server uses the MCP stdio transport and works with the GovBR-DS data included in the package, without HTTP calls during queries.

Configuration in MCP clients

Claude Desktop

Add the server to the Claude Desktop configuration file:

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

After saving the file, restart Claude Desktop.

See also the Claude MCP documentation.

Claude Code

Register the server from the terminal:

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

Use claude mcp list to confirm the registration.

Codex

Add to the ~/.codex/config.toml file:

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

It is also possible to register from the terminal:

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

Restart Codex after manually changing the configuration.

See also the Codex MCP documentation.

Kiro

In Kiro, open or create .kiro/settings/mcp.json in the workspace. To make the server available globally, use ~/.kiro/settings/mcp.json:

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

After saving, open the Kiro MCP panel and confirm that govbr-ds is connected.

See also the Kiro MCP documentation.

Local development

Clone the repository and install the dependencies:

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

Running the MCP server

Start the server in development mode:

npm run dev

The server uses the MCP stdio transport.

Since stdout is reserved for MCP protocol communication, application logs must be sent to stderr.

Avoid:

console.log("Servidor iniciado");

Prefer:

console.error("Servidor iniciado");

MCP Inspector

The project can be tested using the MCP Inspector.

Run:

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

In the Inspector you can test the available features.

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

Synchronizing the GovBR-DS documentation

To update the local index:

npx tsx scripts/sync-components.ts

The synchronization process:

1. accesses the public GovBR-DS repository through the GitLab API;

2. identifies the documented components;

3. downloads the Markdown files of each component;

4. downloads the accessibility documentation when available;

5. parses the Markdown files;

6. normalizes the data;

7. generates the local dataset used by the MCP.

The generated data is stored in:

src/data/components.generated.ts

The file is generated automatically and should not be edited manually.

During normal operation, the MCP server does not query GitLab.

This allows using the Tools, Resources, Prompts, and search even without an internet connection.

Running the tests

Run:

npm test

The test suite covers areas such as:

• Markdown parsing;

• component search;

• case-insensitive search;

• accent normalization;

• aliases;

• canonicalization;

• search ranking;

• snippet generation;

• MCP Tools;

• MCP Resources;

• MCP Prompts;

• documentation formatting;

• handling of non-existent components.

The unit tests do not depend on GitLab availability.

Development

Install the dependencies:

npm install

Run the server:

npm run dev

Run the tests:

npm test

Update the local documentation:

npx tsx scripts/sync-components.ts

Open the MCP Inspector:

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

Data source

The documentation used by this project is obtained from the official GovBR Design System repository:

GovBR-DS

The current ingestion process mainly uses:

ds/componentes/

Component documentation usually has a structure similar to:

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

The main file generally contains information such as:

• description;

• usage;

• anatomy;

• types;

• behavior;

• specifications.

When available, the *-access.md file contains the specific accessibility guidelines.

Not all components have exactly the same set of files.

The synchronization process was designed to handle these differences without interrupting dataset generation.

Project principles

Official documentation first

Whenever possible, the information provided by the MCP should be grounded in the synchronized official GovBR-DS documentation.

The goal is to reduce situations where an AI agent invents a rule or behavior that does not exist in the Design System.

LLM-independent

The MCP server does not depend on:

• OpenAI;

• Anthropic;

• Google;

• local models;

• any other AI provider.

The model is the responsibility of the connected MCP client.

Local runtime

External requests are used during documentation synchronization, not during normal MCP queries.

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

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

Simple search before complex infrastructure

The current search uses deterministic textual ranking.

The project does not depend on:

• embeddings;

• vector database;

• RAG infrastructure;

• external search service.

For the current amount of documentation, a well-structured local search keeps the project simpler, more predictable, and lighter.

Small responses

The search_docs Tool returns relevant snippets instead of sending entire documents to the model.

This helps reduce:

• context size;

• token consumption;

• irrelevant information;

• excessively large responses.

When the full document is needed, the agent can use get_component or the MCP Resources.

Roadmap

Completed

• MCP server with stdio transport

• component listing

• individual component query

• GovBR-DS documentation synchronization

• structured Markdown parser

• automatic local dataset generation

• local documentation search

• relevance ranking

• Portuguese query normalization

• MCP Resources

• accessibility Resources

• component catalog

• MCP Prompts

• component autocomplete in Prompts

Planned

• official HTML and CSS implementation examples

• integration with @govbr-ds/core

• GovBR Web Components documentation

• GovBR React Components documentation

• implementation examples per component

• GovBR-DS code validation

• accessibility validation helpers

• npm publication

• MCP Registry publication

• HTTP transport

Related project

This MCP was developed to complement the govbr-design-system skill.

The two projects have different responsibilities:

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

They can be used together by compatible agents.

Conceptually:

                    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

How to contribute

Contributions are welcome.

Some interesting areas for contribution:

• documentation parser improvement;

• search relevance improvement;

• creation of new tests;

• support for new official GovBR-DS sources;

• improved compatibility with MCP clients;

• support for the official libraries;

• identification of undocumented components;

• correction of incorrectly parsed data.

Before submitting a Pull Request:

npm test

Also confirm that the project still passes the typecheck/build used in the repository.

Disclaimer

govbr-ds-mcp is an independent open source project.

It is not maintained, endorsed, or officially supported by the Brazilian Federal Government or by the team responsible for the GovBR Design System.

The documentation and resources of GovBR-DS used by the project remain subject to the licenses and terms of their respective original projects.

License

See the LICENSE file for information about this project's license.