stimulus_plumbers_mcp 0.4.4 → 0.4.8

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.4"
+    VERSION = "0.4.8"
   end
 end

data/lib/stimulus_plumbers_mcp.rb

@@ -9,18 +9,39 @@ require "stimulus_plumbers"
 require "stimulus_plumbers_tailwind"
 
 require_relative "stimulus_plumbers/mcp/version"
+require_relative "stimulus_plumbers/mcp/loaders/support/docs_table_parser"
+require_relative "stimulus_plumbers/mcp/loaders/support/gem_vendor_path"
+
+require_relative "stimulus_plumbers/mcp/loaders/component_docs_loader"
+require_relative "stimulus_plumbers/mcp/loaders/component_requirements"
+require_relative "stimulus_plumbers/mcp/loaders/component_schema_loader"
+require_relative "stimulus_plumbers/mcp/loaders/component_theme_loader"
+
+require_relative "stimulus_plumbers/mcp/loaders/controller_docs_loader"
+require_relative "stimulus_plumbers/mcp/loaders/controller_schema_loader"
+
+require_relative "stimulus_plumbers/mcp/loaders/icons_loader"
+require_relative "stimulus_plumbers/mcp/loaders/tailwind_loader"
+
+require_relative "stimulus_plumbers/mcp/loaders/aria_loader"
 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/loaders/versions_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/component_docs"
+require_relative "stimulus_plumbers/mcp/plugins/component_schema"
+require_relative "stimulus_plumbers/mcp/plugins/component_theme"
+
+require_relative "stimulus_plumbers/mcp/plugins/controller_docs"
+require_relative "stimulus_plumbers/mcp/plugins/controller_schema"
+
+require_relative "stimulus_plumbers/mcp/plugins/icons"
 require_relative "stimulus_plumbers/mcp/plugins/tailwind"
+
+require_relative "stimulus_plumbers/mcp/plugins/aria"
+require_relative "stimulus_plumbers/mcp/plugins/guide"
+require_relative "stimulus_plumbers/mcp/plugins/versions"
+
 require_relative "stimulus_plumbers/mcp/server"
+require_relative "stimulus_plumbers/mcp/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stimulus_plumbers_mcp
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.8
 platform: ruby
 authors:
 - Ryan Chang
@@ -69,31 +69,54 @@ description: A local MCP server that exposes the stimulus-plumbers API schema an
   documentation to LLM-powered IDEs
 email:
 - ryancyq@gmail.com
-executables: []
+executables:
+- stimulus-plumbers-mcp
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/stimulus_plumbers/mcp/loaders/component_controller_map.rb
-- lib/stimulus_plumbers/mcp/loaders/docs_loader.rb
+- README.md
+- bin/bump-version
+- bin/mcp-query
+- bin/server
+- bin/stimulus-plumbers-mcp
+- lib/stimulus_plumbers/mcp/cli.rb
+- lib/stimulus_plumbers/mcp/loaders/aria_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/component_docs_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/component_requirements.rb
+- lib/stimulus_plumbers/mcp/loaders/component_schema_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/component_theme_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/controller_docs_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/controller_schema_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/guide.md
 - 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/loaders/icons_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/support/docs_table_parser.rb
+- lib/stimulus_plumbers/mcp/loaders/support/gem_vendor_path.rb
+- lib/stimulus_plumbers/mcp/loaders/tailwind_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/versions_loader.rb
+- lib/stimulus_plumbers/mcp/plugins/aria.rb
 - lib/stimulus_plumbers/mcp/plugins/base.rb
-- lib/stimulus_plumbers/mcp/plugins/docs.rb
+- lib/stimulus_plumbers/mcp/plugins/component_docs.rb
+- lib/stimulus_plumbers/mcp/plugins/component_schema.rb
+- lib/stimulus_plumbers/mcp/plugins/component_theme.rb
+- lib/stimulus_plumbers/mcp/plugins/controller_docs.rb
+- lib/stimulus_plumbers/mcp/plugins/controller_schema.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/icons.rb
 - lib/stimulus_plumbers/mcp/plugins/tailwind.rb
-- lib/stimulus_plumbers/mcp/plugins/theme.rb
+- lib/stimulus_plumbers/mcp/plugins/versions.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: {}
+metadata:
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/ryancyq/stimulus-plumbers/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/ryancyq/stimulus-plumbers
+  source_code_uri: https://github.com/ryancyq/stimulus-plumbers/tree/main/stimulus-plumbers-mcp
 rdoc_options: []
 require_paths:
 - lib

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

@@ -1,38 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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/schema_loader.rb

@@ -1,45 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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