stimulus_plumbers_mcp 0.4.5 → 0.4.8

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class TailwindLoader
+      class << self
+        def 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] = component_classes(theme, key, params)
+          end
+        end
+
+        private
+
+        def component_classes(theme, key, params)
+          classes = { 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 { |val| classes["#{param}:#{val}"] = theme.resolve(key, param => val)[:classes].to_s }
+          end
+
+          classes
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class VersionsLoader
+      class << self
+        def call
+          {
+            component_docs:    component_docs_source,
+            component_guide:   component_guide_source,
+            component_schema:  component_schema_source,
+            component_theme:   component_theme_source,
+
+            controller_docs:   controller_docs_source,
+            controller_guide:  controller_guide_source,
+            controller_schema: controller_schema_source,
+
+            icons:             icons_source,
+            tailwind:          tailwind_source,
+            tailwind_guide:    tailwind_guide_source
+          }
+        end
+
+        private
+
+        def gem_version(gem_name)
+          Gem::Specification.find_by_name(gem_name).version.to_s
+        rescue Gem::MissingSpecError
+          nil
+        end
+
+        def component_docs_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_guide_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_schema_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_theme_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def controller_docs_source
+          dir = ControllerDocsLoader.docs_dir
+          return { version: nil, resolved_from: nil } unless dir && Dir.exist?(dir)
+
+          { version: npm_package_version(File.join(dir, "..", "..")), resolved_from: npm_docs_resolved_from(dir) }
+        end
+
+        def controller_guide_source
+          path = GuideLoader.controller_guide_path
+          return { version: nil, resolved_from: nil } unless path && File.exist?(path)
+
+          { version:       npm_package_version(File.join(File.dirname(path), "..")),
+            resolved_from: npm_docs_resolved_from(path)
+}
+        end
+
+        def controller_schema_source
+          path = ControllerSchemaLoader.resolved_path
+          return { version: nil, resolved_from: nil } unless path
+
+          { version:       npm_package_version(File.join(File.dirname(path), "..")),
+            resolved_from: controller_schema_resolved_from(path)
+}
+        end
+
+        def controller_schema_resolved_from(path)
+          case path
+          when %r{node_modules} then "node_modules"
+          when %r{vendor}       then "stimulus_plumbers gem vendor"
+          else "monorepo sibling dist/"
+          end
+        end
+
+        # Shared by controller_docs_source and controller_guide_source — both read from the same
+        # npm package's docs/ tree, dev sibling checkout vs vendored into the rails gem.
+        def npm_docs_resolved_from(path)
+          path.include?("vendor") ? "stimulus_plumbers gem vendor" : "monorepo sibling stimulus-plumbers/docs"
+        end
+
+        # package_root is the npm package's own directory — no package.json there means a vendored
+        # copy that didn't carry one along, so fall back to the wrapping gem's version.
+        def npm_package_version(package_root)
+          package_json = File.join(package_root, "package.json")
+          return gem_version("stimulus_plumbers") unless File.exist?(package_json)
+
+          JSON.parse(File.read(package_json))["version"]
+        end
+
+        def icons_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+
+        def tailwind_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+
+        def tailwind_guide_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class Aria < Base
+        class << self
+          def loader_key = :aria
+
+          def loader = AriaLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "aria://reference",
+                name:        "aria-reference",
+                description: "WCAG 2.1 AA criteria, JS keyboard navigation patterns, and per-component ARIA " \
+                             "patterns for this library. For generic ARIA role/WCAG technique reference not " \
+                             "specific to this library, use the MDN MCP server (https://developer.mozilla.org/en-US/mcp)",
+                mime_type:   "text/markdown"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            return unless uri == "aria://reference"
+
+            text_resource(uri, "text/markdown", store[:aria])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,43 +3,52 @@
 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).
+      # Plugin contract: required members raise NotImplementedError; optional members have defaults.
+      class Base
+        # Returned by a tool block to signal not-found (see text_tool).
         NotFound = Struct.new(:message)
 
-        def register_tools(_server, _store); end
+        class << self
+          def loader_key
+            raise NotImplementedError, "#{name} must define .loader_key"
+          end
 
-        def not_found(message)
-          NotFound.new(message)
-        end
+          def loader
+            raise NotImplementedError, "#{name} must define .loader"
+          end
 
-        # resources/read content for a JSON payload.
-        def json_resource(uri, data)
-          [{ uri: uri, mimeType: "application/json", text: JSON.generate(data) }]
-        end
+          def read(_uri, _store)
+            raise NotImplementedError, "#{name} must define .read"
+          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
+          def static_resources = []
+
+          def dynamic_resource_templates = []
+
+          def register_tools(_server, _store); end
+
+          def not_found(message)
+            NotFound.new(message)
+          end
+
+          def json_resource(uri, data)
+            [{ uri: uri, mimeType: "application/json", text: JSON.generate(data) }]
+          end
+
+          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 }])
+          # 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

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class ComponentDocs < Base
+        class << self
+          def loader_key = :component_docs
+
+          def loader = ComponentDocsLoader
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/docs",
+                name:         "component-docs",
+                description:  "Full markdown documentation and ERB examples for a component",
+                mime_type:    "text/markdown"
+              ),
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/helper",
+                name:         "component-helper",
+                description:  "Full sp_ helper option surface: keyword options with defaults and slot methods",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            docs = store[:component_docs]
+
+            case uri
+            when %r{\Acomponent://([^/]+)/docs\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{\Acomponent://([^/]+)/helper\z}
+              doc = docs[Regexp.last_match(1).to_sym]
+              doc ? json_resource(uri, doc[:signature]) : missing(uri, Regexp.last_match(1))
+            end
+          end
+
+          def register_tools(server, store)
+            docs = store[:component_docs]
+
+            register_list_component_docs(server, docs)
+            register_get_component_examples(server, docs)
+            register_get_component_helper(server, docs)
+          end
+
+          private
+
+          def missing(uri, name)
+            json_resource(uri, { error: "no documentation for: #{name}" })
+          end
+
+          def register_list_component_docs(server, docs)
+            text_tool(
+              server,
+              name:        "list_component_docs",
+              description: "Lists components that have markdown docs (component://{name}/docs) and " \
+                           "helper signatures (component://{name}/helper)"
+            ) do
+              JSON.generate(docs.keys)
+            end
+          end
+
+          def register_get_component_examples(server, docs)
+            text_tool(
+              server,
+              name:         "get_component_examples",
+              description:  "Returns ERB usage examples for a component from the documentation",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              examples = docs[name.to_sym]&.dig(:examples) || []
+              examples.empty? ? not_found("no examples for: #{name}") : examples.join("\n\n")
+            end
+          end
+
+          def register_get_component_helper(server, docs)
+            text_tool(
+              server,
+              name:         "get_component_helper",
+              description:  "Returns the full sp_ helper surface for a component: keyword options with " \
+                            "defaults plus slot methods (e.g. icon_leading, card.with_action). For themed " \
+                            "params/controllers use get_component_schema",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              doc = docs[name.to_sym]
+              doc ? JSON.generate(doc[:signature]) : not_found("no documentation for: #{name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class ComponentSchema < Base
+        class << self
+          def loader_key = :component_schema
+
+          def loader = ComponentSchemaLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "component://index",
+                name:        "components-index",
+                description: "Index of all stimulus-plumbers component theme keys",
+                mime_type:   "application/json"
+              ),
+              ::MCP::Resource.new(
+                uri:         "component://integration",
+                name:        "component-integration",
+                description: "Mapping from Rails component name to the Stimulus controller identifiers it requires",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/schema",
+                name:         "component-schema",
+                description:  "Params, valid values, defaults, and required controllers for a component",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            schema = store[:component_schema]
+
+            case uri
+            when "component://index"
+              json_resource(uri, schema[:components].keys)
+            when "component://integration"
+              json_resource(uri, schema[:controllers])
+            when %r{\Acomponent://([^/]+)/schema\z}
+              key = Regexp.last_match(1).to_sym
+              json_resource(uri, component_data(schema, key) || { error: "unknown component: #{key}" })
+            end
+          end
+
+          def register_tools(server, store)
+            schema = store[:component_schema]
+            data_by_component = component_data_map(schema)
+
+            register_list_components(server, schema)
+            register_get_component_schema(server, data_by_component)
+            register_get_field_as_values(server, schema)
+            register_get_field_as_controller(server, schema)
+          end
+
+          private
+
+          def register_list_components(server, schema)
+            text_tool(server, name: "list_components", description: "Lists all stimulus-plumbers component theme keys") do
+              JSON.generate(schema[:components].keys)
+            end
+          end
+
+          def register_get_component_schema(server, data_by_component)
+            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_component_helper. Keys are renderer-level (e.g. combobox_listbox), not " \
+                            "f.field(as:) values — for the as: value's backing controller use get_field_as_controller",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              data = data_by_component[name.to_sym]
+              data ? JSON.generate(data) : not_found("unknown component: #{name}")
+            end
+          end
+
+          def register_get_field_as_values(server, schema)
+            text_tool(
+              server,
+              name:         "get_field_as_values",
+              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
+
+          def register_get_field_as_controller(server, schema)
+            text_tool(
+              server,
+              name:         "get_field_as_controller",
+              description:  "Returns the Stimulus controller identifier backing an f.field/f.collection_field " \
+                            "as: value (e.g. \"select\" -> \"combobox-dropdown\"), for as: values whose picker " \
+                            "is controller-backed. Plain input as: values (text, email, file, ...) return not-found",
+              input_schema: { properties: { as: { type: "string" } }, required: ["as"] }
+            ) do |as:|
+              controller = schema[:field_as_controllers][as.to_sym]
+              controller ? JSON.generate(controller: controller) : not_found("no dedicated controller for as: #{as}")
+            end
+          end
+
+          # Resolve component_data at module scope; define_tool blocks run in another context.
+          def component_data_map(schema)
+            keys = (schema[:components].keys + schema[:controllers].keys).uniq
+            keys.to_h { |key| [key, component_data(schema, key)] }
+          end
+
+          def component_data(schema, key)
+            params = schema[:components][key]
+            required = schema[:controllers]
+            return nil unless params || required.key?(key)
+
+            (params || {}).merge(controllers: required[key] || [])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class ComponentTheme < Base
+        class << self
+          def loader_key = :component_theme
+
+          def loader = ComponentThemeLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "component://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:         "component://theme",
+                name:        "component-theme-index",
+                description: "Index of all component keys that can be implemented in a custom theme",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/theme",
+                name:         "component-theme-interface",
+                description:  "Method name, param signature, and return contract for implementing a component in a custom theme",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            theme = store[:component_theme]
+
+            case uri
+            when "component://theme/base"
+              text_resource(uri, "text/markdown", theme[:base_doc])
+            when "component://theme"
+              json_resource(uri, theme[:components].keys)
+            when %r{\Acomponent://([^/]+)/theme\z}
+              key = Regexp.last_match(1).to_sym
+              json_resource(uri, theme[:components][key] || { error: "unknown component: #{key}" })
+            end
+          end
+
+          def register_tools(server, store)
+            theme = store[:component_theme]
+
+            register_list_component_themes(server, theme)
+            register_get_component_theme(server, theme)
+          end
+
+          private
+
+          def register_list_component_themes(server, theme)
+            text_tool(
+              server,
+              name:        "list_component_themes",
+              description: "Lists all component keys that can be implemented in a custom theme"
+            ) do
+              JSON.generate(theme[:components].keys)
+            end
+          end
+
+          def register_get_component_theme(server, theme)
+            text_tool(
+              server,
+              name:         "get_component_theme",
+              description:  "Returns the method name, param signature, and return contract for implementing " \
+                            "a component in a custom theme. For the built-in Tailwind theme's output use " \
+                            "get_component_tailwind; for themed params use get_component_schema",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              data = theme[:components][name.to_sym]
+              data ? JSON.generate(data) : not_found("unknown component: #{name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      # Shares the controller:// scheme with Plugins::ControllerSchema, distinguished by the
+      # docs/ path segment (ControllerSchema is per-identifier schema data; docs/ is
+      # narrative markdown, grouped by controller family, not individual identifier).
+      class ControllerDocs < Base
+        class << self
+          def loader_key = :controller_docs
+
+          def loader = ControllerDocsLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "controller://docs",
+                name:        "controller-docs-index",
+                description: "Index of JS controller narrative docs, grouped by controller family " \
+                             "(e.g. :calendar covers calendar-month/-year/-decade)",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "controller://docs/{name}",
+                name:         "controller-doc",
+                description:  "Narrative usage doc for a controller family, for plain-JS/Hotwire consumers " \
+                              "without Rails helpers",
+                mime_type:    "text/markdown"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            docs = store[:controller_docs]
+
+            case uri
+            when "controller://docs"
+              json_resource(uri, docs.keys)
+            when %r{\Acontroller://docs/(.+)\z}
+              key = Regexp.last_match(1).to_sym
+              docs[key] ? text_resource(uri, "text/markdown", docs[key]) : missing(uri, key)
+            end
+          end
+
+          def register_tools(server, store)
+            docs = store[:controller_docs]
+
+            register_list_controller_docs(server, docs)
+            register_get_controller_docs(server, docs)
+          end
+
+          private
+
+          def missing(uri, key)
+            json_resource(uri, { error: "no controller docs for: #{key}" })
+          end
+
+          def register_list_controller_docs(server, docs)
+            text_tool(
+              server,
+              name:        "list_controller_docs",
+              description: "Lists controller doc families available at controller://docs/{name} — " \
+                           "grouped by family, not individual controller identifier"
+            ) do
+              JSON.generate(docs.keys)
+            end
+          end
+
+          def register_get_controller_docs(server, docs)
+            text_tool(
+              server,
+              name:         "get_controller_docs",
+              description:  "Returns the narrative usage doc for a controller family (e.g. \"calendar\", " \
+                            "\"combobox\") — for individual controller targets/values/outlets use get_controller_schema",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              doc = docs[name.to_sym]
+              doc || not_found("no controller docs for: #{name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end