io.github.petalframework/petal-components-mcp
Phoenix LiveView component schemas from petal_components, exposed to AI coding assistants.
Open source Repository Open in the app JSON README (API)
About
Phoenix LiveView component schemas from petal_components, exposed to AI coding assistants.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- petalframework
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-09-02T02:59:04Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:00
- Updated
- 2026-08-29 04:01:00
- Origin id
io.github.petalframework/petal-components-mcp
README
# petal-components-mcp
An MCP server that exposes [petal_components](https://github.com/petalframework/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)
```sh
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.
## 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: `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
```sh
# 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:
```sh
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
```sh
# 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
```sh
fly deploy --remote-only
```
### Syncing after a new petal_components release on Hex
```sh
# 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:
```sh
curl https://mcp.petal.build/healthz
# {"ok":true,"petal_components_version":"3.2.0","components":79,...}
```
## Background
This is the artifact for [bet 002](../bets/002-petal-components-mcp.md) — 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.