stimulus_plumbers_mcp 0.4.4 → 0.4.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ce340e2b2d68fcfef0406efd76e88e91c5214c653bc44cbed78d6ebf23bd4e
-  data.tar.gz: c4ec9ad1abdabfb7ab464b685e604d78feec3a67b10944339885adbd5f322668
+  metadata.gz: 33ad1eb09fa4ed8fa1780dffe068f475fc04f3b3e1f179d6cbda211190155dc9
+  data.tar.gz: 29fecb05f19a17c3b398d8eb9189167e87cfe2f6f13d2b511472884ed9ebc935
 SHA512:
-  metadata.gz: 752269bd37dc2716c2fdabf2aab3bb6cecb9bd6aaae82ff245c95414ef98c9a670ac1da896a32dafa00b9d47b8231214b5f150f3ca1efd7705faafe978eabccb
-  data.tar.gz: 8540984025d8870982f1d75d8a33a51dfcb3096084eb8c8d0ef0dc5cc39f62b02310f787568a0d34a8cb49ac055273b6f2fa7254b398a67703879d750dceb9f5
+  metadata.gz: cd757ac9c1c357f3b71c1683816ab497718215ac181e2773af6d02bca45f95114c725e501a3218a71aefa11a4e090d233efdaa085a0a01e7af399745f4082284
+  data.tar.gz: 8481e2f13c22dfccbfa0e089442bdec11fe9475c408e4d189567ea4b60b2557aa1f959698c5bc511d428b079f1fbcc5038b327729b4e43b7eb78da8f2261720c

data/README.md

@@ -0,0 +1,120 @@
+# stimulus-plumbers-mcp
+
+MCP server for [`stimulus_plumbers`](../stimulus-plumbers-rails). Exposes the component API schema, documentation, and Stimulus controller metadata to LLM-powered IDEs.
+
+## Requirements
+
+- Ruby >= 3.0
+- Node (contributors only — to build the Stimulus controller manifest)
+
+## Installation
+
+```bash
+gem install stimulus_plumbers_mcp
+```
+
+## Resources
+
+| URI | Content |
+|-----|---------|
+| `guide://overview` | **Start here** — map of the form/view/stimulus API with pointers to every tool/resource |
+| `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_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` | `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
+
+```json
+{
+  "mcpServers": {
+    "stimulus-plumbers": {
+      "command": "gem",
+      "args": ["exec", "stimulus-plumbers-mcp"]
+    }
+  }
+}
+```
+
+Requires Ruby >= 3.3. No `cwd` required. Pin a specific version by adding it to your `Gemfile` and running `bundle exec gem exec stimulus-plumbers-mcp`.
+
+## Stimulus Manifest
+
+`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
+3. `../stimulus-plumbers/dist/controllers.manifest.json` — monorepo dev fallback
+
+No extra steps needed for setups 1 or 2.
+
+## Development
+
+```bash
+git clone https://github.com/ryancyq/stimulus-plumbers
+cd stimulus-plumbers/stimulus-plumbers-mcp
+bundle install
+
+# Build the Stimulus controller manifest (pure Node, no toolchain install needed)
+cd ../stimulus-plumbers && node --run build:manifest && cd -
+
+# Start the server
+bundle exec ruby bin/server
+```
+
+### Manual querying
+
+`bin/mcp-query` wraps the JSON-RPC stdio protocol for quick manual inspection:
+
+```bash
+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 '{"name":"button"}'
+bundle exec ruby bin/mcp-query read guide://overview
+bundle exec ruby bin/mcp-query read component://form/docs
+```
+
+```bash
+bundle exec rake test:unit  # unit tests
+bundle exec rake rubocop    # lint
+bundle exec rake coverage   # run tests with coverage
+```
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

data/bin/bump-version

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+VERSION = ARGV[0]
+
+if VERSION.nil? || VERSION.empty?
+  warn "Usage: #{$PROGRAM_NAME} <version>"
+  exit 1
+end
+
+OUTPUT_FILE = File.expand_path("../lib/stimulus_plumbers/mcp/version.rb", __dir__)
+
+output = <<~RUBY
+  # frozen_string_literal: true
+
+  module StimulusPlumbers
+    module MCP
+      VERSION = "#{VERSION}"
+    end
+  end
+RUBY
+
+File.write(OUTPUT_FILE, output)
+system("bundle > /dev/null")
+
+puts VERSION

data/bin/mcp-query

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Query the stimulus-plumbers MCP server over stdio.
+#
+# Usage:
+#   bin/mcp-query tools                         # list available tools
+#   bin/mcp-query resources                     # list available resources
+#   bin/mcp-query tool <name> [args_json]       # call a tool (args_json defaults to {})
+#   bin/mcp-query read <uri>                    # read a resource
+
+require "bundler/setup"
+require "json"
+require "open3"
+require "rbconfig"
+
+SERVER = File.join(__dir__, "server")
+
+def usage
+  warn <<~USAGE
+    Usage:
+      bin/mcp-query tools
+      bin/mcp-query resources
+      bin/mcp-query tool <name> [args_json]
+      bin/mcp-query read <uri>
+  USAGE
+  exit 1
+end
+
+def die(message)
+  warn "error: #{message}"
+  exit 1
+end
+
+def build_requests(*requests)
+  client_info = { name: "mcp-query", version: "1.0" }
+  init_params = { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: client_info }
+  handshake = [
+    { jsonrpc: "2.0", id: 1, method: "initialize", params: init_params },
+    { jsonrpc: "2.0", method: "notifications/initialized" }
+  ]
+  "#{(handshake + requests).map { JSON.generate(_1) }.join("\n")}\n"
+end
+
+def query_server(requests)
+  stdout, _stderr, = Open3.capture3(RbConfig.ruby, SERVER, stdin_data: requests)
+  parsed = stdout.each_line.filter_map do |l|
+    JSON.parse(l.strip)
+  rescue StandardError
+    nil
+  end
+  response = parsed.find { |r| r["id"] == 2 }
+  raise "No response from server" unless response
+
+  response
+end
+
+def print_error_and_exit(response)
+  warn "error: #{JSON.pretty_generate(response["error"])}"
+  exit 1
+end
+
+subcommand = ARGV.shift || usage
+
+case subcommand
+when "tools"
+  response = query_server(build_requests({ jsonrpc: "2.0", id: 2, method: "tools/list" }))
+  print_error_and_exit(response) if response["error"]
+
+  response.dig("result", "tools").each do |tool|
+    puts "  #{tool["name"]}"
+    puts "    #{tool["description"]}"
+    puts
+  end
+
+when "resources"
+  response = query_server(build_requests({ jsonrpc: "2.0", id: 2, method: "resources/list" }))
+  print_error_and_exit(response) if response["error"]
+
+  response.dig("result", "resources").each do |res|
+    puts "  #{res["uri"]}"
+    puts "    #{res["description"] || res["name"]}"
+    puts
+  end
+
+when "tool"
+  name = ARGV.shift || die("tool requires a name")
+  args = JSON.parse(ARGV.shift || "{}")
+
+  request = { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: name, arguments: args } }
+  response = query_server(build_requests(request))
+  print_error_and_exit(response) if response["error"]
+
+  response.dig("result", "content").each { puts _1["text"] }
+
+when "read"
+  uri = ARGV.shift || die("read requires a URI")
+
+  request = { jsonrpc: "2.0", id: 2, method: "resources/read", params: { uri: uri } }
+  response = query_server(build_requests(request))
+  print_error_and_exit(response) if response["error"]
+
+  response.dig("result", "contents").each { puts _1["text"] }
+
+else
+  usage
+end

data/bin/server

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Monorepo dev entry point — loads lib via require_relative (no gem install needed).
+require "bundler/setup"
+require_relative "../lib/stimulus_plumbers_mcp"
+
+StimulusPlumbers::MCP::CLI.run

data/bin/stimulus-plumbers-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# gem exec entry point — loads via installed gem load path (no clone needed).
+require "stimulus_plumbers_mcp"
+
+StimulusPlumbers::MCP::CLI.run

data/lib/stimulus_plumbers/mcp/cli.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module CLI
+      def self.run
+        server = Server.build
+        warn "[stimulus-plumbers-mcp] server started (version #{VERSION})"
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+    end
+  end
+end

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`).