fix: tool execution fix and documention

Author: seuros

GATEWAY.md

@@ -0,0 +1,77 @@
+# ActionMCP Gateway Guide
+
+This document explains the Gateway concept in ActionMCP, how it authenticates callers, and how tools/prompts/resources receive the caller context.
+
+## What the Gateway Does
+- Runs **before** any tool/prompt/resource.
+- Authenticates the request and resolves one or more identifiers.
+- Seeds `ActionMCP::Current` with those identifiers for downstream use.
+- Rejects the request with `ActionMCP::UnauthorizedError` if authentication fails.
+
+## Lifecycle
+1) Request hits the MCP endpoint.  
+2) `ApplicationGateway#authenticate!` executes.  
+3) On success, it returns a hash whose keys match `identified_by` declarations.  
+4) Identifiers are stored on `ActionMCP::Current` and the session; tools/prompts/resources can read them via helper methods (`current_user`, etc.).  
+5) On failure, a JSON-RPC error (`-32001 Unauthorized`) is returned; no tool code runs.
+
+## Implementing `ApplicationGateway`
+`action_mcp:install` generates `app/mcp/application_gateway.rb`. You customize only `identified_by` and `authenticate!`.
+
+```ruby
+# app/mcp/application_gateway.rb
+class ApplicationGateway < ActionMCP::Gateway
+  identified_by :user, :organization
+
+  protected
+
+  def authenticate!
+    token = extract_bearer_token
+    raise ActionMCP::UnauthorizedError, "Missing token" unless token
+
+    payload = ActionMCP::JwtDecoder.decode(token)
+    user = User.find_by(id: payload["sub"])
+    org  = Organization.find_by(id: payload["org_id"])
+
+    raise ActionMCP::UnauthorizedError, "Unauthorized" unless user && org
+
+    { user: user, organization: org }
+  end
+end
+```
+
+### Accessing Identifiers
+Inside tools/prompts/resources:
+```ruby
+class MyTool < ApplicationMCPTool
+  def perform
+    render text: "Hi #{current_user.name} from #{current_organization.name}"
+  end
+end
+```
+`current_user` and `current_organization` are provided via `ActionMCP::Current`.
+
+## Authentication Patterns
+- **Bearer JWT (recommended):** Use `extract_bearer_token`, validate signature, resolve user/org/roles.
+- **API Key header:** Look up a key table; return identifiers; throttle invalid attempts.
+- **Session cookies:** Generally avoid—MCP traffic is not browser-oriented and runs best stateless.
+
+## Authorization vs Authentication
+- Gateway authenticates and attaches identity.  
+- Authorization should stay in tools/prompts (e.g., `authorize! current_user, :action`), because permissions depend on the specific operation.
+
+## Error Handling
+- Raise `ActionMCP::UnauthorizedError` for auth failures; include only user-safe messages.  
+- Avoid leaking reason details (e.g., “token expired”) unless you are certain they’re safe to expose.
+
+## Testing Checklist
+- Missing token → unauthorized.  
+- Invalid token → unauthorized.  
+- Valid token → identifiers set (`ActionMCP::Current.user`).  
+- Multi-tenant: ensure the correct org/tenant is bound.
+
+## Production Hardening Tips
+- Keep `authenticate!` fast (DB lookups OK; no remote HTTP).  
+- Prefer short-lived tokens; rotate signing keys.  
+- Log auth failures at warn level without secrets.  
+- Pair with `mcp_vanilla.ru` if web middleware interferes; Gateway still runs as usual.

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

app/jobs/action_mcp/tool_execution_job.rb

@@ -27,7 +27,7 @@ def perform(task_id, tool_name, arguments, meta = {})
       @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 @@ def validate_session(task)
       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 @@ def prepare_tool(session, tool_name, arguments)
           params: @task.request_params
         }
       })
+      # Enable report_progress! inside the tool during task-augmented runs
+      tool.instance_variable_set(:@_task, task)
 
       tool
     end