Petal Components MCP server

petal-components-mcp

An MCP server that exposes petal_components — the Shadcn-style component library for Phoenix LiveView — to AI coding assistants (Claude Code, Cursor, Windsurf, etc).

Without this, AI agents writing HEEx invent raw Tailwind soup and never reach for pc components. With it, the AI gets the full schema for every component on demand — attrs, slots, defaults, allowed values, usage examples — and writes idiomatic petalcomponents markup by default.

Install (Claude Code)

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

Then in any Phoenix project, ask the AI to build something. It'll call listcomponents and getcomponent to ground its output in real petal_components schemas.

Available tools

• list_components — every component in the library with a one-line summary
• get_component — full schema (attrs, slots, defaults, values, docs) + HEEx usage example

Coming soon: searchcomponents (natural-language match) and generatepattern (composed blocks like form-in-card, modal-with-form, dashboard skeletons).

How it works

The MCP server is a thin TypeScript service that bundles a JSON snapshot of every component in petalcomponents. The JSON is generated by a Mix task that introspects Phoenix.Component.components/0 on every loaded PetalComponents. module — so the schemas are always in sync with the actual library, no manual duplication.

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

Running locally

# 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

The extraction is self-contained — scripts/extract/ is a tiny Mix project that pulls petalcomponents from Hex, introspects every Phoenix.Component.components/0, and writes src/schemas.json. No need for a local petalcomponents clone.

To use a local server with Claude Code:

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

Deploy (Fly.io)

The MCP server is hosted at mcp.petal.build on Fly.io as a standalone app.

First-time setup

# 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

After step 3, Fly prints the DNS records you need. Add a CNAME at the petal.build DNS provider:

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

Then fly certs check mcp.petal.build will go green once propagation hits.

Subsequent deploys

fly deploy --remote-only

Syncing after a new petal_components release on Hex

# 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

The /healthz endpoint reports the bundled version, so you can confirm a deploy went out:

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

Background

Shortened. The full README is on GitHub.