actionmcp 0.100.0 → 0.100.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b01884f2ba4ded4a59d6c235583edbd00dae36da78215da26a1fbf83039838f
-  data.tar.gz: c97745755f33ece7ce05a4a2a904cde23e3fe67c3f1ecf9ee0cc962e6bdc9177
+  metadata.gz: 5df97e0bdac66054109edabe63756d639e74bb3068d70d4028bd990b2bee8442
+  data.tar.gz: db73f42cf5307f09e3b4484799057fc10ee4a5341efa58aef99ab25be82abc4c
 SHA512:
-  metadata.gz: 545540e721a557860d9263873c841fd703afd1ea9bed05ea489b738c5a81594cc6f560fdf3959d6d9ff992b3e4b247eb8efead8f5f234946429903b00ce06a96
-  data.tar.gz: 8c4a3d2abe05b4f65b26e6dfdd751350973e029341c8ed8bb1e3f880a046477afd59ce236a71d6e607dd82ab3220eaac1c3ee462c7c8861c1ec79a814eaa42ca
+  metadata.gz: 0fa54e67f4f7c5e60ba16bd708557534e3b374e19e16d8456289e269e3649c4117407d5e6b4c2ce5c3645476084ab7444e81681a7a900953b4d25da50e534ddc
+  data.tar.gz: 1b783e0ddb8c502cf9438049b7f88c74a89e2bb8e48fdd795789741a7de77b12507412c4b66116b299f7a6b7c75b0279bddf787c6ca522e246e66bee139dd694

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.100.0
+  version: 0.100.1
 platform: ruby
 authors:
 - Abdelkader Boudih