petal-components-mcp

petal-components-mcp

petal_components（Phoenix LiveView 向けの Shadcn スタイルのコンポーネントライブラリ）を AI コーディングアシスタント（Claude Code、Cursor、Windsurf など）に公開する MCP サーバーです。

これがないと、HEEx を記述する AI エージェントは素の Tailwind の寄せ集めを作り、pc_* コンポーネントを使おうとしません。この MCP サーバーがあれば、AI は必要に応じて各コンポーネントの完全なスキーマ（属性、スロット、デフォルト値、許可される値、使用例）を取得し、標準で petal_components に即したマークアップを記述します。

インストール（Claude Code）

claude mcp add petal --transport http https://mcp.petal.build

その後、任意の Phoenix プロジェクトで、AI に何かを作るよう依頼します。AI は list_components と get_component を呼び出して、実際の petal_components スキーマに基づいた出力を作成します。

利用可能なツール

• list_components — ライブラリ内のすべてのコンポーネントと、各コンポーネントの概要を一行で表示します
• get_component — 完全なスキーマ（属性、スロット、デフォルト値、値、ドキュメント）と、HEEx の使用例を表示します

近日公開：search_components（自然言語で検索）と generate_pattern（カード内フォーム、フォーム付きモーダル、ダッシュボードのひな型などの構成済みブロック）。

仕組み

MCP サーバーは、petal_components の各コンポーネントの JSON スナップショットをバンドルした、シンプルな TypeScript サービスです。JSON は、ロード済みの各 PetalComponents.* モジュールに対して Phoenix.Component.__components__/0 を調査する Mix タスクによって生成されるため、手作業で重複させることなく、スキーマを常に実際のライブラリと同期できます。

petal_components (Hex)              petal-components-mcp (this repo)
       │                                       │
       │ mix run extract_schemas.exs           │
       │─────────────────────────────────────► src/schemas.json
                                               │
                                               │ tsc
                                               ▼
                                         dist/server.js  ◄── deployed to Fly

ローカルでの実行

# Regenerate schemas from the latest petal_components on Hex
npm run extract     # cd scripts/extract && mix deps.get && mix run extract_schemas.exs

# Build and serve
npm install
npm run build
PORT=8765 npm start

# Health check
curl http://localhost:8765/healthz

抽出処理は自己完結しており、scripts/extract/ は Hex から petal_components を取得し、各 Phoenix.Component.__components__/0 を調査して src/schemas.json に書き出す小さな Mix プロジェクトです。ローカルに petal_components のクローンを用意する必要はありません。

Claude Code でローカルサーバーを使うには：

claude mcp add petal-local --transport http http://localhost:8765/mcp

デプロイ（Fly.io）

MCP サーバーは、独立したアプリとして Fly.io 上の mcp.petal.build でホストされています。

初回セットアップ

# 1. Create the app (one-time, requires Fly auth)
fly apps create petal-components-mcp

# 2. Deploy
fly deploy --remote-only

# 3. Add the custom domain
fly certs add mcp.petal.build

手順 3 の後、Fly に必要な DNS レコードが表示されます。petal.build の DNS プロバイダーで CNAME を追加します：

mcp.petal.build  CNAME  petal-components-mcp.fly.dev

その後、DNS の伝播が完了すると fly certs check mcp.petal.build が成功します。

以降のデプロイ

fly deploy --remote-only

Hex で petal_components の新しいリリースが公開された後の同期

# 1. Regenerate schemas from the latest petal_components on Hex
npm run extract

# 2. Eyeball the diff (catches surprises before they ship to AI agents worldwide)
git diff src/schemas.json | head -50

# 3. Commit and deploy
git add src/schemas.json
git commit -m "chore: sync schemas with petal_components vX.Y.Z"
git push
fly deploy --remote-only

/healthz エンドポイントはバンドルされたバージョンを返すため、デプロイが反映されたことを確認できます：

curl https://mcp.petal.build/healthz
# {"ok":true,"petal_components_version":"3.2.0","components":79,...}

背景

これは bet 002 の成果物です。Phoenix UI ツールの主要なインストール／発見経路が AI コーディングアシスタントになるかどうかを検証します。仮説、指標、中止基準については bet を参照してください。

ライセンス

MIT。