actionmcp 0.52.2 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a11c68a5511cb3cafd2f90ae24aa31e2099f41c8b4ee3d357719574f598752d4
-  data.tar.gz: 145398e069f03f6bd2697a16efca476d47983ccdcf84f3730f9ea0b0223eec03
+  metadata.gz: 8f3d6323b7f8ce694050a031c566f30e33d637116e2869cda61fbbaad0702411
+  data.tar.gz: ef8bfccea1b3109146b3e490340a44c4a6071e08c6aed3bd72ddecd5fd95638a
 SHA512:
-  metadata.gz: 9bb02d28a5b99c70bde877ab7e481619c26d55f68b47fbebc40e384400fc445c4683e04e35ac6bc9f837028bb5af9ec84928662fb8fd93e80e3a7bcec446e6ad
-  data.tar.gz: 78c11ff2bc200f7a482ffefc516b2ab2ad487399b37685d3fe49cd907de6b1e6a3aafd891ea584b3b2387c4567c4d58c1ed9db5d6aaca35b065ac613f505c4d8
+  metadata.gz: 2665d85224ce5b07a115936d1f1d159b70c8068a8a221e2f196bebd9564b9e753a73acd15b86241b04d277e70dc6dc5db818fecda505cfab9beb999d8483aecb
+  data.tar.gz: 56a568c5aca9693534a46d1013a9fdd8cb168a92e10b6c947dc02bb345f0c0a4f5b812edac990ddaa84c0ba589c500d47b7841f22b8542b1f36a120d2c8a1756

data/README.md

@@ -476,16 +476,21 @@ This ensures all thread pools are properly terminated and tasks are completed.
 
 **ActionMCP** runs as a standalone Rack application. **Do not attempt to mount it in your application's `routes.rb`**—it is not designed to be mounted as an engine at a custom path. When you use `run ActionMCP::Engine` in your `mcp.ru`, the MCP endpoint is always available at the root path (`/`).
 
-### Installing the Configuration Generator
+### Installing ActionMCP
 
-ActionMCP includes a generator to help you create the configuration file:
+ActionMCP includes generators to help you set up your project quickly. The install generator creates all necessary base classes and configuration files:
 
 ```bash
-# Generate the mcp.yml configuration file
-bin/rails generate action_mcp:config
+# Install ActionMCP with base classes and configuration
+bin/rails generate action_mcp:install
 ```
 
-This will create `config/mcp.yml` with example configurations for all environments.
+This will create:
+- `app/mcp/prompts/application_mcp_prompt.rb` - Base prompt class
+- `app/mcp/tools/application_mcp_tool.rb` - Base tool class  
+- `app/mcp/resource_templates/application_mcp_res_template.rb` - Base resource template class
+- `app/mcp/application_gateway.rb` - Gateway for authentication
+- `config/mcp.yml` - Configuration file with example settings for all environments
 
 > **Note:** Authentication and authorization are not included. You are responsible for securing the endpoint.
 
@@ -493,6 +498,8 @@ This will create `config/mcp.yml` with example configurations for all environmen
 
 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).
+
 ### Creating an ApplicationGateway
 
 When you run the install generator, it creates an `ApplicationGateway` class:
@@ -645,14 +652,14 @@ location /mcp/ {
 
 ActionMCP includes Rails generators to help you quickly set up your MCP server components.
 
-You can generate the base classes for your MCP Prompt and Tool using the following command:
+First, install ActionMCP to create base classes and configuration:
 
 ```bash
 bin/rails action_mcp:install:migrations  # to copy the migrations
 bin/rails generate action_mcp:install 
 ```
 
-This will create the base application classes in your app directory.
+This will create the base application classes, configuration file, and authentication gateway in your app directory.
 
 ### Generate a New Prompt
 

data/app/controllers/action_mcp/oauth/endpoints_controller.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module ActionMCP
+  module OAuth
+    # OAuth 2.1 endpoints controller
+    # Handles authorization, token, introspection, and revocation endpoints
+    class EndpointsController < ActionController::Base
+      protect_from_forgery with: :null_session
+      before_action :check_oauth_enabled
+
+      # GET /oauth/authorize
+      # Authorization endpoint for OAuth 2.1 authorization code flow
+      def authorize
+        # Extract parameters
+        client_id = params[:client_id]
+        redirect_uri = params[:redirect_uri]
+        response_type = params[:response_type]
+        scope = params[:scope]
+        state = params[:state]
+        code_challenge = params[:code_challenge]
+        code_challenge_method = params[:code_challenge_method]
+
+        # Validate required parameters
+        if client_id.blank? || redirect_uri.blank? || response_type.blank?
+          return render_error("invalid_request", "Missing required parameters")
+        end
+
+        # Validate response type
+        unless response_type == "code"
+          return render_error("unsupported_response_type", "Only authorization code flow supported")
+        end
+
+        # Validate PKCE if required
+        if oauth_config["pkce_required"] && code_challenge.blank?
+          return render_error("invalid_request", "PKCE required")
+        end
+
+        # In a real implementation, this would show a consent page
+        # For now, we'll auto-approve for configured clients
+        if auto_approve_client?(client_id)
+          # Generate authorization code
+          user_id = current_user&.id || "anonymous"
+
+          begin
+            code = ActionMCP::OAuth::Provider.generate_authorization_code(
+              client_id: client_id,
+              redirect_uri: redirect_uri,
+              scope: scope || default_scope,
+              code_challenge: code_challenge,
+              code_challenge_method: code_challenge_method,
+              user_id: user_id
+            )
+
+            # Redirect back to client with authorization code
+            redirect_params = { code: code }
+            redirect_params[:state] = state if state
+            redirect_to "#{redirect_uri}?#{redirect_params.to_query}", allow_other_host: true
+          rescue ActionMCP::OAuth::Error => e
+            render_error(e.oauth_error_code, e.message)
+          end
+        else
+          # In production, show consent page
+          render_consent_page(client_id, redirect_uri, scope, state, code_challenge, code_challenge_method)
+        end
+      end
+
+      # POST /oauth/token
+      # Token endpoint for exchanging authorization codes and refreshing tokens
+      def token
+        grant_type = params[:grant_type]
+
+        case grant_type
+        when "authorization_code"
+          handle_authorization_code_grant
+        when "refresh_token"
+          handle_refresh_token_grant
+        when "client_credentials"
+          handle_client_credentials_grant
+        else
+          render_token_error("unsupported_grant_type", "Unsupported grant type")
+        end
+      rescue ActionMCP::OAuth::Error => e
+        render_token_error(e.oauth_error_code, e.message)
+      end
+
+      # POST /oauth/introspect
+      # Token introspection endpoint (RFC 7662)
+      def introspect
+        token = params[:token]
+        return render_introspection_error unless token
+
+        # Authenticate client for introspection
+        client_id, client_secret = extract_client_credentials
+        return render_introspection_error unless client_id
+
+        begin
+          token_info = ActionMCP::OAuth::Provider.introspect_token(token)
+          render json: token_info
+        rescue ActionMCP::OAuth::Error
+          render json: { active: false }
+        end
+      end
+
+      # POST /oauth/revoke
+      # Token revocation endpoint (RFC 7009)
+      def revoke
+        token = params[:token]
+        token_type_hint = params[:token_type_hint]
+
+        return head :bad_request unless token
+
+        # Authenticate client
+        client_id, client_secret = extract_client_credentials
+        return head :unauthorized unless client_id
+
+        begin
+          ActionMCP::OAuth::Provider.revoke_token(token, token_type_hint: token_type_hint)
+          head :ok
+        rescue ActionMCP::OAuth::Error
+          head :bad_request
+        end
+      end
+
+      private
+
+      def check_oauth_enabled
+        auth_methods = ActionMCP.configuration.authentication_methods
+        unless auth_methods&.include?("oauth")
+          head :not_found
+        end
+      end
+
+      def oauth_config
+        @oauth_config ||= ActionMCP.configuration.oauth_config || {}
+      end
+
+      def handle_authorization_code_grant
+        code = params[:code]
+        client_id = params[:client_id]
+        client_secret = params[:client_secret]
+        redirect_uri = params[:redirect_uri]
+        code_verifier = params[:code_verifier]
+
+        # Extract client credentials from Authorization header if not in params
+        if client_id.blank?
+          client_id, client_secret = extract_client_credentials
+        end
+
+        return render_token_error("invalid_request", "Missing required parameters") if code.blank? || client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.exchange_code_for_token(
+          code: code,
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          code_verifier: code_verifier
+        )
+
+        render json: token_response
+      end
+
+      def handle_refresh_token_grant
+        refresh_token = params[:refresh_token]
+        scope = params[:scope]
+
+        # Extract client credentials
+        client_id, client_secret = extract_client_credentials
+        client_id ||= params[:client_id]
+        client_secret ||= params[:client_secret]
+
+        return render_token_error("invalid_request", "Missing required parameters") if refresh_token.blank? || client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.refresh_access_token(
+          refresh_token: refresh_token,
+          client_id: client_id,
+          client_secret: client_secret,
+          scope: scope
+        )
+
+        render json: token_response
+      end
+
+      def handle_client_credentials_grant
+        scope = params[:scope]
+
+        # Extract client credentials
+        client_id, client_secret = extract_client_credentials
+        client_id ||= params[:client_id]
+        client_secret ||= params[:client_secret]
+
+        return render_token_error("invalid_request", "Missing client credentials") if client_id.blank?
+
+        token_response = ActionMCP::OAuth::Provider.client_credentials_grant(
+          client_id: client_id,
+          client_secret: client_secret,
+          scope: scope
+        )
+
+        render json: token_response
+      end
+
+      def extract_client_credentials
+        auth_header = request.headers["Authorization"]
+        if auth_header&.start_with?("Basic ")
+          encoded = auth_header.split(" ", 2).last
+          decoded = Base64.decode64(encoded)
+          decoded.split(":", 2)
+        else
+          [ nil, nil ]
+        end
+      end
+
+      def auto_approve_client?(client_id)
+        # In development/testing, auto-approve known clients
+        # In production, this should check a proper client registry
+        Rails.env.development? || Rails.env.test? || oauth_config["auto_approve_clients"]&.include?(client_id)
+      end
+
+      def current_user
+        # This should be implemented by the application
+        # For now, return a default user for development
+        if Rails.env.development? || Rails.env.test?
+          OpenStruct.new(id: "dev_user", email: "dev@example.com")
+        else
+          # In production, this should integrate with your authentication system
+          nil
+        end
+      end
+
+      def default_scope
+        oauth_config["default_scope"] || "mcp:tools mcp:resources mcp:prompts"
+      end
+
+      def render_error(error_code, description)
+        render json: {
+          error: error_code,
+          error_description: description
+        }, status: :bad_request
+      end
+
+      def render_token_error(error_code, description)
+        render json: {
+          error: error_code,
+          error_description: description
+        }, status: :bad_request
+      end
+
+      def render_introspection_error
+        render json: { active: false }, status: :bad_request
+      end
+
+      def render_consent_page(client_id, redirect_uri, scope, state, code_challenge, code_challenge_method)
+        # In production, this would render a proper consent page
+        # For now, just auto-deny unknown clients
+        render json: {
+          error: "access_denied",
+          error_description: "User denied authorization"
+        }, status: :forbidden
+      end
+    end
+  end
+end

data/app/controllers/action_mcp/oauth/metadata_controller.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module OAuth
+    # Controller for OAuth 2.1 metadata endpoints
+    # Provides server discovery information as per RFC 8414
+    class MetadataController < ActionController::Base
+      before_action :check_oauth_enabled
+
+      # GET /.well-known/oauth-authorization-server
+      # Returns OAuth Authorization Server Metadata as per RFC 8414
+      def authorization_server
+        metadata = {
+          issuer: issuer_url,
+          authorization_endpoint: authorization_endpoint,
+          token_endpoint: token_endpoint,
+          introspection_endpoint: introspection_endpoint,
+          revocation_endpoint: revocation_endpoint,
+          response_types_supported: response_types_supported,
+          grant_types_supported: grant_types_supported,
+          token_endpoint_auth_methods_supported: token_endpoint_auth_methods_supported,
+          scopes_supported: scopes_supported,
+          code_challenge_methods_supported: code_challenge_methods_supported,
+          service_documentation: service_documentation
+        }
+
+        # Add optional fields based on configuration
+        if oauth_config["enable_dynamic_registration"]
+          metadata[:registration_endpoint] = registration_endpoint
+        end
+
+        if oauth_config["jwks_uri"]
+          metadata[:jwks_uri] = oauth_config["jwks_uri"]
+        end
+
+        render json: metadata
+      end
+
+      # GET /.well-known/oauth-protected-resource
+      # Returns Protected Resource Metadata as per RFC 8705
+      def protected_resource
+        metadata = {
+          resource: issuer_url,
+          authorization_servers: [ issuer_url ],
+          scopes_supported: scopes_supported,
+          bearer_methods_supported: [ "header" ],
+          resource_documentation: resource_documentation
+        }
+
+        render json: metadata
+      end
+
+      private
+
+      def check_oauth_enabled
+        auth_methods = ActionMCP.configuration.authentication_methods
+        unless auth_methods&.include?("oauth")
+          head :not_found
+        end
+      end
+
+      def oauth_config
+        @oauth_config ||= ActionMCP.configuration.oauth_config || {}
+      end
+
+      def issuer_url
+        @issuer_url ||= oauth_config["issuer_url"] || request.base_url
+      end
+
+      def authorization_endpoint
+        "#{issuer_url}/oauth/authorize"
+      end
+
+      def token_endpoint
+        "#{issuer_url}/oauth/token"
+      end
+
+      def introspection_endpoint
+        "#{issuer_url}/oauth/introspect"
+      end
+
+      def revocation_endpoint
+        "#{issuer_url}/oauth/revoke"
+      end
+
+      def registration_endpoint
+        "#{issuer_url}/oauth/register"
+      end
+
+      def response_types_supported
+        [ "code" ]
+      end
+
+      def grant_types_supported
+        grants = [ "authorization_code" ]
+        grants << "refresh_token" if oauth_config["enable_refresh_tokens"]
+        grants << "client_credentials" if oauth_config["enable_client_credentials"]
+        grants
+      end
+
+      def token_endpoint_auth_methods_supported
+        methods = [ "client_secret_basic", "client_secret_post" ]
+        methods << "none" if oauth_config["allow_public_clients"]
+        methods
+      end
+
+      def scopes_supported
+        oauth_config["scopes_supported"] || [ "mcp:tools", "mcp:resources", "mcp:prompts" ]
+      end
+
+      def code_challenge_methods_supported
+        methods = []
+        if oauth_config["pkce_required"] || oauth_config["pkce_supported"]
+          methods << "S256"
+          methods << "plain" if oauth_config["allow_plain_pkce"]
+        end
+        methods
+      end
+
+      def service_documentation
+        oauth_config["service_documentation"] || "#{request.base_url}/docs"
+      end
+
+      def resource_documentation
+        oauth_config["resource_documentation"] || "#{request.base_url}/docs/api"
+      end
+    end
+  end
+end

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

@@ -4,17 +4,17 @@
 #
 # Table name: action_mcp_session_messages
 #
-#  id                                     :bigint           not null, primary key
-#  direction(The message recipient)       :string           default("client"), not null
-#  is_ping(Whether the message is a ping) :boolean          default(FALSE), not null
-#  message_json                           :jsonb
-#  message_type(The type of the message)  :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
+#  id                   :bigint           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
 #
@@ -22,7 +22,7 @@
 #
 # Foreign Keys
 #
-#  fk_action_mcp_session_messages_session_id  (session_id => action_mcp_sessions.id) ON DELETE => cascade ON UPDATE => cascade
+#  fk_rails_...  (session_id => action_mcp_sessions.id) ON DELETE => cascade ON UPDATE => cascade
 #
 module ActionMCP
   class Session

data/app/models/action_mcp/session.rb

@@ -4,23 +4,34 @@
 #
 # Table name: action_mcp_sessions
 #
-#  id                                                  :string           not null, primary key
-#  client_capabilities(The capabilities of the client) :jsonb
-#  client_info(The information about the client)       :jsonb
-#  ended_at(The time the session ended)                :datetime
-#  initialized                                         :boolean          default(FALSE), not null
-#  messages_count                                      :integer          default(0), not null
-#  prompt_registry                                     :jsonb
-#  protocol_version                                    :string
-#  resource_registry                                   :jsonb
-#  role(The role of the session)                       :string           default("server"), not null
-#  server_capabilities(The capabilities of the server) :jsonb
-#  server_info(The information about the server)       :jsonb
-#  sse_event_counter                                   :integer          default(0), not null
-#  status                                              :string           default("pre_initialize"), not null
-#  tool_registry                                       :jsonb
-#  created_at                                          :datetime         not null
-#  updated_at                                          :datetime         not null
+#  id                     :string           not null, primary key
+#  authentication_method  :string           default("none")
+#  client_capabilities    :json
+#  client_info            :json
+#  ended_at               :datetime
+#  initialized            :boolean          default(FALSE), not null
+#  messages_count         :integer          default(0), not null
+#  oauth_access_token     :string
+#  oauth_refresh_token    :string
+#  oauth_token_expires_at :datetime
+#  oauth_user_context     :json
+#  prompt_registry        :json
+#  protocol_version       :string
+#  resource_registry      :json
+#  role                   :string           default("server"), not null
+#  server_capabilities    :json
+#  server_info            :json
+#  sse_event_counter      :integer          default(0), not null
+#  status                 :string           default("pre_initialize"), not null
+#  tool_registry          :json
+#  created_at             :datetime         not null
+#  updated_at             :datetime         not null
+#
+# Indexes
+#
+#  index_action_mcp_sessions_on_authentication_method   (authentication_method)
+#  index_action_mcp_sessions_on_oauth_access_token      (oauth_access_token) UNIQUE
+#  index_action_mcp_sessions_on_oauth_token_expires_at  (oauth_token_expires_at)
 #
 module ActionMCP
   ##
@@ -323,6 +334,94 @@ module ActionMCP
       end
     end
 
+    # OAuth Session Management
+    # Required by MCP 2025-03-26 specification for session binding
+
+    # Store OAuth token and user context in session
+    def store_oauth_token(access_token:, refresh_token: nil, expires_at:, user_context: {})
+      update!(
+        oauth_access_token: access_token,
+        oauth_refresh_token: refresh_token,
+        oauth_token_expires_at: expires_at,
+        oauth_user_context: user_context,
+        authentication_method: "oauth"
+      )
+    end
+
+    # Retrieve OAuth token information
+    def oauth_token_info
+      return nil unless oauth_access_token
+
+      {
+        access_token: oauth_access_token,
+        refresh_token: oauth_refresh_token,
+        expires_at: oauth_token_expires_at,
+        user_context: oauth_user_context || {},
+        authentication_method: authentication_method
+      }
+    end
+
+    # Check if OAuth token is valid and not expired
+    def oauth_token_valid?
+      return false unless oauth_access_token
+      return true unless oauth_token_expires_at
+
+      oauth_token_expires_at > Time.current
+    end
+
+    # Clear OAuth token data
+    def clear_oauth_token!
+      update!(
+        oauth_access_token: nil,
+        oauth_refresh_token: nil,
+        oauth_token_expires_at: nil,
+        oauth_user_context: nil,
+        authentication_method: "none"
+      )
+    end
+
+    # Update OAuth token (for refresh flow)
+    def update_oauth_token(access_token:, refresh_token: nil, expires_at:)
+      update!(
+        oauth_access_token: access_token,
+        oauth_refresh_token: refresh_token,
+        oauth_token_expires_at: expires_at
+      )
+    end
+
+    # Get user information from OAuth context
+    def oauth_user
+      return nil unless oauth_user_context.is_a?(Hash)
+
+      OpenStruct.new(oauth_user_context)
+    end
+
+    # Check if session is authenticated via OAuth
+    def oauth_authenticated?
+      authentication_method == "oauth" && oauth_token_valid?
+    end
+
+    # Find session by OAuth access token (class method)
+    def self.find_by_oauth_token(access_token)
+      find_by(oauth_access_token: access_token)
+    end
+
+    # Find sessions with expired OAuth tokens (class method)
+    def self.with_expired_oauth_tokens
+      where("oauth_token_expires_at IS NOT NULL AND oauth_token_expires_at < ?", Time.current)
+    end
+
+    # Cleanup expired OAuth tokens (class method)
+    def self.cleanup_expired_oauth_tokens
+      with_expired_oauth_tokens.update_all(
+        oauth_access_token: nil,
+        oauth_refresh_token: nil,
+        oauth_token_expires_at: nil,
+        oauth_user_context: nil,
+        authentication_method: "none"
+      )
+    end
+
     private
 
     # if this session is from a server, the writer is the client

data/config/routes.rb

@@ -3,6 +3,16 @@
 ActionMCP::Engine.routes.draw do
   get "/up", to: "/rails/health#show", as: :action_mcp_health_check
 
+  # OAuth 2.1 metadata endpoints
+  get "/.well-known/oauth-authorization-server", to: "oauth/metadata#authorization_server", as: :oauth_authorization_server_metadata
+  get "/.well-known/oauth-protected-resource", to: "oauth/metadata#protected_resource", as: :oauth_protected_resource_metadata
+
+  # OAuth 2.1 endpoints
+  get "/oauth/authorize", to: "oauth/endpoints#authorize", as: :oauth_authorize
+  post "/oauth/token", to: "oauth/endpoints#token", as: :oauth_token
+  post "/oauth/introspect", to: "oauth/endpoints#introspect", as: :oauth_introspect
+  post "/oauth/revoke", to: "oauth/endpoints#revoke", as: :oauth_revoke
+
   # MCP 2025-03-26 Spec routes
   get "/", to: "application#show", as: :mcp_get
   post "/", to: "application#create", as: :mcp_post