stimulus_plumbers_mcp 0.4.4 → 0.4.8

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

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class ControllerSchema < Base
+        class << self
+          def loader_key = :controller_schema
+
+          def loader = ControllerSchemaLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "controller://index",
+                name:        "controllers-index",
+                description: "Index of all Stimulus controller identifiers in @stimulus-plumbers/controllers",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "controller://{name}/schema",
+                name:         "controller-schema",
+                description:  "Targets, values, outlets, and classes for a Stimulus controller",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            controllers = store[:controller_schema]
+
+            case uri
+            when "controller://index"
+              json_resource(uri, controllers.keys)
+            when %r{\Acontroller://([^/]+)/schema\z}
+              identifier = Regexp.last_match(1)
+              json_resource(uri, controllers[identifier] || { error: "unknown controller: #{identifier}" })
+            end
+          end
+
+          def register_tools(server, store)
+            controllers = store[:controller_schema]
+
+            register_list_controllers(server, controllers)
+            register_get_controller_schema(server, controllers)
+          end
+
+          private
+
+          def register_list_controllers(server, controllers)
+            text_tool(
+              server,
+              name:        "list_controllers",
+              description: "Lists all Stimulus controller identifiers provided by @stimulus-plumbers/controllers"
+            ) do
+              JSON.generate(controllers.keys)
+            end
+          end
+
+          def register_get_controller_schema(server, controllers)
+            text_tool(
+              server,
+              name:         "get_controller_schema",
+              description:  "Returns targets, values (with types and defaults), outlets, and classes for a " \
+                            "Stimulus controller. For narrative usage docs use get_controller_docs",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              data = controllers[name]
+              data ? JSON.generate(data) : not_found("unknown controller: #{name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,27 +3,81 @@
 module StimulusPlumbers
   module MCP
     module Plugins
-      module Guide
-        extend Base
+      class Guide < Base
+        GUIDE_NAMES = %w[component controller tailwind theme].freeze
 
-        LOADER_KEY = :guide
-        LOADER     = GuideLoader
+        class << self
+          def loader_key = :guide
 
-        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
+          def loader = GuideLoader
 
-        DYNAMIC_RESOURCE_TEMPLATES = [].freeze
+          def 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
+          end
 
-        def self.read(uri, store)
-          return unless uri == "guide://overview"
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "guide://{name}",
+                name:         "guide",
+                description:  "Per-package usage guide: component (Rails forms/views), controller " \
+                              "(plain-JS/non-Rails setup), tailwind (Tailwind install/theming), theme " \
+                              "(custom theme integration contract)",
+                mime_type:    "text/markdown"
+              )
+            ].freeze
+          end
 
-          text_resource(uri, "text/markdown", store[:guide])
+          def read(uri, store)
+            guide = store[:guide]
+
+            case uri
+            when "guide://overview"
+              text_resource(uri, "text/markdown", guide[:overview])
+            when %r{\Aguide://(#{GUIDE_NAMES.join("|")})\z}
+              text_resource(uri, "text/markdown", guide[Regexp.last_match(1).to_sym])
+            end
+          end
+
+          def register_tools(server, store)
+            guide = store[:guide]
+
+            register_list_guides(server)
+            register_get_guide(server, guide)
+          end
+
+          private
+
+          def register_list_guides(server)
+            text_tool(
+              server,
+              name:        "list_guides",
+              description: "Lists available per-package usage guides — see guide://overview for the full map"
+            ) do
+              JSON.generate(GUIDE_NAMES)
+            end
+          end
+
+          def register_get_guide(server, guide)
+            text_tool(
+              server,
+              name:         "get_guide",
+              description:  "Returns a per-package usage guide: component (Rails forms/views), controller " \
+                            "(plain-JS/non-Rails setup), tailwind (Tailwind install/theming), theme (custom " \
+                            "theme integration contract)",
+              input_schema: { properties: { name: { type: "string", enum: GUIDE_NAMES } }, required: ["name"] }
+            ) do |name:|
+              guide[name.to_sym] || not_found("unknown guide: #{name}")
+            end
+          end
         end
       end
     end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class Icons < Base
+        class << self
+          def loader_key = :icons
+
+          def loader = IconsLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "component://icons",
+                name:        "icons",
+                description: "All available icon names bundled with the Tailwind theme",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            return unless uri == "component://icons"
+
+            json_resource(uri, store[:icons])
+          end
+
+          def register_tools(server, store)
+            text_tool(
+              server,
+              name:        "list_icons",
+              description: "Lists all available icon names bundled with the Tailwind theme"
+            ) do
+              JSON.generate(store[:icons])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,53 +3,77 @@
 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}" })
+      class Tailwind < Base
+        class << self
+          def loader_key = :tailwind
+
+          def loader = TailwindLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "component://tailwind",
+                name:        "component-tailwind-index",
+                description: "Index of component keys implemented by the stimulus-plumbers Tailwind theme",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/tailwind",
+                name:         "component-tailwind-classes",
+                description:  "Tailwind CSS utility classes emitted per variant for a component",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            tailwind = store[:tailwind]
+
+            case uri
+            when "component://tailwind"
+              json_resource(uri, tailwind.keys)
+            when %r{\Acomponent://([^/]+)/tailwind\z}
+              key = Regexp.last_match(1).to_sym
+              json_resource(uri, tailwind[key] || { error: "unknown component: #{key}" })
+            end
+          end
+
+          def register_tools(server, store)
+            tailwind = store[:tailwind]
+
+            register_list_component_tailwind(server, tailwind)
+            register_get_component_tailwind(server, tailwind)
+          end
+
+          private
+
+          def register_list_component_tailwind(server, tailwind)
+            text_tool(
+              server,
+              name:        "list_component_tailwind",
+              description: "Lists component keys implemented by the stimulus-plumbers Tailwind theme"
+            ) do
+              JSON.generate(tailwind.keys)
+            end
           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}")
+          def register_get_component_tailwind(server, tailwind)
+            text_tool(
+              server,
+              name:         "get_component_tailwind",
+              description:  "Returns Tailwind CSS utility classes emitted per variant for a component. " \
+                            "For themed params/controllers use get_component_schema; for the Rails helper " \
+                            "surface use get_component_helper",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              data = tailwind[name.to_sym]
+              data ? JSON.generate(data) : not_found("unknown component: #{name}")
+            end
           end
         end
       end