Skip to main content
Glama
petal-components-mcp

petal-components-mcp

Official

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 petal_components 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 list_components and get_component to ground its output in real petal_components schemas.

Related MCP server: daisyui-mcp-server

Available tools

  • get_install_instructions - step-by-step install for a Phoenix project (dep, Tailwind v4 CSS, use PetalComponents, JS hooks), plus an optional step that syncs the petal_components usage rules into CLAUDE.md or AGENTS.md via usage_rules

  • 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: search_components (natural-language match) and generate_pattern (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 petal_components. 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 petal_components from Hex, introspects every Phoenix.Component.__components__/0, and writes src/schemas.json. No need for a local petal_components 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

This is the artifact for bet 002 — testing whether AI coding assistants become the dominant install/discovery channel for Phoenix UI tooling. See the bet for hypothesis, metrics, and kill criteria.

License

MIT.

Available Tools

2 tools
get_componentAInspect

Get the full schema for a single petal_components component — attrs, slots, defaults, allowed values, and a HEEx usage example. Call this any time you're about to write a Phoenix LiveView component reference like <.pc_button> or <.input>, to ensure the attrs and slots match the real library.

Inputs: name (required).

list_componentsAInspect

List every component available in petal_components (the Shadcn-style Phoenix LiveView component library). Use this first to see what's available before composing HEEx markup.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    Each tool has a distinct purpose: list_components provides an overview, get_component provides detailed schema for a single component. No overlap.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern in snake_case (list_components, get_component), which is predictable and clear.

    Tool Count4/5

    Two tools is minimal but appropriate for the server's read-only purpose of querying component schemas. A few more tools (e.g., search) could enhance, but not essential.

    Completeness5/5

    Covers the full lifecycle of accessing component information: listing all components and retrieving detailed schema for one. No gaps for the intended use case.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers