stimulus_plumbers_mcp 0.4.5 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c888ecb5ce465abc47875df8b2924ed833930400af77b9ebc546207173adf4d3
-  data.tar.gz: 9f2278aa3c144f18e82a3070894bbfd4aeb1a30870b0ca1611c137252aedcaac
+  metadata.gz: 33ad1eb09fa4ed8fa1780dffe068f475fc04f3b3e1f179d6cbda211190155dc9
+  data.tar.gz: 29fecb05f19a17c3b398d8eb9189167e87cfe2f6f13d2b511472884ed9ebc935
 SHA512:
-  metadata.gz: e62c6f7a43d006f158e2bf309f7a044ddff0bc74534667d2c736ac9f7c8dd5f977f0daf1b00ba063b4a5d6dc7c0d7043949cc89ca40e0a203847ba0e25cb87ad
-  data.tar.gz: 8d7dafd931f3db501d06b48436ab5d028d5e4fb57d49b1a8ed4cc20c5ffad7ccdb6bebf45cc166438cafb55cf637ced44bb48e78339998189f2ebd7629c13878
+  metadata.gz: cd757ac9c1c357f3b71c1683816ab497718215ac181e2773af6d02bca45f95114c725e501a3218a71aefa11a4e090d233efdaa085a0a01e7af399745f4082284
+  data.tar.gz: 8481e2f13c22dfccbfa0e089442bdec11fe9475c408e4d189567ea4b60b2557aa1f959698c5bc511d428b079f1fbcc5038b327729b4e43b7eb78da8f2261720c

data/README.md

@@ -18,34 +18,44 @@ gem install stimulus_plumbers_mcp
 | URI | Content |
 |-----|---------|
 | `guide://overview` | **Start here** — map of the form/view/stimulus API with pointers to every tool/resource |
-| `schema://components` | Index of all component theme keys |
-| `schema://components/{name}` | Params, valid values, defaults + required controllers |
-| `schema://icons` | All available icon names |
-| `schema://stimulus` | Map from component key → required Stimulus controller identifiers |
-| `docs://components/{name}` | Full markdown doc with ERB examples |
-| `helper://components/{name}` | Full `sp_` helper surface: keyword options + defaults (grouped by helper signature) + slot methods (with block-required flag) |
-| `stimulus://controllers` | Index of Stimulus controller identifiers |
-| `stimulus://controllers/{identifier}` | Targets, values, outlets, classes for a controller |
-| `theme://base` | Custom theme authoring guide |
-| `theme://components` | Index of theme-implementable component keys |
-| `theme://components/{name}` | Method name, param signature, return contract |
-| `tailwind://components` | Index of Tailwind theme component keys |
-| `tailwind://components/{name}` | Tailwind CSS classes per variant |
+| `guide://{name}` | Per-package usage guide: `component` (Rails forms/views), `controller` (plain-JS/non-Rails setup), `tailwind` (Tailwind install/theming), `theme` (custom theme integration contract) |
+| `aria://reference` | WCAG 2.1 AA criteria, keyboard navigation patterns, and per-component ARIA patterns |
+| `component://index` | Index of all component theme keys |
+| `component://icons` | All available icon names |
+| `component://integration` | Map from component key → required Stimulus controller identifiers |
+| `component://{name}/schema` | Params, valid values, defaults + required controllers |
+| `component://{name}/docs` | Full markdown doc with ERB examples |
+| `component://{name}/helper` | Full `sp_` helper surface: keyword options + defaults (grouped by helper signature) + slot methods |
+| `component://theme` | Index of theme-implementable component keys |
+| `component://{name}/theme` | Method name, param signature, return contract |
+| `component://theme/base` | Custom theme authoring guide |
+| `component://tailwind` | Index of Tailwind theme component keys |
+| `component://{name}/tailwind` | Tailwind CSS classes per variant |
+| `controller://index` | Index of Stimulus controller identifiers |
+| `controller://{name}/schema` | Targets, values, outlets, classes for a controller |
+| `controller://docs` | Index of JS controller narrative docs, grouped by controller family |
+| `controller://docs/{name}` | Narrative usage doc for a controller family (plain-JS/Hotwire, no Rails helpers) |
+| `versions://sources` | Resolved version (and resolution path) of each source gem/package |
 
 ## Tools
 
 | Tool | Input | Output |
 |------|-------|--------|
 | `list_components` | — | All component theme keys |
-| `list_docs` | — | Components with markdown docs + helper signatures (the `docs://`/`helper://` `{name}` set) |
-| `get_component_schema` | `component` | Themed params (type/variant/size) + defaults + required controllers |
-| `get_helper_signature` | `component` | Full `sp_` helper surface — keyword options grouped by helper signature (incl. `icon_leading`) + slot methods |
-| `get_erb_examples` | `component` | ERB code fences from docs |
-| `get_field_types` | `builder_method` (`field`/`collection_field`/`choice`) | Valid `as:` values |
+| `list_component_docs` | — | Components with markdown docs + helper signatures (the `component://{name}/docs`+`/helper` set) |
+| `get_component_schema` | `name` | Themed params (type/variant/size) + defaults + required controllers |
+| `get_component_helper` | `name` | Full `sp_` helper surface — keyword options grouped by helper signature (incl. `icon_leading`) + slot methods |
+| `get_component_examples` | `name` | ERB code fences from docs |
+| `get_field_as_values` | `builder_method` (`field`/`collection_field`/`choice`) | Valid `as:` values |
+| `get_component_theme` | `name` | Method signature + return contract for custom theme |
+| `get_component_tailwind` | `name` | Tailwind CSS utility classes per variant |
 | `list_controllers` | — | All Stimulus controller identifiers |
-| `get_controller_schema` | `controller` | Targets, values, outlets, classes |
-| `get_theme_interface` | `component` | Method signature + return contract for custom theme |
-| `get_tailwind_classes` | `component` | Tailwind CSS utility classes per variant |
+| `get_controller_schema` | `name` | Targets, values, outlets, classes |
+| `list_controller_docs` | — | Controller doc families available at `controller://docs/{name}` |
+| `get_controller_docs` | `name` | Narrative usage doc for a controller family |
+| `get_source_versions` | — | Resolved version (and resolution path) of each source |
+| `list_guides` | — | Available per-package guide names (`component`/`controller`/`tailwind`/`theme`) |
+| `get_guide` | `name` | Per-package usage guide content |
 
 ## IDE Setup
 
@@ -64,7 +74,7 @@ Requires Ruby >= 3.3. No `cwd` required. Pin a specific version by adding it to
 
 ## Stimulus Manifest
 
-`stimulus://` resources require the controller manifest. The server resolves it in order:
+`controller://` resources require the controller manifest. The server resolves it in order:
 
 1. `node_modules/@stimulus-plumbers/controllers/dist/controllers.manifest.json` — npm/yarn/bun projects
 2. `vendor/controllers.manifest.json` inside the installed `stimulus_plumbers` gem — importmaps fallback
@@ -94,9 +104,9 @@ bundle exec ruby bin/server
 bundle exec ruby bin/mcp-query tools                                  # list tools
 bundle exec ruby bin/mcp-query resources                              # list resources
 bundle exec ruby bin/mcp-query tool list_components                   # call a tool (no args)
-bundle exec ruby bin/mcp-query tool get_component_schema '{"component":"button"}'
+bundle exec ruby bin/mcp-query tool get_component_schema '{"name":"button"}'
 bundle exec ruby bin/mcp-query read guide://overview
-bundle exec ruby bin/mcp-query read docs://components/form
+bundle exec ruby bin/mcp-query read component://form/docs
 ```
 
 ```bash

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class AriaLoader
+      FILENAME = "ARIA.md"
+
+      class << self
+        def call
+          path = resolved_path
+          path ? File.read(path) : ""
+        end
+
+        private
+
+        def resolved_path
+          aria_paths.find { |p| File.exist?(p) }
+        end
+
+        def aria_paths
+          [
+            # 1. Monorepo dev checkout — the root file is the freshest copy while working locally.
+            File.expand_path(File.join(__dir__, "../../../../..", FILENAME)),
+            # 2. gem exec — vendored into the rails gem at release time (bin/release).
+            GemVendorPath.resolve(FILENAME)
+          ].compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentDocsLoader
+      class << self
+        def docs_dir
+          @docs_dir ||= resolve_docs_dir
+        end
+
+        def 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: DocsTableParser.call(content)
+            }
+          end
+        end
+
+        private
+
+        def 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
+
+        def extract_erb_examples(content)
+          content.scan(%r{```erb\n(.*?)```}m).map(&:first).map(&:strip)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentRequirements
+      class << self
+        def call
+          Components.constants
+                    .map { |c| Components.const_get(c) }
+                    .grep(Class)
+                    .to_h { |klass| [component_key(klass), controllers_for(klass).uniq] }
+        end
+
+        private
+
+        # 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 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 nested?(mod, value)
+          value.is_a?(Module) && !value.name.nil? && value.name.start_with?("#{mod.name}::")
+        end
+
+        def component_key(klass)
+          klass.name.demodulize.underscore.to_sym
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentSchemaLoader
+      # Not derivable from Form::Fields::Renderer's method names (`search:` renders via
+      # `render_combobox_typeahead`, but wires up "combobox-dropdown", not
+      # "combobox-typeahead") — hand-maintained; keep in sync with form.md's "backed by" notes.
+      FIELD_AS_CONTROLLERS = {
+        date:                      "combobox-date",
+        time:                      "combobox-time",
+        select:                    "combobox-dropdown",
+        search:                    "combobox-dropdown",
+        collection_select:         "combobox-dropdown",
+        grouped_collection_select: "combobox-dropdown"
+      }.freeze
+
+      class << self
+        def call
+          {
+            components:           extract_schema,
+            field_as:             extract_field_as,
+            field_as_controllers: FIELD_AS_CONTROLLERS,
+            controllers:          ComponentRequirements.call
+          }
+        end
+
+        private
+
+        def 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 extract_field_as
+          {
+            field:            Form::Fields::Renderer::FIELD.keys,
+            collection_field: Form::Fields::Renderer::COLLECTION.keys,
+            choice:           Form::Fields::Renderer::CHOICE.keys
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ComponentThemeLoader
+      class << self
+        def call
+          {
+            base_doc:   base_doc,
+            components: extract_interface
+          }
+        end
+
+        private
+
+        # Same file ComponentDocsLoader already serves at component://theme/docs — avoids a duplicate heredoc.
+        def base_doc
+          path = File.join(ComponentDocsLoader.docs_dir, "theme.md")
+          File.exist?(path) ? File.read(path) : ""
+        end
+
+        def 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 format_param(meta)
+          valid = meta[:validate]
+          entry = { default: meta[:default] }
+          entry[:valid] = valid.to_a if valid.respond_to?(:to_a)
+          entry
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ControllerDocsLoader
+      class << self
+        def docs_dir
+          @docs_dir ||= resolve_docs_dir
+        end
+
+        def call
+          Dir[File.join(docs_dir, "*.md")].to_h do |path|
+            [File.basename(path, ".md").to_sym, File.read(path)]
+          end
+        end
+
+        private
+
+        def resolve_docs_dir
+          # 1. Monorepo dev checkout — the JS package's own docs are freshest while working locally.
+          dev_path = File.expand_path(File.join(__dir__, "../../../../..", "stimulus-plumbers", "docs", "component"))
+          return dev_path if Dir.exist?(dev_path)
+
+          # 2. gem exec — vendored into the rails gem at release time, under vendor/controller/docs/
+          # (mirrors the MCP server's controller:// resource namespace).
+          GemVendorPath.resolve("controller", "docs") || dev_path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class ControllerSchemaLoader
+      MANIFEST_FILENAME = "controllers.manifest.json"
+      # Vendored as manifest.json — the "controllers" prefix is redundant once nested
+      # under vendor/controller/ (mirrors the MCP server's controller:// namespace).
+      VENDOR_FILENAME = "manifest.json"
+
+      class << self
+        def call
+          path = resolved_path
+
+          unless path
+            StimulusPlumbers::Logger.warn(
+              "controller manifest not found. Tried:\n" \
+              "#{manifest_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
+
+        # Reused by VersionsLoader to report which fallback location resolved.
+        def resolved_path
+          manifest_paths.find { |p| File.exist?(p) }
+        end
+
+        private
+
+        def 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
+            GemVendorPath.resolve("controller", VENDOR_FILENAME),
+            # 3. Monorepo dev fallback
+            File.expand_path(
+              File.join(__dir__, "../../../../..", "stimulus-plumbers", "dist", MANIFEST_FILENAME)
+            )
+          ].compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# stimulus-plumbers — overview
+
+Accessible Rails view components plus a themed form builder, backed by Stimulus controllers.
+Start here, then drill into the per-package guides and per-component resources/tools below.
+
+## Per-package guides
+- `guide://component` — building forms (`f.field`/`f.collection_field`/`f.choice`) and views
+  (`sp_*` helpers) with the Rails gem
+- `guide://controller` — plain-JS / non-Rails setup for `@stimulus-plumbers/controllers`
+- `guide://tailwind` — Tailwind theme install + icons
+- `guide://theme` — implementing a custom theme (subclassing `Themes::Base`)
+
+Tools: `list_guides`, `get_guide(name:)`.
+
+## Building forms and views
+Valid `as:` values: `get_field_as_values(builder_method:)`. Combobox-backed `as:` values' controller
+identifier: `get_field_as_controller(as:)` — `component://{name}/schema` keys are renderer-level, not
+`as:` values. Component helper surface: `get_component_helper(name)`; themed params:
+`get_component_schema(name)`; ERB examples: `get_component_examples(name)`. List everything with
+`list_components`; `list_component_docs` shows which components have full docs
+(`component://{name}/docs`) and helper signatures (`component://{name}/helper`). Icon options take a
+name from `component://icons` (or `list_icons`). All 77 schema components are queryable via
+`get_component_schema`; only a subset have full docs and ERB examples — use `list_component_docs` to
+see what's covered. Full form builder reference: `component://form/docs`.
+
+## Stimulus integration
+Most display components are pure markup; interactive ones (combobox, popover, calendar) emit their
+`data-controller` attributes automatically. Component → required controllers: `component://integration`.
+Controller identifiers and details (targets/values/outlets/classes): `controller://index`,
+`get_controller_schema(id)` / `list_controllers`.
+Narrative docs by controller family: `get_controller_docs(name)` / `controller://docs/{name}`.
+
+## How this server is organized
+- **Resources** live under entity namespaces — `component://` (Rails `sp_*` helper surface: schema,
+  docs, helper, theme, tailwind, icons facets), `controller://` (plain-JS Stimulus surface: schema,
+  docs facets), `guide://` (per-package usage guides) — plus `aria://reference` and `versions://sources`.
+  **Tools** (`get_*`, `list_*`) expose the same data for targeted lookups. Use whichever your client prefers.
+- `aria://reference` — WCAG 2.1 AA criteria and component ARIA patterns. For generic ARIA/WCAG reference,
+  connect the MDN MCP server too: `claude mcp add --transport http mdn https://mcp.mdn.mozilla.net/`
+- Each source (schema, docs, theme, tailwind, icons, stimulus, stimulus_docs, guide) is read from an
+  independently-versioned gem/npm package — `versions://sources` / `get_source_versions` reports what's
+  actually resolved, useful if data looks stale or inconsistent with the app code you're generating for.
+  `icons` versions with the Tailwind theme gem, not the schema gem, since the bundled icon set is
+  Tailwind-specific.
+- **View generation** uses the form builder + `sp_` helper tools/resources above. The `component://theme`
+  and `component://tailwind` facets 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/guide_loader.rb

@@ -3,12 +3,48 @@
 module StimulusPlumbers
   module MCP
     class GuideLoader
-      OVERVIEW_PATH = File.expand_path("guide/overview.md", __dir__).freeze
+      OVERVIEW_PATH = File.expand_path("guide.md", __dir__).freeze
 
-      def self.call
-        return "" unless File.exist?(OVERVIEW_PATH)
+      class << self
+        def call
+          {
+            overview:   read_file(OVERVIEW_PATH),
+            component:  read_file(component_guide_path),
+            controller: read_file(controller_guide_path),
+            tailwind:   read_file(tailwind_guide_path),
+            theme:      read_file(File.join(ComponentDocsLoader.docs_dir, "theme.md"))
+          }
+        end
 
-        File.read(OVERVIEW_PATH)
+        # Reused by VersionsLoader to report which fallback location resolved.
+        def controller_guide_path
+          # 1. Monorepo dev checkout — the JS package's own docs are freshest while working locally.
+          dev_path = File.expand_path(File.join(__dir__, "../../../../..", "stimulus-plumbers", "docs", "guide.md"))
+          return dev_path if File.exist?(dev_path)
+
+          # 2. gem exec — vendored into the rails gem at release time, under vendor/controller/guide.md.
+          GemVendorPath.resolve("controller", "guide.md")
+        end
+
+        private
+
+        def read_file(path)
+          path && File.exist?(path) ? File.read(path) : ""
+        end
+
+        def component_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-rails/docs/guide.md", __dir__)
+        end
+
+        def tailwind_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers_tailwind").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-tailwind/docs/guide.md", __dir__)
+        end
       end
     end
   end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class IconsLoader
+      class << self
+        def call
+          heroicon_dir = Themes::Tailwind::Icons::Heroicon.send(:svg_dir)
+          custom_dir   = Themes::Tailwind::Icons::Custom.send(:svg_dir)
+
+          (outline_names(heroicon_dir) + solid_names(heroicon_dir) + custom_names(custom_dir) + alias_names).uniq.sort
+        end
+
+        private
+
+        def outline_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "outline", "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def solid_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "solid", "*.svg")].map { |f| "#{File.basename(f, ".svg")}/solid" }
+        end
+
+        def custom_names(custom_dir)
+          Dir[File.join(custom_dir, "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def alias_names
+          Themes::Tailwind::Icon::ALIASES.keys
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/support/docs_table_parser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class DocsTableParser
+      class << self
+        def call(content)
+          tables = tables_with_headings(content)
+          { helpers: option_helpers(tables), slots: slot_methods(tables) }
+        end
+
+        # A standalone bold label (e.g. `**Time**`) between `#` headings is treated as a
+        # sub-heading, since some docs use one to introduce a table scoped to part of a
+        # section. It only labels the single table immediately following it — a fenced
+        # code block or a second table both clear it, so it can't leak onto later tables.
+        def tables_with_headings(content)
+          state = { heading: nil, subheading: nil, fenced: false, buffer: [], tables: [] }
+          content.each_line { |line| scan_line(line, state) }
+          flush_table(state)
+          state[:tables]
+        end
+
+        private
+
+        def 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 slot_methods(tables)
+          tables.select { |t| t[:header].first == "Slot method" }
+                .flat_map { |t| t[:rows].map { |r| slot_row(r) } }
+        end
+
+        def option_row(cells)
+          { option: clean(cells[0]), default: clean(cells[1]), description: cells[2].to_s }
+        end
+
+        def slot_row(cells)
+          slot = clean(cells[0])
+          description = cells[1].to_s
+          { slot: slot, description: description, block: block_required?(slot, description) }
+        end
+
+        def block_required?(slot, description)
+          slot.include?("{") || description.match?(%r{block required}i)
+        end
+
+        def scan_line(line, state)
+          if line.start_with?("```")
+            toggle_fence(state)
+          elsif state[:fenced]
+            nil
+          elsif (heading = line[%r{\A#+\s+(.+)}, 1])
+            set_heading(state, heading)
+          elsif (subheading = line[%r{\A\*\*([^*]+)\*\*}, 1])
+            set_subheading(state, subheading)
+          elsif line.lstrip.start_with?("|")
+            state[:buffer] << line
+          else
+            flush_table(state)
+          end
+        end
+
+        def toggle_fence(state)
+          flush_table(state)
+          state[:subheading] = nil
+          state[:fenced] = !state[:fenced]
+        end
+
+        def set_heading(state, heading)
+          flush_table(state)
+          state[:heading] = clean(heading)
+          state[:subheading] = nil
+        end
+
+        def set_subheading(state, subheading)
+          flush_table(state)
+          state[:subheading] = clean(subheading)
+        end
+
+        def flush_table(state)
+          return if state[:buffer].empty?
+
+          heading = [state[:heading], state[:subheading]].compact.join(" — ")
+          state[:tables] << build_table(state[:buffer]).merge(heading: heading)
+          state[:buffer] = []
+          state[:subheading] = nil
+        end
+
+        def 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 split_row(line)
+          line.strip.delete_prefix("|").delete_suffix("|")
+              .split(%r{(?<!\\)\|})
+              .map { |c| c.gsub('\|', "|").strip }
+        end
+
+        def clean(cell)
+          cell.to_s.gsub(%r{[`*]}, "").sub(%r{:\z}, "").strip
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/support/gem_vendor_path.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    # Path under the stimulus_plumbers gem's vendor/ dir (populated by bin/release),
+    # used by loaders as their `gem exec` fallback when there's no monorepo checkout.
+    module GemVendorPath
+      GEM_NAME = "stimulus_plumbers"
+
+      def self.resolve(*relative)
+        gem_dir = Gem::Specification.find_by_name(GEM_NAME).gem_dir
+        File.join(gem_dir, "vendor", *relative)
+      rescue Gem::MissingSpecError
+        nil
+      end
+    end
+  end
+end