petal-components-mcp

petal-components-mcp

一个 MCP 服务，可将 petal_components — Phoenix LiveView 的 Shadcn 风格组件库 — 提供给 AI 编码助手（Claude Code、Cursor、Windsurf 等）。

没有它，编写 HEEx 的 AI Agent 会堆砌原始的 Tailwind 样式，却从不使用 pc_* 组件。有了它，AI 就能按需获取每个组件的完整架构信息 — 属性、插槽、默认值、允许的取值、用法示例 — 并默认编写符合惯例的 petal_components 标记。

安装（Claude Code）

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

然后，在任何 Phoenix 项目中，让 AI 构建一些内容。它会调用 list_components 和 get_component，根据真实的 petal_components 架构信息生成内容。

可用工具

• list_components — 列出库中的所有组件，并提供一行摘要
• get_component — 完整架构信息（属性、插槽、默认值、取值、文档）+ HEEx 用法示例

即将推出：search_components（自然语言匹配）和 generate_pattern（组合式区块，例如卡片中的表单、带表单的模态框、仪表板骨架）。

工作原理

MCP 服务是一个精简的 TypeScript 服务，其中打包了 petal_components 中每个组件的 JSON 快照。JSON 由 Mix 任务生成，该任务会检查每个已加载的 PetalComponents.* 模块中的 Phoenix.Component.__components__/0，因此架构信息始终与实际库保持同步，无需手动重复维护。

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

在本地运行

# 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

提取过程是独立的 — scripts/extract/ 是一个小型 Mix 项目，它从 Hex 拉取 petal_components，检查每个 Phoenix.Component.__components__/0，并写入 src/schemas.json。无需在本地克隆 petal_components。

要通过 Claude Code 使用本地服务：

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

部署（Fly.io）

MCP 服务作为独立应用托管在 Fly.io 上，地址为 mcp.petal.build。

首次设置

# 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

完成第 3 步后，Fly 会显示所需的 DNS 记录。在 petal.build DNS 提供商处添加一条 CNAME 记录：

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

传播完成后，运行 fly certs check mcp.petal.build 就会显示为绿色。

后续部署

fly deploy --remote-only

Hex 上发布新版 petal_components 后进行同步

# 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

/healthz 端点会报告打包的版本，因此你可以确认部署已完成：

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

背景

这是 bet 002 的产物 — 用于测试 AI 编码助手是否会成为 Phoenix UI 工具的主要安装与发现渠道。有关假设、指标和终止标准，请参阅该 bet。

许可证

MIT。