mcp_ui_server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e86e8b7f99554463688dffab057d1a465bd988af0a4694d96d6e83ece785e8cd
+  data.tar.gz: d00cd82a7d4babd4fe3260d45cfd25778dd74a59ebe3474237b392463b9f4232
+SHA512:
+  metadata.gz: 7517c8f95a006b3447296b0944b72a0c7f04dfc2e62d53edc2dde6f21c6274488b00eec121878f9e51ef7b78d7d7ac1fee149c189e8fff9833ae085d93c68c61
+  data.tar.gz: '047493ed74e88cf1f0ce106e498400f60cda03843f0d21c9af84d381e61732660f67859725adce12bbf1f402ac343a5169a1c27ec469bf4057b498495a7d9d3e'

data/README.md

@@ -0,0 +1,182 @@
+# MCP UI Server SDK for Ruby
+
+This is the Ruby server-side SDK for MCP UI. It provides helper methods to create UI resources that can be sent to the mcp-ui client.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mcp_ui_server', git: 'https://github.com/idosal/mcp-ui'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+The main method is `McpUiServer.create_ui_resource`. It helps you construct a valid UIResource hash.
+
+### URI Requirements
+
+All UI resources must use the `ui://` URI scheme. The SDK will validate it and raise a `McpUiServer::Error` if an invalid URI is provided.
+
+```ruby
+# Valid URI
+McpUiServer.create_ui_resource(uri: 'ui://my-app/greeting', ...)
+
+# Invalid URI - will raise McpUiServer::Error
+McpUiServer.create_ui_resource(uri: 'http://example.com', ...)
+```
+
+### Content Type Support
+
+The Ruby SDK follows Ruby conventions by using snake_case symbols for content types:
+
+- `:raw_html` - Raw HTML content
+- `:external_url` - External URL content  
+- `:remote_dom` - Remote DOM content
+
+The SDK maintains protocol consistency by internally mapping these to the camelCase format used in the MCP-UI specification.
+
+### Creating a `raw_html` resource
+
+```ruby
+require 'mcp_ui_server'
+
+resource = McpUiServer.create_ui_resource(
+  uri: 'ui://my-app/greeting',
+  content: {
+    type: :raw_html,
+    htmlString: '<h1>Hello, World!</h1>'
+  }
+)
+
+# The resulting resource hash can be serialized to JSON and sent in your API response.
+# {
+#   "type": "resource",
+#   "resource": {
+#     "uri": "ui://my-app/greeting",
+#     "mimeType": "text/html",
+#     "text": "<h1>Hello, World!</h1>"
+#   }
+# }
+```
+
+### Creating an `external_url` resource
+
+```ruby
+require 'mcp_ui_server'
+
+resource = McpUiServer.create_ui_resource(
+  uri: 'ui://my-app/external-page',
+  content: {
+    type: :external_url,
+    iframeUrl: 'https://example.com'
+  }
+)
+
+# Results in:
+# {
+#   "type": "resource",
+#   "resource": {
+#     "uri": "ui://my-app/external-page",
+#     "mimeType": "text/uri-list",
+#     "text": "https://example.com"
+#   }
+# }
+```
+
+### Creating a `remote_dom` resource
+
+```ruby
+require 'mcp_ui_server'
+
+script = "..." # Your javascript bundle for the remote-dom
+
+resource = McpUiServer.create_ui_resource(
+  uri: 'ui://my-app/complex-view',
+  content: {
+    type: :remote_dom,
+    script: script,
+    framework: :react # or :webcomponents
+  }
+)
+```
+
+### Using `blob` encoding
+
+For binary content or to avoid encoding issues, you can use `blob` encoding, which will Base64 encode the content.
+
+```ruby
+resource = McpUiServer.create_ui_resource(
+  uri: 'ui://my-app/greeting',
+  content: {
+    type: :raw_html,
+    htmlString: '<h1>Hello, World!</h1>'
+  },
+  encoding: :blob
+)
+```
+
+## Error Handling
+
+The SDK uses a custom `McpUiServer::Error` class for all SDK-specific errors. This makes it easy to rescue and handle SDK errors separately from other application errors.
+
+```ruby
+begin
+  resource = McpUiServer.create_ui_resource(
+    uri: 'http://invalid-scheme',
+    content: { type: :raw_html, htmlString: '<h1>Hello</h1>' }
+  )
+rescue McpUiServer::Error => e
+  puts "MCP UI SDK Error: #{e.message}"
+  # Handle SDK-specific errors
+rescue => e
+  puts "Other error: #{e.message}"
+  # Handle other errors
+end
+```
+
+Common error scenarios:
+- Invalid URI scheme (not starting with `ui://`)
+- Unknown content type (only `:raw_html`, `:external_url`, `:remote_dom` are supported)
+- Missing required content keys (e.g., `htmlString` for `raw_html`)
+- Unknown encoding type
+
+## Constants
+
+The SDK provides constants for MIME types and content types:
+
+```ruby
+# MIME type constants
+McpUiServer::MIME_TYPE_HTML          # 'text/html'
+McpUiServer::MIME_TYPE_URI_LIST      # 'text/uri-list'
+McpUiServer::MIME_TYPE_REMOTE_DOM    # 'application/vnd.mcp-ui.remote-dom; framework=%s'
+
+# Content type constants (Ruby snake_case)
+McpUiServer::CONTENT_TYPE_RAW_HTML      # :raw_html
+McpUiServer::CONTENT_TYPE_EXTERNAL_URL  # :external_url
+McpUiServer::CONTENT_TYPE_REMOTE_DOM    # :remote_dom
+
+# Protocol mapping (for internal use)
+McpUiServer::PROTOCOL_CONTENT_TYPES     # { raw_html: 'rawHtml', ... }
+
+# URI scheme constant
+McpUiServer::UI_URI_SCHEME           # 'ui://'
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bundle exec rubocop` to check for code style.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/idosal/mcp-ui.
+
+## License
+
+The gem is available as open source under the terms of the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0). 

data/lib/mcp_ui_server/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module McpUiServer
+  VERSION = '0.1.0'
+end

data/lib/mcp_ui_server.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative 'mcp_ui_server/version'
+require 'base64'
+
+# The McpUiServer module provides helper methods for creating UI resources
+# compatible with the Model Context Protocol UI (mcp-ui) client.
+module McpUiServer
+  class Error < StandardError; end
+
+  # MIME type constants
+  MIME_TYPE_HTML = 'text/html'
+  MIME_TYPE_URI_LIST = 'text/uri-list'
+  MIME_TYPE_REMOTE_DOM = 'application/vnd.mcp-ui.remote-dom+javascript; framework=%s'
+
+  # Content type constants
+  CONTENT_TYPE_RAW_HTML = :raw_html
+  CONTENT_TYPE_EXTERNAL_URL = :external_url
+  CONTENT_TYPE_REMOTE_DOM = :remote_dom
+
+  # Protocol mapping (snake_case to camelCase for protocol consistency)
+  PROTOCOL_CONTENT_TYPES = {
+    raw_html: 'rawHtml',
+    external_url: 'externalUrl',
+    remote_dom: 'remoteDom'
+  }.freeze
+
+  # Required content keys for each content type
+  REQUIRED_CONTENT_KEYS = {
+    CONTENT_TYPE_RAW_HTML => :htmlString,
+    CONTENT_TYPE_EXTERNAL_URL => :iframeUrl,
+    CONTENT_TYPE_REMOTE_DOM => :script
+  }.freeze
+
+  # URI scheme constant
+  UI_URI_SCHEME = 'ui://'
+
+  # Creates a UIResource hash structure for an MCP response.
+  # This structure can then be serialized to JSON by your web framework.
+  #
+  # @param uri [String] The unique identifier for the resource (e.g., 'ui://greeting/1').
+  # @param content [Hash] A hash describing the UI content.
+  #   - :type [Symbol] The type of content. One of :raw_html, :external_url, or :remote_dom.
+  #   - :htmlString [String] The raw HTML content (required if type is :raw_html).
+  #   - :iframeUrl [String] The URL for an external page (required if type is :external_url).
+  #   - :script [String] The remote-dom script (required if type is :remote_dom).
+  #   - :framework [Symbol] The remote-dom framework, e.g., :react or :webcomponents (required, for :remote_dom).
+  # @param encoding [Symbol] The encoding method. :text for plain string, :blob for base64 encoded.
+  #
+  # @return [Hash] A UIResource hash ready to be included in an MCP response.
+  #
+  # @raise [McpUiServer::Error] if URI scheme is invalid, content type is unknown,
+  #   encoding type is unknown, or required content keys are missing.
+  def self.create_ui_resource(uri:, content:, encoding: :text)
+    validate_uri_scheme(uri)
+
+    resource = { uri: uri }
+
+    content_value = process_content(content, resource)
+    process_encoding(encoding, resource, content_value)
+
+    {
+      type: 'resource',
+      resource: resource
+    }
+  end
+
+  # private
+
+  def self.validate_uri_scheme(uri)
+    raise Error, "URI must start with '#{UI_URI_SCHEME}' but got: #{uri}" unless uri.start_with?(UI_URI_SCHEME)
+  end
+  private_class_method :validate_uri_scheme
+
+  def self.validate_content_type(content_type)
+    return if PROTOCOL_CONTENT_TYPES.key?(content_type)
+
+    supported_types = PROTOCOL_CONTENT_TYPES.keys.join(', ')
+    raise Error, "Unknown content type: #{content_type}. Supported types: #{supported_types}"
+  end
+  private_class_method :validate_content_type
+
+  def self.process_content(content, resource)
+    content_type = content.fetch(:type)
+    validate_content_type(content_type)
+
+    case content_type
+    when CONTENT_TYPE_RAW_HTML
+      process_raw_html_content(content, resource)
+    when CONTENT_TYPE_EXTERNAL_URL
+      process_external_url_content(content, resource)
+    when CONTENT_TYPE_REMOTE_DOM
+      process_remote_dom_content(content, resource)
+    end
+  end
+  private_class_method :process_content
+
+  def self.process_raw_html_content(content, resource)
+    resource[:mimeType] = MIME_TYPE_HTML
+    required_key = REQUIRED_CONTENT_KEYS[CONTENT_TYPE_RAW_HTML]
+    content.fetch(required_key) { raise Error, "Missing required key :#{required_key} for raw_html content" }
+  end
+  private_class_method :process_raw_html_content
+
+  def self.process_external_url_content(content, resource)
+    resource[:mimeType] = MIME_TYPE_URI_LIST
+    required_key = REQUIRED_CONTENT_KEYS[CONTENT_TYPE_EXTERNAL_URL]
+    content.fetch(required_key) { raise Error, "Missing required key :#{required_key} for external_url content" }
+  end
+  private_class_method :process_external_url_content
+
+  def self.process_remote_dom_content(content, resource)
+    framework = content.fetch(:framework) { raise Error, 'Missing required key :framework for remote_dom content' }
+    resource[:mimeType] = MIME_TYPE_REMOTE_DOM % framework
+    required_key = REQUIRED_CONTENT_KEYS[CONTENT_TYPE_REMOTE_DOM]
+    content.fetch(required_key) { raise Error, "Missing required key :#{required_key} for remote_dom content" }
+  end
+  private_class_method :process_remote_dom_content
+
+  def self.process_encoding(encoding, resource, content_value)
+    case encoding
+    when :text
+      resource[:text] = content_value
+    when :blob
+      resource[:blob] = Base64.strict_encode64(content_value)
+    else
+      raise Error, "Unknown encoding type: #{encoding}. Supported types: :text, :blob"
+    end
+  end
+  private_class_method :process_encoding
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: mcp_ui_server
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ido Salomon
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby server SDK for MCP UI.
+email:
+- idosalomon@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/mcp_ui_server.rb
+- lib/mcp_ui_server/version.rb
+homepage: https://github.com/idosal/mcp-ui
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby Server SDK for MCP UI
+test_files: []