GovBR-DS MCP
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-DSMCP サーバーは内部で 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
BUTTONsearch_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-mcpclaude 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 installMCP サーバーの実行
開発モードでサーバーを起動します。
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-mcpInspector で利用可能な機能をテストできます。
Tools
list_components
get_component
search_docsResources
govbr-ds://catalog
govbr-ds://components/{slug}
govbr-ds://components/{slug}/accessibilityPrompts
implement_govbr_component
review_govbr_component
check_govbr_accessibilityGovBR-DS ドキュメントの同期
ローカルインデックスを更新するには:
npx tsx scripts/sync-components.ts同期プロセス:
GitLab API を介して公開の GovBR-DS リポジトリにアクセスします。
ドキュメント化されたコンポーネントを特定します。
各コンポーネントの Markdown ファイルをダウンロードします。
利用可能な場合はアクセシビリティドキュメントをダウンロードします。
Markdown ファイルを解析します。
データを正規化します。
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.tsMCP Inspector を開きます。
npx @modelcontextprotocol/inspector npx tsx src/index.tsデータソース
このプロジェクトで使用されるドキュメントは、GovBR Design System の公式リポジトリから取得されます。
現在の取り込みプロセスでは主に以下を使用します。
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ファイルを参照してください。
Available Tools
3 toolsget_componentA
Obtém a documentação oficial sincronizada completa de um componente do GovBR Design System. Use quando já souber qual componente GovBR-DS precisa consultar.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The tool name and description imply a read-only operation without side effects, but it does not explicitly state that the operation is safe or what the response format will be. Since no annotations are provided, the description carries the burden but remains reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of one functional sentence and a usage note. It is well-structured and directly addresses the tool's purpose without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for a simple retrieval tool, indicating the source (GovBR Design System) and the condition for use (knowing the component). It does not detail the output structure, but given the lack of an output schema and the straightforward nature of the operation, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'name' is defined in the schema with type and minLength but no description. The tool description implies that 'name' should be the component name, but does not provide explicit format or examples. The parameter semantics are only partially conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete official documentation for a specific GovBR Design System component, and explicitly notes it should be used when the component name is already known, distinguishing it from the sibling tools list_components and search_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Use quando já souber qual componente GovBR-DS precisa consultar.' This clearly indicates it is for direct retrieval by name, contrasting with listing or searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_componentsA
Lista os componentes documentados do GovBR Design System disponíveis neste servidor. Use para descobrir quais componentes GovBR-DS podem ser consultados.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses an important scope constraint (components 'available on this server'), but does not describe output format, ordering, pagination, or confirm the read-only nature beyond the verb 'list'. Adequate for a simple operation, but lacks richer behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and resource, and every sentence adds value. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with no output schema, the description is sufficiently complete: it states what is listed, the scope (this server), and the intended use case. While it doesn't specify the return shape, the simplicity of a list tool makes this an acceptable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema covers 100% (empty schema). Baseline for 0 params is 4. The description adds no parameter-specific meaning, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lists the documented components of GovBR Design System available on this server' with a specific verb and resource. It also distinguishes itself from siblings by framing this as the discovery gateway for which GovBR-DS components can be queried, contrasting with get_component and search_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use to discover which GovBR-DS components can be consulted.' This tells the agent when to invoke the tool, though it does not explicitly name alternatives or exclusionary conditions. A clear, non-exhaustive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_docsA
Pesquisa na documentação oficial sincronizada do GovBR Design System (GovBR-DS). Use esta ferramenta sempre que precisar responder perguntas sobre componentes, uso, comportamento, acessibilidade, padrões ou recomendações do GovBR-DS. Prefira esta fonte em vez de pesquisa web para dúvidas sobre GovBR-DS.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| component | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not mention side effects, read-only nature, authentication, rate limits, or any behavioral traits beyond the obvious 'search' action. The description adds no insight into what happens during the search or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with purpose, and goes straight to the point. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately simple but has no output schema, no annotations, and no parameter documentation. The description covers the what and when but omits return format, query construction, component filter usage, and potential limitations. Given the available structured data, it remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
schema_description_coverage is 0% and the description does not reference any parameters (query, limit, component). It only implies searching for components but does not explain how to use parameters or their semantics. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Pesquisa na documentação oficial sincronizada do GovBR Design System' (searches the official synchronized documentation), which clearly identifies the action (search) and resource (GovBR-DS docs). It distinguishes from siblings like list_components and get_component by focusing on searching across documentation rather than retrieving specific component details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use the tool ('sempre que precisar responder perguntas sobre componentes, uso, comportamento, acessibilidade, padrões ou recomendações do GovBR-DS') and even recommends it over web search for GovBR-DS questions. It lacks an explicit 'when not to use' relative to sibling tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
get_component - First observed
list_components - First observed
search_docs
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: list_components is for discovery, get_component is for retrieving full docs of a known component, and search_docs is for answering arbitrary questions across the documentation. Their usage guidance avoids ambiguity.
All tools follow a consistent verb_noun pattern: list_components, get_component, and search_docs. The naming clearly signals the operation being performed, and any plural/singular variation follows conventional API naming.
With three tools, the server is lean but well-scoped for its purpose of querying GovBR-DS documentation. Each tool earns its place by covering a distinct access mode: browsing, direct retrieval, and searching.
For a read-only documentation server, the surface is complete: users can discover available components, fetch complete documentation for a known component, and search for behavioral or accessibility guidance. No obvious dead ends or missing operations exist for the stated domain.
Maintenance
Related MCP Connectors
Access and search Branch's official API documentation directly within any AI agent or client.
Serves your design system and coding standards to coding agents, so they stop guessing.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Connect AI agents to ProductNow's context engine to search, create, review, and act.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol implementation that enables AI-powered access to documentation resources, featuring URI-based navigation, template matching, and structured documentation management.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching and reading of PortOne documentation, including OpenAPI schemas and product guides, through the Model Context Protocol. It allows AI agents to easily access and integrate payment-related technical specifications into their workflows.8 npmISC
- AlicenseAqualityDmaintenanceProvides AI assistants with direct access to the complete Godot Engine documentation, including classes, tutorials, and features. It enables developers to retrieve and analyze official documentation through natural language interfaces using the Model Context Protocol.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to query Brazilian public data such as CEP, CNPJ, DDD, exchange rates, banks, and holidays via the Model Context Protocol.12MIT