stimulus_plumbers_mcp 0.4.5 → 0.4.9

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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class Versions < Base
+        class << self
+          def loader_key = :versions
+
+          def loader = VersionsLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "versions://sources",
+                name:        "source-versions",
+                description: "Resolved version (and resolution path, for stimulus) of each gem/package " \
+                             "backing this server's data — use to spot version drift between sources",
+                mime_type:   "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            return unless uri == "versions://sources"
+
+            json_resource(uri, store[:versions])
+          end
+
+          def register_tools(server, store)
+            text_tool(
+              server,
+              name:        "get_source_versions",
+              description: "Returns the resolved version (and resolution path, for stimulus) of each " \
+                           "gem/package backing this server's data — use to spot version drift between sources"
+            ) do
+              JSON.generate(store[:versions])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/server.rb

@@ -4,12 +4,19 @@ module StimulusPlumbers
   module MCP
     module Server
       PLUGINS = [
+        Plugins::ComponentDocs,
+        Plugins::ComponentSchema,
+        Plugins::ComponentTheme,
+
+        Plugins::ControllerDocs,
+        Plugins::ControllerSchema,
+
+        Plugins::Icons,
+        Plugins::Tailwind,
+
+        Plugins::Aria,
         Plugins::Guide,
-        Plugins::Schema,
-        Plugins::Docs,
-        Plugins::Stimulus,
-        Plugins::Theme,
-        Plugins::Tailwind
+        Plugins::Versions
       ].freeze
 
       INSTRUCTIONS = "Use these resources and tools for accurate API references when " \
@@ -17,24 +24,34 @@ module StimulusPlumbers
                      "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] }
+        store = build_store
         report_sources(store)
 
         server = new_server
         server.resources_read_handler do |params|
-          PLUGINS.lazy.filter_map { |plugin| plugin.read(params[:uri], store) }.first || []
+          PLUGINS.lazy.filter_map { |plugin| plugin.read(params[:uri], store) }.first ||
+            unknown_resource(params[:uri])
         end
         PLUGINS.each { |plugin| plugin.register_tools(server, store) }
         server
       end
 
+      def self.build_store
+        PLUGINS.to_h { |plugin| [plugin.loader_key, plugin.loader.call] }
+      end
+
+      def self.unknown_resource(uri)
+        message = "unknown resource: #{uri} — read guide://overview for a map of available resources"
+        [{ uri: uri, mimeType: "application/json", text: JSON.generate(error: message) }]
+      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 }
+          resources:          PLUGINS.flat_map(&:static_resources),
+          resource_templates: PLUGINS.flat_map(&:dynamic_resource_templates)
         )
       end
 

data/lib/stimulus_plumbers/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module StimulusPlumbers
   module MCP
-    VERSION = "0.4.5"
+    VERSION = "0.4.9"
   end
 end