stimulus_plumbers_mcp 0.4.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00ce340e2b2d68fcfef0406efd76e88e91c5214c653bc44cbed78d6ebf23bd4e
+  data.tar.gz: c4ec9ad1abdabfb7ab464b685e604d78feec3a67b10944339885adbd5f322668
+SHA512:
+  metadata.gz: 752269bd37dc2716c2fdabf2aab3bb6cecb9bd6aaae82ff245c95414ef98c9a670ac1da896a32dafa00b9d47b8231214b5f150f3ca1efd7705faafe978eabccb
+  data.tar.gz: 8540984025d8870982f1d75d8a33a51dfcb3096084eb8c8d0ef0dc5cc39f62b02310f787568a0d34a8cb49ac055273b6f2fa7254b398a67703879d750dceb9f5

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentControllerMap
+      def self.call
+        Components.constants
+                  .map { |c| Components.const_get(c) }
+                  .grep(Class)
+                  .to_h { |klass| [component_key(klass), controllers_for(klass).uniq] }
+      end
+
+      # 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 self.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 self.nested?(mod, value)
+        value.is_a?(Module) && !value.name.nil? && value.name.start_with?("#{mod.name}::")
+      end
+
+      def self.component_key(klass)
+        klass.name.demodulize.underscore.to_sym
+      end
+      private_class_method :controllers_for, :nested?, :component_key
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class DocsLoader
+      DOCS_DIR = File.expand_path(
+        "../../../../../stimulus-plumbers-rails/docs/component",
+        __dir__
+      )
+
+      def self.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: extract_signature(content)
+          }
+        end
+      end
+
+      def self.extract_erb_examples(content)
+        content.scan(%r{```erb\n(.*?)```}m).map(&:first).map(&:strip)
+      end
+
+      # Parse `| Option |` / `| Slot method |` doc tables into the helper surface.
+      # Options are grouped under the heading (sub-helper signature) above them.
+      def self.extract_signature(content)
+        tables = tables_with_headings(content)
+        { helpers: option_helpers(tables), slots: slot_methods(tables) }
+      end
+
+      def self.option_helpers(tables)
+        tables.select { |t| t[:header].first == "Option" }
+              .filter_map do |t|
+                options = t[:rows].map { |r| option_row(r) }
+                { signature: t[:heading], options: options } unless options.empty?
+              end
+      end
+
+      def self.slot_methods(tables)
+        tables.select { |t| t[:header].first == "Slot method" }
+              .flat_map { |t| t[:rows].map { |r| slot_row(r) } }
+      end
+
+      def self.option_row(cells)
+        { option: clean(cells[0]), default: clean(cells[1]), description: cells[2].to_s }
+      end
+
+      def self.slot_row(cells)
+        slot = clean(cells[0])
+        description = cells[1].to_s
+        { slot: slot, description: description, block: block_required?(slot, description) }
+      end
+
+      def self.block_required?(slot, description)
+        slot.include?("{") || description.match?(%r{block required}i)
+      end
+
+      # Tag each table with the heading above it; skip fenced code (so ```ruby
+      # comments aren't read as headings).
+      def self.tables_with_headings(content)
+        state = { heading: nil, fenced: false, buffer: [], tables: [] }
+        content.each_line { |line| scan_line(line, state) }
+        flush_table(state)
+        state[:tables]
+      end
+
+      def self.scan_line(line, state)
+        if line.start_with?("```")
+          flush_table(state)
+          state[:fenced] = !state[:fenced]
+        elsif state[:fenced]
+          nil
+        elsif (heading = line[%r{\A#+\s+(.+)}, 1])
+          flush_table(state)
+          state[:heading] = clean(heading)
+        elsif line.lstrip.start_with?("|")
+          state[:buffer] << line
+        else
+          flush_table(state)
+        end
+      end
+
+      def self.flush_table(state)
+        return if state[:buffer].empty?
+
+        state[:tables] << build_table(state[:buffer]).merge(heading: state[:heading])
+        state[:buffer] = []
+      end
+
+      def self.build_table(lines)
+        rows = lines.map { |l| split_row(l) }.reject { |cells| cells.all? { |c| c.match?(%r{\A:?-+:?\z}) } }
+        { header: rows.first, rows: rows.drop(1) }
+      end
+
+      # Split a markdown table row, honouring escaped pipes (`\|`) inside cells.
+      def self.split_row(line)
+        line.strip.delete_prefix("|").delete_suffix("|")
+            .split(%r{(?<!\\)\|})
+            .map { |c| c.gsub('\|', "|").strip }
+      end
+
+      def self.clean(cell)
+        cell.to_s.gsub(%r{[`*]}, "").sub(%r{:\z}, "").strip
+      end
+
+      private_class_method :option_helpers,
+                           :slot_methods,
+                           :option_row,
+                           :slot_row,
+                           :block_required?,
+                           :tables_with_headings,
+                           :scan_line,
+                           :flush_table,
+                           :build_table,
+                           :split_row,
+                           :clean
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class GuideLoader
+      OVERVIEW_PATH = File.expand_path("guide/overview.md", __dir__).freeze
+
+      def self.call
+        return "" unless File.exist?(OVERVIEW_PATH)
+
+        File.read(OVERVIEW_PATH)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class SchemaLoader
+      def self.call
+        {
+          components: extract_schema,
+          field_as:   extract_field_as,
+          icons:      extract_icons,
+          stimulus:   ComponentControllerMap.call
+        }
+      end
+
+      def self.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 self.extract_field_as
+        {
+          field:            Form::Fields::Renderer::FIELD.keys,
+          collection_field: Form::Fields::Renderer::COLLECTION.keys,
+          choice:           Form::Fields::Renderer::CHOICE.keys
+        }
+      end
+
+      def self.extract_icons
+        heroicon_dir = Themes::Tailwind::Icons::Heroicon.send(:svg_dir)
+        custom_dir   = Themes::Tailwind::Icons::Custom.send(:svg_dir)
+
+        outline = Dir[File.join(heroicon_dir, "outline", "*.svg")].map { |f| File.basename(f, ".svg") }
+        solid   = Dir[File.join(heroicon_dir, "solid",   "*.svg")].map { |f| "#{File.basename(f, ".svg")}/solid" }
+        customs = Dir[File.join(custom_dir, "*.svg")].map { |f| File.basename(f, ".svg") }
+        aliases = Themes::Tailwind::Icon::ALIASES.keys
+
+        (outline + solid + customs + aliases).uniq.sort
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class StimulusManifest
+      MANIFEST_PATH = File.expand_path(
+        File.join(__dir__, "../../../../..", "stimulus-plumbers", "dist", "controllers.manifest.json")
+      ).freeze
+
+      def self.call
+        unless File.exist?(MANIFEST_PATH)
+          StimulusPlumbers::Logger.warn(
+            "controllers.manifest.json not found at #{MANIFEST_PATH}. " \
+            "Run `node --run build:manifest` in stimulus-plumbers/ to generate it."
+          )
+          return {}
+        end
+
+        JSON.parse(File.read(MANIFEST_PATH))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class TailwindThemeLoader
+      def self.call
+        theme = Themes::TailwindTheme.new
+
+        Themes::Base::SCHEMA.each_with_object({}) do |(key, params), result|
+          # Skip keys with no _classes method — calling resolve would trigger Logger.warn
+          next unless theme.respond_to?(:"#{key}_classes", true)
+
+          result[key] = {}
+          result[key][:default] = theme.resolve(key)[:classes].to_s
+
+          params.each do |param, meta|
+            valid = meta[:validate]
+            next unless valid.respond_to?(:to_a)
+
+            valid.to_a.each do |val|
+              classes = theme.resolve(key, param => val)[:classes].to_s
+              result[key]["#{param}:#{val}"] = classes
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ThemeLoader
+      BASE_DOC = <<~MARKDOWN
+        # Custom Theme Implementation Guide
+
+        A custom theme is a Ruby class that extends `StimulusPlumbers::Themes::Base` and defines
+        `{component_key}_classes(**args)` methods for the components you want to style.
+
+        ## Method Convention
+
+        - **Name:** `{component_key}_classes` — e.g. `button_classes`, `form_group_classes`
+        - **Params:** keyword arguments matching the schema params for that component
+        - **Return:** a Hash with a `:classes` key containing a space-separated CSS class string
+
+        ```ruby
+        def button_classes(type: :default, variant: :default, size: :md)
+          { classes: "..." }
+        end
+        ```
+
+        Components with no params still receive empty kwargs:
+
+        ```ruby
+        def form_group_classes
+          { classes: "..." }
+        end
+        ```
+
+        ## Minimal Example
+
+        ```ruby
+        class MyTheme < StimulusPlumbers::Themes::Base
+          private
+
+          def button_classes(type: :default, variant: :default, size: :md)
+            base = "inline-flex items-center gap-2 rounded px-3 py-2"
+            variant_class = { primary: "bg-blue-600 text-white", destructive: "bg-red-600 text-white" }.fetch(variant, "bg-gray-100")
+            { classes: [base, variant_class].join(" ") }
+          end
+
+          def link_classes(type: :default, variant: :default)
+            { classes: "underline text-blue-600 hover:text-blue-800" }
+          end
+        end
+        ```
+
+        ## Registration
+
+        ```ruby
+        StimulusPlumbers.configure do |config|
+          config.theme.register(:my_theme, MyTheme)
+          config.theme = :my_theme
+        end
+        ```
+
+        ## Component Keys
+
+        See `theme://components` for the full list of component keys that can be themed.
+        Use `theme://components/{name}` for the method signature and param details per component.
+
+        ## Partial Implementation
+
+        You only need to define methods for components you want to style — unimplemented keys
+        return an empty hash, which renders the component with no CSS classes.
+      MARKDOWN
+
+      def self.call
+        {
+          base_doc:   BASE_DOC,
+          components: extract_interface
+        }
+      end
+
+      def self.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 self.format_param(meta)
+        valid = meta[:validate]
+        entry = { default: meta[:default] }
+        entry[:valid] = valid.to_a if valid.respond_to?(:to_a)
+        entry
+      end
+
+      private_class_method :extract_interface, :format_param
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      # Shared contract + content helpers for plugins, which `extend` this.
+      #
+      # Each plugin defines: LOADER_KEY, LOADER, STATIC_RESOURCES,
+      # DYNAMIC_RESOURCE_TEMPLATES, and read(uri, store). Tools are optional —
+      # plugins with tools override register_tools, the rest inherit the no-op.
+      module Base
+        # Returned by a tool block to signal "not found" — rendered as an MCP
+        # error response with a structured { error: } payload (see text_tool).
+        NotFound = Struct.new(:message)
+
+        def register_tools(_server, _store); end
+
+        def not_found(message)
+          NotFound.new(message)
+        end
+
+        # resources/read content for a JSON payload.
+        def json_resource(uri, data)
+          [{ uri: uri, mimeType: "application/json", text: JSON.generate(data) }]
+        end
+
+        # resources/read content for raw text (e.g. markdown).
+        def text_resource(uri, mime_type, text)
+          [{ uri: uri, mimeType: mime_type, text: text }]
+        end
+
+        # Define a tool whose block returns the response text, or `not_found(msg)`
+        # for a uniform error (isError + { error: } JSON). Declaring `**args` makes
+        # the MCP gem inject :server_context, which tool blocks don't want — drop it.
+        def text_tool(server, name:, description:, input_schema: nil, &block)
+          server.define_tool(name: name, description: description, input_schema: input_schema) do |**args|
+            args.delete(:server_context)
+            result = block.call(**args)
+            if result.is_a?(NotFound)
+              ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(error: result.message) }], error: true)
+            else
+              ::MCP::Tool::Response.new([{ type: "text", text: result }])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/docs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Docs
+        extend Base
+
+        LOADER_KEY = :docs
+        LOADER     = DocsLoader
+
+        STATIC_RESOURCES = [].freeze
+        DYNAMIC_RESOURCE_TEMPLATES = [
+          ::MCP::ResourceTemplate.new(
+            uri_template: "docs://components/{name}",
+            name:         "component-docs",
+            description:  "Full markdown documentation and ERB examples for a component",
+            mime_type:    "text/markdown"
+          ),
+          ::MCP::ResourceTemplate.new(
+            uri_template: "helper://components/{name}",
+            name:         "component-helper-signature",
+            description:  "Full sp_ helper option surface: keyword options with defaults and slot methods",
+            mime_type:    "application/json"
+          )
+        ].freeze
+
+        def self.read(uri, store)
+          docs = store[:docs]
+
+          case uri
+          when %r{\Adocs://components/(.+)\z}
+            doc = docs[Regexp.last_match(1).to_sym]
+            doc ? text_resource(uri, "text/markdown", doc[:content]) : missing(uri, Regexp.last_match(1))
+          when %r{\Ahelper://components/(.+)\z}
+            doc = docs[Regexp.last_match(1).to_sym]
+            doc ? json_resource(uri, doc[:signature]) : missing(uri, Regexp.last_match(1))
+          end
+        end
+
+        def self.missing(uri, name)
+          json_resource(uri, { error: "no documentation for: #{name}" })
+        end
+        private_class_method :missing
+
+        def self.register_tools(server, store)
+          docs = store[:docs]
+
+          text_tool(
+            server,
+            name:        "list_docs",
+            description: "Lists components that have markdown docs (docs://components/{name}) and " \
+                         "helper signatures (helper://components/{name})"
+          ) do
+            JSON.generate(docs.keys)
+          end
+
+          text_tool(
+            server,
+            name:         "get_erb_examples",
+            description:  "Returns ERB usage examples for a component from the documentation",
+            input_schema: { properties: { component: { type: "string" } }, required: ["component"] }
+          ) do |component:|
+            examples = docs[component.to_sym]&.dig(:examples) || []
+            examples.empty? ? not_found("no examples for: #{component}") : examples.join("\n\n")
+          end
+
+          text_tool(
+            server,
+            name:         "get_helper_signature",
+            description:  "Returns the full sp_ helper surface for a component: keyword options with " \
+                          "defaults plus slot methods (e.g. icon_leading, card.with_action)",
+            input_schema: { properties: { component: { type: "string" } }, required: ["component"] }
+          ) do |component:|
+            doc = docs[component.to_sym]
+            doc ? JSON.generate(doc[:signature]) : not_found("no documentation for: #{component}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/guide.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Guide
+        extend Base
+
+        LOADER_KEY = :guide
+        LOADER     = GuideLoader
+
+        STATIC_RESOURCES = [
+          ::MCP::Resource.new(
+            uri:         "guide://overview",
+            name:        "overview",
+            description: "Start here — how to build views and forms with stimulus-plumbers, with pointers to every tool/resource",
+            mime_type:   "text/markdown"
+          )
+        ].freeze
+
+        DYNAMIC_RESOURCE_TEMPLATES = [].freeze
+
+        def self.read(uri, store)
+          return unless uri == "guide://overview"
+
+          text_resource(uri, "text/markdown", store[:guide])
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/schema.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Schema
+        extend Base
+
+        LOADER_KEY = :schema
+        LOADER     = SchemaLoader
+
+        STATIC_RESOURCES = [
+          ::MCP::Resource.new(
+            uri:         "schema://components",
+            name:        "components-index",
+            description: "Index of all stimulus-plumbers component theme keys",
+            mime_type:   "application/json"
+          ),
+          ::MCP::Resource.new(
+            uri:         "schema://icons",
+            name:        "icons",
+            description: "All available icon names from the active theme registry",
+            mime_type:   "application/json"
+          ),
+          ::MCP::Resource.new(
+            uri:         "schema://stimulus",
+            name:        "stimulus-wiring",
+            description: "Mapping from Rails component name to the Stimulus controller identifiers it requires",
+            mime_type:   "application/json"
+          )
+        ].freeze
+
+        DYNAMIC_RESOURCE_TEMPLATES = [
+          ::MCP::ResourceTemplate.new(
+            uri_template: "schema://components/{name}",
+            name:         "component-schema",
+            description:  "Params, valid values, defaults, and required controllers for a component",
+            mime_type:    "application/json"
+          )
+        ].freeze
+
+        def self.read(uri, store)
+          schema = store[:schema]
+
+          case uri
+          when "schema://components"
+            json_resource(uri, schema[:components].keys)
+          when "schema://icons"
+            json_resource(uri, schema[:icons])
+          when "schema://stimulus"
+            json_resource(uri, schema[:stimulus])
+          when %r{\Aschema://components/(.+)\z}
+            key = Regexp.last_match(1).to_sym
+            json_resource(uri, component_data(schema, key) || { error: "unknown component: #{key}" })
+          end
+        end
+
+        def self.register_tools(server, store)
+          schema = store[:schema]
+          data_by_component = component_data_map(schema)
+
+          text_tool(server, name: "list_components", description: "Lists all stimulus-plumbers component theme keys") do
+            JSON.generate(schema[:components].keys)
+          end
+
+          text_tool(
+            server,
+            name:         "get_component_schema",
+            description:  "Returns themed params (e.g. type/variant/size) with valid values, defaults, and " \
+                          "required Stimulus controllers. For the full helper surface (icon options, slots) " \
+                          "use get_helper_signature",
+            input_schema: { properties: { component: { type: "string" } }, required: ["component"] }
+          ) do |component:|
+            data = data_by_component[component.to_sym]
+            data ? JSON.generate(data) : not_found("unknown component: #{component}")
+          end
+
+          text_tool(
+            server,
+            name:         "get_field_types",
+            description:  "Returns valid as: values for a form builder method",
+            input_schema: {
+              properties: { builder_method: { type: "string", enum: %w[field collection_field choice] } },
+              required:   ["builder_method"]
+            }
+          ) do |builder_method:|
+            values = schema[:field_as][builder_method.to_sym]
+            values ? JSON.generate(values) : not_found("unknown builder_method: #{builder_method}")
+          end
+        end
+
+        # Resolve component_data at module scope; define_tool blocks run in another context.
+        def self.component_data_map(schema)
+          keys = (schema[:components].keys + schema[:stimulus].keys).uniq
+          keys.to_h { |key| [key, component_data(schema, key)] }
+        end
+
+        def self.component_data(schema, key)
+          params = schema[:components][key]
+          wiring = schema[:stimulus]
+          return nil unless params || wiring.key?(key)
+
+          (params || {}).merge(controllers: wiring[key] || [])
+        end
+
+        private_class_method :component_data_map, :component_data
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/stimulus.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Stimulus
+        extend Base
+
+        LOADER_KEY = :stimulus
+        LOADER     = StimulusManifest
+
+        STATIC_RESOURCES = [
+          ::MCP::Resource.new(
+            uri:         "stimulus://controllers",
+            name:        "stimulus-controllers-index",
+            description: "Index of all Stimulus controller identifiers in @stimulus-plumbers/controllers",
+            mime_type:   "application/json"
+          )
+        ].freeze
+
+        DYNAMIC_RESOURCE_TEMPLATES = [
+          ::MCP::ResourceTemplate.new(
+            uri_template: "stimulus://controllers/{identifier}",
+            name:         "stimulus-controller-schema",
+            description:  "Targets, values, outlets, and classes for a Stimulus controller",
+            mime_type:    "application/json"
+          )
+        ].freeze
+
+        def self.read(uri, store)
+          controllers = store[:stimulus]
+
+          case uri
+          when "stimulus://controllers"
+            json_resource(uri, controllers.keys)
+          when %r{\Astimulus://controllers/(.+)\z}
+            identifier = Regexp.last_match(1)
+            json_resource(uri, controllers[identifier] || { error: "unknown controller: #{identifier}" })
+          end
+        end
+
+        def self.register_tools(server, store)
+          controllers = store[:stimulus]
+
+          text_tool(
+            server,
+            name:        "list_controllers",
+            description: "Lists all Stimulus controller identifiers provided by @stimulus-plumbers/controllers"
+          ) do
+            JSON.generate(controllers.keys)
+          end
+
+          text_tool(
+            server,
+            name:         "get_controller_schema",
+            description:  "Returns targets, values (with types and defaults), outlets, and classes for a Stimulus controller",
+            input_schema: { properties: { controller: { type: "string" } }, required: ["controller"] }
+          ) do |controller:|
+            data = controllers[controller]
+            data ? JSON.generate(data) : not_found("unknown controller: #{controller}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/tailwind.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Tailwind
+        extend Base
+
+        LOADER_KEY = :tailwind
+        LOADER     = TailwindThemeLoader
+
+        STATIC_RESOURCES = [
+          ::MCP::Resource.new(
+            uri:         "tailwind://components",
+            name:        "tailwind-components-index",
+            description: "Index of component keys implemented by the stimulus-plumbers Tailwind theme",
+            mime_type:   "application/json"
+          )
+        ].freeze
+
+        DYNAMIC_RESOURCE_TEMPLATES = [
+          ::MCP::ResourceTemplate.new(
+            uri_template: "tailwind://components/{name}",
+            name:         "tailwind-component-classes",
+            description:  "Tailwind CSS utility classes emitted per variant for a component",
+            mime_type:    "application/json"
+          )
+        ].freeze
+
+        def self.read(uri, store)
+          tailwind = store[:tailwind]
+
+          case uri
+          when "tailwind://components"
+            json_resource(uri, tailwind.keys)
+          when %r{\Atailwind://components/(.+)\z}
+            key = Regexp.last_match(1).to_sym
+            json_resource(uri, tailwind[key] || { error: "unknown component: #{key}" })
+          end
+        end
+
+        def self.register_tools(server, store)
+          tailwind = store[:tailwind]
+
+          text_tool(
+            server,
+            name:         "get_tailwind_classes",
+            description:  "Returns Tailwind CSS utility classes emitted per variant for a component",
+            input_schema: { properties: { component: { type: "string" } }, required: ["component"] }
+          ) do |component:|
+            data = tailwind[component.to_sym]
+            data ? JSON.generate(data) : not_found("unknown component: #{component}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/theme.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      module Theme
+        extend Base
+
+        LOADER_KEY = :theme
+        LOADER     = ThemeLoader
+
+        STATIC_RESOURCES = [
+          ::MCP::Resource.new(
+            uri:         "theme://base",
+            name:        "theme-base",
+            description: "Guide for implementing a custom stimulus-plumbers theme: method convention, return format",
+            mime_type:   "text/markdown"
+          ),
+          ::MCP::Resource.new(
+            uri:         "theme://components",
+            name:        "theme-components-index",
+            description: "Index of all component keys that can be implemented in a custom theme",
+            mime_type:   "application/json"
+          )
+        ].freeze
+
+        DYNAMIC_RESOURCE_TEMPLATES = [
+          ::MCP::ResourceTemplate.new(
+            uri_template: "theme://components/{name}",
+            name:         "theme-component-interface",
+            description:  "Method name, param signature, and return contract for implementing a component in a custom theme",
+            mime_type:    "application/json"
+          )
+        ].freeze
+
+        def self.read(uri, store)
+          theme = store[:theme]
+
+          case uri
+          when "theme://base"
+            text_resource(uri, "text/markdown", theme[:base_doc])
+          when "theme://components"
+            json_resource(uri, theme[:components].keys)
+          when %r{\Atheme://components/(.+)\z}
+            key = Regexp.last_match(1).to_sym
+            json_resource(uri, theme[:components][key] || { error: "unknown component: #{key}" })
+          end
+        end
+
+        def self.register_tools(server, store)
+          theme = store[:theme]
+
+          text_tool(
+            server,
+            name:         "get_theme_interface",
+            description:  "Returns the method name, param signature, and return contract for a custom theme component",
+            input_schema: { properties: { component: { type: "string" } }, required: ["component"] }
+          ) do |component:|
+            data = theme[:components][component.to_sym]
+            data ? JSON.generate(data) : not_found("unknown component: #{component}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/server.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Server
+      PLUGINS = [
+        Plugins::Guide,
+        Plugins::Schema,
+        Plugins::Docs,
+        Plugins::Stimulus,
+        Plugins::Theme,
+        Plugins::Tailwind
+      ].freeze
+
+      INSTRUCTIONS = "Use these resources and tools for accurate API references when " \
+                     "generating Rails/ERB view code with the stimulus-plumbers UI library. " \
+                     "Read guide://overview first for a map of the form/view/stimulus API."
+
+      def self.build
+        store = PLUGINS.to_h { |plugin| [plugin::LOADER_KEY, plugin::LOADER.call] }
+        report_sources(store)
+
+        server = new_server
+        server.resources_read_handler do |params|
+          PLUGINS.lazy.filter_map { |plugin| plugin.read(params[:uri], store) }.first || []
+        end
+        PLUGINS.each { |plugin| plugin.register_tools(server, store) }
+        server
+      end
+
+      def self.new_server
+        ::MCP::Server.new(
+          name:               "stimulus-plumbers",
+          version:            StimulusPlumbers::MCP::VERSION,
+          instructions:       INSTRUCTIONS,
+          resources:          PLUGINS.flat_map { |p| p::STATIC_RESOURCES },
+          resource_templates: PLUGINS.flat_map { |p| p::DYNAMIC_RESOURCE_TEMPLATES }
+        )
+      end
+
+      # Loaders fail soft (sibling paths may be absent), so report what resolved
+      # and warn loudly on any empty source instead of starting silently wrong.
+      def self.report_sources(store)
+        summary = store.map { |key, value| "#{key}=#{source_size(value)}" }.join(" ")
+        StimulusPlumbers::Logger.info("sources: #{summary}")
+        store.each_key do |key|
+          StimulusPlumbers::Logger.warn("source '#{key}' is empty") if empty_source?(store[key])
+        end
+      end
+
+      def self.source_size(value)
+        case value
+        when String     then value.empty? ? 0 : "ok"
+        when Hash       then value.key?(:components) ? value[:components].size : value.size
+        when Enumerable then value.size
+        else value.nil? ? 0 : 1
+        end
+      end
+
+      def self.empty_source?(value)
+        content = value.is_a?(Hash) && value.key?(:components) ? value[:components] : value
+        content.respond_to?(:empty?) && content.empty?
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    VERSION = "0.4.4"
+  end
+end

data/lib/stimulus_plumbers_mcp.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+require "action_view/version"
+require "uri" if ActionView.version < Gem::Version.new("7.3")
+require "mcp"
+require "action_view"
+require "stimulus_plumbers"
+require "stimulus_plumbers_tailwind"
+
+require_relative "stimulus_plumbers/mcp/version"
+require_relative "stimulus_plumbers/mcp/loaders/guide_loader"
+require_relative "stimulus_plumbers/mcp/loaders/schema_loader"
+require_relative "stimulus_plumbers/mcp/loaders/docs_loader"
+require_relative "stimulus_plumbers/mcp/loaders/stimulus_manifest"
+require_relative "stimulus_plumbers/mcp/loaders/component_controller_map"
+require_relative "stimulus_plumbers/mcp/loaders/theme_loader"
+require_relative "stimulus_plumbers/mcp/loaders/tailwind_theme_loader"
+require_relative "stimulus_plumbers/mcp/plugins/base"
+require_relative "stimulus_plumbers/mcp/plugins/guide"
+require_relative "stimulus_plumbers/mcp/plugins/schema"
+require_relative "stimulus_plumbers/mcp/plugins/docs"
+require_relative "stimulus_plumbers/mcp/plugins/stimulus"
+require_relative "stimulus_plumbers/mcp/plugins/theme"
+require_relative "stimulus_plumbers/mcp/plugins/tailwind"
+require_relative "stimulus_plumbers/mcp/server"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: stimulus_plumbers_mcp
+version: !ruby/object:Gem::Version
+  version: 0.4.4
+platform: ruby
+authors:
+- Ryan Chang
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: stimulus_plumbers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: stimulus_plumbers_tailwind
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A local MCP server that exposes the stimulus-plumbers API schema and
+  documentation to LLM-powered IDEs
+email:
+- ryancyq@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/stimulus_plumbers/mcp/loaders/component_controller_map.rb
+- lib/stimulus_plumbers/mcp/loaders/docs_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/guide_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/schema_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/stimulus_manifest.rb
+- lib/stimulus_plumbers/mcp/loaders/tailwind_theme_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/theme_loader.rb
+- lib/stimulus_plumbers/mcp/plugins/base.rb
+- lib/stimulus_plumbers/mcp/plugins/docs.rb
+- lib/stimulus_plumbers/mcp/plugins/guide.rb
+- lib/stimulus_plumbers/mcp/plugins/schema.rb
+- lib/stimulus_plumbers/mcp/plugins/stimulus.rb
+- lib/stimulus_plumbers/mcp/plugins/tailwind.rb
+- lib/stimulus_plumbers/mcp/plugins/theme.rb
+- lib/stimulus_plumbers/mcp/server.rb
+- lib/stimulus_plumbers/mcp/version.rb
+- lib/stimulus_plumbers_mcp.rb
+homepage: https://github.com/ryancyq/stimulus-plumbers
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: MCP server for the stimulus-plumbers UI library
+test_files: []