VaneUI

@vaneui/mcp

VaneUI のドキュメントを AI コーディングエージェントに公開する Model Context Protocol サーバーです。MCP 対応クライアント（Claude Code、Claude Desktop、Cursor、VS Code など）は、必要に応じてコンポーネントのドキュメントを読み込み、1 回のツール呼び出しで検索できます。これにより、エージェントはプロンプトにルールを手動で貼り付けなくても、正しい VaneUI コードを作成できます。

コンポーネントのリファレンス全体、導入ガイドとカスタマイズガイド、各コンポーネントの構造化されたプロパティ表に加え、search_docs と get_component_props の 2 つのツールを提供します。

要件

• Node.js 24（以下の npx コマンドでサーバーがダウンロードされ、実行されます）。

クイックスタート

サーバーは stdio 経由で実行され、npm では @vaneui/mcp として公開されています。以下のスニペットを使ってクライアントに追加してください。ローカルでのクローンやビルドは不要です。

Claude Code

claude mcp add vaneui -- npx -y @vaneui/mcp

Claude Desktop

claude_desktop_config.json を編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vaneui": {
      "command": "npx",
      "args": ["-y", "@vaneui/mcp"]
    }
  }
}

その後、Claude Desktop を再起動します。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "vaneui": {
      "command": "npx",
      "args": ["-y", "@vaneui/mcp"]
    }
  }
}

VS Code

code --add-mcp '{"name":"vaneui","command":"npx","args":["-y","@vaneui/mcp"]}'

または .vscode/mcp.json に追加します（VS Code では servers キーを使用します）。

{
  "servers": {
    "vaneui": {
      "command": "npx",
      "args": ["-y", "@vaneui/mcp"]
    }
  }
}

その他のクライアント

stdio MCP サーバーを受け入れるクライアントであれば、どれでも使用できます。クライアントの設定形式に従い、コマンドに npx、引数に -y @vaneui/mcp を指定してください。

使用方法

サーバーを接続したら、自然言語で VaneUI を使って構築するだけです。エージェントはツールを通じて適切なドキュメントを自動的に取得します。

• 「VaneUI を使って、タイトル、機能一覧、塗りつぶしのプライマリボタンがある料金カードを作成してください。」 → エージェントは card、list、button のプロパティを読み込み、正しく組み合わせます。
• 「Chip のデフォルトの外観とバリアントは何ですか？」 → get_component_props はプロパティ表を返します（Chip のデフォルトは primary ではなく secondary + outline です）。
• 「すべての Button にアプリ全体のデフォルト値を設定するにはどうすればよいですか？」 → search_docs が theme-defaults ガイドを見つけ、ThemeProvider themeDefaults のパターンを示します。
• 「flex-1 に対応する VaneUI のプロパティはどれですか？」 → search_docs がプロパティと Tailwind の対応表から見つけます。

動作確認

サーバーを追加してクライアントを再起動した後、次を確認してください。

• クライアントに、search_docs と get_component_props のツール（および vaneui://docs/* リソース）を持つ vaneui という名前のサーバーが表示されます。
• サーバーを直接テストするには、ターミナルで npx -y @vaneui/mcp を実行します。サーバーが起動し、stdio で待機します（MCP stdio サーバーでは出力がないのが正常です。終了するには Ctrl+C を押してください）。

ツール

search_docs

ドキュメント全体を対象に、部分文字列または正規表現で検索します。

パラメーター	型	備考
query	string	必須。大文字と小文字を区別しません。
regex	boolean	任意。true の場合、query は JavaScript の正規表現として解析されます。デフォルトは false です。

最大 50 件の検索結果を返します。各結果には uri、slug、lineNumber、および前後の短い snippet が含まれます。プロパティ名、デフォルト値、クラスの対応関係を推測する前にこのツールを使用してください。答えはほとんどの場合、すでにドキュメントに記載されています。

get_component_props

@vaneui/ui の ComponentCategories、ComponentKeys、defaultTheme、PropDescriptions から直接取得した、単一のコンポーネントのプロパティ／カテゴリー／デフォルト値／説明をまとめた表を返します。

Param	Type	Notes
slug	string	必須です。リソースのベース名と一致するコンポーネントのスラッグです。例：button、card、icon-button、page-title。

{ prop, category, isDefault, description, isCommon } 行の JSON 配列を返します。コンポーネントの正確なプロパティ一覧が必要なとき（共通レイアウトプロパティとコンポーネント固有のプロパティを使い分ける場合や、カテゴリー内でデフォルトとなるプロパティを確認する場合など）に使用してください。

利用可能なリソース

各ドキュメントファイルは、vaneui://docs/<slug> という名前のリソースとして公開されます。<slug> は、ソースファイル名から拡張子 .md を除き、小文字にしたものです。すべてのリソースの mimeType は text/markdown です。

例：

• vaneui://docs/claude — VaneUI プロジェクトの概要。
• vaneui://docs/component-usage、vaneui://docs/prop-to-tailwind-mapping、vaneui://docs/component-patterns、vaneui://docs/props-and-theme、vaneui://docs/css-conventions、vaneui://docs/testing、vaneui://docs/e2e-testing、vaneui://docs/playground-examples — エージェント向けのルールファイル。
• vaneui://docs/installation、vaneui://docs/usage-basics、vaneui://docs/core-concepts — 入門ガイド。
• vaneui://docs/theming-overview、vaneui://docs/using-theme-provider、vaneui://docs/theme-defaults、vaneui://docs/theme-and-override、vaneui://docs/extra-classes、vaneui://docs/customizing-styles、vaneui://docs/variant-inheritance、vaneui://docs/css-variables — カスタマイズガイド。
• vaneui://docs/common-props — 共通のレイアウト／タイポグラフィプロパティのリファレンス。
• vaneui://docs/button、vaneui://docs/card、vaneui://docs/modal、... — コンポーネントごとに1つずつ用意されています。

---

開発

このセクションは、サーバー自体に取り組むコントリビューターとメンテナー向けです。

ソース

ビルド時に、隣接する2つのリポジトリからドキュメントコーパスをまとめます。

• vaneui/（vaneui/vaneui のチェックアウト） — API リファレンスとエージェント向けルール（CLAUDE.md と .claude/rules/*.md）。
• vaneui-web/（vaneui/web のチェックアウト） — 説明形式のガイドとコンポーネントごとのリファレンス。app/docs/data/**/*.md にプレーンな Markdown として記述されています（コンポーネントごとに1ファイル、フロントマター付き）。

各 .md ファイルは、ベース名をキーとして resources/ に格納されます（ファイル名はすべて一意であるため、コーパスはフラットです）。vaneui/ のファイルはそのままコピーされます。vaneui-web/ のページは、vaneui-web 独自のインクルードヘルパー（lib/docs/includes.mjs）を使って {% include "x.md" %} タグを展開して書き込まれるため、各リソースの内容は vaneui.com のページと一致します。名前が _ で始まるファイルとディレクトリは、ページにインクルードされるパーシャルであるため、それ自体のリソースは作成されません。さらに、scripts/sync-component-props.mjs は各コンポーネントの componentKey フロントマターを読み取り、@vaneui/ui がエクスポートするメタデータと結合して、resources/component-props.json を生成します。

ビルド

resources/ は git にコミットされているため、新しくクローンすれば、サーバーの実行に必要なものはすべて揃っています。

npm install
npm run build       # tsc only — uses the committed resources/
npm start           # run the built server over stdio

コマンドとして node /absolute/path/to/vaneui-mcp/dist/server.js を指定すると、クライアントをローカルビルドに接続できます。

コーパスの再同期（メンテナー向け）

同期スクリプトは、vaneui/ と vaneui-web/ がこのリポジトリの兄弟フォルダー（../vaneui と ../vaneui-web として解決されます）にあることを前提としています。別の場所にある場合は、VANEUI_PATH / VANEUI_WEB_PATH 環境変数で変更してください。vaneui-web/ で npm install を先に実行してください。include ヘルパーがそこから @vaneui/md を読み込むためです。include が見つからない場合や循環している場合、同期は停止します。

npm run build:full  # re-sync resources/ from the sibling repos, then tsc

• npm run sync — 寛容な同期です。両方のソースにあるすべての .md を resources/ にコピーし、component-props.json を書き込みます。⚠️ 最初に resources/ を消去します。兄弟リポジトリが見つからない場合、部分的なバンドルが生成されます。build:full を使用することをおすすめします。
• npm run sync:strict — 厳格な同期です。兄弟リポジトリが見つからない場合、または MD ファイルが見つからない場合、ゼロ以外の終了コードで終了します。prepublishOnly で使用されます。

ドキュメントの追加または更新

1. vaneui/ または vaneui-web/ にあるソースの Markdown を編集（または作成）します。
   • コンポーネントリファレンス：vaneui-web/app/docs/data/<category>/<slug>.md（フロントマター付き）。
   • ナラティブガイド：vaneui-web/app/docs/data/{getting-started,customization,reference}/。
   • エージェントルール：vaneui/.claude/rules/<slug>.md。
2. npm run build:full を実行して、resources/ を再生成し、再コンパイルします。
3. ソースの変更とともに、再生成された resources/ をコミットし、MCP クライアントを再起動します。

src/resources.ts は起動時に resources ディレクトリを読み込むため、ファイルを追加してもレジストリの編集は不要です。

ライセンス

MIT