Livewire Flux

Npm CodeQL License Downloads Sponsor

An MCP (Model Context Protocol) server that provides access to Livewire Flux Components and Layouts from Livewire Flux. This server allows AI assistants to fetch and search through Flux component and layout documentation on demand.

⚠️ Disclaimer

This is a personal project and is not affiliated with Livewire Flux.

Support Me

Hey folks,

Do you like this package? Do you find it useful, and it fits well in your project?

I am glad to help you, and I would be so grateful if you considered supporting my work.

You can even choose 😃:

• You can sponsor me 😎
• You can buy me a coffee ☕ or a pizza 🍕
• You can "Star ⭐" this repository (it's free BTW 😉)

What it does

This MCP server scrapes and provides structured access to the Livewire Flux documentation, enabling AI assistants to:

• Fetch documentation for specific Flux components from https://fluxui.dev/components/
• Fetch documentation for specific Flux layouts from https://fluxui.dev/layouts/
• Access component and layout reference sections with API details, props, and usage patterns
• Search through component and layout documentation content
• List all available Flux components
• Browse and search all available Heroicons for use with flux:icon component
• Access up-to-date documentation directly from the official Flux website
• High-performance caching with 24-hour expiration for optimal response times

Available MCP Tools

The server provides four MCP tools:

1. fetch_flux_docs - Fetches documentation for components or layouts

   • component (optional): Specific component name to fetch docs for
   • layout (optional): Specific layout name to fetch docs for (e.g., "header", "sidebar")
   • version (optional): Flux major version to target — 'v1' or 'v2' (default 'v2')
   • Automatically includes reference sections when available
   • Fetches from https://fluxui.dev/components/{component} or https://fluxui.dev/layouts/{layout} (v2); routes to https://v1.fluxui.dev/components/{component} when version='v1'
   • When the page is a paid Flux component, a [NOTICE] This is a Flux Pro component … line is prepended to the response

2. list_flux_components - Lists all available Flux components

   • version (optional): 'v1' or 'v2' (default 'v2')
   • tier (optional): 'free', 'pro', or 'all' (default 'all'). On 'all', each component is annotated [Pro] or [Free]. On v1, the tier argument is ignored (v1 has no Pro tier).
   • Provides component names and their documentation paths

3. list_flux_layouts - Lists all available Flux layouts

   • version (optional): 'v1' or 'v2' (default 'v2'). On v1 the tool returns a brief "layouts are not available in v1" notice without making any HTTP request.
   • Provides layout names and their documentation paths

4. list_flux_component_icons - Lists all available Heroicons for flux:icon component

   • variant (optional): Filter by icon variant (outline, solid, mini, micro)
   • search (optional): Search term to filter icon names
   • Fetches actual icon names from Heroicons GitHub repository
   • Provides usage examples, dimensions, and GitHub links for each variant
   • Returns comprehensive list of all available icons with proper Flux syntax

Example Usage

Once the MCP server is running, AI assistants can use it to:

• Get documentation for a specific component: "Show me the Button component docs"
• Get documentation for a specific layout: "Show me the header layout docs"
• List available components: "What Flux components are available?"
• List available layouts: "What Flux layouts are available?"
• Browse all available icons: "Show me all Heroicons available for flux:icon"
• Search for specific icons: "Find all arrow icons in the outline variant"
• Get icon usage examples: "How do I use the user icon in solid variant?"

The server automatically fetches the latest documentation from fluxui.dev/components, fluxui.dev/layouts, and Heroicons from GitHub, presenting everything in a structured format for easy consumption by AI assistants. When fetching component or layout documentation, it includes both the main content and the reference section with detailed API information.

Versions

Flux ships in two major versions, and the MCP server supports both:

• v2 (default) — the current host at fluxui.dev. Used when version is omitted or set to 'v2'. Supports components, layouts, and Pro-tier awareness.
• v1 — the legacy host at v1.fluxui.dev. Used when version='v1'. Components only — Flux v1 has no /layouts route and no Pro tier. list_flux_layouts returns a friendly notice on v1 without making any HTTP request; tier is ignored on list_flux_components for v1.

The version argument is accepted on fetch_flux_docs, list_flux_components, and list_flux_layouts. list_flux_component_icons is version-independent (Heroicons are not part of Flux versioning).

Pro tier awareness

A subset of Flux v2 components is only available with a paid Flux Pro license. The MCP server surfaces this in two ways:

• Notice on fetch. When fetch_flux_docs retrieves a component that is Pro, the response is prepended with a single [NOTICE] This is a Flux Pro component — requires a paid Flux license. line.
• Tier filter on listing. list_flux_components accepts tier='free' to hide Pro components, tier='pro' to show only Pro ones, or tier='all' (default) to list everything with [Pro] / [Free] annotations next to each name.

The list of Pro components is derived from fluxui.dev/pricing with a hardcoded fallback baked into the server, so tier filtering still works correctly if the pricing page is unreachable.

Manually Registering the MCP Server

Sometimes you may need to manually register the Livewire Flux MCP server with your editor of choice. You should register the MCP server using the following details:

Command	npx
Args	livewire-flux-mcp

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

Performance & Caching

The MCP server includes intelligent caching to provide optimal performance:

• 24-hour cache expiration - Content is cached for 1 day to balance freshness with performance
• Automatic cache management - Expired entries are automatically cleaned up
• Intelligent cache keys - Different cache entries for different parameters (component, layout, version, tier, variant)
• GitHub API rate limit protection - Prevents hitting GitHub API limits when fetching Heroicons
• Instant responses - Cached requests return in milliseconds instead of seconds

Cache Behavior

• Documentation requests: Cached per component/layout and version combination
• Component listings: Cached globally (refreshed daily)
• Layout listings: Cached globally (refreshed daily)
• Icon listings: Cached per variant and search combination
• Cache storage: In-memory (resets when server restarts)

The caching system is particularly beneficial for the list_flux_component_icons tool, which can make up to 4 GitHub API calls per request without caching.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Maurizio
• All Contributors

License

The MIT License (MIT). Please see License File for more information.