livewire-flux-mcp

Livewire Flux MCP

一个 MCP（模型上下文协议）服务，可访问 Livewire Flux 中的 Livewire Flux 组件和布局。该服务允许 AI 助手按需获取和搜索 Flux 组件及布局文档。

⚠️ 免责声明

这是一个个人项目，与 Livewire Flux 无关。

功能介绍

该 MCP 服务会抓取 Livewire Flux 文档并提供结构化访问，让 AI 助手能够：

• 获取 https://fluxui.dev/components/ 中特定 Flux 组件的文档
• 获取 https://fluxui.dev/layouts/ 中特定 Flux 布局的文档
• 访问组件和布局参考章节，查看 API 详情、属性和用法
• 搜索组件和布局文档内容
• 列出所有可用的 Flux 组件
• 浏览并搜索所有可用于 flux:icon 组件的 Heroicons
• 直接访问来自 Flux 官方网站的最新文档
• 高性能缓存，缓存有效期为 24 小时，以获得最佳响应速度

为什么不直接使用 Laravel Boost？

Boost 已经通过 search-docs 工具索引了 Flux，回答很多问题时这已经足够。但它有两点不足：

• 答案范围可控。 search-docs 会在包含 1.7 万份文档的语料库中进行语义搜索，因此针对宽泛 Flux 问题的回答可能会包含数千个 token 的内容倾倒 (laravel/boost#290)。该服务只会获取你指定的组件页面及其参考章节。
• 了解 Pro 套餐限制。 Boost 随附的 fluxui-development 技能内置了组件列表，却不会告诉你的 Agent 哪些组件需要付费 Flux 许可证。该服务会实时读取套餐信息并标记相关组件，让你的 Agent 不再编写无法发布的标记。

如果你使用 Boost，运行 npx livewire-flux-mcp install 即可将两者连接起来——参见AI 指南与技能。两者相辅相成：继续使用 Boost 处理 Laravel、Livewire、Pest 等内容；让该服务负责回答 Flux 相关问题。

设置你的 Agent

该服务通过 stdio 运行，并使用 npx 启动，因此无需全局安装。 每个 Agent 保存配置的方式都不同——请在下方选择你的 Agent。

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

claude mcp add --transport stdio --scope project flux-docs -- npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

codex mcp add flux-docs -- npx -y livewire-flux-mcp

[mcp_servers.flux-docs]
command = "npx"
args = ["-y", "livewire-flux-mcp"]

gemini mcp add --scope project flux-docs npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

{
    "servers": {
        "flux-docs": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

code --add-mcp '{"name":"flux-docs","command":"npx","args":["-y","livewire-flux-mcp"]}'

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

注册服务器会告知你的 Agent 这些工具存在，但不会告诉它何时使用这些工具——而在 Laravel Boost 项目中，它甚至不会使用这些工具，因为 Boost 自带一个 fluxui-development 技能，会将 Flux 查询发送到自己的 search-docs 工具，并包含一个硬编码的组件列表。此软件包提供了相应指南来解决这个问题：

npx livewire-flux-mcp install

安装程序会检测适用项：composer.json 中的 livewire/flux-pro 会选择 fluxui-pro 指南键，livewire/flux 会选择 fluxui-free，而 .claude/ 目录则会添加子 Agent。使用 --boost 或 --claude 限定范围，使用 --path <dir> 指定其他位置，或使用 --dry-run 预览。之后运行 php artisan boost:update，让 Boost 载入这些文件。

关于覆盖。 此技能是有意替换的——Boost 最后解析自定义技能，并根据 frontmatter 中的 name 匹配，因此必须将 fluxui-development 设为相同名称才能生效。指南绝不会被覆盖：如果该路径下已有文件，或 Flux 软件包本身随附了该指南，我们会将其保留在我们的代码块下方；代码块由 {{-- livewire-flux-mcp:begin --}} 标记界定，因此重新运行时只会刷新该部分。除非传入 --force，否则安装程序未写入的任何文件都不会改动。

要撤销更改，请删除已安装的文件并运行 php artisan boost:update——Boost 会恢复自己的版本。

Laravel Boost 只会自动发现 Composer 软件包中的指南和技能，因此 npm 软件包无法自动注册它们。此安装程序会写入 Boost 文档中所述的自定义指南和技能路径，因此能够正常工作，并且在运行 boost:update 后仍会保留。

支持我

大家好：

你喜欢这个软件包吗？觉得它有用，而且适合你的项目吗？

我很乐意为你提供帮助。如果你愿意支持我的工作，我将不胜感激。

你还可以选择以下方式 😃：

• 赞助我 😎
• 请我喝杯咖啡 ☕ 或吃个披萨 🍕
• 给这个仓库点个“Star ⭐”（完全免费哦 😉）

可用的 MCP 工具

该服务提供四种 MCP 工具：

1. fetch_flux_docs - 获取组件或布局的文档

   • component（可选）：要获取文档的特定组件名称
   • layout（可选）：要获取文档的特定布局名称（例如，“header”“sidebar”）
   • version（可选）：目标 Flux 主版本 — 'v1' 或 'v2'（默认值为 'v2'）
   • 如有可用内容，会自动包含参考章节
   • 从 https://fluxui.dev/components/{component} 或 https://fluxui.dev/layouts/{layout}（v2）获取；当 version='v1' 时，路由至 https://v1.fluxui.dev/components/{component}
   • 如果页面对应的是付费 Flux 组件，响应开头会添加一行 [NOTICE] This is a Flux Pro component …

2. list_flux_components - 列出所有可用的 Flux 组件

   • version（可选）：'v1' 或 'v2'（默认值为 'v2'）
   • tier（可选）：'free'、'pro' 或 'all'（默认值为 'all'）。设置为 'all' 时，每个组件都会标注为 [Pro] 或 [Free]。在 v1 中会忽略 tier 参数（v1 没有 Pro 等级）。
   • 提供组件名称及其文档路径

3. list_flux_layouts - 列出所有可用的 Flux 布局

   • version（可选）：'v1' 或 'v2'（默认值为 'v2'）。在 v1 中，该工具会返回简短提示“layouts are not available in v1”，且不会发起任何 HTTP 请求。
   • 提供布局名称及其文档路径
   • 布局名称从 fluxui.dev/layouts 读取；如果该索引不可用，则回退到 fluxui.dev/components 上的全站导航 — 无论哪种情况，单独的 /layouts/{name} 页面都不受影响

4. list_flux_component_icons - 列出所有可用于 flux:icon 组件的 Heroicons

   • variant（可选）：按图标变体筛选（outline、solid、mini、micro）
   • search（可选）：用于筛选图标名称的搜索词
   • 从 Heroicons GitHub 仓库获取实际图标名称
   • 为每种变体提供用法示例、尺寸和 GitHub 链接
   • 返回所有可用图标的完整列表，并采用正确的 Flux 语法

用法示例

MCP 服务运行后，AI 助手可以使用它来：

• 获取特定组件的文档：“显示 Button 组件文档”
• 获取特定布局的文档：“显示 header 布局文档”
• 列出可用组件：“有哪些 Flux 组件可用？”
• 列出可用布局：“有哪些 Flux 布局可用？”
• 浏览所有可用图标：“显示所有可用于 flux:icon 的 Heroicons”
• 搜索特定图标：“查找 outline 变体中的所有箭头图标”
• 获取图标用法示例：“如何使用 solid 变体中的 user 图标？”

该服务会自动从 fluxui.dev/components、fluxui.dev/layouts 和 GitHub 上的 Heroicons 获取最新文档，并以结构化格式呈现所有内容，方便 AI 助手使用。获取组件或布局文档时，会同时包含主要内容和提供详细 API 信息的参考章节。

版本

Flux 提供两个主版本，MCP 服务均支持：

• v2（默认）— 当前主机为 fluxui.dev。省略 version 或将其设为 'v2' 时使用。支持组件、布局和 Pro 等级识别。
• v1 — 旧版主机为 v1.fluxui.dev。设置 version='v1' 时使用。仅支持组件 — Flux v1 没有 /layouts 路由，也没有 Pro 等级。list_flux_layouts 在 v1 中会返回友好提示，且不会发起任何 HTTP 请求；list_flux_components 在 v1 中会忽略 tier。

fetch_flux_docs、list_flux_components 和 list_flux_layouts 均接受 version 参数。list_flux_component_icons 与版本无关（Heroicons 不属于 Flux 版本体系）。

Pro 版级别说明

Flux v2 的部分组件仅限持有付费 Flux Pro 许可证的用户使用。MCP 服务通过两种方式说明这一点：

• 获取时提示。 当 fetch_flux_docs 获取到 Pro 组件时，响应开头会添加一行 [NOTICE] This is a Flux Pro component — requires a paid Flux license.。
• 列表中的级别筛选。 list_flux_components 接受 tier='free' 以隐藏 Pro 组件，接受 tier='pro' 以仅显示 Pro 组件，或接受 tier='all'（默认值）以列出所有组件，并在每个名称旁标注 [Pro] / [Free]。

Pro 组件列表根据 fluxui.dev/pricing 生成，并在服务中内置了硬编码的备用列表，因此即使无法访问价格页面，级别筛选仍能正常工作。

手动注册 MCP 服务

如果你的编辑器不在设置你的 Agent中涵盖的六种编辑器之列，请使用以下信息手动注册服务：

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

-y 会跳过首次启动时的安装确认，因为 stdio 服务无法响应此确认。

性能与缓存

MCP 服务包含智能缓存，以提供最佳性能：

• 24 小时缓存过期时间——内容缓存 1 天，在新鲜度与性能之间取得平衡
• 自动缓存管理——自动清理过期条目
• 智能缓存键——针对不同参数（组件、布局、版本、级别、变体）使用不同的缓存条目
• GitHub API 速率限制保护——获取 Heroicons 时避免触及 GitHub API 限制
• 即时响应——缓存请求在毫秒内返回，而非数秒

缓存行为

• 文档请求：按组件／布局与版本组合缓存
• 组件列表：全局缓存（每日刷新）
• 布局列表：全局缓存（每日刷新）
• 图标列表：按变体和搜索组合缓存
• 缓存存储：内存中（服务重启时会重置）

缓存系统对 list_flux_component_icons 工具尤其有益；如果不使用缓存，该工具每次请求最多会调用 GitHub API 4 次。

更新日志

有关近期更改的更多信息，请参阅 CHANGELOG。

贡献

详情请参阅 CONTRIBUTING。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞。

致谢

• Maurizio
• 所有贡献者

许可证

MIT 许可证（MIT）。更多信息请参阅许可证文件。