Petal Components MCP

petal-components-mcp

Um servidor MCP que expõe petal_components — a biblioteca de componentes no estilo Shadcn para Phoenix LiveView — para assistentes de codificação com IA (Claude Code, Cursor, Windsurf, etc).

Sem isso, agentes de IA que escrevem HEEx inventam sopa de Tailwind crua e nunca alcançam os componentes pc_*. Com isso, a IA obtém o schema completo de cada componente sob demanda — atributos, slots, padrões, valores permitidos, exemplos de uso — e escreve marcação idiomática de petal_components por padrão.

Instalação (Claude Code)

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

Em seguida, em qualquer projeto Phoenix, peça à IA para construir algo. Ela chamará list_components e get_component para fundamentar sua saída em schemas reais de petal_components.

Ferramentas disponíveis

• list_components — cada componente da biblioteca com um resumo de uma linha
• get_component — schema completo (atributos, slots, padrões, valores, documentação) + exemplo de uso em HEEx

Em breve: search_components (correspondência em linguagem natural) e generate_pattern (blocos compostos como formulário-em-card, modal-com-formulário, esqueletos de dashboard).

Como funciona

O servidor MCP é um serviço TypeScript enxuto que agrupa um snapshot JSON de cada componente em petal_components. O JSON é gerado por uma tarefa Mix que inspeciona Phoenix.Component.__components__/0 em cada módulo PetalComponents.* carregado — então os schemas estão sempre sincronizados com a biblioteca real, sem duplicação manual.

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

Executando localmente

# 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

A extração é autocontida — scripts/extract/ é um pequeno projeto Mix que puxa petal_components do Hex, inspeciona cada Phoenix.Component.__components__/0 e escreve src/schemas.json. Não é necessário um clone local de petal_components.

Para usar um servidor local com Claude Code:

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

Deploy (Fly.io)

O servidor MCP está hospedado em mcp.petal.build no Fly.io como um aplicativo independente.

Configuração inicial

# 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

Após o passo 3, o Fly imprime os registros DNS que você precisa. Adicione um CNAME no provedor de DNS da petal.build:

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

Então fly certs check mcp.petal.build ficará verde assim que a propagação ocorrer.

Deploys subsequentes

fly deploy --remote-only

Sincronização após um novo lançamento de petal_components no 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

O endpoint /healthz reporta a versão empacotada, então você pode confirmar que um deploy foi publicado:

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

Contexto

Este é o artefato para bet 002 — testando se assistentes de codificação com IA se tornam o canal dominante de instalação/descoberta para ferramentas de UI do Phoenix. Veja a bet para hipótese, métricas e critérios de eliminação.

Licença

MIT.