stimulus_plumbers_mcp 0.4.5 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c888ecb5ce465abc47875df8b2924ed833930400af77b9ebc546207173adf4d3
-  data.tar.gz: 9f2278aa3c144f18e82a3070894bbfd4aeb1a30870b0ca1611c137252aedcaac
+  metadata.gz: 7d89f95c23f003c323773ab4dc24b1b21ca2fd891fdc388c77e65987942cb581
+  data.tar.gz: 5c32a25cf7e0cf97f11d0bf6f209dc4d3ff33068d1fd4fa10d83ccb2578e3474
 SHA512:
-  metadata.gz: e62c6f7a43d006f158e2bf309f7a044ddff0bc74534667d2c736ac9f7c8dd5f977f0daf1b00ba063b4a5d6dc7c0d7043949cc89ca40e0a203847ba0e25cb87ad
-  data.tar.gz: 8d7dafd931f3db501d06b48436ab5d028d5e4fb57d49b1a8ed4cc20c5ffad7ccdb6bebf45cc166438cafb55cf637ced44bb48e78339998189f2ebd7629c13878
+  metadata.gz: 1d8f30f1f03e404e8996f0e12012f624e2df37dab801accf2f194f5d5a758c6e56369e74525a0ffa91537d56a04f03273e9b0de546c78d4e9a6f1d27f2a8c558
+  data.tar.gz: e8feda10a77d64456f63ccb8bc88dc20061aa9a6145d0bff8e15adc18fea0b8491f0a1017d54186302a96079598789e7376d058e9cafac56571f00e37dda28b1

data/README.md

@@ -18,34 +18,48 @@ gem install stimulus_plumbers_mcp
 | URI | Content |
 |-----|---------|
 | `guide://overview` | **Start here** — map of the form/view/stimulus API with pointers to every tool/resource |
-| `schema://components` | Index of all component theme keys |
-| `schema://components/{name}` | Params, valid values, defaults + required controllers |
-| `schema://icons` | All available icon names |
-| `schema://stimulus` | Map from component key → required Stimulus controller identifiers |
-| `docs://components/{name}` | Full markdown doc with ERB examples |
-| `helper://components/{name}` | Full `sp_` helper surface: keyword options + defaults (grouped by helper signature) + slot methods (with block-required flag) |
-| `stimulus://controllers` | Index of Stimulus controller identifiers |
-| `stimulus://controllers/{identifier}` | Targets, values, outlets, classes for a controller |
-| `theme://base` | Custom theme authoring guide |
-| `theme://components` | Index of theme-implementable component keys |
-| `theme://components/{name}` | Method name, param signature, return contract |
-| `tailwind://components` | Index of Tailwind theme component keys |
-| `tailwind://components/{name}` | Tailwind CSS classes per variant |
+| `guide://{name}` | Per-package usage guide: `component` (Rails forms/views), `controller` (plain-JS/non-Rails setup), `tailwind` (Tailwind install/theming), `theme` (custom theme integration contract) |
+| `aria://reference` | WCAG 2.1 AA criteria, keyboard navigation patterns, and per-component ARIA patterns |
+| `component://index` | Index of all component theme keys |
+| `component://icons` | All available icon names |
+| `component://integration` | Map from component key → required Stimulus controller identifiers |
+| `component://{name}/schema` | Params, valid values, defaults + required controllers |
+| `component://{name}/docs` | Full markdown doc with ERB examples |
+| `component://{name}/helper` | Full `sp_` helper surface: keyword options + defaults (grouped by helper signature) + slot methods |
+| `component://theme` | Index of theme-implementable component keys |
+| `component://{name}/theme` | Method name, param signature, return contract |
+| `component://theme/base` | Custom theme authoring guide |
+| `component://tailwind` | Index of Tailwind theme component keys |
+| `component://{name}/tailwind` | Tailwind CSS classes per variant |
+| `controller://index` | Index of Stimulus controller identifiers |
+| `controller://{name}/schema` | Targets, values, outlets, classes for a controller |
+| `controller://docs` | Index of JS controller narrative docs, grouped by controller family |
+| `controller://docs/{name}` | Narrative usage doc for a controller family (plain-JS/Hotwire, no Rails helpers) |
+| `versions://sources` | Resolved version (and resolution path) of each source gem/package |
 
 ## Tools
 
 | Tool | Input | Output |
 |------|-------|--------|
 | `list_components` | — | All component theme keys |
-| `list_docs` | — | Components with markdown docs + helper signatures (the `docs://`/`helper://` `{name}` set) |
-| `get_component_schema` | `component` | Themed params (type/variant/size) + defaults + required controllers |
-| `get_helper_signature` | `component` | Full `sp_` helper surface — keyword options grouped by helper signature (incl. `icon_leading`) + slot methods |
-| `get_erb_examples` | `component` | ERB code fences from docs |
-| `get_field_types` | `builder_method` (`field`/`collection_field`/`choice`) | Valid `as:` values |
+| `list_component_docs` | — | Components with markdown docs + helper signatures (the `component://{name}/docs`+`/helper` set) |
+| `get_component_schema` | `name` | Themed params (type/variant/size) + defaults + required controllers |
+| `get_component_helper` | `name` | Full `sp_` helper surface — keyword options grouped by helper signature (incl. `icon_leading`) + slot methods |
+| `get_component_examples` | `name` | ERB code fences from docs |
+| `get_field_as_values` | `builder_method` (`field`/`collection_field`/`choice`) | Valid `as:` values |
+| `get_field_as_controller` | `as` | Stimulus controller identifier backing a controller-backed `as:` value |
+| `list_component_themes` | — | Component keys implementable in a custom theme |
+| `get_component_theme` | `name` | Method signature + return contract for custom theme |
+| `list_component_tailwind` | — | Component keys implemented by the Tailwind theme |
+| `get_component_tailwind` | `name` | Tailwind CSS utility classes per variant |
+| `list_icons` | — | All available icon names bundled with the Tailwind theme |
 | `list_controllers` | — | All Stimulus controller identifiers |
-| `get_controller_schema` | `controller` | Targets, values, outlets, classes |
-| `get_theme_interface` | `component` | Method signature + return contract for custom theme |
-| `get_tailwind_classes` | `component` | Tailwind CSS utility classes per variant |
+| `get_controller_schema` | `name` | Targets, values, outlets, classes |
+| `list_controller_docs` | — | Controller doc families available at `controller://docs/{name}` |
+| `get_controller_docs` | `name` | Narrative usage doc for a controller family |
+| `get_source_versions` | — | Resolved version (and resolution path) of each source |
+| `list_guides` | — | Available per-package guide names (`component`/`controller`/`tailwind`/`theme`) |
+| `get_guide` | `name` | Per-package usage guide content |
 
 ## IDE Setup
 
@@ -60,11 +74,11 @@ gem install stimulus_plumbers_mcp
 }
 ```
 
-Requires Ruby >= 3.3. No `cwd` required. Pin a specific version by adding it to your `Gemfile` and running `bundle exec gem exec stimulus-plumbers-mcp`.
+Requires Ruby >= 3.3 for the `gem exec` subcommand (the gem itself supports Ruby >= 3.0). No `cwd` required. Pin a specific version by adding it to your `Gemfile` and running `bundle exec gem exec stimulus-plumbers-mcp`.
 
 ## Stimulus Manifest
 
-`stimulus://` resources require the controller manifest. The server resolves it in order:
+`controller://` resources require the controller manifest. The server resolves it in order:
 
 1. `node_modules/@stimulus-plumbers/controllers/dist/controllers.manifest.json` — npm/yarn/bun projects
 2. `vendor/controllers.manifest.json` inside the installed `stimulus_plumbers` gem — importmaps fallback
@@ -72,6 +86,10 @@ Requires Ruby >= 3.3. No `cwd` required. Pin a specific version by adding it to
 
 No extra steps needed for setups 1 or 2.
 
+Each controller's schema also includes a `wiring` field (which methods/events/targets/values the
+`stimulus_plumbers` gem's Ruby helpers reference for it), sourced from that gem's own
+`vendor/component/manifest.json`, built by `rake build:manifest`.
+
 ## Development
 
 ```bash
@@ -82,6 +100,9 @@ bundle install
 # Build the Stimulus controller manifest (pure Node, no toolchain install needed)
 cd ../stimulus-plumbers && node --run build:manifest && cd -
 
+# Build the Ruby wiring manifest (needs the controller manifest above)
+cd ../stimulus-plumbers-rails && bundle exec rake build:manifest && cd -
+
 # Start the server
 bundle exec ruby bin/server
 ```
@@ -94,9 +115,9 @@ bundle exec ruby bin/server
 bundle exec ruby bin/mcp-query tools                                  # list tools
 bundle exec ruby bin/mcp-query resources                              # list resources
 bundle exec ruby bin/mcp-query tool list_components                   # call a tool (no args)
-bundle exec ruby bin/mcp-query tool get_component_schema '{"component":"button"}'
+bundle exec ruby bin/mcp-query tool get_component_schema '{"name":"button"}'
 bundle exec ruby bin/mcp-query read guide://overview
-bundle exec ruby bin/mcp-query read docs://components/form
+bundle exec ruby bin/mcp-query read component://form/docs
 ```
 
 ```bash

data/lib/stimulus_plumbers/mcp/loaders/aria_loader.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class AriaLoader
+      FILENAME = "ARIA.md"
+
+      class << self
+        def call
+          path = resolved_path
+          path ? File.read(path) : ""
+        end
+
+        private
+
+        def resolved_path
+          aria_paths.find { |p| File.exist?(p) }
+        end
+
+        def aria_paths
+          [
+            # 1. Monorepo dev checkout — the root file is the freshest copy while working locally.
+            File.expand_path(File.join(__dir__, "../../../../..", FILENAME)),
+            # 2. gem exec — vendored into the rails gem at release time (bin/release).
+            GemVendorPath.resolve(FILENAME)
+          ].compact
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/component_docs_loader.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentDocsLoader
+      class << self
+        def docs_dir
+          @docs_dir ||= resolve_docs_dir
+        end
+
+        def call
+          Dir[File.join(docs_dir, "*.md")].each_with_object({}) do |path, result|
+            name = File.basename(path, ".md").to_sym
+            content = File.read(path)
+            result[name] = {
+              content:   content,
+              examples:  extract_erb_examples(content),
+              signature: DocsTableParser.call(content)
+            }
+          end
+        end
+
+        private
+
+        def resolve_docs_dir
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers").gem_dir
+          File.join(gem_dir, "docs/component")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-rails/docs/component", __dir__)
+        end
+
+        def extract_erb_examples(content)
+          content.scan(%r{```erb\n(.*?)```}m).map(&:first).map(&:strip)
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/component_manifest_loader.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    # Reads the stimulus_plumbers gem's own generated wiring manifest (vendor/component/manifest.json).
+    # Unlike ControllerSchemaLoader, this never crosses ecosystems — stimulus_plumbers is always
+    # installed alongside this gem (hard runtime dependency), so there's no node_modules-style path.
+    class ComponentManifestLoader
+      MANIFEST_FILENAME = "manifest.json"
+
+      class << self
+        def call
+          path = resolved_path
+
+          unless path
+            StimulusPlumbers::Logger.warn(
+              "component manifest not found. Tried:\n" \
+              "#{manifest_paths.map { |p| "  - #{p}" }.join("\n")}\n" \
+              "Run `bundle exec rake build:manifest` in stimulus-plumbers-rails/ to generate it."
+            )
+            return {}
+          end
+
+          JSON.parse(File.read(path))
+        end
+
+        def resolved_path
+          manifest_paths.find { |p| File.exist?(p) }
+        end
+
+        private
+
+        def manifest_paths
+          [
+            # 1. gem exec / installed gem — vendored at release time
+            GemVendorPath.resolve("component", MANIFEST_FILENAME),
+            # 2. Monorepo dev fallback
+            File.expand_path(
+              File.join(__dir__, "../../../../..", "stimulus-plumbers-rails", "vendor", "component", MANIFEST_FILENAME)
+            )
+          ].compact
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/component_requirements.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentRequirements
+      class << self
+        def call
+          Components.constants
+                    .map { |c| Components.const_get(c) }
+                    .grep(Class)
+                    .to_h { |klass| [component_key(klass), controllers_for(klass).uniq] }
+        end
+
+        private
+
+        # Controllers from a component class plus its nested sub-components (e.g. Combobox::Date),
+        # keyed to the top-level component. Skips references to sibling components.
+        def controllers_for(mod)
+          mod.constants(false).flat_map do |const|
+            value = mod.const_get(const)
+            if const.to_s.end_with?("CONTROLLER")
+              Array(value).grep(String).flat_map(&:split)
+            elsif nested?(mod, value)
+              controllers_for(value)
+            else
+              []
+            end
+          end
+        end
+
+        def nested?(mod, value)
+          value.is_a?(Module) && !value.name.nil? && value.name.start_with?("#{mod.name}::")
+        end
+
+        def component_key(klass)
+          klass.name.demodulize.underscore.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/component_schema_loader.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentSchemaLoader
+      # Not derivable from Form::Fields::Renderer's method names (`search:` renders via
+      # `render_combobox_typeahead`, but wires up "combobox-dropdown", not
+      # "combobox-typeahead") — hand-maintained; keep in sync with form.md's "backed by" notes.
+      FIELD_AS_CONTROLLERS = {
+        date:                      "combobox-date",
+        time:                      "combobox-time",
+        select:                    "combobox-dropdown",
+        search:                    "combobox-dropdown",
+        collection_select:         "combobox-dropdown",
+        grouped_collection_select: "combobox-dropdown"
+      }.freeze
+
+      class << self
+        def call
+          {
+            components:           extract_schema,
+            field_as:             extract_field_as,
+            field_as_controllers: FIELD_AS_CONTROLLERS,
+            controllers:          ComponentRequirements.call
+          }
+        end
+
+        private
+
+        def extract_schema
+          Themes::Base::SCHEMA.transform_values do |param_schema|
+            param_schema.transform_values do |meta|
+              v = meta[:validate]
+              { default: meta[:default], valid: v.respond_to?(:to_a) ? v.to_a : v.inspect }
+            end
+          end
+        end
+
+        def extract_field_as
+          {
+            field:            Form::Fields::Renderer::FIELD.keys,
+            collection_field: Form::Fields::Renderer::COLLECTION.keys,
+            choice:           Form::Fields::Renderer::CHOICE.keys
+          }
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/component_theme_loader.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentThemeLoader
+      class << self
+        def call
+          {
+            base_doc:   base_doc,
+            components: extract_interface
+          }
+        end
+
+        private
+
+        # Same file ComponentDocsLoader already serves at component://theme/docs — avoids a duplicate heredoc.
+        def base_doc
+          path = File.join(ComponentDocsLoader.docs_dir, "theme.md")
+          File.exist?(path) ? File.read(path) : ""
+        end
+
+        def extract_interface
+          Themes::Base::SCHEMA.each_with_object({}) do |(key, params), result|
+            result[key] = {
+              method:  "#{key}_classes",
+              params:  params.transform_values { |meta| format_param(meta) },
+              returns: "{ classes: String }"
+            }
+          end
+        end
+
+        def format_param(meta)
+          valid = meta[:validate]
+          entry = { default: meta[:default] }
+          entry[:valid] = valid.to_a if valid.respond_to?(:to_a)
+          entry
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/controller_docs_loader.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ControllerDocsLoader
+      class << self
+        def docs_dir
+          @docs_dir ||= resolve_docs_dir
+        end
+
+        def call
+          Dir[File.join(docs_dir, "*.md")].to_h do |path|
+            [File.basename(path, ".md").to_sym, File.read(path)]
+          end
+        end
+
+        private
+
+        def resolve_docs_dir
+          # 1. Monorepo dev checkout — the JS package's own docs are freshest while working locally.
+          dev_path = File.expand_path(File.join(__dir__, "../../../../..", "stimulus-plumbers", "docs", "component"))
+          return dev_path if Dir.exist?(dev_path)
+
+          # 2. gem exec — vendored into the rails gem at release time, under vendor/controller/docs/
+          # (mirrors the MCP server's controller:// resource namespace).
+          GemVendorPath.resolve("controller", "docs") || dev_path
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/controller_schema_loader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ControllerSchemaLoader
+      MANIFEST_FILENAME = "controllers.manifest.json"
+      # Vendored as manifest.json — the "controllers" prefix is redundant once nested
+      # under vendor/controller/ (mirrors the MCP server's controller:// namespace).
+      VENDOR_FILENAME = "manifest.json"
+
+      class << self
+        def call
+          path = resolved_path
+
+          unless path
+            StimulusPlumbers::Logger.warn(
+              "controller manifest not found. Tried:\n" \
+              "#{manifest_paths.map { |p| "  - #{p}" }.join("\n")}\n" \
+              "Run `node --run build:manifest` in stimulus-plumbers/ to generate it."
+            )
+            return {}
+          end
+
+          controllers = JSON.parse(File.read(path))
+          wiring = ComponentManifestLoader.call
+          default_wiring = { "actions" => [], "listens" => [], "targets" => [], "values" => [] }
+
+          controllers.transform_values { |data| data.merge("wiring" => wiring[data["identifier"]] || default_wiring) }
+        end
+
+        # Reused by VersionsLoader to report which fallback location resolved.
+        def resolved_path
+          manifest_paths.find { |p| File.exist?(p) }
+        end
+
+        private
+
+        def manifest_paths
+          [
+            # 1. npm/yarn/bun project — version matches project lockfile
+            File.join(Dir.pwd, "node_modules/@stimulus-plumbers/controllers/dist", MANIFEST_FILENAME),
+            # 2. importmaps users — vendored in Rails gem at release time
+            GemVendorPath.resolve("controller", VENDOR_FILENAME),
+            # 3. Monorepo dev fallback
+            File.expand_path(
+              File.join(__dir__, "../../../../..", "stimulus-plumbers", "dist", MANIFEST_FILENAME)
+            )
+          ].compact
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/guide.md

@@ -0,0 +1,48 @@
+# stimulus-plumbers — overview
+
+Accessible Rails view components plus a themed form builder, backed by Stimulus controllers.
+Start here, then drill into the per-package guides and per-component resources/tools below.
+
+## Per-package guides
+- `guide://component` — building forms (`f.field`/`f.collection_field`/`f.choice`) and views
+  (`sp_*` helpers) with the Rails gem
+- `guide://controller` — plain-JS / non-Rails setup for `@stimulus-plumbers/controllers`
+- `guide://tailwind` — Tailwind theme install + icons
+- `guide://theme` — implementing a custom theme (subclassing `Themes::Base`)
+
+Tools: `list_guides`, `get_guide(name:)`.
+
+## Building forms and views
+Valid `as:` values: `get_field_as_values(builder_method:)`. Combobox-backed `as:` values' controller
+identifier: `get_field_as_controller(as:)` — `component://{name}/schema` keys are renderer-level, not
+`as:` values. Component helper surface: `get_component_helper(name)`; themed params:
+`get_component_schema(name)`; ERB examples: `get_component_examples(name)`. List everything with
+`list_components`; `list_component_docs` shows which components have full docs
+(`component://{name}/docs`) and helper signatures (`component://{name}/helper`). Icon options take a
+name from `component://icons` (or `list_icons`). All schema components are queryable via
+`get_component_schema`; only a subset have full docs and ERB examples — use `list_component_docs` to
+see what's covered. Full form builder reference: `component://form/docs`.
+
+## Stimulus integration
+Most display components are pure markup; interactive ones (combobox, popover, calendar) emit their
+`data-controller` attributes automatically. Component → required controllers: `component://integration`.
+Controller identifiers and details (targets/values/outlets/classes): `controller://index`,
+`get_controller_schema(id)` / `list_controllers`.
+Narrative docs by controller family: `get_controller_docs(name)` / `controller://docs/{name}`.
+
+## How this server is organized
+- **Resources** live under entity namespaces — `component://` (Rails `sp_*` helper surface: schema,
+  docs, helper, theme, tailwind, icons facets), `controller://` (plain-JS Stimulus surface: schema,
+  docs facets), `guide://` (per-package usage guides) — plus `aria://reference` and `versions://sources`.
+  **Tools** (`get_*`, `list_*`) expose the same data for targeted lookups. Use whichever your client prefers.
+- `aria://reference` — WCAG 2.1 AA criteria and component ARIA patterns. For generic ARIA/WCAG reference,
+  connect the MDN MCP server too: `claude mcp add --transport http mdn https://mcp.mdn.mozilla.net/`
+- Each source (schema, docs, theme, tailwind, icons, stimulus, stimulus_docs, guide) is read from an
+  independently-versioned gem/npm package — `versions://sources` / `get_source_versions` reports what's
+  actually resolved, useful if data looks stale or inconsistent with the app code you're generating for.
+  `icons` versions with the Tailwind theme gem, not the schema gem, since the bundled icon set is
+  Tailwind-specific.
+- **View generation** uses the form builder + `sp_` helper tools/resources above. The `component://theme`
+  and `component://tailwind` facets are for *theme authors* implementing a custom theme — skip them when
+  generating views.
+- **Errors are uniform:** a not-found tool/resource returns `{ "error": "..." }` (tools also set `isError`).

data/lib/stimulus_plumbers/mcp/loaders/guide_loader.rb

@@ -3,12 +3,48 @@
 module StimulusPlumbers
   module MCP
     class GuideLoader
-      OVERVIEW_PATH = File.expand_path("guide/overview.md", __dir__).freeze
+      OVERVIEW_PATH = File.expand_path("guide.md", __dir__).freeze
 
-      def self.call
-        return "" unless File.exist?(OVERVIEW_PATH)
+      class << self
+        def call
+          {
+            overview:   read_file(OVERVIEW_PATH),
+            component:  read_file(component_guide_path),
+            controller: read_file(controller_guide_path),
+            tailwind:   read_file(tailwind_guide_path),
+            theme:      read_file(File.join(ComponentDocsLoader.docs_dir, "theme.md"))
+          }
+        end
 
-        File.read(OVERVIEW_PATH)
+        # Reused by VersionsLoader to report which fallback location resolved.
+        def controller_guide_path
+          # 1. Monorepo dev checkout — the JS package's own docs are freshest while working locally.
+          dev_path = File.expand_path(File.join(__dir__, "../../../../..", "stimulus-plumbers", "docs", "guide.md"))
+          return dev_path if File.exist?(dev_path)
+
+          # 2. gem exec — vendored into the rails gem at release time, under vendor/controller/guide.md.
+          GemVendorPath.resolve("controller", "guide.md")
+        end
+
+        private
+
+        def read_file(path)
+          path && File.exist?(path) ? File.read(path) : ""
+        end
+
+        def component_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-rails/docs/guide.md", __dir__)
+        end
+
+        def tailwind_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers_tailwind").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-tailwind/docs/guide.md", __dir__)
+        end
       end
     end
   end

data/lib/stimulus_plumbers/mcp/loaders/icons_loader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class IconsLoader
+      class << self
+        def call
+          heroicon_dir = Themes::Tailwind::Icons::Heroicon.send(:svg_dir)
+          custom_dir   = Themes::Tailwind::Icons::Custom.send(:svg_dir)
+
+          (outline_names(heroicon_dir) + solid_names(heroicon_dir) + custom_names(custom_dir) + alias_names).uniq.sort
+        end
+
+        private
+
+        def outline_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "outline", "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def solid_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "solid", "*.svg")].map { |f| "#{File.basename(f, ".svg")}/solid" }
+        end
+
+        def custom_names(custom_dir)
+          Dir[File.join(custom_dir, "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def alias_names
+          Themes::Tailwind::Icon::ALIASES.keys
+        end
+      end
+    end
+  end
+end