GovBR DS MCP

브라질 연방 정부 디자인 시스템(GovBR-DS)을 위한 오픈소스 Model Context Protocol(MCP) 서버입니다.

govbr-ds-mcp는 AI 에이전트에게 GovBR-DS 문서, 구성 요소, 접근성 지침, 검색, Resources 및 개발을 위한 재사용 가능한 워크플로우에 대한 구조화된 접근을 제공합니다.

목표는 Codex, Claude Code, Kiro 및 기타 MCP 호환 클라이언트와 같은 도구가 사전 학습된 모델 지식에만 의존하는 대신 동기화된 공식 문서를 기반으로 GovBR Design System을 이해하고 활용할 수 있도록 하는 것입니다.

이 패키지는 npm에 govbr-ds-mcp로 게시되어 있으며 다음 명령으로 직접 실행할 수 있습니다:

npx -y govbr-ds-mcp

이 프로젝트는 커뮤니티 기반의 독립 프로젝트입니다. 브라질 연방 정부의 공식 프로젝트도 아니고 GovBR-DS를 담당하는 팀의 프로젝트도 아닙니다.

왜 이 프로젝트인가?

AI 에이전트는 프론트엔드 코드를 빠르게 생성할 수 있지만 항상 다음 사항을 알지는 못합니다:

• 어떤 GovBR-DS 구성 요소를 사용해야 하는지;

• 특정 구성 요소가 어떻게 동작해야 하는지;

• 어떤 접근성 권장 사항이 적용되는지;

• 어떤 사용 패턴이 권장되는지;

• 특정 정보가 GovBR-DS 문서의 어디에 위치하는지.

govbr-ds-mcp는 Model Context Protocol을 통해 GovBR-DS 문서를 제공함으로써 이 문제를 해결하고자 합니다.

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 서버가 작동할 수 있습니다.

현재 이 프로젝트는 GovBR-DS의 문서화된 구성 요소 37개를 동기화합니다.

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

서버는 GovBR-DS를 사용한 일반적인 개발 워크플로우를 위한 재사용 가능한 Prompts를 제공합니다.

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 전송을 사용하며 쿼리 중 HTTP 호출 없이 패키지에 포함된 GovBR-DS 데이터로 작동합니다.

MCP 클라이언트 구성

Claude Desktop

Claude Desktop 구성 파일에 서버를 추가합니다:

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

파일을 저장한 후 Claude Desktop을 다시 시작합니다.

또한 Claude MCP 문서를 참조하세요.

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를 다시 시작합니다.

또한 Codex MCP 문서를 참조하세요.

Kiro

Kiro에서 워크스페이스에 .kiro/settings/mcp.json을 열거나 생성합니다. 서버를 전역으로 사용하려면 ~/.kiro/settings/mcp.json을 사용합니다:

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

저장 후 Kiro의 MCP 패널을 열고 govbr-ds가 연결되어 있는지 확인합니다.

또한 Kiro MCP 문서를 참조하세요.

로컬 개발

저장소를 클론하고 의존성을 설치합니다:

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. GitLab API를 통해 GovBR-DS 공개 저장소에 접근합니다;

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의 동기화된 공식 문서에 기반해야 합니다.

목표는 AI 에이전트가 Design System에 존재하지 않는 규칙이나 동작을 만들어내는 상황을 줄이는 것입니다.

LLM 독립

MCP 서버는 다음에 의존하지 않습니다:

• OpenAI;

• Anthropic;

• Google;

• 로컬 모델;

• 기타 AI 공급업체.

모델은 연결된 MCP 클라이언트의 책임입니다.

로컬 런타임

외부 요청은 문서 동기화 중에 사용되며 일반 MCP 쿼리 중에는 사용되지 않습니다.

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

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

복잡한 인프라보다 단순한 검색

현재 검색은 결정적 텍스트 순위를 사용합니다.

이 프로젝트는 다음에 의존하지 않습니다:

• 임베딩;

• 벡터 데이터베이스;

• RAG 인프라;

• 외부 검색 서비스.

현재 문서량으로 볼 때 잘 구조화된 로컬 검색은 프로젝트를 더 단순하고 예측 가능하며 가볍게 유지합니다.

작은 응답

search_docs Tool은 전체 문서를 모델로 보내는 대신 관련 스니펫을 반환합니다.

이는 다음을 줄이는 데 도움이 됩니다:

• 컨텍스트 양;

• 토큰 소비;

• 관련 없는 정보;

• 과도하게 큰 응답.

전체 문서가 필요할 때 에이전트는 get_component 또는 MCP Resources를 사용할 수 있습니다.

로드맵

완료

• stdio 전송을 사용하는 MCP 서버

• 구성 요소 목록

• 개별 구성 요소 조회

• 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 파일을 참조하십시오.