stimulus_plumbers_mcp 0.4.5 → 0.4.8

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

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

data/lib/stimulus_plumbers/mcp/loaders/guide/overview.md

@@ -1,48 +0,0 @@
-# stimulus-plumbers — overview
-
-Accessible Rails view components plus a themed form builder, backed by Stimulus controllers.
-Start here, then drill into the per-component resources/tools below.
-
-## Tailwind theme setup
-The `stimulus_plumbers_tailwind` gem provides themed CSS classes for all components. After adding it to
-your Gemfile, run the install generator once:
-  bin/rails generate stimulus_plumbers_tailwind:install
-This injects an `@source` directive into your Tailwind CSS entry file so component classes are included
-in the compiled output. The generator checks `app/assets/stylesheets/application.tailwind.css`,
-`app/assets/stylesheets/application.css`, and `app/javascript/entrypoints/application.css` in that
-order. Override with `TAILWIND_CSS_FILE=/path/to/entry.css`. The path updates automatically on
-`assets:precompile` and `tailwindcss:build` — no re-run needed after `bundle update`.
-
-## Building forms
-Use `StimulusPlumbers::Form::Builder` (set `config.action_view.default_form_builder`, or pass
-`builder:` to `form_with`). Two levels:
-- **Level 2 — recommended.** Full accessible field (label + input + hint + error):
-  `f.field(attr, as:)`, `f.collection_field(attr, as:, collection:, ...)`, `f.choice(attr, as:)`.
-  Valid `as:` values come from `get_field_types` (pass `builder_method: "field"`, `"collection_field"`, or `"choice"`).
-- **Level 1.** Native helper overrides (`f.text_field`, `f.select`, `f.check_box`, ...) render
-  only the themed input element — use when you control the surrounding markup.
-Submit with `f.submit` (themed button). Full form reference + examples: read `docs://components/form`.
-
-## Building views
-Render components with `sp_*` helpers (`sp_button`, `sp_button_group`, `sp_card`, `sp_list`,
-`sp_link`, `sp_avatar`, `sp_divider`, `sp_icon`, `sp_popover`). For any component:
-- `get_helper_signature(name)` — full helper surface: keyword options (incl. `icon_leading`) + slot methods
-- `get_component_schema(name)` — themed params (type/variant/size) with valid values + defaults
-- `get_erb_examples(name)` — runnable ERB snippets
-List everything with `list_components`; `list_docs` shows which components have full docs
-(`docs://components/{name}`) and helper signatures (`helper://components/{name}`).
-Icon options take a name from `schema://icons`.
-All 77 schema components are queryable via `get_component_schema`; only a subset have full docs and ERB examples — use `list_docs` to see what's covered.
-
-## Stimulus wiring
-Most display components are pure markup; interactive ones (combobox, popover, calendar) emit their
-`data-controller` wiring automatically. Component → required controllers: `schema://stimulus`.
-Controller details (targets/values/outlets/classes): `get_controller_schema(id)` / `list_controllers`.
-
-## How this server is organized
-- **Resources** (`schema://`, `docs://`, `helper://`, `theme://`, `tailwind://`, `guide://`) are for
-  browsing/pulling context; **tools** (`get_*`, `list_*`) are for targeted lookups. They expose the
-  same data two ways — use whichever your client prefers.
-- **View generation** uses the form builder + `sp_` helper tools/resources above. The `theme://` and
-  `tailwind://` surfaces are for *theme authors* implementing a custom theme — skip them when generating views.
-- **Errors are uniform:** a not-found tool/resource returns `{ "error": "..." }` (tools also set `isError`).

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,47 +0,0 @@
-# frozen_string_literal: true
-
-module StimulusPlumbers
-  module MCP
-    class StimulusManifestLoader
-      MANIFEST_FILENAME = "controllers.manifest.json"
-
-      def self.call
-        paths = manifest_paths
-        path  = paths.find { |p| File.exist?(p) }
-
-        unless path
-          StimulusPlumbers::Logger.warn(
-            "#{MANIFEST_FILENAME} not found. Tried:\n" \
-            "#{paths.map { |p| "  - #{p}" }.join("\n")}\n" \
-            "Run `node --run build:manifest` in stimulus-plumbers/ to generate it."
-          )
-          return {}
-        end
-
-        JSON.parse(File.read(path))
-      end
-
-      def self.manifest_paths
-        [
-          # 1. npm/yarn/bun project — version matches project lockfile
-          File.join(Dir.pwd, "node_modules/@stimulus-plumbers/controllers/dist", MANIFEST_FILENAME),
-          # 2. importmaps users — vendored in Rails gem at release time
-          gem_vendor_path,
-          # 3. Monorepo dev fallback
-          File.expand_path(
-            File.join(__dir__, "../../../../..", "stimulus-plumbers", "dist", MANIFEST_FILENAME)
-          )
-        ].compact
-      end
-
-      def self.gem_vendor_path
-        gem_dir = Gem::Specification.find_by_name("stimulus_plumbers").gem_dir
-        File.join(gem_dir, "vendor", MANIFEST_FILENAME)
-      rescue Gem::MissingSpecError
-        nil
-      end
-
-      private_class_method :manifest_paths, :gem_vendor_path
-    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

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

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

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

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

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

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