mcp-auth 0.1.0

data/lib/generators/mcp/auth/install_generator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Mcp
+  module Auth
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path('templates', __dir__)
+
+        desc "Generates MCP Auth migrations, initializer, and views"
+
+        def copy_migrations
+          migration_template "create_oauth_clients.rb.erb",
+                             "db/migrate/create_mcp_auth_oauth_clients.rb",
+                             migration_version: migration_version
+
+          migration_template "create_authorization_codes.rb.erb",
+                             "db/migrate/create_mcp_auth_authorization_codes.rb",
+                             migration_version: migration_version
+
+          migration_template "create_access_tokens.rb.erb",
+                             "db/migrate/create_mcp_auth_access_tokens.rb",
+                             migration_version: migration_version
+
+          migration_template "create_refresh_tokens.rb.erb",
+                             "db/migrate/create_mcp_auth_refresh_tokens.rb",
+                             migration_version: migration_version
+        end
+
+        def copy_initializer
+          template "initializer.rb", "config/initializers/mcp_auth.rb"
+        end
+
+        def copy_views
+          # Create the directory first
+          empty_directory "app/views/mcp/auth"
+
+          # Copy consent view template
+          template "views/consent.html.erb", "app/views/mcp/auth/consent.html.erb"
+        end
+
+        def show_readme
+          if File.exist?(File.join(self.class.source_root, "README"))
+            readme "README"
+          end
+        rescue Thor::Error
+          # Skip silently
+        end
+
+        def show_post_install_message
+          say "\n" + "="*80
+          say "MCP Auth has been installed!", :green
+          say "="*80
+          say "\nFiles created:"
+          say "  - db/migrate/*_create_mcp_auth_*.rb (4 migrations)"
+          say "  - config/initializers/mcp_auth.rb"
+          say "  - app/views/mcp/auth/consent.html.erb"
+          say "\nNext steps:"
+          say "1. Run migrations: rails db:migrate"
+          say "2. Configure: config/initializers/mcp_auth.rb"
+          say "3. Customize consent view: app/views/mcp/auth/consent.html.erb"
+          say "4. Mount routes in config/routes.rb (if not already done):"
+          say "   mount Mcp::Auth::Engine => '/'"
+          say "\nDocumentation: https://github.com/SerhiiBorozenets/mcp-auth"
+          say "="*80 + "\n"
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/mcp/auth/templates/README

@@ -0,0 +1,114 @@
+===============================================================================
+
+MCP Auth has been installed!
+
+Next steps:
+
+1. Run the migrations:
+
+   rails db:migrate
+
+2. Configure the initializer at config/initializers/mcp_auth.rb
+
+   Set your OAuth secret and customize user data fetching.
+
+3. Ensure your ApplicationController has authentication methods:
+
+    - current_user: returns the currently signed-in user
+    - current_org: returns the current organization (optional)
+    - user_signed_in?: returns true if user is signed in
+
+4. Set environment variables (optional):
+
+   MCP_HMAC_SECRET: Secret key for signing JWTs
+   MCP_AUTHORIZATION_SERVER_URL: Custom authorization server URL
+
+5. Your OAuth endpoints are now available at:
+
+    - /.well-known/oauth-protected-resource (Protected Resource Metadata)
+    - /.well-known/oauth-authorization-server (Authorization Server Metadata)
+    - /oauth/authorize (Authorization endpoint)
+    - /oauth/token (Token endpoint)
+    - /oauth/register (Dynamic client registration)
+    - /oauth/revoke (Token revocation)
+    - /oauth/introspect (Token introspection)
+
+6. Mount the routes in your config/routes.rb:
+
+   Rails.application.routes.draw do
+   # Mount MCP Auth routes at the top
+   mount Mcp::Auth::Engine => "/"
+
+   # ... your other routes
+   end
+
+CUSTOMIZING THE CONSENT SCREEN
+-------------------------------
+
+The generator has created a default consent view at:
+app/views/mcp/auth/consent.html.erb
+
+To use your custom consent view:
+
+1. Edit config/initializers/mcp_auth.rb and set:
+   config.use_custom_consent_view = true
+
+2. Customize app/views/mcp/auth/consent.html.erb to match your branding
+
+3. Available instance variables in the view:
+   @client_name - Name of the OAuth client requesting access
+   @requested_scopes - Array of human-readable permission descriptions
+   @authorization_params - Hash containing OAuth flow parameters
+
+4. The form must POST to oauth_approve_path with:
+    - All @authorization_params as hidden fields
+    - A button with name="approved" value="true" for approval
+    - A button with name="approved" value="false" for denial
+
+Example form:
+<%= form_with url: oauth_approve_path, method: :post do |f| %>
+<% @authorization_params.each do |key, value| %>
+<%= f.hidden_field key, value: value, id: nil %>
+<% end %>
+<%= f.button 'Deny', name: 'approved', value: 'false' %>
+<%= f.button 'Authorize', name: 'approved', value: 'true' %>
+<% end %>
+
+TESTING THE OAUTH FLOW
+-----------------------
+
+1. Start your Rails server:
+   rails server
+
+2. Test the discovery endpoints:
+   curl http://localhost:3000/.well-known/oauth-protected-resource
+   curl http://localhost:3000/.well-known/oauth-authorization-server
+
+3. Register a test client:
+   curl -X POST http://localhost:3000/oauth/register \
+   -H "Content-Type: application/json" \
+   -d '{
+   "client_name": "Test Client",
+   "redirect_uris": ["http://localhost:3000/callback"]
+     }'
+
+4. Use the returned client_id and client_secret for OAuth flow
+
+RAKE TASKS
+----------
+
+Clean up expired tokens:
+rake mcp_auth:cleanup
+
+Show statistics:
+rake mcp_auth:stats
+
+Revoke tokens for a client:
+rake mcp_auth:revoke_client_tokens[CLIENT_ID]
+
+Revoke tokens for a user:
+rake mcp_auth:revoke_user_tokens[USER_ID]
+
+For more information, see: https://github.com/SerhiiBorozenets/mcp-auth
+
+===============================================================================

data/lib/generators/mcp/auth/templates/create_access_tokens.rb.erb

@@ -0,0 +1,23 @@
+class CreateMcpAuthAccessTokens < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_table :mcp_auth_access_tokens do |t|
+      t.string :token, null: false, index: { unique: true }
+      t.string :client_id, null: false
+      t.string :resource
+      t.string :scope
+      t.references :user, foreign_key: true
+      t.references :org, foreign_key: true, null: true
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+
+    add_index :mcp_auth_access_tokens, :client_id
+    add_index :mcp_auth_access_tokens, :expires_at
+  end
+
+  def down
+    remove_index :mcp_auth_access_tokens, :client_id
+    remove_index :mcp_auth_access_tokens, :expires_at
+    drop_table :mcp_auth_access_tokens
+  end
+end

data/lib/generators/mcp/auth/templates/create_authorization_codes.rb.erb

@@ -0,0 +1,26 @@
+class CreateMcpAuthAuthorizationCodes < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_table :mcp_auth_authorization_codes do |t|
+      t.string :code, null: false, index: { unique: true }
+      t.string :client_id, null: false
+      t.string :redirect_uri, null: false
+      t.string :code_challenge
+      t.string :code_challenge_method
+      t.string :resource
+      t.string :scope
+      t.references :user, foreign_key: true
+      t.references :org, foreign_key: true, null: true
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+
+    add_index :mcp_auth_authorization_codes, :client_id
+    add_index :mcp_auth_authorization_codes, :expires_at
+  end
+
+  def down
+    remove_index :mcp_auth_authorization_codes, :client_id
+    remove_index :mcp_auth_authorization_codes, :expires_at
+    drop_table :mcp_auth_authorization_codes
+  end
+end

data/lib/generators/mcp/auth/templates/create_oauth_clients.rb.erb

@@ -0,0 +1,22 @@
+class CreateMcpAuthOauthClients < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_table :mcp_auth_oauth_clients, id: false do |t|
+      t.uuid :client_id, primary_key: true, null: false, default: -> { 'gen_random_uuid()' }
+      t.string :client_secret, null: false
+      t.text :redirect_uris
+      t.text :grant_types
+      t.text :response_types
+      t.string :scope
+      t.string :client_name
+      t.string :client_uri
+      t.timestamps
+    end
+
+    add_index :mcp_auth_oauth_clients, :client_id, unique: true
+  end
+
+  def down
+    remove_index :mcp_auth_oauth_clients, :client_id
+    drop_table :mcp_auth_oauth_clients
+  end
+end

data/lib/generators/mcp/auth/templates/create_refresh_tokens.rb.erb

@@ -0,0 +1,22 @@
+class CreateMcpAuthRefreshTokens < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_table :mcp_auth_refresh_tokens do |t|
+      t.string :token, null: false, index: { unique: true }
+      t.string :client_id, null: false
+      t.string :scope
+      t.references :user, foreign_key: true
+      t.references :org, foreign_key: true, null: true
+      t.datetime :expires_at, null: false
+      t.timestamps
+    end
+
+    add_index :mcp_auth_refresh_tokens, :client_id
+    add_index :mcp_auth_refresh_tokens, :expires_at
+  end
+
+  def down
+    remove_index :mcp_auth_refresh_tokens, :client_id
+    remove_index :mcp_auth_refresh_tokens, :expires_at
+    drop_table :mcp_auth_refresh_tokens
+  end
+end

data/lib/generators/mcp/auth/templates/initializer.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+Mcp::Auth.configure do |config|
+  # ============================================================================
+  # OAUTH CONFIGURATION
+  # ============================================================================
+
+  # OAuth secret for signing JWTs
+  # Should be a secure random string in production (use: rails secret)
+  config.oauth_secret = ENV.fetch('MCP_HMAC_SECRET', Rails.application.secret_key_base)
+
+  # Authorization server URL (optional - defaults to same as resource server)
+  # Set this if you're using a separate authorization server
+  # Example: config.authorization_server_url = 'https://auth.example.com'
+  config.authorization_server_url = ENV.fetch('MCP_AUTHORIZATION_SERVER_URL', nil)
+
+  # ============================================================================
+  # MCP SERVER CONFIGURATION
+  # ============================================================================
+
+  # MCP Server Path - where your MCP server is mounted
+  # This MUST match the path where you mount FastMCP or your MCP server
+  # Default: '/mcp'
+  # Examples: '/api/mcp', '/v1/assistant', '/assistant/api'
+  config.mcp_server_path = ENV.fetch('MCP_SERVER_PATH', '/mcp')
+
+  # MCP Documentation URL - link to your MCP server documentation
+  # Can be a full URL (https://docs.example.com/mcp) or a path (/docs/mcp)
+  # Default: nil (will auto-generate as {mcp_server_path}/docs)
+  # Examples:
+  #   config.mcp_docs_url = '/docs/mcp-api'
+  #   config.mcp_docs_url = 'https://docs.example.com/mcp-api'
+  config.mcp_docs_url = ENV.fetch('MCP_DOCS_URL', nil)
+
+  # ============================================================================
+  # TOKEN LIFETIMES (in seconds)
+  # ============================================================================
+
+  config.access_token_lifetime = 3600           # 1 hour
+  config.refresh_token_lifetime = 2_592_000     # 30 days
+  config.authorization_code_lifetime = 1800     # 30 minutes
+
+  # ============================================================================
+  # USER DATA FETCHER
+  # ============================================================================
+
+  # This proc is called when generating tokens to fetch user-specific data
+  # Customize this based on your application's user and organization models
+  #
+  # Expected return value: Hash with keys:
+  #   - :email (String) - User's email address
+  #   - :api_key_id (String/Integer, optional) - API key ID if using API keys
+  #   - :api_key_secret (String, optional) - API key secret if using API keys
+  config.fetch_user_data = proc do |data|
+    user = User.find(data[:user_id])
+
+    # Example: If you have API keys per organization user
+    # org_user = OrgUser.find_by(user_id: data[:user_id], org_id: data[:org_id])
+    # api_key = org_user&.api_key
+
+    {
+      email: user.email,
+      api_key_id: nil,      # Set to your API key ID if applicable
+      api_key_secret: nil   # Set to your API key secret if applicable
+    }
+  rescue ActiveRecord::RecordNotFound
+    { email: 'unknown@example.com', api_key_id: nil, api_key_secret: nil }
+  end
+
+  # ============================================================================
+  # AUTHENTICATION METHODS
+  # ============================================================================
+
+  # Methods used to get current user and organization in your controllers
+  # Change these if you use different method names (e.g., authenticated_user)
+  config.current_user_method = :current_user
+  config.current_org_method = :current_org
+
+  # ============================================================================
+  # SCOPE CONFIGURATION
+  # ============================================================================
+
+  # Register scopes that your application needs:
+  #
+  # Syntax:
+  #   config.register_scope 'scope_key',
+  #     name: 'Display Name',
+  #     description: 'What this scope allows (shown to users)',
+  #     required: false  # Set to true if scope is always required
+  #
+  # IMPORTANT: At least one scope should be registered for OAuth to work properly.
+
+  # Basic read access - typically required
+  config.register_scope 'mcp:read',
+                        name: 'Read Access',
+                        description: 'Read your data and resources',
+                        required: true  # Usually required for MCP to function
+
+  # Write access - allows modifications
+  config.register_scope 'mcp:write',
+                        name: 'Write Access',
+                        description: 'Create and modify data on your behalf',
+                        required: false
+
+  # Execute tools and automated actions
+  # config.register_scope 'mcp:tools',
+  #   name: 'Execute Tools',
+  #   description: 'Run tools and perform automated actions in your account'
+
+  # Analytics and reporting
+  # config.register_scope 'mcp:analytics',
+  #   name: 'Analytics Access',
+  #   description: 'View analytics dashboards, charts, and reports'
+
+  # Data export capabilities
+  # config.register_scope 'mcp:export',
+  #   name: 'Data Export',
+  #   description: 'Export data in CSV, PDF, and Excel formats'
+
+  # Administrative access
+  # config.register_scope 'mcp:admin',
+  #   name: 'Administrative Access',
+  #   description: 'Manage settings, users, and perform administrative actions',
+  #   required: false
+
+  # Custom application-specific scopes
+  # config.register_scope 'mcp:orders',
+  #   name: 'Order Management',
+  #   description: 'View and manage customer orders'
+
+  # config.register_scope 'mcp:notifications',
+  #   name: 'Send Notifications',
+  #   description: 'Send notifications and messages on your behalf'
+
+  # ============================================================================
+  # SCOPE VALIDATION (OPTIONAL)
+  # ============================================================================
+
+  # Validate which scopes users can approve based on their roles/permissions
+  # This callback is called for each requested scope during authorization
+  #
+  # Parameters:
+  #   - user: Current user object
+  #   - org: Current organization object (may be nil)
+  #   - scope: Scope being requested (String)
+  #
+  # Return:
+  #   - true: User can approve this scope
+  #   - false: User cannot approve this scope (will be filtered out)
+  #
+  # Example: Restrict admin scope to admin users only
+  # config.validate_scope_for_user = proc do |user, org, scope|
+  #   case scope
+  #   when 'mcp:admin'
+  #     # Only admins can approve admin scope
+  #     user.admin? || org&.admins&.include?(user)
+  #   when 'mcp:analytics'
+  #     # Check if user has analytics permission
+  #     user.has_permission?(:view_analytics)
+  #   when 'mcp:export'
+  #     # Check if organization plan includes export
+  #     org&.plan&.includes_export?
+  #   else
+  #     true  # Allow all other scopes
+  #   end
+  # end
+
+  # ============================================================================
+  # CUSTOM CONSENT VIEW (OPTIONAL)
+  # ============================================================================
+
+  # Set to true to use your own consent view instead of the gem's default
+  # The view will be at app/views/mcp/auth/consent.html.erb
+  config.use_custom_consent_view = false
+
+  # Path to custom consent view (relative to app/views)
+  # Only used if use_custom_consent_view is true
+  config.consent_view_path = 'mcp/auth/consent'
+
+  # To customize the consent screen:
+  # 1. Set use_custom_consent_view = true
+  # 2. Copy the default view from the gem or generate it:
+  #    rails generate mcp:auth:install
+  # 3. Edit app/views/mcp/auth/consent.html.erb
+  # 4. The view has access to these instance variables:
+  #    - @client_name: Name of the OAuth client requesting access
+  #    - @requested_scopes: Array of scope hashes with keys:
+  #        * :key - Scope identifier (e.g., 'mcp:read')
+  #        * :name - Human-readable name (e.g., 'Read Access')
+  #        * :description - What the scope allows
+  #        * :required - Whether scope is required (true/false)
+  #        * :pre_selected - Whether scope was in the original request
+  #    - @authorization_params: Hash of OAuth parameters to preserve
+end
+
+# Include controller helpers in ApplicationController
+Rails.application.config.to_prepare do
+  ApplicationController.include Mcp::Auth::ControllerHelpers
+end