preline-mcp

Preline MCP

意图

通过 Preline MCP 服务，将 Preline UI 组件和区块集成到 HTML 文件中。该服务提供 6 个工具，可返回可直接用于集成的 HTML、CSS 和 JS。

在以下情况下激活：

• 用户提到“preline”“add preline”“/preline”或“use preline”
• 用户请求 Preline 库中的 Tailwind CSS 组件
• 用户请求区块（现成的页面版块）或起始页面

默认规则

• 切勿猜测 slug。 所有版块、组件和类别标识符都是精确的 kebab-case 字符串。始终先通过 components_list 或 blocks_categories 查找。
• 一次处理一个。 获取一个组件或区块，将其完整集成后，再处理下一个。
• 插入任何内容前，始终先读取目标文件。
• 已知组件类型时，调用 components_list({ section: "<inferred-slug>" })，以缩短响应内容。仅在无法确定时省略 section。

决策：组件还是区块

用户说法	使用
“component” / “components”	组件工作流
“block” / “blocks”（或“example” / “examples”）	区块工作流
含义模糊	自行判断；区块能提供更完整的结果

澄清模糊请求

遇到以下任一情况时，请让用户选择，不要猜测：

• 抽象请求。 请求过于抽象，无法有把握地对应到某个类别／分区，更不用说某个区块／组件，例如“给我做个定价页面”“我需要一个好看的表单”“给我看看仪表盘示例”。从下面的第 1 步开始。
• 候选项并列。 请求具体到足以确定某个类别／分区，但 blocks_in_category / components_list({ section }) 仍会给出 2 个或更多候选项，而且它们的标题和描述对请求提到的每项标准都同样符合（布局／功能／风格类别相同），请求中也没有足够信息打破平局。直接跳到下面的第 3 步，只列出并列候选项。

如果恰好有一个候选项符合请求中的全部描述（“基础手风琴”“带标签页的 SaaS 首屏”），则直接进入常规工作流——不要盘问用户你已经可以确定的内容；当某个选项明显最合适时，也不要为了稳妥而提问。

所有澄清问题和列表默认使用英语——只有在用户用其他语言回复后，才切换为用户使用的语言。

区块：

1. 询问适合的类别。 调用 blocks_categories()，并列出相关的 mainSection / subSection / category 路径及其标题和描述——目录为每个类别都提供了一行描述，因此请直接展示，不要自行编造摘要。
2. 尝试一轮内确定。 如果用户的回复既指出了类别，又对项目作了足够具体的描述，能够识别出唯一匹配项（例如特定布局、功能或风格），则调用 blocks_in_category 确认准确 ID，然后直接调用 single_block——完全跳过第 3 步。
3. 否则，询问哪个区块最合适。 调用 blocks_in_category({ mainSection, subSection, category })，列出区块标题和描述；如果是上述并列候选项的情况，则只列出这些候选项，并请用户选择最符合需求的一项。
4. 获取并集成选定的区块，调用 single_block。

组件——流程相同，但使用分区而非类别：

1. 询问适合哪个分区（获取完整列表时调用 components_list()；能够推断分区后调用 components_list({ section })）。
2. 如果回复指出了分区，且对组件的描述足够具体，能够识别出唯一匹配项 → 直接通过 single_component 确定（依靠 relative 元数据——参见“智能组件选择”——选择合适的默认项／变体）。
3. 否则，列出该分区中的组件（标题和描述；存在 relative.category 分组时也一并列出；如果是上述并列候选项的情况，则只列出这些候选项），并询问哪项最合适。
4. 使用 single_component 获取并集成。

每轮只问一个重点明确的问题，并附上简短、易浏览的列表——这比开放式地问“你想要什么？”更好，也比为了避免提问而猜测 slug 更好。

复合式与布局请求

当请求描述多个组件——若干部分、一个区域、完整页面或应用外壳——时，不要临时逐个获取。先规划整体结果，再一次获取并集成一个节点。相同步骤适用于任何形式：仪表板、设置页面、产品页面、多步表单、“包含 X、Y 和 Z 的卡片／区块／布局”等。

1. 先确定贯穿整体的约束。 适用于整个结果的内容——类系统（主题令牌还是实用类 → isUtilityBased / theme）、共享表面／颜色、间距／密度、重复元素状态——都要预先确定。后续每次获取和编辑时都保持一致。
2. 分解为树形结构： 容器 → 区域 → 叶组件。记录下来；每个叶节点对应一次获取。
3. 发现每个节点——先定位，再确认。 使用 references/catalog-map.md 确定查找位置：抽象意图（整个页面／区域／外壳）→ 合适的 blocks_categories 分支（有合适的现成区块时，将其用作骨架）；每个具名元素 → 合适的 components_list({ section })。映射只告诉你在哪里查找——插入前，务必根据工具输出确认确切的 slug。
4. 从最外层开始组装，每次一个。 骨架／外层容器负责设定共享表面和脚本／初始化锚点；然后逐个填充内部区域，并在处理下一个区域前完整集成当前区域（遵循集成规则）。保留返回的类，只更改文本——除非用户明确要求更改特定表面／颜色／状态。写入标记前，先应用所有结构性调整（见集成规则中的写入前先调整）。
5. 逐项核对最终结果是否符合请求。

扩展方法和示例请参阅 references/composite-layouts.md。

工作流：组件

1. components_list({ section: "<slug>" })   → get valid component IDs
2. single_component({ section, component }) → get HTML/CSS/JS
3. Read target file
4. Integrate HTML, CSS, scripts, init (see Integration Rules)
5. Repeat from step 1 only after integration is complete

工作流：区块

1. blocks_categories()                                    → get hierarchy
2. blocks_in_category({ mainSection, subSection, category }) → get block IDs
3. single_block({ mainSection, subSection, category, block }) → get HTML/CSS/JS
4. Read target file
5. Integrate HTML, CSS, scripts, init (see Integration Rules)
6. Repeat from step 1 only after integration is complete

集成规则

HTML - 插入到用户需要的位置。

CSS（`` 部分）：

• 必须放在 <head> 内，紧挨着 </head> 之前
• 绝不能放在 <body> 内或 </body> 附近

外部脚本（`` 部分）：

• `` 标签是响应部分标记，并非目标文件中的位置
• 放置算法：打开目标文件，从 </body> 开始向上扫描，跳过空行、注释和非结构性标签（</script>、</style> 等）
• 遇到的第一个结构性结束标签（</main>、</section>、</div>、</footer>、</article>）就是锚点
• 在该锚点之后插入 <script src> 标签，并根据现有的 Preline 核心脚本调整顺序。Preline 核心脚本是已加载且 src 包含 preline 的 <script src>（例如 …/preline/dist/index.js；具体路径因安装方式而异）：
  • src 不包含 preline 的脚本（第三方库：lodash、apexcharts 等）→ 放在 Preline 核心脚本之前
  • src 包含 preline 的脚本（Preline 辅助脚本，例如 hs-*-helpers.js）→ 放在 Preline 核心脚本之后
  • 如果还没有 Preline 核心脚本，则按以下顺序放置：不含 preline 的脚本，然后是含 preline 的脚本
  • 内联初始化 <script> 始终放在最后，紧挨着 </body> 之前

初始化（`` 部分）：

• 紧挨着 </body> 之前放置
• 除非代码块中已经包含 <script> 标签，否则用 window.addEventListener('load', () => { ... }) 包裹

大型响应（工件）： 将响应写入临时暂存文件时，用 Read 工具读取一次（大型文件使用 offset/limit），将所需代码块复制到目标文件，然后删除暂存文件。只需放置部分内容时，不要把整个工件都读入上下文。

写入前先调整。 如果请求与获取的标记不一致——例如用户未要求的区域（面包屑、演示菜单、占位徽标）、区块或标签不同——先在内存中生成最终标记，再一次性写入目标区域。绝不要先原样插入获取的标记，再通过一连串后续编辑来重构：每次这样的编辑都会重复传输大量标记、占用上下文，并使文件状态不同步。

相同令牌 = 相同颜色。 主题令牌（bg-navbar、bg-sidebar、bg-layer 等）在同一主题中保持一致——若要让两个表面颜色相同，就给它们使用相同的令牌类。绝不要通过读取项目的 CSS 来把令牌解析为原始颜色。

信任返回的标记——不要重新验证。 MCP 返回的类、结构和 data-hs-* 属性由 Preline 保证有效。这是最应避免的时间消耗。不要：

• grep、解析或扫描用户编译后的 CSS（例如 main.css），以“确认”某个类是否存在或确定设计令牌对应的颜色——Preline 类会在使用方的构建步骤中解析，因此某个样式表中没有它并不意味着什么；
• 编写 HTML/DOM/AST 验证器（Python HTMLParser、标签配对检查器等）——SVG 和空元素会让简单解析器出错，产生误报；
• 重新读取已放置的工件，或重新打开已编辑的文件，只为“再次检查”生成的代码。

放置标记，只修改文本，然后继续。根据请求进行核对（用户提到的每个元素是否都已包含？），不要通过审查生成的代码或项目的 CSS 来验证。

智能组件选择

components_list 可能会为每个组件返回一个 relative 对象：

• isSectionDefault: true - 此区域推荐的默认选项；请求含糊时优先选择
  • 例外：如果描述提到“多个变体”，而用户只需要一个，则改选单变体组件
• category - 逻辑分组（例如 "color-variants"、"states"）
• isCategoryDefault: true - 该类别推荐的默认选项；请求暗示某种风格分组时优先选择

可用主题

default（蓝色）· harvest（琥珀色）· retro（紫红色）· moon（灰度）· ocean（青色）· bubblegum（粉色）· cashmere（灰紫色）· autumn（橙色）· olive（绿色）

在 single_component 或 single_block 中传入 isUtilityBased: true, theme: "<name>"。

关键参考资料

• references/catalog-map.md - 路由映射：区块意图本体（完整页面/外壳）以及按用途分组的所有组件分区，并标注 JS 插件。在进行任何发现调用前，先打开此文件，选择合适的 section / blocks 分支。
• references/composite-layouts.md - 多组件/页面/外壳请求的完整方法，并附有示例说明
• references/mcp-tools-reference.md - 完整的参数规格、布局算法详情以及全部 6 种工具