Skip to main content
Glama
petalframework

petal-components-mcp

Official
by petalframework
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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

  • 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesComponent function name (e.g. 'button', 'modal', 'input'). Get the full list via list_components.

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description explains the return content but doesn't explicitly state read-only behavior or potential error conditions. Adequate but could be more transparent about side-effect-free nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both essential and front-loaded with the primary purpose. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter tool with no output schema, the description covers what the tool returns and how it relates to the sibling, making it fully adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes the 'name' parameter; description adds useful cross-reference to 'list_components' for obtaining valid names, enhancing the value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the full schema for a single petal_components component, listing specific details (attrs, slots, defaults, etc.) and contrasting with sibling list_components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises calling when writing a Phoenix LiveView component reference to ensure attrs and slots match, providing strong when-to-use guidance. Does not explicitly state when not to use it, but the context implies it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the scope ('every component') but does not mention output format, ordering, or other behavioral traits. Adequate for a simple list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. First sentence states the action and resource, second provides usage guidance. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, no output schema, and no annotations, the description provides essential purpose and usage context. Complete for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has zero parameters, so baseline is 4. Description adds no parameter information, but none is needed as there are none to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists every component in a specific library (petal_components), providing a distinct purpose from the sibling tool get_component, which presumably retrieves details for a single component.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this first to see what's available before composing HEEx markup,' giving clear guidance on when to use it. Lacks explicit exclusion, but the sibling context implies differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedget_component
    • First observedlist_components
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
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

ActivityActive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/petalframework/petal-components-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server