fast_mcp_jwt_auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a40c2263c74d33678f1b189fd831d51e5ea5ebf4e498fb3334e93f3763997e99
+  data.tar.gz: ef51aae1fa0e79848a23f67cf4a77194d67dfd244594edcc9f4ffcd356069249
+SHA512:
+  metadata.gz: 357905685ab8feab45e48cfa5dc0b2c302b8e795c82038b98046f1ae732edbd6e685787e3b3b149c3967c4e4f711fab040fb95c489aceb1491448e65db248a0f
+  data.tar.gz: df3d0ace55cf03367db55b0c0cb290319d12b20a015f3ac771b4e72e0cbea499159ae6c684535507eea103f3afedd5dd8adaa070315985e2d679ee6578644976

data/.mcp.json

@@ -0,0 +1,30 @@
+{
+  "mcpServers": {
+    "workvector-production": {
+      "type": "sse",
+      "name": "WorkVector Production",
+      "url": "https://workvector.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${WORKVECTOR_TOKEN}"
+      }
+    },
+    "filesystem-project": {
+      "type": "stdio",
+      "name": "Filesystem",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${PWD}"
+      ]
+    },
+    "llmmn-production": {
+      "type": "sse",
+      "name": "LLM Memory Notes Production",
+      "url": "https://llm-memory.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${LLMMN_TOKEN}"
+      }
+    }
+  }
+}

data/.mcp.json.example

@@ -0,0 +1,30 @@
+{
+  "mcpServers": {
+    "example-server": {
+      "type": "sse",
+      "name": "Example MCP Server",
+      "url": "https://example.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${MCP_JWT_TOKEN}"
+      }
+    },
+    "workvector-production": {
+      "type": "sse",
+      "name": "WorkVector Production",
+      "url": "https://workvector.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${WORKVECTOR_TOKEN}"
+      }
+    },
+    "filesystem-project": {
+      "type": "stdio",
+      "name": "Filesystem",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${PWD}"
+      ]
+    }
+  }
+}

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+
+plugins:
+  - rubocop-minitest
+
+Layout/LineLength:
+  Max: 200
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Relax some metrics for reasonable code
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 35
+
+# Allow longer module for JWT authentication patch - it's a cohesive logical unit
+Metrics/ModuleLength:
+  Max: 130
+
+# Allow development dependencies in gemspec for gems
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+ruby-3.4.2

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-08-19
+
+### Added
+- Initial release of FastMcp JWT Auth gem
+- JWT token extraction from Authorization: Bearer headers
+- Configurable JWT decoder callback for token decoding
+- Configurable user finder callback for user lookup from decoded tokens
+- Token validation with configurable callback (defaults to expiration check)
+- Current user setter and resetter with configurable callbacks
+- Automatic Rails integration via Railtie
+- Lazy patch application for FastMcp::Transports::RackTransport
+- Comprehensive test suite with mocked dependencies
+- Error handling with graceful fallback to normal request processing
+- Support for Rails 7.0+ and Ruby 3.1+
+
+### Changed
+- N/A (initial release)
+
+### Deprecated  
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- N/A (initial release)

data/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the `fast_mcp_jwt_auth` gem.
+
+## Gem Overview
+
+FastMCp Jwt Auth provides JWT authentication for FastMcp RackTransport, enabling secure user authentication in MCP requests.
+It integrates seamlessly with Rails, allowing you to authenticate users using JWT tokens in a Rails application.
+
+## Code Conventions
+
+### Code Quality
+- Max 200 chars/line (soft limit - prefer readability over strict compliance)
+  - breaking Ruby chain calls destroys the natural sentence flow and readability
+- 14 lines/method, 110 lines/class
+- Comments and tests in English
+- KEEP CODE DRY (Don't Repeat Yourself)
+
+### Ruby/Rails Philosophy
+- **DO IT RUBY WAY OR RAILS WAY** - it's not Python, Java or PHP!
+- Strong use of Ruby metaprogramming techniques
+- code line should look like human sentence (e.g. `3.times do` not `for i in 0..2 do` - Ruby syntax reads like English)
+- keep code raising exceptions when it's programmer's fault - DO NOT validate method parameters, expect them to be correct! Only validate user input
+- do not repeat name of parameter in method name (e.g. `def create_new_user_from_user(user)` should be `def create_new_user_from(user)`)
+- do not use extra variable if used only once - saves memory and reduces GC pressure under high traffic (e.g. `user = User.find(params[:id]); user.update(...)` should be `User.find(params[:id]).update(...)`) - use `.tap do` for chaining when you need to use the object later
+- use metaprogramming instead of case statements (e.g. `self.send(method_name, params)` instead of `case method_name; when "find_slot"...` - let Ruby handle method dispatch and NoMethodError)
+- PREFER FUNCTIONAL STYLE: use flat_map, map, select over loops and temp variables (e.g. `items.flat_map(&:children).uniq` not `results = []; items.each { |i| results.concat(i.children) }; results.uniq`)
+- USE PATTERN MATCHING: Ruby 3.0+ `case/in` for complex conditionals instead of if/elsif chains - more expressive and catches unhandled cases
+- ONE CLEAR RESPONSIBILITY: each method should do one thing well - if method has "and" in description, split it (e.g. `normalize_and_search` → `normalize` + `search`)
+- FOLLOW KISS PRINCIPLE: Keep It Simple, Stupid - avoid unnecessary complexity, use simple solutions first
+- ALWAYS TEST YOUR CODE
+
+### Error Handling
+- Use meaningful exception classes (not generic StandardError)
+- Log errors with context using the configured logger
+- Proper error propagation with fallback mechanisms
+- Use `rescue_from` for common exceptions in Rails integration
+
+### Performance Considerations
+- Use database connection pooling efficiently
+- Avoid blocking operations in main threads
+- Cache expensive operations
+- Monitor thread lifecycle and cleanup
+
+### Thread Safety
+- All operations must be thread-safe for cluster mode
+- Use proper synchronization when accessing shared resources
+- Handle thread lifecycle correctly (creation, monitoring, cleanup)
+- Use connection checkout/checkin pattern for database operations
+
+### Gem Specific Guidelines
+
+#### Configuration
+- Use configuration object pattern for all settings
+- Provide sensible defaults that work out of the box
+- Make all components configurable but not required
+- Support both programmatic and initializer-based configuration
+
+#### Rails Integration
+- Use Railtie for automatic Rails integration
+- Hook into appropriate Rails lifecycle events
+- Respect Rails conventions for logging and error handling
+- Provide manual configuration options for non-Rails usage
+
+#### Error Recovery
+- Implement automatic retry with backoff for transient errors
+- Provide fallback mechanisms when PubSub fails
+- Log errors appropriately without flooding logs
+- Handle connection failures gracefully
+
+#### Testing
+- Test all public interfaces
+- Mock external dependencies (PostgreSQL, FastMcp)
+- Test error conditions and edge cases
+- Provide test helpers for gem users
+- Test both Rails and non-Rails usage
+
+## Architecture
+
+### Components
+
+1. **FastMcpJwtAuth::Service** - Core JWT authentication service
+   - Handles JWT token generation and validation
+   - Integrates with FastMcp RackTransport for secure requests
+2. **FastMcpJwtAuth::Configuration** - Configuration management
+   - Manages settings like JWT secret, expiration, and algorithm
+3. **FastMcpJwtAuth::RackTransportPatch** - Monkey patch for FastMcp transport
+   - Overrides `send_message` to include JWT authentication
+4. **FastMcpJwtAuth::Railtie** - Rails integration and lifecycle management
+   - Automatically patches FastMcp::Transports::RackTransport during Rails initialization
+
+### Message Flow
+
+1. **MCP Request Received** - FastMcp RackTransport receives HTTP request with Authorization header
+2. **JWT Extraction** - Extract Bearer token from Authorization header (`HTTP_AUTHORIZATION`)
+3. **Token Decoding** - Use configured `jwt_decoder` callback to decode JWT token
+4. **Token Validation** - Validate token expiration and other claims using `token_validator` callback
+5. **User Lookup** - Find user from decoded token using `user_finder` callback
+6. **User Assignment** - Set current user in context using `current_user_setter` callback
+7. **Request Processing** - Continue with normal MCP request handling
+8. **Cleanup** - Clear current user context using `current_resetter` callback
+
+### Thread Management
+
+The gem is designed to be thread-safe for use in Rails applications:
+
+- **Request Isolation** - Each MCP request runs in its own thread context
+- **Current User Context** - Uses thread-local storage via Rails `Current` class for user context
+- **Monkey Patching Safety** - Patch is applied only once using thread-safe flag checking
+- **No Shared State** - All operations are stateless except for configuration (immutable after initialization)
+- **Callback Thread Safety** - User-provided callbacks (`jwt_decoder`, `user_finder`, etc.) must be thread-safe
+- **Automatic Cleanup** - Current user context is always cleared after request processing (even on exceptions)
+
+## Dependencies
+
+### Runtime Dependencies
+- **rails** (>= 7.0) - Required for Rails integration, Current class, and logger support
+
+### Development Dependencies
+- **jwt** (~> 2.0) - Used in tests for JWT token generation and decoding examples
+- **minitest** (~> 5.16) - Test framework
+- **rubocop** (~> 1.21) - Ruby code style enforcement
+- **rubocop-minitest** (~> 0.25) - Minitest-specific RuboCop rules
+- **rubocop-rails** (~> 2.0) - Rails-specific RuboCop rules
+
+### External Dependencies
+- **FastMcp** - The gem monkey patches `FastMcp::Transports::RackTransport` (not declared as dependency to avoid circular dependencies)
+- **JWT Library** - Users must provide their own JWT decoder implementation (commonly `jwt` gem)
+
+## Development
+
+### Running Tests
+```bash
+bundle exec rake test
+```
+
+### Linting
+```bash
+bundle exec rubocop
+```
+
+### Console
+```bash
+bundle exec rake console
+```
+
+## Project-Specific Info
+- **LLM Memory identifier**: `fast_mcp_jwt_auth`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 josefchmel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# FastMcp JWT Auth
+
+**JWT Authorization header authentication extension for [FastMcp](https://github.com/yjacquin/fast-mcp) RackTransport.**
+
+This gem extends the [FastMcp](https://github.com/yjacquin/fast-mcp) gem to enable JWT-based user authentication via Authorization headers in Rails applications. It provides configurable callbacks for token decoding, user lookup, and validation.
+
+## Problem
+
+FastMcp::Transports::RackTransport doesn't have built-in JWT authentication support. For integrating with external MCP clients that use JWT tokens for authentication, you need a way to:
+
+1. Extract JWT tokens from Authorization headers
+2. Decode and validate the tokens
+3. Find users based on token payload
+4. Set `Current.user` for the request duration
+
+## Solution
+
+This gem provides a monkey patch for `FastMcp::Transports::RackTransport` that:
+
+1. Extracts JWT tokens from `Authorization: Bearer` headers
+2. Decodes tokens using configurable callbacks
+3. Validates token expiration and other claims
+4. Finds users using configurable lookup logic
+5. Sets `Current.user` for request duration
+6. Cleans up `Current` after request processing
+
+## Installation
+
+**Prerequisites**: This gem requires the [fast-mcp](https://github.com/yjacquin/fast-mcp) gem to be installed first.
+
+Add both gems to your application's Gemfile:
+
+```ruby
+gem 'fast-mcp'                                    # Required base gem
+gem 'fast_mcp_jwt_auth', github: 'jchsoft/fast_mcp_jwt_auth'  # This extension
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+**Note**: The `fast-mcp` gem provides the core MCP (Model Context Protocol) server functionality, while this gem extends it with JWT authentication support.
+
+## Usage
+
+### Automatic Integration
+
+**No configuration needed for basic usage!** Just add the gem to your Gemfile and configure the callbacks.
+
+The gem will:
+- ✅ **Automatically patch** FastMcp::Transports::RackTransport during Rails initialization
+- ✅ **Extract JWT tokens** from Authorization: Bearer headers automatically  
+- ✅ **Use Rails.logger** for logging (no configuration required)
+- ✅ **Handle errors gracefully** with fallback to normal request processing
+
+### MCP Server Configuration
+
+⚠️ **IMPORTANT**: This gem enables JWT authentication for your Rails application when used with the `fast_mcp` gem. For MCP clients to authenticate with your Rails app, they need to send JWT tokens in the `Authorization: Bearer` header.
+
+### Client-Side MCP Configuration 
+
+When your Rails app is running as an MCP server (using `fast_mcp` gem and `fast_mcp_jwt_auth` gem), MCP clients need to be configured with proper authentication headers to connect to it.
+
+For example create or update your `.mcp.json` configuration file:
+
+```bash
+cp .mcp.json.example .mcp.json
+```
+
+**Critical: The `headers` section with `Authorization: Bearer` is essential for JWT authentication:**
+
+```json
+{
+  "mcpServers": {
+    "your-rails-app": {
+      "type": "sse",
+      "name": "Your Rails MCP Server",
+      "url": "https://your-rails-app.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${JWT_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Real Example - WorkVector Integration
+
+```json
+{
+  "mcpServers": {
+    "workvector-production": {
+      "type": "sse",
+      "name": "WorkVector Production", 
+      "url": "https://workvector.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${WORKVECTOR_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Why Headers are Critical
+
+❌ **This WON'T work** - missing authentication:
+```json
+{
+  "mcpServers": {
+    "your-app": {
+      "type": "sse",
+      "url": "https://your-app.com/mcp/sse"
+    }
+  }
+}
+```
+
+✅ **This WILL work** - includes JWT authentication header:
+```json
+{
+  "mcpServers": {
+    "your-app": {
+      "type": "sse", 
+      "url": "https://your-app.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer ${JWT_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+Use environment variables for sensitive tokens in your `.mcp.json`:
+
+- `${WORKVECTOR_TOKEN}` - Your WorkVector authentication token
+- `${MCP_JWT_TOKEN}` - JWT token for other MCP servers
+- `${PWD}` - Current working directory path
+
+Set these in your environment or `.env` file:
+
+```bash
+export WORKVECTOR_TOKEN="your_workvector_token_here"
+export MCP_JWT_TOKEN="your_jwt_token_here"
+```
+
+### Security Best Practices
+
+- ✅ **Never commit** `.mcp.json` to version control (it's in `.gitignore`)
+- ✅ **Use environment variables** for tokens instead of hardcoding them
+- ✅ **Keep tokens secure** and rotate them regularly
+- ✅ **Use the example file** as a template for new environments
+
+## Configuration
+
+Create an initializer to configure JWT decoding and user lookup:
+
+```ruby
+# config/initializers/fast_mcp_jwt_auth.rb
+FastMcpJwtAuth.configure do |config|
+  config.enabled = true
+  
+  # JWT token decoding callback
+  config.jwt_decoder = ->(jwt_token) do
+    JWT.decode(jwt_token, Rails.application.credentials.secret_key_base, true, algorithm: 'HS256')[0]
+  end
+  
+  # User lookup callback
+  config.user_finder = ->(decoded_token) do
+    User.find_by(authentication_token: decoded_token['authentication_token'])
+  end
+  
+  # Optional: Token validation callback (defaults to expiration check)
+  config.token_validator = ->(decoded_token) do
+    decoded_token['exp'].nil? || decoded_token['exp'] >= Time.current.to_i
+  end
+  
+  # Optional: Custom current user setter (defaults to Current.user=)
+  config.current_user_setter = ->(user) do
+    Current.user = user
+  end
+  
+  # Optional: Custom context resetter (defaults to Current.reset)
+  config.current_resetter = -> do
+    Current.reset
+  end
+end
+```
+
+### WorkVector Integration Example
+
+For WorkVector-style JWT integration using JwtIdClaim:
+
+```ruby
+# config/initializers/fast_mcp_jwt_auth.rb
+FastMcpJwtAuth.configure do |config|
+  config.enabled = true
+  
+  # Use JwtIdClaim for token decoding (WorkVector pattern)
+  config.jwt_decoder = ->(jwt_token) do
+    JwtIdClaim.decode(jwt_token)
+  end
+  
+  # Find user by authentication_token from JWT payload
+  config.user_finder = ->(decoded_token) do
+    User.find_by(authentication_token: decoded_token[:authentication_token])
+  end
+end
+```
+
+## Configuration Callbacks
+
+The gem provides these configurable callbacks:
+
+- **`jwt_decoder`**: Callback for JWT token decoding (required)
+- **`user_finder`**: Callback for user lookup from decoded token (required)  
+- **`token_validator`**: Callback for token validation (optional, defaults to expiration check)
+- **`current_user_setter`**: Callback for setting current user (optional, defaults to `Current.user=`)
+- **`current_resetter`**: Callback for resetting current context (optional, defaults to `Current.reset`)
+
+## How It Works
+
+1. **Request Processing**: When FastMcp processes an MCP request, the patch intercepts it
+2. **Header Extraction**: Looks for `Authorization: Bearer <token>` header
+3. **Token Decoding**: Uses configured `jwt_decoder` callback to decode the JWT
+4. **Token Validation**: Validates token using `token_validator` callback
+5. **User Lookup**: Finds user using `user_finder` callback
+6. **Context Setting**: Sets current user using `current_user_setter` callback
+7. **Request Processing**: Continues with normal MCP request processing
+8. **Cleanup**: Resets current context using `current_resetter` callback
+
+## Error Handling
+
+The gem handles errors gracefully:
+- Invalid JWT tokens are logged as warnings but don't break request processing
+- Missing or malformed Authorization headers are ignored silently
+- Decoding errors fall back to normal request processing without authentication
+- User lookup failures result in no authentication but normal request processing
+
+## Requirements
+
+- Ruby >= 3.1.0
+- Rails >= 7.0
+- FastMcp gem
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Testing
+
+```bash
+rake test
+rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jchsoft/fast_mcp_jwt_auth.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/fast_mcp_jwt_auth/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FastMcpJwtAuth
+  # Configuration class for FastMcpJwtAuth gem settings
+  class Configuration
+    attr_accessor :enabled, :logger, :jwt_decoder, :user_finder, :token_validator,
+                  :current_user_setter, :current_resetter
+
+    def initialize
+      @enabled = true
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      @jwt_decoder = nil
+      @user_finder = nil
+      @token_validator = lambda do |decoded_token|
+        decoded_token[:exp].nil? || decoded_token[:exp] >= Time.current.to_i
+      end
+      @current_user_setter = ->(user) { Current.user = user }
+      @current_resetter = -> { Current.reset }
+    end
+  end
+end

data/lib/fast_mcp_jwt_auth/rack_transport_patch.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Monkey patch for FastMcp::Transports::RackTransport
+# Adds JWT authentication support via Authorization header
+
+module FastMcpJwtAuth
+  # Lazy patch application - applies patch when FastMcp transport is first accessed
+  module RackTransportPatch
+    @patch_applied = false
+
+    def self.apply_patch!
+      return FastMcpJwtAuth.log_debug("RackTransport patch already applied, skipping") if @patch_applied
+      return FastMcpJwtAuth.log_debug("FastMcp::Transports::RackTransport not defined yet, skipping patch") unless defined?(FastMcp::Transports::RackTransport)
+      return FastMcpJwtAuth.log_debug("JWT authentication disabled, skipping patch") unless FastMcpJwtAuth.config.enabled
+
+      apply_patch_to_transport
+    end
+
+    def self.apply_patch_to_transport
+      FastMcpJwtAuth.log_info "Applying JWT authentication patch to FastMcp::Transports::RackTransport"
+      patch_transport_class
+      @patch_applied = true
+      FastMcpJwtAuth.log_info "JWT authentication patch applied successfully"
+    end
+
+    def self.patch_transport_class
+      FastMcp::Transports::RackTransport.prepend(JwtAuthenticationPatch)
+    end
+
+    def self.patch_applied?
+      @patch_applied
+    end
+
+    # The actual patch module that gets prepended
+    module JwtAuthenticationPatch
+      def handle_mcp_request(request, env)
+        authenticate_user_from_jwt(request)
+        super
+      ensure
+        clear_current_user
+      end
+
+      private
+
+      def authenticate_user_from_jwt(request)
+        extract_jwt_token(request)&.tap do |jwt_token|
+          FastMcpJwtAuth.log_debug "Extracted JWT token from Authorization header (length: #{jwt_token.length} chars)"
+          authenticate_user_with_token(jwt_token)
+        end
+      rescue StandardError => e
+        log_authentication_error(e)
+      end
+
+      def extract_jwt_token(request)
+        auth_header = request.env["HTTP_AUTHORIZATION"]
+        return log_and_return("No Authorization header found in request") unless auth_header
+        return log_and_return("Authorization header present but not Bearer token format: #{auth_header[0..20]}...") unless auth_header.start_with?("Bearer ")
+
+        auth_header.sub("Bearer ", "")
+      end
+
+      def log_and_return(message)
+        FastMcpJwtAuth.log_debug message
+        nil
+      end
+
+      def log_authentication_error(exception)
+        FastMcpJwtAuth.log_error "JWT token authentication failed with exception: #{exception.class.name} - #{exception.message}"
+        FastMcpJwtAuth.log_debug "JWT authentication error backtrace: #{exception.backtrace&.first(3)&.join("; ")}"
+      end
+
+      def authenticate_user_with_token(jwt_token)
+        return FastMcpJwtAuth.log_warn("JWT decoder not configured, skipping token authentication") unless FastMcpJwtAuth.config.jwt_decoder
+
+        decode_and_authenticate_token(jwt_token)
+      rescue StandardError => e
+        FastMcpJwtAuth.log_error "JWT token decoding failed: #{e.class.name} - #{e.message}"
+      end
+
+      def decode_and_authenticate_token(jwt_token)
+        FastMcpJwtAuth.log_debug "Attempting to decode JWT token"
+        return FastMcpJwtAuth.log_warn("JWT decoder returned nil - token may be invalid or malformed") unless (decoded_token = FastMcpJwtAuth.config.jwt_decoder.call(jwt_token))
+
+        FastMcpJwtAuth.log_debug "JWT token decoded successfully, checking validity"
+        return unless token_valid?(decoded_token)
+
+        FastMcpJwtAuth.log_debug "JWT token validation passed, looking up user"
+        authenticate_found_user(find_user_from_token(decoded_token))
+      end
+
+      def authenticate_found_user(user)
+        if user
+          FastMcpJwtAuth.log_debug "Setting current user context"
+          assign_current_user(user)
+          FastMcpJwtAuth.log_info "User authentication completed successfully"
+        else
+          FastMcpJwtAuth.log_warn "Authentication failed: no user found for token"
+        end
+      end
+
+      def token_valid?(decoded_token)
+        return log_debug_and_return_true?("No token validator configured, considering token valid") unless FastMcpJwtAuth.config.token_validator
+
+        validate_decoded_token(decoded_token)
+      rescue StandardError => e
+        FastMcpJwtAuth.log_error "Token validation failed with exception: #{e.class.name} - #{e.message}"
+        false
+      end
+
+      def validate_decoded_token(decoded_token)
+        FastMcpJwtAuth.log_debug "Running token validation"
+        FastMcpJwtAuth.config.token_validator.call(decoded_token).tap do |valid|
+          log_validation_result(valid)
+        end
+      end
+
+      def log_validation_result(valid)
+        if valid
+          FastMcpJwtAuth.log_debug "Token validation passed"
+        else
+          FastMcpJwtAuth.log_warn "Token validation failed - validator returned falsy value"
+        end
+      end
+
+      def log_debug_and_return_true?(message)
+        FastMcpJwtAuth.log_debug message
+        true
+      end
+
+      def find_user_from_token(decoded_token)
+        return FastMcpJwtAuth.log_warn("User finder not configured, cannot authenticate user") unless FastMcpJwtAuth.config.user_finder
+
+        lookup_user_from_decoded_token(decoded_token)
+      rescue StandardError => e
+        FastMcpJwtAuth.log_error "User lookup failed with exception: #{e.class.name} - #{e.message}"
+        nil
+      end
+
+      def lookup_user_from_decoded_token(decoded_token)
+        FastMcpJwtAuth.log_debug "Looking up user from decoded token"
+        FastMcpJwtAuth.config.user_finder.call(decoded_token).tap do |user|
+          log_user_lookup_result(user)
+        end
+      end
+
+      def log_user_lookup_result(user)
+        if user
+          FastMcpJwtAuth.log_debug "User found successfully: #{user}"
+        else
+          FastMcpJwtAuth.log_warn "User finder returned nil - user may not exist or be inactive"
+        end
+      end
+
+      def assign_current_user(user)
+        FastMcpJwtAuth.config.current_user_setter&.call(user)
+      end
+
+      def clear_current_user
+        FastMcpJwtAuth.config.current_resetter&.call
+      end
+    end
+  end
+end
+
+# NOTE: Patch is automatically applied by Railtie initializer when Rails loads

data/lib/fast_mcp_jwt_auth/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module FastMcpJwtAuth
+  # Rails integration for automatic FastMcpJwtAuth setup
+  class Railtie < Rails::Railtie
+    # Apply patch to FastMcp::Transports::RackTransport after all initializers are loaded
+    initializer "fast_mcp_jwt_auth.apply_patch", after: :load_config_initializers do
+      Rails.application.config.after_initialize do
+        FastMcpJwtAuth.config.enabled ? FastMcpJwtAuth::Railtie.apply_jwt_patch : FastMcpJwtAuth::Railtie.log_disabled_status
+      end
+    end
+
+    class << self
+      def apply_jwt_patch
+        FastMcpJwtAuth.log_debug "Attempting to apply RackTransport patch"
+        FastMcpJwtAuth::RackTransportPatch.apply_patch!
+      end
+
+      def log_disabled_status
+        FastMcpJwtAuth.log_info "JWT authentication disabled"
+      end
+    end
+  end
+end

data/lib/fast_mcp_jwt_auth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FastMcpJwtAuth
+  VERSION = "0.1.0"
+end

data/lib/fast_mcp_jwt_auth.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "fast_mcp_jwt_auth/version"
+require_relative "fast_mcp_jwt_auth/configuration"
+
+# JWT Authorization header authentication for FastMcp RackTransport.
+# Enables FastMcp RackTransport to authenticate users via JWT tokens passed through Authorization headers
+# with configurable callbacks for token decoding and user lookup.
+module FastMcpJwtAuth
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  def self.config
+    self.configuration ||= Configuration.new
+  end
+
+  # Simple logging helper - uses Rails.logger since this gem is Rails-specific
+  def self.logger
+    Rails.logger
+  end
+
+  # DRY logging with consistent prefix - Ruby metaprogramming way
+  %i[debug info warn error].each do |level|
+    define_singleton_method("log_#{level}") do |message|
+      logger&.public_send(level, "FastMcpJwtAuth: #{message}")
+    end
+  end
+end
+
+# Load patch after module is fully defined
+require_relative "fast_mcp_jwt_auth/rack_transport_patch"
+require_relative "fast_mcp_jwt_auth/railtie" if defined?(Rails)

data/sig/fast_mcp_jwt_auth.rbs

@@ -0,0 +1,4 @@
+module FastMcpJwtAuth
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: fast_mcp_jwt_auth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- josefchmel
+bindir: exe
+cert_chain: []
+date: 2025-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Enables FastMcp RackTransport to authenticate users via JWT tokens passed
+  through Authorization headers with configurable callbacks for token decoding and
+  user lookup
+email:
+- chmel@jchsoft.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".mcp.json"
+- ".mcp.json.example"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/fast_mcp_jwt_auth.rb
+- lib/fast_mcp_jwt_auth/configuration.rb
+- lib/fast_mcp_jwt_auth/rack_transport_patch.rb
+- lib/fast_mcp_jwt_auth/railtie.rb
+- lib/fast_mcp_jwt_auth/version.rb
+- sig/fast_mcp_jwt_auth.rbs
+homepage: https://github.com/jchsoft/fast_mcp_jwt_auth
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/jchsoft/fast_mcp_jwt_auth
+  source_code_uri: https://github.com/jchsoft/fast_mcp_jwt_auth
+  changelog_uri: https://github.com/jchsoft/fast_mcp_jwt_auth/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: JWT Authorization header authentication for FastMcp RackTransport
+test_files: []