stimulus_plumbers_mcp 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ce340e2b2d68fcfef0406efd76e88e91c5214c653bc44cbed78d6ebf23bd4e
-  data.tar.gz: c4ec9ad1abdabfb7ab464b685e604d78feec3a67b10944339885adbd5f322668
+  metadata.gz: c888ecb5ce465abc47875df8b2924ed833930400af77b9ebc546207173adf4d3
+  data.tar.gz: 9f2278aa3c144f18e82a3070894bbfd4aeb1a30870b0ca1611c137252aedcaac
 SHA512:
-  metadata.gz: 752269bd37dc2716c2fdabf2aab3bb6cecb9bd6aaae82ff245c95414ef98c9a670ac1da896a32dafa00b9d47b8231214b5f150f3ca1efd7705faafe978eabccb
-  data.tar.gz: 8540984025d8870982f1d75d8a33a51dfcb3096084eb8c8d0ef0dc5cc39f62b02310f787568a0d34a8cb49ac055273b6f2fa7254b398a67703879d750dceb9f5
+  metadata.gz: e62c6f7a43d006f158e2bf309f7a044ddff0bc74534667d2c736ac9f7c8dd5f977f0daf1b00ba063b4a5d6dc7c0d7043949cc89ca40e0a203847ba0e25cb87ad
+  data.tar.gz: 8d7dafd931f3db501d06b48436ab5d028d5e4fb57d49b1a8ed4cc20c5ffad7ccdb6bebf45cc166438cafb55cf637ced44bb48e78339998189f2ebd7629c13878

data/README.md

@@ -0,0 +1,110 @@
+# 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 |
+| `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 |
+
+## 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_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 |
+
+## 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
+
+`stimulus://` 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 '{"component":"button"}'
+bundle exec ruby bin/mcp-query read guide://overview
+bundle exec ruby bin/mcp-query read docs://components/form
+```
+
+```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/docs_loader.rb

@@ -3,13 +3,20 @@
 module StimulusPlumbers
   module MCP
     class DocsLoader
-      DOCS_DIR = File.expand_path(
-        "../../../../../stimulus-plumbers-rails/docs/component",
-        __dir__
-      )
+      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|
+        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] = {

data/lib/stimulus_plumbers/mcp/loaders/guide/overview.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-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/stimulus_manifest.rb

@@ -2,22 +2,46 @@
 
 module StimulusPlumbers
   module MCP
-    class StimulusManifest
-      MANIFEST_PATH = File.expand_path(
-        File.join(__dir__, "../../../../..", "stimulus-plumbers", "dist", "controllers.manifest.json")
-      ).freeze
+    class StimulusManifestLoader
+      MANIFEST_FILENAME = "controllers.manifest.json"
 
       def self.call
-        unless File.exist?(MANIFEST_PATH)
+        paths = manifest_paths
+        path  = paths.find { |p| File.exist?(p) }
+
+        unless path
           StimulusPlumbers::Logger.warn(
-            "controllers.manifest.json not found at #{MANIFEST_PATH}. " \
+            "#{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(MANIFEST_PATH))
+        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/plugins/stimulus.rb

@@ -7,7 +7,7 @@ module StimulusPlumbers
         extend Base
 
         LOADER_KEY = :stimulus
-        LOADER     = StimulusManifest
+        LOADER     = StimulusManifestLoader
 
         STATIC_RESOURCES = [
           ::MCP::Resource.new(

data/lib/stimulus_plumbers/mcp/version.rb

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

data/lib/stimulus_plumbers_mcp.rb

@@ -24,3 +24,4 @@ require_relative "stimulus_plumbers/mcp/plugins/stimulus"
 require_relative "stimulus_plumbers/mcp/plugins/theme"
 require_relative "stimulus_plumbers/mcp/plugins/tailwind"
 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.5
 platform: ruby
 authors:
 - Ryan Chang
@@ -69,12 +69,20 @@ 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:
+- 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/component_controller_map.rb
 - lib/stimulus_plumbers/mcp/loaders/docs_loader.rb
+- lib/stimulus_plumbers/mcp/loaders/guide/overview.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
@@ -93,7 +101,12 @@ files:
 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