heroui-v2-mcp

HeroUI v2 (https://v2.heroui.com) のコンポーネントドキュメント、ソースコード、スタイル定義、テーマトークンのための MCP (Model Context Protocol) サーバーです。

公式の @heroui/react-mcp が対象としているのは HeroUI v3 であり、その背後にデプロイ済みの Cloudflare Worker、R2 バケット、PostHog プロジェクトが必要なのとは異なり、これはスタンドアロンのローカルサーバーです。heroui-inc/heroui@main (v2.x を追跡するブランチ) と raw.githubusercontent.com から直接オンデマンドですべてを取得し、プロセスの生存期間中は結果をメモリにキャッシュします。クラウドアカウント、API デプロイ、抽出パイプラインは不要です。

なぜ別プロジェクトなのか

HeroUI v3 (ブランチ v3、サイト heroui.com) と v2 (ブランチ main、サイト v2.heroui.com) は、異なる互換性のないコンポーネントモデルです。パッケージレイアウトが異なり、v2 サイトには llms.txt がなく、docs フォルダ構造 (/docs/components/* と /docs/react/*) も異なり、スタイリングアプローチ (packages/core/theme/src/components 配下の tailwind-variants ファイルと v3 が使用するもの) も異なります。公式 MCP は v2 ドキュメントの提供を明示的に拒否するため、このプロジェクトはそのツールサーフェスをミラーリングしつつ、v2 のデータソースを指し示しています。

Related MCP server: UI Toolkit MCP Server

ツール

インストールと実行

パッケージは npm に heroui-v2-mcp として公開されているため、使用するためにクローンやビルドの手順は必要ありません。

Claude Code / Claude Desktop / Cursor から使用する

MCP 設定に追加してください。npx がオンデマンドでダウンロードして実行します:

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

または、グローバルにインストールしてバイナリを直接指定します:

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

ローカル開発 (ソースから)

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

GitHub レート制限

ディレクトリ一覧は GitHub REST API 経由で取得されますが、認証なしの場合、これは1時間あたり60リクエストに制限されています。ファイルの内容 (raw.githubusercontent.com) はこの制限の対象外です。多くのコンポーネントを閲覧中に 403 エラーが発生した場合は、トークンを設定してください:

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

データの解決方法

• コンポーネントリスト = main ブランチの apps/docs/content/docs/components/*.mdx 配下のファイル。

• ほとんどのドキュメントスラグは、packages/components/<slug> パッケージに 1:1 でマッピングされます。一部のドキュメントページは、別のパッケージにバンドルされているサブコンポーネントを文書化しています (例：textarea は @heroui/input に含まれ、checkbox-group は @heroui/checkbox に含まれます)。src/constants.ts の COMPONENT_PACKAGE_ALIASES を参照してください。

• プロパティ/API テーブルは、各 .mdx ドキュメントページに埋め込まれた <APITable data={[...]} /> JSX リテラルから解析されます (その配列は JS リテラルとして評価されます。これは公式リポジトリからの静的データであり、任意/信頼できない入力ではありません)。

• テーマトークンは packages/core/theme/src/colors/{semantic,common}.ts と default-layout.ts から取得されます。

キャッシュ

すべての GitHub レスポンス (ファイル内容またはディレクトリ一覧) は、30 分間 (src/constants.ts の CACHE_TTL_MS) メモリにキャッシュされます。より早く更新するには、プロセスを再起動してください。