actionmcp 0.111.0 → 0.200.0

data/lib/action_mcp/content/validation.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "addressable/uri"
+require "base64"
+require "json"
+require "json_schemer"
+require "active_support/core_ext/object/deep_dup"
+
+module ActionMCP
+  module Content
+    # Stable MCP wire-shape validation shared by content and response value objects.
+    module Validation
+      META_PROPERTY = {
+        "_meta" => { "type" => "object" }
+      }.freeze
+
+      ANNOTATIONS = {
+        "type" => "object",
+        "properties" => {
+          "audience" => {
+            "type" => "array",
+            "items" => { "type" => "string", "enum" => %w[assistant user] }
+          },
+          "lastModified" => { "type" => "string" },
+          "priority" => { "type" => "number", "minimum" => 0, "maximum" => 1 }
+        }
+      }.freeze
+
+      ICON = {
+        "type" => "object",
+        "required" => [ "src" ],
+        "properties" => {
+          "src" => { "type" => "string", "format" => "uri" },
+          "mimeType" => { "type" => "string" },
+          "sizes" => { "type" => "array", "items" => { "type" => "string" } },
+          "theme" => { "type" => "string", "enum" => %w[dark light] }
+        }
+      }.freeze
+
+      DEFINITIONS = {
+        "Annotations" => ANNOTATIONS,
+        "Icon" => ICON,
+        "TextContent" => {
+          "type" => "object",
+          "required" => %w[text type],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "text" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "text" }
+          )
+        },
+        "ImageContent" => {
+          "type" => "object",
+          "required" => %w[data mimeType type],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "data" => { "type" => "string", "format" => "byte" },
+            "mimeType" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "image" }
+          )
+        },
+        "AudioContent" => {
+          "type" => "object",
+          "required" => %w[data mimeType type],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "data" => { "type" => "string", "format" => "byte" },
+            "mimeType" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "audio" }
+          )
+        },
+        "TextResourceContents" => {
+          "type" => "object",
+          "required" => %w[text uri],
+          "properties" => META_PROPERTY.merge(
+            "mimeType" => { "type" => "string" },
+            "text" => { "type" => "string" },
+            "uri" => { "type" => "string", "format" => "uri" }
+          )
+        },
+        "BlobResourceContents" => {
+          "type" => "object",
+          "required" => %w[blob uri],
+          "properties" => META_PROPERTY.merge(
+            "blob" => { "type" => "string", "format" => "byte" },
+            "mimeType" => { "type" => "string" },
+            "uri" => { "type" => "string", "format" => "uri" }
+          )
+        },
+        "EmbeddedResource" => {
+          "type" => "object",
+          "required" => %w[resource type],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "resource" => {
+              "anyOf" => [
+                { "$ref" => "#/$defs/TextResourceContents" },
+                { "$ref" => "#/$defs/BlobResourceContents" }
+              ]
+            },
+            "type" => { "type" => "string", "const" => "resource" }
+          )
+        },
+        "ResourceLink" => {
+          "type" => "object",
+          "required" => %w[name type uri],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "description" => { "type" => "string" },
+            "icons" => { "type" => "array", "items" => { "$ref" => "#/$defs/Icon" } },
+            "mimeType" => { "type" => "string" },
+            "name" => { "type" => "string" },
+            "size" => { "type" => "integer" },
+            "title" => { "type" => "string" },
+            "type" => { "type" => "string", "const" => "resource_link" },
+            "uri" => { "type" => "string", "format" => "uri" }
+          )
+        },
+        "ContentBlock" => {
+          "anyOf" => %w[TextContent ImageContent AudioContent ResourceLink EmbeddedResource].map do |name|
+            { "$ref" => "#/$defs/#{name}" }
+          end
+        },
+        "Resource" => {
+          "type" => "object",
+          "required" => %w[name uri],
+          "properties" => META_PROPERTY.merge(
+            "annotations" => { "$ref" => "#/$defs/Annotations" },
+            "description" => { "type" => "string" },
+            "icons" => { "type" => "array", "items" => { "$ref" => "#/$defs/Icon" } },
+            "mimeType" => { "type" => "string" },
+            "name" => { "type" => "string" },
+            "size" => { "type" => "integer" },
+            "title" => { "type" => "string" },
+            "uri" => { "type" => "string", "format" => "uri" }
+          )
+        },
+        "PromptMessage" => {
+          "type" => "object",
+          "required" => %w[content role],
+          "properties" => {
+            "content" => { "$ref" => "#/$defs/ContentBlock" },
+            "role" => { "type" => "string", "enum" => %w[assistant user] }
+          }
+        },
+        "GetPromptResult" => {
+          "type" => "object",
+          "required" => [ "messages" ],
+          "properties" => META_PROPERTY.merge(
+            "description" => { "type" => "string" },
+            "messages" => { "type" => "array", "items" => { "$ref" => "#/$defs/PromptMessage" } }
+          )
+        },
+        "CallToolResult" => {
+          "type" => "object",
+          "required" => [ "content" ],
+          "properties" => META_PROPERTY.merge(
+            "content" => { "type" => "array", "items" => { "$ref" => "#/$defs/ContentBlock" } },
+            "isError" => { "type" => "boolean" },
+            "structuredContent" => { "type" => "object" }
+          )
+        }
+      }.freeze
+
+      FORMAT_VALIDATORS = {
+        "byte" => lambda do |value, _format|
+          Base64.strict_decode64(value)
+          true
+        rescue ArgumentError
+          false
+        end,
+        "uri" => lambda do |value, _format|
+          Addressable::URI.parse(value).absolute?
+        rescue Addressable::URI::InvalidURIError, TypeError
+          false
+        end
+      }.freeze
+
+      SCHEMERS = %w[Annotations ContentBlock Resource GetPromptResult CallToolResult].to_h do |name|
+        schema = {
+          "$schema" => "https://json-schema.org/draft/2020-12/schema",
+          "$ref" => "#/$defs/#{name}",
+          "$defs" => DEFINITIONS
+        }
+        [ name, JSONSchemer.schema(schema, formats: FORMAT_VALIDATORS) ]
+      end.freeze
+
+      module_function
+
+      def validate_annotations!(annotations)
+        return if annotations.nil?
+
+        validate!(SCHEMERS.fetch("Annotations"), annotations, "annotations")
+      end
+
+      def validate_content_block!(content)
+        validate!(SCHEMERS.fetch("ContentBlock"), content, "content")
+      end
+
+      def validate_resource!(resource)
+        validate!(SCHEMERS.fetch("Resource"), resource, "resource")
+      end
+
+      def validate_prompt_result!(result)
+        validate!(SCHEMERS.fetch("GetPromptResult"), result, "prompt result")
+      end
+
+      def validate_tool_result!(result)
+        validate!(SCHEMERS.fetch("CallToolResult"), result, "tool result")
+      end
+
+      def copy_object!(value, label)
+        source =
+          if value.is_a?(Hash)
+            value
+          elsif value.is_a?(Array)
+            nil
+          elsif value.respond_to?(:to_hash)
+            value.to_hash
+          elsif value.respond_to?(:to_h)
+            value.to_h
+          end
+
+        raise ArgumentError, "#{label} must be a JSON object" unless source.is_a?(Hash)
+
+        source.deep_dup.tap { |copy| ensure_json!(copy, label) }
+      end
+
+      def copy_content_block!(content)
+        copy = copy_object!(content, "content")
+        validate_content_block!(copy)
+        copy
+      end
+
+      def ensure_json!(value, label)
+        JSON.generate(value)
+      rescue JSON::GeneratorError, JSON::NestingError => e
+        raise ArgumentError, "#{label} must be JSON-serializable: #{e.message}"
+      end
+
+      def validate!(schemer, value, label)
+        ensure_json!(value, label)
+        error = schemer.validate(value).first
+        return value unless error
+
+        pointer = error.fetch("data_pointer", "")
+        location = pointer.empty? ? "" : " at #{pointer}"
+        raise ArgumentError, "#{label} is not valid MCP 2025-11-25 data#{location}: #{error.fetch('error')}"
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/action_mcp/content.rb

@@ -15,7 +15,8 @@ module ActionMCP
       # @param annotations [Hash, nil] Optional annotations for the content.
       def initialize(type, annotations: nil)
         @type = type
-        @annotations = annotations
+        @annotations = annotations.nil? ? nil : Validation.copy_object!(annotations, "annotations")
+        Validation.validate_annotations!(@annotations)
       end
 
       # Returns a hash representation of the content.
@@ -24,6 +25,7 @@ module ActionMCP
       def to_h
         h = { type: @type }
         h[:annotations] = @annotations if @annotations
+        Validation.validate_annotations!(@annotations)
         h
       end
 

data/lib/action_mcp/dev/runner.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Dev
+    # A single command that boots the ActionMCP dev loop: the standalone MCP
+    # server plus, when a compiled-views tier is present, the vite view builder
+    # in watch mode, plus an optional public tunnel.
+    #
+    # Note on the reload model: MCP Apps views are delivered to hosts as
+    # inlined resource text inside a sandboxed iframe, so there is no websocket
+    # channel for classic in-browser HMR. The dev loop is watch-and-rebuild:
+    # editing a view triggers a vite rebuild of its bundle + manifest, and the
+    # next tool invocation in the MCP client renders the fresh view.
+    #
+    # Usage from the generated binstub:
+    #   ActionMCP::Dev::Runner.new(root: Dir.pwd, argv: ARGV).run
+    class Runner
+      DEFAULT_PORT = 62_770
+      VIEWS_SUBDIR = "app/mcp/views"
+      BUILD_BIN = "action-mcp-build-views"
+
+      # A child process to supervise.
+      Spec = Struct.new(:label, :command, :env, keyword_init: true)
+
+      attr_reader :root, :options
+
+      def initialize(root:, argv: [], env: ENV, out: $stdout)
+        @root = File.expand_path(root)
+        @env = env
+        @out = out
+        @options = parse(argv)
+        @pids = {}
+      end
+
+      # The set of child processes this invocation would start. Pure — no
+      # spawning — so the wiring is unit-testable.
+      #
+      # @return [Array<Spec>]
+      def plan
+        specs = [ server_spec ]
+        specs << views_spec if run_views?
+        specs << tunnel_spec if @options[:tunnel]
+        specs
+      end
+
+      # Whether the vite view-builder should run: opt-in tier is present and the
+      # user did not disable it.
+      def run_views?
+        @options[:views] && File.directory?(File.join(@root, VIEWS_SUBDIR))
+      end
+
+      def run
+        if @options[:help]
+          @out.puts usage
+          return 0
+        end
+
+        specs = plan
+        print_banner(specs)
+
+        specs.each { |spec| spawn(spec) }
+        install_signal_traps
+        supervise
+      end
+
+      private
+
+      def parse(argv)
+        opts = { port: DEFAULT_PORT, views: true, tunnel: false, help: false }
+        args = argv.dup
+
+        until args.empty?
+          arg = args.shift
+          case arg
+          when "-h", "--help"      then opts[:help] = true
+          when "--no-views"        then opts[:views] = false
+          when "--tunnel"          then opts[:tunnel] = true
+          when "-p", "--port"      then opts[:port] = Integer(args.shift)
+          else
+            if (m = arg.match(/\A--port=(.+)\z/))
+              opts[:port] = Integer(m[1])
+            elsif arg.match?(/\A\d+\z/)
+              opts[:port] = Integer(arg) # bare port, matching `bin/mcp 3001`
+            else
+              raise ArgumentError, "unknown option: #{arg}\n\n#{usage}"
+            end
+          end
+        end
+
+        opts
+      end
+
+      def server_spec
+        rackup = File.join(@root, "mcp", "config.ru")
+        command =
+          if falcon_available?
+            [ "bundle", "exec", "falcon", "serve",
+              "--bind", "http://127.0.0.1:#{@options[:port]}", "--config", rackup ]
+          else
+            [ "bundle", "exec", "rails", "server", "-c", rackup,
+              "-b", "127.0.0.1", "-p", @options[:port].to_s ]
+          end
+        Spec.new(label: "server", command: command, env: {})
+      end
+
+      def views_spec
+        command = [ *node_runner, BUILD_BIN, "--watch", "--root", @root ]
+        Spec.new(label: "views", command: command, env: {})
+      end
+
+      def tunnel_spec
+        command = [ "cloudflared", "tunnel", "--url", "http://localhost:#{@options[:port]}" ]
+        Spec.new(label: "tunnel", command: command, env: {})
+      end
+
+      # Prefer the package runner matching the lockfile in the project so the
+      # locally-installed @action-mcp/vite-plugin bin resolves.
+      def node_runner
+        if File.exist?(File.join(@root, "bun.lock")) || File.exist?(File.join(@root, "bun.lockb"))
+          [ "bunx" ]
+        elsif File.exist?(File.join(@root, "pnpm-lock.yaml"))
+          [ "pnpm", "exec" ]
+        else
+          [ "npx" ]
+        end
+      end
+
+      def falcon_available?
+        Gem::Specification.find_by_name("falcon")
+        true
+      rescue Gem::MissingSpecError
+        false
+      end
+
+      def spawn(spec)
+        @out.puts "  ▸ #{spec.label}: #{spec.command.join(' ')}"
+        pid = Process.spawn(spec.env, *spec.command, chdir: @root)
+        @pids[pid] = spec.label
+      end
+
+      def install_signal_traps
+        %w[INT TERM].each do |sig|
+          Signal.trap(sig) { shutdown(sig) }
+        end
+      end
+
+      # Wait for any child to exit; when one dies, tear the rest down so the dev
+      # loop never limps along half-up.
+      def supervise
+        pid = Process.wait
+        label = @pids.delete(pid)
+        status = $?
+        @out.puts "\n[action-mcp] #{label} exited (#{status.exitstatus || status.termsig}); stopping dev loop."
+        shutdown("TERM")
+        status.exitstatus || 1
+      rescue Interrupt
+        shutdown("TERM")
+        130
+      end
+
+      def shutdown(sig)
+        @pids.each_key do |pid|
+          Process.kill(sig, pid)
+        rescue Errno::ESRCH
+          # already gone
+        end
+        @pids.each_key do |pid|
+          Process.wait(pid)
+        rescue Errno::ECHILD
+          # already reaped
+        end
+        @pids.clear
+        exit(0) if sig == "INT"
+      end
+
+      def print_banner(specs)
+        @out.puts "ActionMCP dev loop"
+        @out.puts "  server:    http://localhost:#{@options[:port]}"
+        @out.puts "  views:     #{run_views? ? 'watching app/mcp/views' : 'disabled'}"
+        @out.puts "  tunnel:    #{@options[:tunnel] ? 'cloudflared' : 'off (pass --tunnel)'}"
+        @out.puts "  inspect:   npx @modelcontextprotocol/inspector " \
+                  "--url http://localhost:#{@options[:port]}"
+        @out.puts "  (#{specs.size} process#{'es' if specs.size != 1})"
+        @out.puts
+      end
+
+      def usage
+        <<~USAGE
+          Usage: bin/mcp dev [options]
+
+          Boots the MCP server and, when app/mcp/views exists, the vite view
+          builder in watch mode.
+
+          Options:
+            -p, --port PORT   Server port (default: #{DEFAULT_PORT})
+            --no-views        Do not start the view builder
+            --tunnel          Expose the server publicly via cloudflared
+            -h, --help        Show this help
+        USAGE
+      end
+    end
+  end
+end

data/lib/action_mcp/engine.rb

@@ -9,6 +9,16 @@ module ActionMCP
   class Engine < ::Rails::Engine
     isolate_namespace ActionMCP
 
+    def self.endpoint_path_matcher(path)
+      endpoint = ActionDispatch::Journey::Router::Utils.normalize_path(path)
+      formatted_endpoint = /\A#{Regexp.escape(endpoint)}(?:\.[^\/.]+)?\z/
+
+      lambda do |request_path|
+        normalized_path = ActionDispatch::Journey::Router::Utils.normalize_path(request_path)
+        formatted_endpoint.match?(normalized_path)
+      end
+    end
+
     ActiveSupport::Inflector.inflections(:en) do |inflect|
       inflect.acronym "MCP"
     end
@@ -43,13 +53,25 @@ module ActionMCP
       # Eager load MCP components if profile includes "all"
       # This runs after Zeitwerk is fully set up
       ActionMCP.configuration.eager_load_if_needed
+
+      # Register compiled MCP Apps views after registries
+      # are (re)built. Runs on each dev reload so rebuilt view bundles/hashes
+      # are picked up without restarting the server; runs once at boot in
+      # production.
+      ActionMCP::Apps::ViewManifest.load! if ActionMCP.configuration.mcp_apps_enabled
     end
 
     initializer "action_mcp.insert_middleware" do |app|
+      endpoint_paths = [ ActionMCP::Engine.endpoint_path_matcher(ActionMCP.configuration.base_path) ].freeze
+
       config.middleware.use ActionDispatch::HostAuthorization, app.config.hosts if app.config.hosts.present?
       config.middleware.use ActionMCP::Middleware::OriginValidation,
-                            [ ActionMCP.configuration.base_path ].compact.freeze
-      config.middleware.use JSONRPC_Rails::Middleware::Validator, [ ActionMCP.configuration.base_path ].compact.freeze
+                            endpoint_paths
+      config.middleware.use JSONRPC_Rails::Middleware::Validator,
+                            endpoint_paths,
+                            payload_validator: ActionMCP::ProtocolValidator,
+                            batch_policy: :reject,
+                            require_json_content_type: true
     end
 
     # Load MCP profiles during initialization

data/lib/action_mcp/json_rpc_handler_base.rb

@@ -31,6 +31,8 @@ module ActionMCP
       # Notification methods
       NOTIFICATIONS_INITIALIZED = "notifications/initialized"
       NOTIFICATIONS_CANCELLED = "notifications/cancelled"
+      NOTIFICATIONS_PROGRESS = "notifications/progress"
+      NOTIFICATIONS_ROOTS_LIST_CHANGED = "notifications/roots/list_changed"
 
       # Elicitation methods
       ELICITATION_CREATE = "elicitation/create"
@@ -73,9 +75,6 @@ module ActionMCP
         transport.send_pong(id)
         # In return mode, get the response that was just created
         transport.messaging_mode == :return ? transport.get_last_response : true
-      when %r{^notifications/}
-        process_notifications(rpc_method, params)
-        true
       end
     end
 
@@ -83,18 +82,14 @@ module ActionMCP
     def process_notifications(rpc_method, params)
       case rpc_method
       when Methods::NOTIFICATIONS_CANCELLED
-        handle_cancelled_notification(params)
+        transport.receive_cancelled_notification(params)
+      when Methods::NOTIFICATIONS_PROGRESS
+        transport.receive_progress_notification(params)
+      when Methods::NOTIFICATIONS_TASKS_STATUS
+        transport.receive_task_status_notification(params)
       else
         Rails.logger.warn("Unknown notifications method: #{rpc_method}")
       end
     end
-
-    private
-
-    # Handle cancelled notification
-    def handle_cancelled_notification(params)
-      Rails.logger.warn "\e[31m Request #{params['requestId']} cancelled: #{params['reason']}\e[0m"
-      # we don't need to do anything here
-    end
   end
 end

data/lib/action_mcp/logging/logger.rb

@@ -92,50 +92,50 @@ module ActionMCP
       # Check if debug level is enabled
       # @return [Boolean] true if debug messages will be logged
       def debug?
-        state.should_log?(:debug)
+        should_log?(:debug)
       end
 
       # Check if info level is enabled
       # @return [Boolean] true if info messages will be logged
       def info?
-        state.should_log?(:info)
+        should_log?(:info)
       end
 
       # Check if notice level is enabled
       # @return [Boolean] true if notice messages will be logged
       def notice?
-        state.should_log?(:notice)
+        should_log?(:notice)
       end
 
       # Check if warning level is enabled
       # @return [Boolean] true if warning messages will be logged
       def warning?
-        state.should_log?(:warning)
+        should_log?(:warning)
       end
       alias_method :warn?, :warning?
 
       # Check if error level is enabled
       # @return [Boolean] true if error messages will be logged
       def error?
-        state.should_log?(:error)
+        should_log?(:error)
       end
 
       # Check if critical level is enabled
       # @return [Boolean] true if critical messages will be logged
       def critical?
-        state.should_log?(:critical)
+        should_log?(:critical)
       end
 
       # Check if alert level is enabled
       # @return [Boolean] true if alert messages will be logged
       def alert?
-        state.should_log?(:alert)
+        should_log?(:alert)
       end
 
       # Check if emergency level is enabled
       # @return [Boolean] true if emergency messages will be logged
       def emergency?
-        state.should_log?(:emergency)
+        should_log?(:emergency)
       end
 
       private
@@ -147,7 +147,7 @@ module ActionMCP
       # @yield Block that returns message
       # @return [void]
       def log(level, message = nil, data: nil, &block)
-        return unless state.should_log?(level)
+        return unless should_log?(level)
 
         # Evaluate message from block if provided
         final_message = if block_given?
@@ -174,8 +174,7 @@ module ActionMCP
         # Add logger name if present
         params[:logger] = name if name
 
-        # Send via session's messaging service
-        session.messaging_service.send_notification("notifications/message", params)
+        ActionMCP::Server::TransportHandler.new(session).send_logging_message_notification(**params)
       rescue StandardError => e
         # Fallback to Rails logger if MCP transport fails
         Rails.logger.error "Failed to send MCP log notification: #{e.message}"
@@ -203,6 +202,12 @@ module ActionMCP
           end
         end
       end
+
+      def should_log?(message_level)
+        return false unless ActionMCP::Logging.enabled?
+
+        Level.coerce(message_level) >= Level.coerce(ActionMCP::Logging.level_for(session))
+      end
     end
   end
 end