actionmcp 0.71.1 → 0.80.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 203f9e44a8802e007a19f41ddb89e2961fae87fb14bc0157e398dd6b80561cc3
-  data.tar.gz: d644c46fe4e73c1c5532d14f2e1541d511e4311479c15ef5d946aa135c4f290d
+  metadata.gz: ea96963047c8bb5e9fa9fd88163a14798c8780a531fa1600e3681bd92ca1b4fe
+  data.tar.gz: aae9fc897bd554fba0442735b184d9eac03a381c3b07e052869ce76ce714555d
 SHA512:
-  metadata.gz: c9472a20f2aafc0c4ac4b74d8924e741b4cb94dd69154d44b060d2a75fcc01edcda857be40611c7c24b6d1c4ee5410705b776999534c35521301fef737e57d35
-  data.tar.gz: 78afc85939383e260a89726dbc10c516a4c7da3dded794d55545c51ed98ba2179b433d402a552c1964f15a95c9e51c0e2e6ac531f18e1e145ae4a9ebe47b893e
+  metadata.gz: 47947a7bba2e39a33b1793cbf8af4a38dcf26e0eebcc19989b143d4279f8f71fc05c646169d4739dd8e52f23c2f34df5a232d4cd414e6872cc636ab4c5a22ae5
+  data.tar.gz: 8e2b06ddaf6b1174035dc3e4a6315aaf8d624ac5a096d647f252c40c533f5d20ebf02b3b8b5355d81617de98dfccf63d4342ec540558f8dbc5072043aee11c4a

data/README.md

@@ -24,7 +24,15 @@ This means an AI (like an LLM) can request information or actions from your appl
 
 ## Protocol Support
 
-ActionMCP supports **MCP 2025-06-18** (current) with backward compatibility for **MCP 2025-03-26**. For a detailed (and entertaining) breakdown of protocol versions, features, and our design decisions, see [The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md).
+ActionMCP supports **MCP 2025-06-18** (current) with backward compatibility for **MCP 2025-03-26**. The protocol implementation is fully compliant with the MCP specification, including:
+
+- **JSON-RPC 2.0** transport layer
+- **Capability negotiation** during initialization
+- **Error handling** with proper error codes (-32601 for method not found, -32002 for consent required)
+- **Session management** with resumable sessions
+- **Change notifications** for dynamic capability updates
+
+For a detailed (and entertaining) breakdown of protocol versions, features, and our design decisions, see [The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md).
 
 *Don't Panic: The guide contains everything you need to know about surviving MCP protocol versions.*
 
@@ -42,25 +50,27 @@ In short, ActionMCP helps you build an MCP server (the component that exposes ca
 
 To start using ActionMCP, add it to your project:
 
-- **Using Bundler (Rails or Ruby projects):** Add the gem to your Gemfile and run bundle install:
+```bash
+# Add gem to your Gemfile
+$ bundle add actionmcp
 
-  ```bash
-  $ bundle add actionmcp
-  ```
+# Install dependencies
+bundle install
 
-After adding the gem, run the install generator to set up the basic ActionMCP structure:
+# Copy migrations from the engine
+bin/rails action_mcp:install:migrations
 
-```bash
-bundle install
-bin/rails action_mcp:install:migrations  # Copy migrations from the engine
-bin/rails generate action_mcp:install    # Creates base classes and configuration
-bin/rails db:migrate                     # Creates necessary database tables
+# Generate base classes and configuration
+bin/rails generate action_mcp:install
+
+# Create necessary database tables
+bin/rails db:migrate
 ```
 
 The `action_mcp:install` generator will:
 - Create base application classes (ApplicationGateway, ApplicationMCPTool, etc.)
 - Generate the MCP configuration file (`config/mcp.yml`)
-- Set up the basic directory structure for MCP components
+- Set up the basic directory structure for MCP components (`app/mcp/`)
 
 Database migrations are copied separately using `bin/rails action_mcp:install:migrations`.
 
@@ -127,6 +137,7 @@ Key features:
 - Return multiple response types (text, images, errors)
 - Progressive responses with multiple render calls
 - Automatic input validation based on property definitions
+- **Consent management for sensitive operations**
 
 **Example:**
 
@@ -160,6 +171,47 @@ class CalculateSumTool < ApplicationMCPTool
 end
 ```
 
+#### Consent Management
+
+For tools that perform sensitive operations (file system access, database modifications, external API calls), you can require explicit user consent:
+
+```ruby
+class FileSystemTool < ApplicationMCPTool
+  tool_name "read_file"
+  description "Read contents of a file"
+  
+  # Require explicit consent before execution
+  requires_consent!
+
+  property :file_path, type: "string", description: "Path to file", required: true
+
+  def perform
+    # This code only runs after user grants consent
+    content = File.read(file_path)
+    render(text: "File contents: #{content}")
+  end
+end
+```
+
+**Consent Flow:**
+1. When a consent-required tool is called without consent, it returns a JSON-RPC error with code `-32002`
+2. The client must explicitly grant consent for the specific tool
+3. Once granted, the tool can execute normally for that session
+4. Consent is session-scoped and can be revoked at any time
+
+**Managing Consent:**
+
+```ruby
+# Check if consent is granted
+session.consent_granted_for?("read_file")
+
+# Grant consent for a tool
+session.grant_consent("read_file")
+
+# Revoke consent
+session.revoke_consent("read_file")
+```
+
 Tools can be executed by instantiating them and calling the `call` method:
 
 ```ruby
@@ -524,7 +576,7 @@ This will create:
 
 ActionMCP provides a Gateway system similar to ActionCable's Connection for handling authentication. The Gateway allows you to authenticate users and make them available throughout your MCP components.
 
-ActionMCP supports multiple authentication methods including OAuth 2.1, JWT tokens, and no authentication for development. For detailed OAuth 2.1 configuration and usage, see the [OAuth Authentication Guide](OAUTH.md).
+ActionMCP uses a Gateway pattern with pluggable identifiers for authentication. You can implement custom authentication strategies using session-based auth, API keys, bearer tokens, or integrate with existing authentication systems like Warden, Devise, or external OAuth providers.
 
 ### Creating an ApplicationGateway
 
@@ -751,17 +803,97 @@ class ToolTest < ActiveSupport::TestCase
 end
 ```
 
+The TestHelper provides several assertion methods:
+- `assert_tool_findable(name)` - Verifies a tool exists and is registered
+- `assert_prompt_findable(name)` - Verifies a prompt exists and is registered
+- `execute_tool(name, **args)` - Executes a tool with arguments
+- `execute_prompt(name, **args)` - Executes a prompt with arguments
+- `assert_tool_output(result, expected)` - Asserts tool output matches expected text
+- `assert_prompt_output(result)` - Extracts and returns prompt output for assertions
+
 ## Inspecting Your MCP Server
 
 You can use the MCP Inspector to test your server implementation:
 
 ```bash
-npx @modelcontextprotocol/inspector
+# Start your MCP server
+bundle exec rails s -c mcp.ru -p 62770
+
+# In another terminal, run the inspector
+npx @modelcontextprotocol/inspector --url http://localhost:62770
+```
+
+The MCP Inspector provides an interactive interface to:
+- Test tool executions with custom arguments
+- Validate prompt responses
+- Inspect resource templates and their outputs
+- Debug protocol compliance and error handling
+
+## Development Commands
+
+ActionMCP includes several rake tasks for development and debugging:
+
+```bash
+# List all MCP components
+bundle exec rails action_mcp:list
+
+# List specific component types
+bundle exec rails action_mcp:list_tools
+bundle exec rails action_mcp:list_prompts
+bundle exec rails action_mcp:list_resources
+bundle exec rails action_mcp:list_profiles
+
+# Show configuration and statistics
+bundle exec rails action_mcp:info
+bundle exec rails action_mcp:stats
+
+# Show profile configuration
+bundle exec rails action_mcp:show_profile[profile_name]
 ```
 
-The default path will be http://localhost:3000/action_mcp
+## Error Handling and Troubleshooting
+
+ActionMCP provides comprehensive error handling following the JSON-RPC 2.0 specification:
+
+### Error Codes
+
+- **-32601**: Method not found - The requested method doesn't exist
+- **-32002**: Consent required - Tool requires user consent to execute
+- **-32603**: Internal error - Server encountered an unexpected error
+- **-32600**: Invalid request - The request is malformed
+
+### Context-Aware Error Messages
 
-Here's a section you can add to explain the profile system in ActionMCP:
+Tools should return clear error messages to the LLM using the `render` method:
+
+```ruby
+class MyTool < ApplicationMCPTool
+  def perform
+    # Check for error conditions and return clear messages
+    if some_error_condition?
+      render(error: ["Clear error message for the LLM"])
+      return
+    end
+    
+    # Normal processing
+    render(text: "Success message")
+  end
+end
+```
+
+### Common Issues
+
+1. **Session not found**: Ensure sessions are properly created and saved in the session store
+2. **Tool not registered**: Verify tools are properly defined and inherit from ApplicationMCPTool
+3. **Consent required**: Grant consent using `session.grant_consent(tool_name)`
+4. **Middleware conflicts**: Use `mcp_vanilla.ru` to avoid web-specific middleware
+
+### Debugging Tips
+
+- Check server logs for detailed error information
+- Use `bundle exec rails action_mcp:info` to verify configuration
+- Test with MCP Inspector to isolate protocol issues
+- Ensure proper session management in production environments
 
 ## Profiles
 
@@ -875,3 +1007,42 @@ Profiles are particularly useful for:
 5. **Progressive enhancement**: Start with a minimal profile and gradually add capabilities
 
 By leveraging profiles, you can maintain a single ActionMCP codebase while providing tailored MCP capabilities for different contexts.
+
+## Client Usage
+
+ActionMCP includes a client for connecting to remote MCP servers. The client handles session management, protocol negotiation, and provides a simple API for interacting with MCP servers.
+
+For comprehensive client documentation, including examples, session management, transport configuration, and API usage, see [CLIENTUSAGE.md](CLIENTUSAGE.md).
+
+## Production Considerations
+
+### Security
+
+- **Never expose sensitive data** through MCP components
+- **Use authentication** via Gateway for production deployments
+- **Implement proper authorization** in your tools and prompts
+- **Validate all inputs** using property definitions and Rails validations
+- **Use consent management** for sensitive operations
+
+### Performance
+
+- **Configure appropriate thread pools** for high-traffic scenarios
+- **Use Redis or SolidMCP** for production pub/sub
+- **Choose ActiveRecord session store** for session persistence
+- **Monitor session cleanup** to prevent memory leaks
+- **Use profiles** to limit exposed capabilities
+
+### Monitoring
+
+- **Enable logging** and configure appropriate log levels
+- **Monitor session statistics** using `action_mcp:stats`
+- **Track tool usage** and performance metrics
+- **Set up alerts** for error rates and response times
+
+### Deployment
+
+- **Use Falcon** for optimal performance with streaming workloads
+- **Deploy on dedicated ports** or Unix sockets
+- **Use reverse proxies** (Nginx, Apache) for SSL termination
+- **Implement health checks** for your MCP endpoints
+- **Use `mcp_vanilla.ru`** to avoid middleware conflicts

data/app/controllers/action_mcp/application_controller.rb

@@ -12,7 +12,6 @@ module ActionMCP
     include ActionController::Live
     include ActionController::Instrumentation
 
-
     # Provides the ActionMCP::Session for the current request.
     # Handles finding existing sessions via header/param or initializing a new one.
     # Specific controllers/handlers might need to enforce session ID presence based on context.
@@ -29,7 +28,9 @@ module ActionMCP
     end
 
     # Handles GET requests for establishing server-initiated SSE streams (2025-03-26 spec).
-    # @route GET /
+    # <rails-lens:routes:begin>
+    # ROUTE: /, name: mcp_get, via: GET
+    # <rails-lens:routes:end>
     def show
       unless request.accepts.any? { |type| type.to_s == "text/event-stream" }
         return render_not_acceptable("Client must accept 'text/event-stream' for GET requests.")
@@ -52,7 +53,9 @@ module ActionMCP
       return if performed?
 
       last_event_id = request.headers["Last-Event-ID"].presence
-      Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}" if last_event_id && ActionMCP.configuration.verbose_logging
+      if last_event_id && ActionMCP.configuration.verbose_logging
+        Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}"
+      end
 
       response.headers["Content-Type"] = "text/event-stream"
       response.headers["X-Accel-Buffering"] = "no"
@@ -61,7 +64,9 @@ module ActionMCP
       # Add MCP-Protocol-Version header for established sessions
       response.headers["MCP-Protocol-Version"] = session.protocol_version
 
-      Rails.logger.info "Unified SSE (GET): Starting stream for session: #{session.id}" if ActionMCP.configuration.verbose_logging
+      if ActionMCP.configuration.verbose_logging
+        Rails.logger.info "Unified SSE (GET): Starting stream for session: #{session.id}"
+      end
 
       sse = SSE.new(response.stream)
       listener = SSEListener.new(session)
@@ -85,12 +90,16 @@ module ActionMCP
         begin
           missed_events = session.get_sse_events_after(last_event_id.to_i)
           if missed_events.any?
-            Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}" if ActionMCP.configuration.verbose_logging
+            if ActionMCP.configuration.verbose_logging
+              Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}"
+            end
             missed_events.each do |event|
               sse.write(event.to_sse)
             end
-          else
-            Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}" if ActionMCP.configuration.verbose_logging
+          elsif ActionMCP.configuration.verbose_logging
+            if ActionMCP.configuration.verbose_logging
+              Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}"
+            end
           end
         rescue StandardError => e
           Rails.logger.error "Unified SSE (GET): Error sending missed events: #{e.message}"
@@ -116,7 +125,9 @@ module ActionMCP
             Rails.logger.warn "Unified SSE (GET): Heartbeat timed out for session: #{session.id}, closing."
             connection_active.make_false
           rescue StandardError => e
-            Rails.logger.debug "Unified SSE (GET): Heartbeat error for session: #{session.id}: #{e.message}" if ActionMCP.configuration.verbose_logging
+            if ActionMCP.configuration.verbose_logging
+              Rails.logger.debug "Unified SSE (GET): Heartbeat error for session: #{session.id}: #{e.message}"
+            end
             connection_active.make_false
           end
         else
@@ -127,11 +138,15 @@ module ActionMCP
       heartbeat_task = Concurrent::ScheduledTask.execute(heartbeat_interval, &heartbeat_sender)
       sleep 0.1 while connection_active.true? && !response.stream.closed?
     rescue ActionController::Live::ClientDisconnected, IOError => e
-      Rails.logger.debug "Unified SSE (GET): Client disconnected for session: #{session&.id}: #{e.message}" if ActionMCP.configuration.verbose_logging
+      if ActionMCP.configuration.verbose_logging
+        Rails.logger.debug "Unified SSE (GET): Client disconnected for session: #{session&.id}: #{e.message}"
+      end
     rescue StandardError => e
       Rails.logger.error "Unified SSE (GET): Unexpected error for session: #{session&.id}: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
     ensure
-      Rails.logger.debug "Unified SSE (GET): Cleaning up connection for session: #{session&.id}" if ActionMCP.configuration.verbose_logging
+      if ActionMCP.configuration.verbose_logging
+        Rails.logger.debug "Unified SSE (GET): Cleaning up connection for session: #{session&.id}"
+      end
       heartbeat_active&.make_false
       heartbeat_task&.cancel
       listener&.stop
@@ -145,7 +160,9 @@ module ActionMCP
     end
 
     # Handles POST requests containing client JSON-RPC messages according to 2025-03-26 spec.
-    # @route POST /mcp
+    # <rails-lens:routes:begin>
+    # ROUTE: /, name: mcp_post, via: POST
+    # <rails-lens:routes:end>
     def create
       unless post_accept_headers_valid?
         id = extract_jsonrpc_id_from_request
@@ -153,9 +170,7 @@ module ActionMCP
       end
 
       # Reject JSON-RPC batch requests as per MCP 2025-06-18 spec
-      if jsonrpc_params_batch?
-        return render_bad_request("JSON-RPC batch requests are not supported", nil)
-      end
+      return render_bad_request("JSON-RPC batch requests are not supported", nil) if jsonrpc_params_batch?
 
       is_initialize_request = check_if_initialize_request(jsonrpc_params)
       session_initially_missing = extract_session_id.nil?
@@ -197,7 +212,9 @@ module ActionMCP
       result = json_rpc_handler.call(jsonrpc_params)
       process_handler_results(result, session, session_initially_missing, is_initialize_request)
     rescue ActionController::Live::ClientDisconnected, IOError => e
-      Rails.logger.debug "Unified SSE (POST): Client disconnected during response: #{e.message}" if ActionMCP.configuration.verbose_logging
+      if ActionMCP.configuration.verbose_logging
+        Rails.logger.debug "Unified SSE (POST): Client disconnected during response: #{e.message}"
+      end
       begin
         response.stream&.close
       rescue StandardError
@@ -205,12 +222,18 @@ module ActionMCP
       end
     rescue StandardError => e
       Rails.logger.error "Unified POST Error: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
-      id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil rescue nil
+      id = begin
+        jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
+      rescue StandardError
+        nil
+      end
       render_internal_server_error("An unexpected error occurred.", id) unless performed?
     end
 
     # Handles DELETE requests for session termination (2025-03-26 spec).
-    # @route DELETE /
+    # <rails-lens:routes:begin>
+    # ROUTE: /, name: mcp_delete, via: DELETE
+    # <rails-lens:routes:end>
     def destroy
       session_id_from_header = extract_session_id
       return render_bad_request("Mcp-Session-Id header is required for DELETE requests.") unless session_id_from_header
@@ -255,9 +278,7 @@ module ActionMCP
       end
 
       # Handle array values (take the last one as per TypeScript SDK)
-      if header_version.is_a?(Array)
-        header_version = header_version.last
-      end
+      header_version = header_version.last if header_version.is_a?(Array)
 
       # Check if the header version is supported
       unless ActionMCP::SUPPORTED_VERSIONS.include?(header_version)
@@ -268,7 +289,7 @@ module ActionMCP
       end
 
       # If we have an initialized session, check if the header matches the negotiated version
-      if session && session.initialized?
+      if session&.initialized?
         negotiated_version = session.protocol_version
         if header_version != negotiated_version
           ActionMCP.logger.warn "MCP-Protocol-Version mismatch: header=#{header_version}, negotiated=#{negotiated_version}"
@@ -340,9 +361,7 @@ module ActionMCP
     # Processes the results from the JsonRpcHandler.
     def process_handler_results(result, session, session_initially_missing, is_initialize_request)
       # Handle empty result (notifications)
-      if result.nil?
-        return head :accepted
-      end
+      return head :accepted if result.nil?
 
       # Convert to hash for rendering
       payload = if result.respond_to?(:to_h)
@@ -369,9 +388,7 @@ module ActionMCP
     def render_json_response(payload, session, add_session_header)
       response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
       # Add MCP-Protocol-Version header if session has been initialized
-      if session && session.initialized?
-        response.headers["MCP-Protocol-Version"] = session.protocol_version
-      end
+      response.headers["MCP-Protocol-Version"] = session.protocol_version if session&.initialized?
       response.headers["Content-Type"] = "application/json"
       render json: payload, status: :ok
     end
@@ -380,9 +397,7 @@ module ActionMCP
     def render_sse_response(payload, session, add_session_header)
       response.headers[MCP_SESSION_ID_HEADER] = session.id if add_session_header
       # Add MCP-Protocol-Version header if session has been initialized
-      if session && session.initialized?
-        response.headers["MCP-Protocol-Version"] = session.protocol_version
-      end
+      response.headers["MCP-Protocol-Version"] = session.protocol_version if session&.initialized?
       response.headers["Content-Type"] = "text/event-stream"
       response.headers["X-Accel-Buffering"] = "no"
       response.headers["Cache-Control"] = "no-cache"
@@ -425,13 +440,13 @@ module ActionMCP
 
     # Helper to clean up old SSE events for a session
     def cleanup_old_sse_events(session)
-      begin
-        retention_period = session.sse_event_retention_period
-        count = session.cleanup_old_sse_events(retention_period)
-        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}" if count.positive? && ActionMCP.configuration.verbose_logging
-      rescue StandardError => e
-        Rails.logger.error "Error cleaning up old SSE events: #{e.message}"
+      retention_period = session.sse_event_retention_period
+      count = session.cleanup_old_sse_events(retention_period)
+      if count.positive? && ActionMCP.configuration.verbose_logging
+        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}"
       end
+    rescue StandardError => e
+      Rails.logger.error "Error cleaning up old SSE events: #{e.message}"
     end
 
     def format_tools_list(tools, session)
@@ -505,30 +520,30 @@ module ActionMCP
     # Authenticates the request using the configured gateway
     def authenticate_gateway!
       # Skip authentication for initialization-related requests in POST method
-      if request.post? && defined?(jsonrpc_params) && jsonrpc_params
-        return if initialization_related_request?(jsonrpc_params)
+      if request.post? && defined?(jsonrpc_params) && jsonrpc_params && initialization_related_request?(jsonrpc_params)
+        return
       end
 
       gateway_class = ActionMCP.configuration.gateway_class
       return unless gateway_class # Skip if no gateway configured
 
-      gateway = gateway_class.new(request)
-      gateway.call
-    rescue ActionMCP::UnauthorizedError => e
-      render_unauthorized(e.message)
+      begin
+        gateway = gateway_class.new(request)
+        gateway.call
+      rescue ActionMCP::UnauthorizedError => e
+        render_unauthorized(e.message)
+      rescue StandardError => e
+        Rails.logger.error "Gateway authentication error: #{e.class} - #{e.message}"
+        render_unauthorized("Authentication system error")
+      end
     end
 
     # Renders an unauthorized response
     def render_unauthorized(message = "Unauthorized", id = nil)
       id ||= extract_jsonrpc_id_from_request
 
-      # Add WWW-Authenticate header for OAuth discovery as per spec
-      auth_methods = ActionMCP.configuration.authentication_methods || []
-      if auth_methods.include?("oauth")
-        response.headers["WWW-Authenticate"] = 'Bearer realm="MCP API"'
-      end
-
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }, status: :unauthorized
+      # Return JSON-RPC error with 200 status as per MCP specification
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }
     end
   end
 end

data/app/models/action_mcp/session/message.rb

@@ -1,29 +1,40 @@
 # frozen_string_literal: true
 
-# == Schema Information
+# <rails-lens:schema:begin>
+# table = "action_mcp_session_messages"
+# database_dialect = "SQLite"
 #
-# Table name: action_mcp_session_messages
+# columns = [
+#   { name = "id", type = "integer", primary_key = true, nullable = false },
+#   { name = "session_id", type = "string", nullable = false },
+#   { name = "direction", type = "string", nullable = false, default = "client" },
+#   { name = "message_type", type = "string", nullable = false },
+#   { name = "jsonrpc_id", type = "string", nullable = true },
+#   { name = "message_json", type = "json", nullable = true },
+#   { name = "is_ping", type = "boolean", nullable = false, default = "0" },
+#   { name = "request_acknowledged", type = "boolean", nullable = false, default = "0" },
+#   { name = "request_cancelled", type = "boolean", nullable = false, default = "0" },
+#   { name = "created_at", type = "datetime", nullable = false },
+#   { name = "updated_at", type = "datetime", nullable = false }
+# ]
 #
-#  id                   :integer          not null, primary key
-#  direction            :string           default("client"), not null
-#  is_ping              :boolean          default(FALSE), not null
-#  message_json         :json
-#  message_type         :string           not null
-#  request_acknowledged :boolean          default(FALSE), not null
-#  request_cancelled    :boolean          default(FALSE), not null
-#  created_at           :datetime         not null
-#  updated_at           :datetime         not null
-#  jsonrpc_id           :string
-#  session_id           :string           not null
+# indexes = [
+#   { name = "index_action_mcp_session_messages_on_session_id", columns = ["session_id"] }
+# ]
 #
-# Indexes
-#
-#  index_action_mcp_session_messages_on_session_id  (session_id)
-#
-# Foreign Keys
-#
-#  session_id  (session_id => action_mcp_sessions.id) ON DELETE => cascade ON UPDATE => cascade
+# foreign_keys = [
+#   { column = "session_id", references_table = "action_mcp_sessions", references_column = "id", on_delete = "cascade", on_update = "cascade" }
+# ]
 #
+# == Notes
+# - Column 'message_json' should probably have NOT NULL constraint
+# - String column 'session_id' has no length limit - consider adding one
+# - String column 'direction' has no length limit - consider adding one
+# - String column 'message_type' has no length limit - consider adding one
+# - String column 'jsonrpc_id' has no length limit - consider adding one
+# - Column 'message_type' is commonly used in queries - consider adding an index
+# - Column 'is_ping' uses non-conventional prefix - consider removing 'is_' or 'has_'
+# <rails-lens:schema:end>
 module ActionMCP
   class Session
     #

data/app/models/action_mcp/session/resource.rb

@@ -1,29 +1,44 @@
 # frozen_string_literal: true
 
-# == Schema Information
+# <rails-lens:schema:begin>
+# table = "action_mcp_session_resources"
+# database_dialect = "SQLite"
 #
-# Table name: action_mcp_session_resources
+# columns = [
+#   { name = "id", type = "integer", primary_key = true, nullable = false },
+#   { name = "session_id", type = "string", nullable = false },
+#   { name = "uri", type = "string", nullable = false },
+#   { name = "name", type = "string", nullable = true },
+#   { name = "description", type = "text", nullable = true },
+#   { name = "mime_type", type = "string", nullable = false },
+#   { name = "created_by_tool", type = "boolean", nullable = true, default = "0" },
+#   { name = "last_accessed_at", type = "datetime", nullable = true },
+#   { name = "metadata", type = "json", nullable = true },
+#   { name = "created_at", type = "datetime", nullable = false },
+#   { name = "updated_at", type = "datetime", nullable = false }
+# ]
 #
-#  id               :integer          not null, primary key
-#  created_by_tool  :boolean          default(FALSE)
-#  description      :text
-#  last_accessed_at :datetime
-#  metadata         :json
-#  mime_type        :string           not null
-#  name             :string
-#  uri              :string           not null
-#  created_at       :datetime         not null
-#  updated_at       :datetime         not null
-#  session_id       :string           not null
+# indexes = [
+#   { name = "index_action_mcp_session_resources_on_session_id", columns = ["session_id"] }
+# ]
 #
-# Indexes
-#
-#  index_action_mcp_session_resources_on_session_id  (session_id)
-#
-# Foreign Keys
-#
-#  session_id  (session_id => action_mcp_sessions.id) ON DELETE => cascade
+# foreign_keys = [
+#   { column = "session_id", references_table = "action_mcp_sessions", references_column = "id", on_delete = "cascade" }
+# ]
 #
+# == Notes
+# - Association 'session' should specify inverse_of
+# - Column 'name' should probably have NOT NULL constraint
+# - Column 'description' should probably have NOT NULL constraint
+# - Column 'created_by_tool' should probably have NOT NULL constraint
+# - Column 'metadata' should probably have NOT NULL constraint
+# - String column 'session_id' has no length limit - consider adding one
+# - String column 'uri' has no length limit - consider adding one
+# - String column 'name' has no length limit - consider adding one
+# - String column 'mime_type' has no length limit - consider adding one
+# - Large text column 'description' is frequently queried - consider separate storage
+# - Column 'mime_type' is commonly used in queries - consider adding an index
+# <rails-lens:schema:end>
 module ActionMCP
   class Session
     #