GovBR DS MCP

Сервер Model Context Protocol (MCP) с открытым исходным кодом для Дизайн-системы Федерального правительства Бразилии (GovBR-DS).

govbr-ds-mcp предоставляет ИИ-агентам структурированный доступ к документации GovBR-DS, её компонентам, рекомендациям по доступности, поиску, Resources и переиспользуемым рабочим процессам для разработки.

Цель — позволить таким инструментам, как Codex, Claude Code, Kiro и другим клиентам, совместимым с MCP, понимать и использовать GovBR Design System на основе его синхронизированной официальной документации, а не только полагаться на предварительные знания модели.

Пакет опубликован в npm как govbr-ds-mcp и может запускаться напрямую с помощью:

npx -y govbr-ds-mcp

Это общественный и независимый проект. Он не является официальным проектом Федерального правительства Бразилии или команды, ответственной за GovBR-DS.

Зачем нужен этот проект?

ИИ-агенты умеют быстро генерировать фронтенд-код, но не всегда знают:

• какой компонент GovBR-DS следует использовать;

• как должен вести себя тот или иной компонент;

• какие рекомендации по доступности применимы;

• какие паттерны использования рекомендуются;

• где в документации GovBR-DS находится конкретная информация.

govbr-ds-mcp призван решить эту проблему, предоставляя документацию GovBR-DS через 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

Сервер MCP не использует LLM внутри себя и не выполняет внешних запросов во время обычной работы.

Related MCP server: PortOne Global MCP Server

Возможности

Синхронизация документации

Документация получается из официального репозитория GovBR-DS и преобразуется в локальные структурированные данные.

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

Сгенерированные данные хранятся локально, что позволяет серверу MCP работать без доступа к интернету после синхронизации.

В настоящее время проект синхронизирует 37 документированных компонентов GovBR-DS.

MCP Tools

list_components

Выводит список доступных компонентов GovBR-DS в локальном индексе документации.

Пример:

{}

Ответ:

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

get_component

Возвращает полную структурированную документацию конкретного компонента GovBR-DS.

Пример:

{
  "name": "button"
}

Поиск не различает прописные и строчные буквы.

Следующие вызовы эквивалентны:

button
Button
BUTTON

search_docs

Выполняет поиск по локально синхронизированной документации GovBR-DS.

Пример:

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

Поисковый механизм поддерживает:

• поиск без учёта регистра;

• поиск без учёта диакритических знаков;

• удаление стоп-слов на португальском языке;

• алиасы компонентов;

• канонизацию морфологических вариаций;

• приоритизацию идентифицированного компонента;

• ранжирование по релевантности разделов;

• генерацию релевантных сниппетов;

• фильтр по компоненту.

Пример:

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

Поиск полностью выполняется в памяти.

Не используются:

• эмбеддинги;

• векторная база данных;

• Elasticsearch;

• LLM;

• внешние поисковые сервисы.

MCP Resources

Документация GovBR-DS также доступна через MCP Resources.

Каталог компонентов

govbr-ds://catalog

Предоставляет индекс всех синхронизированных компонентов.

Документация компонента

govbr-ds://components/{slug}

Пример:

govbr-ds://components/button

Возвращает полную документацию компонента в формате Markdown.

Документация по доступности

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

Пример:

govbr-ds://components/button/accessibility

Возвращает доступные рекомендации по доступности для компонента.

Не все компоненты GovBR-DS имеют специальную документацию по доступности.

Resources полностью генерируются из локально синхронизированных данных.

MCP Prompts

Сервер предоставляет переиспользуемые Prompts для типовых рабочих процессов разработки с GovBR-DS.

implement_govbr_component

Предоставляет официальную синхронизированную документацию компонента и инструкции для помощи в его реализации.

Пример:

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

Prompt предоставляет модели релевантную документацию компонента, чтобы реализация была основана на GovBR-DS.

review_govbr_component

Предоставляет документацию компонента вместе с фрагментом кода, который необходимо проверить.

Пример:

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

Проверка может затем сравнить предоставленную реализацию с рекомендациями, доступными в синхронизированной документации.

check_govbr_accessibility

Предоставляет рекомендации по доступности компонента для помощи в проверке реализации.

Пример:

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

Сервер MCP не выполняет и не интерпретирует полученный код.

Код обрабатывается только как текст и предоставляется в качестве контекста для подключённой модели.

Архитектура

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

Основной поток приложения:

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

Быстрый старт

• Node.js 22+

• npm

Нет необходимости клонировать или устанавливать пакет глобально. MCP-клиенты могут запускать опубликованный сервер напрямую через npx:

npx -y govbr-ds-mcp

Сервер использует MCP-транспорт stdio и работает с данными GovBR-DS, включёнными в пакет, без HTTP-вызовов во время запросов.

Настройка в MCP-клиентах

Claude Desktop

Добавьте сервер в файл конфигурации Claude Desktop:

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

После сохранения файла перезапустите Claude Desktop.

См. также документацию MCP для Claude.

Claude Code

Зарегистрируйте сервер через терминал:

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

Используйте claude mcp list, чтобы подтвердить регистрацию.

Codex

Добавьте в файл ~/.codex/config.toml:

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

Также можно зарегистрировать через терминал:

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

Перезапустите Codex после ручного изменения конфигурации.

См. также документацию MCP для Codex.

Kiro

В Kiro откройте или создайте .kiro/settings/mcp.json в рабочей области. Чтобы сделать сервер доступным глобально, используйте ~/.kiro/settings/mcp.json:

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

После сохранения откройте панель MCP в Kiro и убедитесь, что govbr-ds подключён.

См. также документацию MCP для Kiro.

Локальная разработка

Клонируйте репозиторий и установите зависимости:

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

Запуск сервера MCP

Запустите сервер в режиме разработки:

npm run dev

Сервер использует MCP-транспорт stdio.

Поскольку stdout зарезервирован для связи по протоколу MCP, логи приложения должны отправляться в stderr.

Избегайте:

console.log("Servidor iniciado");

Предпочитайте:

console.error("Servidor iniciado");

MCP Inspector

Проект можно протестировать с помощью MCP Inspector.

Выполните:

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

В Inspector можно протестировать доступные функции.

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

Синхронизация документации GovBR-DS

Для обновления локального индекса:

npx tsx scripts/sync-components.ts

Процесс синхронизации:

1. обращается к публичному репозиторию GovBR-DS через API GitLab;

2. определяет документированные компоненты;

3. загружает Markdown-файлы каждого компонента;

4. загружает документацию по доступности, если она доступна;

5. интерпретирует Markdown-файлы;

6. нормализует данные;

7. генерирует локальный набор данных, используемый MCP.

Сгенерированные данные хранятся в:

src/data/components.generated.ts

Файл генерируется автоматически и не должен редактироваться вручную.

Во время обычной работы сервер MCP не обращается к GitLab.

Это позволяет использовать Tools, Resources, Prompts и поиск даже без подключения к интернету.

Запуск тестов

Выполните:

npm test

Набор тестов покрывает такие области, как:

• разбор Markdown;

• поиск компонентов;

• поиск без учёта регистра;

• нормализация диакритических знаков;

• алиасы;

• канонизация;

• ранжирование поиска;

• генерация сниппетов;

• MCP Tools;

• MCP Resources;

• MCP Prompts;

• форматирование документации;

• обработка несуществующих компонентов.

Модульные тесты не зависят от доступности GitLab.

Разработка

Установите зависимости:

npm install

Запустите сервер:

npm run dev

Запустите тесты:

npm test

Обновите локальную документацию:

npx tsx scripts/sync-components.ts

Откройте MCP Inspector:

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

Источник данных

Документация, используемая этим проектом, получена из официального репозитория GovBR Design System:

GovBR-DS

Текущий процесс загрузки в основном использует:

ds/componentes/

Документация компонентов обычно имеет структуру, похожую на:

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

Основной файл обычно содержит такую информацию, как:

• описание;

• использование;

• анатомия;

• типы;

• поведение;

• спецификации.

Если доступен, файл *-access.md содержит специальные рекомендации по доступности.

Не все компоненты имеют одинаковый набор файлов.

Процесс синхронизации разработан для обработки этих различий без прерывания генерации набора данных.

Принципы проекта

Сначала официальная документация

Когда это возможно, информация, предоставляемая MCP, должна основываться на синхронизированной официальной документации GovBR-DS.

Цель — уменьшить ситуации, когда ИИ-агент выдумывает правило или поведение, которого нет в Дизайн-системе.

Независимость от LLM

Сервер MCP не зависит от:

• OpenAI;

• Anthropic;

• Google;

• локальных моделей;

• любого другого поставщика ИИ.

Модель является ответственностью подключённого MCP-клиента.

Локальный рантайм

Внешние запросы используются во время синхронизации документации, а не во время обычных запросов к MCP.

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

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

Простой поиск вместо сложной инфраструктуры

Текущий поиск использует детерминированное текстовое ранжирование.

Проект не зависит от:

• эмбеддингов;

• векторной базы данных;

• RAG-инфраструктуры;

• внешнего поискового сервиса.

Для текущего объёма документации хорошо структурированный локальный поиск сохраняет проект более простым, предсказуемым и лёгким.

Небольшие ответы

Tool search_docs возвращает релевантные сниппеты вместо отправки целых документов модели.

Это помогает уменьшить:

• объём контекста;

• потребление токенов;

• нерелевантную информацию;

• чрезмерно большие ответы.

Когда необходим полный документ, агент может использовать get_component или MCP Resources.

Дорожная карта

Завершено

• сервер MCP с транспортом stdio

• список компонентов

• индивидуальный запрос компонентов

• синхронизация документации GovBR-DS

• структурированный парсер Markdown

• автоматическая генерация локального набора данных

• локальный поиск по документации

• ранжирование по релевантности

• нормализация запросов на португальском языке

• MCP Resources

• Resources по доступности

• каталог компонентов

• MCP Prompts

• автодополнение компонентов в Prompts

Запланировано

• официальные примеры реализации HTML и CSS

• интеграция с @govbr-ds/core

• документация GovBR Web Components

• документация GovBR React Components

• примеры реализации по компонентам

• валидация кода GovBR-DS

• помощники для валидации доступности

• публикация в npm

• публикация в MCP Registry

• HTTP-транспорт

Связанный проект

Этот MCP был разработан как дополнение к навыку govbr-design-system.

У двух проектов разные обязанности:

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

Их можно использовать вместе с совместимыми агентами.

Концептуально:

                    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

Как внести вклад

Вклад приветствуется.

Некоторые интересные области для вклада:

• улучшение парсера документации;

• улучшение релевантности поиска;

• создание новых тестов;

• поддержка новых официальных источников GovBR-DS;

• улучшение совместимости с MCP-клиентами;

• поддержка официальных библиотек;

• выявление недокументированных компонентов;

• исправление некорректно интерпретированных данных.

Перед отправкой Pull Request:

npm test

Также убедитесь, что проект продолжает проходить typecheck/build, используемый в репозитории.

Предупреждение

govbr-ds-mcp — это независимый проект с открытым исходным кодом.

Он не поддерживается, не одобряется и не является официально поддерживаемым Федеральным правительством Бразилии или командой, ответственной за GovBR Design System.

Документация и ресурсы GovBR-DS, используемые проектом, по-прежнему подпадают под действие лицензий и условий соответствующих оригинальных проектов.

Лицензия

См. файл LICENSE для получения информации о лицензии этого проекта.