GovBR DS MCP

Model Context Protocol (MCP) サーバー。ブラジル連邦政府デザインシステム（GovBR-DS）向けのオープンソースです。

govbr-ds-mcp は、GovBR-DS のドキュメント、コンポーネント、アクセシビリティガイドライン、検索、Resources、再利用可能なワークフローへの構造化されたアクセスを AI エージェントに提供します。

目的は、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 トランスポートを使用し、パッケージに含まれる GovBR-DS データで動作します。クエリ中に HTTP 呼び出しは行われません。

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 エージェントがデザインシステムに存在しないルールや動作をでっち上げる状況を減らすことです。

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 ツールは、ドキュメント全体をモデルに送信する代わりに、関連するスニペットを返します。

これにより、以下を削減できます。

• コンテキストの量

• トークンの消費

• 無関係な情報

• 過度に大きな応答

完全なドキュメントが必要な場合、エージェントは 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 スキルを補完するために開発されました。

2 つのプロジェクトには異なる責任があります。

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 クライアントとの互換性の改善

• 公式ライブラリのサポート

• ドキュメント化されていないコンポーネントの特定

• 誤って解釈されたデータの修正

プルリクエストを送信する前に:

npm test

また、リポジトリで使用されている typecheck/build をプロジェクトが引き続き通過することを確認してください。

免責事項

govbr-ds-mcp は独立したオープンソースプロジェクトです。

これは、ブラジル連邦政府または GovBR Design System 担当チームによって保守、承認、または公式にサポートされていません。

プロジェクトで使用されるGovBR-DSのドキュメントとリソースは、引き続きそれぞれの元のプロジェクトのライセンスと条件に従います。

ライセンス

このプロジェクトのライセンスについては、LICENSEファイルを参照してください。