docs: add Claude Code configuration and project documentation

- Add .mcp.json with WorkVector and filesystem MCP server configuration
- Add .ruby-version file for Ruby 3.4.2
- Add comprehensive CLAUDE.md with gem overview, architecture, and development guidelines
- Update .gitignore for better project file exclusions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Pepan

.gitignore

@@ -6,3 +6,13 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.idea/*
+
+# macOS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

.mcp.json

@@ -0,0 +1,22 @@
+{
+  "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}"
+      ]
+    }
+  }
+}

.ruby-version

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

CLAUDE.md

@@ -0,0 +1,154 @@
+# 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
+```
+
+## WorkVector Task Access
+- To read a task from WorkVector, use the workvector-production MCP server:
+    1. Use `ListMcpResourcesTool` to get all available resources
+    2. Load template using `ReadMcpResourceTool` with URI "template://task"
+    3. Parse the task URL (e.g., https://workvector.com/jchsoft/tasks/8383) to extract account_code and task_id
+    4. Load task content using the template with account_code and task_id parameters
+- To log work progress, use `mcp__workvector-production__LogWorkProgressTool` with account_code, task_id, description and progress_percent. Log progress incrementally as you work on the task!
+- **IMPORTANT**: Always set progress_percent to max 90% on first task completion - leave a few percent for potential follow-ups and adjustments

lib/fast_mcp_jwt_auth.rb

@@ -26,6 +26,19 @@ def self.config
   def self.logger
     Rails.logger
   end
+
+  # DRY logging with consistent prefix
+  def self.log_debug(message)
+    logger&.debug "FastMcpJwtAuth: #{message}"
+  end
+
+  def self.log_info(message)
+    logger&.info "FastMcpJwtAuth: #{message}"
+  end
+
+  def self.log_warn(message)
+    logger&.warn "FastMcpJwtAuth: #{message}"
+  end
 end
 
 # Load patch after module is fully defined

lib/fast_mcp_jwt_auth/rack_transport_patch.rb

@@ -10,25 +10,25 @@ module RackTransportPatch
 
     def self.apply_patch!
       if @patch_applied
-        FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: RackTransport patch already applied, skipping"
+        FastMcpJwtAuth.log_debug "RackTransport patch already applied, skipping"
         return
       end
 
       unless defined?(FastMcp::Transports::RackTransport)
-        FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: FastMcp::Transports::RackTransport not defined yet, skipping patch"
+        FastMcpJwtAuth.log_debug "FastMcp::Transports::RackTransport not defined yet, skipping patch"
         return
       end
 
       unless FastMcpJwtAuth.config.enabled
-        FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: JWT authentication disabled, skipping patch"
+        FastMcpJwtAuth.log_debug "JWT authentication disabled, skipping patch"
         return
       end
 
-      FastMcpJwtAuth.logger&.info "FastMcpJwtAuth: Applying JWT authentication patch to FastMcp::Transports::RackTransport"
+      FastMcpJwtAuth.log_info "Applying JWT authentication patch to FastMcp::Transports::RackTransport"
 
       patch_transport_class
       @patch_applied = true
-      FastMcpJwtAuth.logger&.info "FastMcpJwtAuth: JWT authentication patch applied successfully"
+      FastMcpJwtAuth.log_info "JWT authentication patch applied successfully"
     end
 
     def self.patch_transport_class
@@ -54,24 +54,22 @@ def authenticate_user_from_jwt(request)
         auth_header = request.env["HTTP_AUTHORIZATION"]
         return unless auth_header&.start_with?("Bearer ")
 
-        jwt_token = auth_header.sub("Bearer ", "")
-        FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: Extracted JWT token from Authorization header"
-
-        authenticate_user_with_token(jwt_token)
+        auth_header.sub("Bearer ", "").tap do |jwt_token|
+          FastMcpJwtAuth.log_debug "Extracted JWT token from Authorization header"
+          authenticate_user_with_token(jwt_token)
+        end
       rescue StandardError => e
-        FastMcpJwtAuth.logger&.warn "FastMcpJwtAuth: JWT token authentication failed: #{e.message}"
+        FastMcpJwtAuth.log_warn "JWT token authentication failed: #{e.message}"
       end
 
       def authenticate_user_with_token(jwt_token)
         return unless FastMcpJwtAuth.config.jwt_decoder
 
-        decoded_token = FastMcpJwtAuth.config.jwt_decoder.call(jwt_token)
-        return unless decoded_token
-
-        return unless token_valid?(decoded_token)
+        FastMcpJwtAuth.config.jwt_decoder.call(jwt_token)&.tap do |decoded_token|
+          next unless token_valid?(decoded_token)
 
-        user = find_user_from_token(decoded_token)
-        assign_current_user(user) if user
+          find_user_from_token(decoded_token)&.tap { |user| assign_current_user(user) }
+        end
       end
 
       def token_valid?(decoded_token)
@@ -83,9 +81,9 @@ def token_valid?(decoded_token)
       def find_user_from_token(decoded_token)
         return unless FastMcpJwtAuth.config.user_finder
 
-        user = FastMcpJwtAuth.config.user_finder.call(decoded_token)
-        FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: Authenticated user: #{user}" if user
-        user
+        FastMcpJwtAuth.config.user_finder.call(decoded_token)&.tap do |user|
+          FastMcpJwtAuth.log_debug "Authenticated user: #{user}"
+        end
       end
 
       def assign_current_user(user)

lib/fast_mcp_jwt_auth/railtie.rb

@@ -7,10 +7,10 @@ class Railtie < Rails::Railtie
     initializer "fast_mcp_jwt_auth.apply_patch", after: :load_config_initializers do
       Rails.application.config.after_initialize do
         if FastMcpJwtAuth.config.enabled
-          FastMcpJwtAuth.logger&.debug "FastMcpJwtAuth: Attempting to apply RackTransport patch"
+          FastMcpJwtAuth.log_debug "Attempting to apply RackTransport patch"
           FastMcpJwtAuth::RackTransportPatch.apply_patch!
         else
-          FastMcpJwtAuth.logger&.info "FastMcpJwtAuth: JWT authentication disabled"
+          FastMcpJwtAuth.log_info "JWT authentication disabled"
         end
       end
     end