actionmcp 0.100.0 → 0.101.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b01884f2ba4ded4a59d6c235583edbd00dae36da78215da26a1fbf83039838f
-  data.tar.gz: c97745755f33ece7ce05a4a2a904cde23e3fe67c3f1ecf9ee0cc962e6bdc9177
+  metadata.gz: 9bf1821cef23dc83ceb6798b128cecc43a2585d3bd7c75996824cbfb960f085a
+  data.tar.gz: fb1b755390487c5b4fff6a75e94540470ef21135bed4978465da9f16f8f201c3
 SHA512:
-  metadata.gz: 545540e721a557860d9263873c841fd703afd1ea9bed05ea489b738c5a81594cc6f560fdf3959d6d9ff992b3e4b247eb8efead8f5f234946429903b00ce06a96
-  data.tar.gz: 8c4a3d2abe05b4f65b26e6dfdd751350973e029341c8ed8bb1e3f880a046477afd59ce236a71d6e607dd82ab3220eaac1c3ee462c7c8861c1ec79a814eaa42ca
+  metadata.gz: a0764d4fea510580d99b6b51428b91545bfd17d9e6ae9828a88b127e6d91c2f5f1d77fb0816f4043ed6de596c0c55719d2b16c73efc38a7dedf5ff027a5236a4
+  data.tar.gz: d828f74be45e7b33877b01265a159fcc76961bba326ac4f31205243bd6bbcd5cb1f4935be627d5ae6bb8aad1fa7644f8611b2514637f94cab74eab7f6184a2d8

data/README.md

@@ -219,6 +219,111 @@ sum_tool = CalculateSumTool.new(a: 5, b: 10)
 result = sum_tool.call
 ```
 
+#### Structured output (output_schema)
+
+Advertise a JSON Schema for your tool's structuredContent and return machine-validated results alongside any text output.
+
+```ruby
+class PriceQuoteTool < ApplicationMCPTool
+  tool_name "price_quote"
+  description "Return a structured price quote"
+
+  property :sku, type: "string", description: "SKU to price", required: true
+
+  output_schema do
+    string :sku, required: true, description: "SKU that was priced"
+    number :price_cents, required: true, description: "Total price in cents"
+    object :meta do
+      string :currency, required: true, enum: %w[USD EUR GBP]
+      boolean :cached, default: false
+    end
+  end
+
+  def perform
+    price_cents = lookup_price_cents(sku) # Implement your lookup
+
+    render structured: { sku: sku,
+                         price_cents: price_cents,
+                         meta: { currency: "USD", cached: false } }
+  end
+end
+```
+
+The schema is included in the tool definition, and the `structured` payload is emitted as `structuredContent` in the response while remaining compatible with text/audio/image renders.
+
+#### Returning resource links from a tool
+
+When you want to hand back a URI instead of embedding the payload, use the built-in `render_resource_link`, which produces the MCP `resource_link` content type.
+
+```ruby
+class ReportLinkTool < ApplicationMCPTool
+  tool_name "report_link"
+  description "Return a downloadable report link"
+
+  property :report_id, type: "string", required: true
+
+  def perform
+    render_resource_link(
+      uri: "reports://#{report_id}.json",
+      name: "Report #{report_id}",
+      description: "Downloadable JSON for report #{report_id}",
+      mime_type: "application/json"
+    )
+  end
+end
+```
+
+Clients can resolve the URI with a separate `resources/read` call, keeping tool responses lightweight while still discoverable.
+
+#### Task-augmented tools (async execution with progress)
+
+Use MCP Tasks when work might take seconds/minutes. Advertise task support with `task_required!` (or `task_optional!`) and let callers opt in by sending `_meta.task` on `tools/call`. While running as a task, you can emit progress updates with `report_progress!`.
+
+```ruby
+class BatchIndexTool < ApplicationMCPTool
+  tool_name "batch_index"
+  description "Index many items asynchronously with progress updates"
+
+  task_required! # advertise that this tool is intended to run as a task
+  property :items, type: "array_string", description: "Items to index", required: true
+
+  def perform
+    total = items.length
+    items.each_with_index do |item, idx|
+      index_item(item) # your indexing logic
+
+      percent = ((idx + 1) * 100.0 / total).round
+      report_progress!(percent: percent, message: "Indexed #{idx + 1}/#{total}")
+    end
+
+    render(text: "Indexed #{total} items")
+  end
+
+  private
+
+  def index_item(item)
+    # Implement your indexing logic here
+  end
+end
+```
+
+Call it as a task from a client by adding `_meta.task` (creates a Task record and runs the tool via `ToolExecutionJob`):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "batch_index",
+    "arguments": { "items": ["a", "b", "c"] },
+    "_meta": { "task": { "ttl": 120000, "pollInterval": 2000 } }
+  }
+}
+```
+
+Poll task status with `tasks/get` or fetch the result when finished with `tasks/result`. Use `tasks/cancel` to stop non-terminal tasks.
+
 ### ActionMCP::ResourceTemplate
 
 `ActionMCP::ResourceTemplate` facilitates the creation of URI templates for dynamic resources that LLMs can access.
@@ -311,6 +416,10 @@ ActionMCP provides comprehensive documentation across multiple specialized guide
   - Transport configuration and connection handling
   - Tool, prompt, and resource collections
   - Production deployment patterns
+- **[🔐 GATEWAY.md](GATEWAY.md)** - Authentication gateway guide
+  - Implementing `ApplicationGateway`
+  - Identifier handling via `ActionMCP::Current`
+  - Auth patterns, error handling, and hardening tips
 
 ### Protocol & Technical Details
 - **[🚀 The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md)** - Protocol versions and migration

data/app/jobs/action_mcp/tool_execution_job.rb

@@ -27,7 +27,7 @@ module ActionMCP
       @session = step(:validate_session, @task)
       return unless @session
 
-      @tool = step(:prepare_tool, @session, tool_name, arguments)
+      @tool = step(:prepare_tool, @session, tool_name, arguments, @task)
       return unless @tool
 
       step(:execute_tool) do
@@ -60,7 +60,7 @@ module ActionMCP
       session
     end
 
-    def prepare_tool(session, tool_name, arguments)
+    def prepare_tool(session, tool_name, arguments, task)
       tool_class = session.registered_tools.find { |t| t.tool_name == tool_name }
       unless tool_class
         @task.update(status_message: "Tool '#{tool_name}' not found")
@@ -76,6 +76,8 @@ module ActionMCP
           params: @task.request_params
         }
       })
+      # Enable report_progress! inside the tool during task-augmented runs
+      tool.instance_variable_set(:@_task, task)
 
       tool
     end

data/lib/action_mcp/configuration.rb

@@ -47,7 +47,9 @@ module ActionMCP
                   # --- Tasks Options (MCP 2025-11-25) ---
                   :tasks_enabled,
                   :tasks_list_enabled,
-                  :tasks_cancel_enabled
+                  :tasks_cancel_enabled,
+                  # --- Schema Validation Options ---
+                  :validate_structured_content
 
     def initialize
       @logging_enabled = false
@@ -69,6 +71,9 @@ module ActionMCP
       @tasks_list_enabled = true
       @tasks_cancel_enabled = true
 
+      # Schema validation - disabled by default for backward compatibility
+      @validate_structured_content = false
+
       # Gateway - resolved lazily to account for Zeitwerk autoloading
       @gateway_class_name = nil
 

data/lib/action_mcp/output_schema_builder.rb

@@ -127,12 +127,12 @@ module ActionMCP
     end
 
     # Define an object property
-    # @param name [Symbol] Object property name
+    # @param name [Symbol, nil] Object property name. If nil, returns schema directly (for array items)
     # @param required [Boolean] Whether the object is required
     # @param description [String] Property description
     # @param additional_properties [Boolean, Hash] Whether to allow additional properties
     # @param block [Proc] Block defining object properties
-    def object(name, required: false, description: nil, additional_properties: nil, &block)
+    def object(name = nil, required: false, description: nil, additional_properties: nil, &block)
       raise ArgumentError, "Object definition requires a block" unless block_given?
 
       # Create nested builder for object properties
@@ -149,10 +149,14 @@ module ActionMCP
       # Add additionalProperties if specified
       add_additional_properties_to_schema(schema, additional_properties)
 
-      @properties[name.to_s] = schema
-      @required << name.to_s if required
-
-      name.to_s
+      if name
+        @properties[name.to_s] = schema
+        @required << name.to_s if required
+        name.to_s
+      else
+        # Return schema directly for use in array items
+        schema
+      end
     end
 
     # Set additionalProperties for the root schema

data/lib/action_mcp/tool.rb

@@ -490,6 +490,9 @@ module ActionMCP
     # Override render to collect Content objects and support structured content
     def render(structured: nil, **args)
       if structured
+        # Validate structured content against output_schema if enabled
+        validate_structured_content!(structured) if self.class._output_schema
+
         # Render structured content
         set_structured_content(structured)
         structured
@@ -553,6 +556,42 @@ module ActionMCP
       @response.set_structured_content(content)
     end
 
+    # Validates structured content against the declared output_schema
+    # Only runs if validate_structured_content is enabled in configuration
+    # @param content [Hash] The structured content to validate
+    # @raise [StructuredContentValidationError] If content doesn't match schema
+    def validate_structured_content!(content)
+      return unless ActionMCP.configuration.validate_structured_content
+
+      schema = self.class._output_schema
+      return unless schema.present?
+
+      # Lazy load json_schemer - only required if validation is enabled
+      gem "json_schemer", ">= 2.4"
+      require "json_schemer"
+
+      schemer = JSONSchemer.schema(schema.deep_stringify_keys)
+      errors = schemer.validate(deep_stringify_content(content)).to_a
+
+      return if errors.empty?
+
+      error_messages = errors.map { |e| e["error"] }.join(", ")
+      raise ActionMCP::StructuredContentValidationError,
+            "Structured content does not match output_schema: #{error_messages}"
+    end
+
+    # Deep stringify keys for validation (handles symbols and nested structures)
+    def deep_stringify_content(content)
+      case content
+      when Hash
+        content.transform_keys(&:to_s).transform_values { |v| deep_stringify_content(v) }
+      when Array
+        content.map { |v| deep_stringify_content(v) }
+      else
+        content
+      end
+    end
+
     private
 
 

data/lib/action_mcp/version.rb

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.100.0"
+  VERSION = "0.101.0"
 
   class << self
     alias version gem_version

data/lib/action_mcp.rb

@@ -31,6 +31,9 @@ module ActionMCP
   require_relative "action_mcp/version"
   require_relative "action_mcp/client"
 
+  # Error raised when structured content doesn't match the declared output_schema
+  class StructuredContentValidationError < StandardError; end
+
   # Protocol version constants
   SUPPORTED_VERSIONS = [
     "2025-11-25", # The Task Master - Tasks, icons, tool naming, polling SSE

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.100.0
+  version: 0.101.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -125,16 +125,16 @@ dependencies:
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.4'
 description: A streamlined, production-focused toolkit for building MCP servers in
   Rails applications. Provides essential base classes, authentication gateways, and
   HTTP transport with minimal dependencies.