fast_mcp_pubsub 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db696202b8d3b7dae7c2231fcb132d6dba086b20e578eac993aac24bb92d820b
+  data.tar.gz: 67f0d7bf55c87fcc35a1f9a9cc2686fef93329ff958c4377e823027670724aea
+SHA512:
+  metadata.gz: 50b8171fab26238c6177e7d450eef9218adc02b76bb1e6434e65a80ef4c0ff998e43f2c3e538fccadde7097ac8928ff0b20c129aba73d36ec8d2a128a213ab2d
+  data.tar.gz: d386411918a12d71f91cb2b9a40a2b3aaa6bf11d527bb637c231a3bc5c9dc76e53814d91a222d418c8dea02ced23ad41aff72bb5db94d48f1982083e65000fca

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/.rubocop.yml

@@ -0,0 +1,40 @@
+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 development dependencies in gemspec for gems
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+# Allow longer blocks for configuration and setup
+Metrics/BlockLength:
+  Exclude:
+    - "test/**/*"
+    - "*.gemspec"
+    - "lib/fast_mcp_pubsub/railtie.rb"  # Debug logging temporarily increases block length

data/.ruby-version

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

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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).
+
+## [1.0.0] - 2025-08-19
+
+### Added
+- Initial implementation of PostgreSQL NOTIFY/LISTEN clustering for FastMcp RackTransport
+- FastMcpPubsub::Service for message broadcasting and listening
+- FastMcpPubsub::Configuration for configurable settings (enabled, channel_name, auto_start, connection_pool_size)
+- RackTransport monkey patch for cluster mode message distribution
+- Rails Railtie for automatic initialization and Rails integration
+- Puma cluster mode integration with automatic worker hooks
+- Payload size validation (7800 bytes limit) with fallback error responses
+- Thread-safe listener management with automatic restart on errors
+- Comprehensive logging via FastMcpPubsub.logger (Rails.logger)
+- Connection pooling for database operations
+- Automatic patch application during Rails initialization
+- Method redefinition protection to avoid warnings
+- Full test coverage (18 tests, 33 assertions)
+- RuboCop compliance (0 offenses)
+
+### Implementation Details
+- **Automatic Integration**: No manual configuration required - just add to Gemfile
+- **Smart Timing**: Patch applied after Rails initializers load via `after: :load_config_initializers`
+- **Dual Mode Support**: Works in both single-worker and cluster mode
+- **Clean Logging**: Simplified logging without complex conditional checks
+- **Warning-Free**: Eliminated method redefinition warnings using proper mocking patterns
+- **Robust Error Handling**: Fallback to local delivery if PostgreSQL NOTIFY fails
+- **Rails-Specific**: Designed for Rails applications with ActiveRecord and PostgreSQL
+
+### Technical Architecture
+- **Patch Strategy**: Monkey patches `FastMcp::Transports::RackTransport#send_message`
+- **Broadcasting**: Uses PostgreSQL NOTIFY/LISTEN for inter-worker communication  
+- **Listener Management**: Dedicated thread per worker with automatic lifecycle management
+- **Configuration**: Simple configuration object with sensible defaults
+- **Integration**: Rails Railtie for seamless Rails integration

data/CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the `fast_mcp_pubsub` gem.
+
+## Gem Overview
+
+FastMcp PubSub provides PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport, enabling message broadcasting across multiple Puma workers in cluster mode.
+
+## 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)
+
+### 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. **FastMcpPubsub::Service** - Core PostgreSQL NOTIFY/LISTEN service
+2. **FastMcpPubsub::Configuration** - Configuration management
+3. **FastMcpPubsub::RackTransportPatch** - Monkey patch for FastMcp transport
+4. **FastMcpPubsub::Railtie** - Rails integration and lifecycle management
+
+### Message Flow
+
+1. `RackTransport#send_message` → `FastMcpPubsub::Service.broadcast`
+2. `Service.broadcast` → PostgreSQL NOTIFY
+3. Each worker's listener thread receives NOTIFY
+4. Listener calls `RackTransport#send_local_message` for local clients
+
+### Thread Management
+
+- One listener thread per worker process
+- Thread cleanup on process exit
+- Automatic restart on listener errors
+- Connection pooling for database operations
+
+## Dependencies
+
+- **Rails** (>= 7.0) - Core framework integration
+- **PostgreSQL** (via pg gem >= 1.0) - Database NOTIFY/LISTEN
+- **ActiveRecord** - Connection pooling and database access
+- **FastMcp** - The transport being patched (development/test dependency)
+
+## Development
+
+### Running Tests
+```bash
+bundle exec rake test
+```
+
+### Linting
+```bash
+bundle exec rubocop
+```
+
+### Console
+```bash
+bundle exec rake console
+```

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,168 @@
+# FastMcp PubSub
+
+**Multi-worker cluster support extension for [fast-mcp](https://github.com/yjacquin/fast-mcp) gem.**
+
+This gem extends the [FastMcp](https://github.com/yjacquin/fast-mcp) gem to work with multiple Puma workers by adding PostgreSQL NOTIFY/LISTEN clustering support for `FastMcp::Transports::RackTransport` in Rails applications.
+
+## Problem
+
+FastMcp::Transports::RackTransport stores SSE clients in an in-memory hash `@sse_clients`. In cluster mode (multiple Puma workers), messages don't reach between workers because each has its own memory space.
+
+## Solution
+
+This gem provides PostgreSQL NOTIFY/LISTEN system for broadcasting messages between workers:
+
+1. `send_message` → PostgreSQL NOTIFY
+2. Listener thread in each worker → PostgreSQL LISTEN  
+3. On notification → `send_local_message` to local clients
+
+## 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', '~> 1.5.0'      # Required base gem
+gem 'fast_mcp_pubsub'           # 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 multi-worker support.
+
+## Usage
+
+### Automatic Integration
+
+**No configuration needed!** Just add the gem to your Gemfile and it works automatically.
+
+The gem will:
+- ✅ **Automatically patch** FastMcp::Transports::RackTransport during Rails initialization
+- ✅ **Start listener** automatically when Rails server starts
+- ✅ **Use Rails.logger** for logging (no configuration required)
+- ✅ **Work in both** single-worker and cluster mode
+
+### Optional Configuration
+
+If you need custom settings:
+
+```ruby
+# config/initializers/fast_mcp_pubsub.rb (optional)
+FastMcpPubsub.configure do |config|
+  config.enabled = Rails.env.production?    # Enable only in production
+  config.channel_name = 'my_custom_channel' # Custom PostgreSQL NOTIFY channel
+  config.auto_start = true                  # Start listener automatically (default: true)
+  config.connection_pool_size = 10          # Database connection pool size
+end
+```
+
+### Puma Cluster Mode
+
+For cluster mode (multiple workers), you need to manually start the listener in each worker process:
+
+```ruby
+# config/puma/production.rb
+workers ENV.fetch("WEB_CONCURRENCY") { 2 }
+preload_app!
+
+on_worker_boot do
+  Rails.logger.info "MCP Transport: Starting PubSub listener for cluster mode worker #{Process.pid}"
+  
+  # Start FastMcpPubsub listener in each worker
+  FastMcpPubsub::Service.start_listener
+  
+  # Your other worker boot code...
+end
+```
+
+**Why manual setup is required:**
+- 🔧 **Master process** automatically detects cluster mode and skips listener startup  
+- 👷 **Worker processes** need explicit listener startup in `on_worker_boot` hook
+- 📡 **Each worker** gets its own listener thread for receiving broadcasts
+- 🔄 **Automatic cleanup** happens on worker shutdown
+
+### Manual Control
+
+```ruby
+# Manually start/stop listener
+FastMcpPubsub::Service.start_listener
+FastMcpPubsub::Service.stop_listener
+
+# Check listener status
+FastMcpPubsub::Service.listener_thread&.alive?
+```
+
+## How It Works
+
+1. **Patches FastMcp::Transports::RackTransport**: Overrides `send_message` method
+2. **Broadcasts via PostgreSQL**: Uses `NOTIFY channel, payload` 
+3. **Listener threads**: Each worker has a dedicated listener thread
+4. **Local delivery**: Messages are delivered to local SSE clients in each worker
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Enable/disable PubSub functionality |
+| `channel_name` | `'mcp_broadcast'` | PostgreSQL NOTIFY channel name |
+| `auto_start` | `true` | Start listener automatically |
+| `connection_pool_size` | `5` | Database connection pool size |
+
+**Note**: Logging is handled automatically via `FastMcpPubsub.logger` which returns `Rails.logger`.
+
+## Error Handling
+
+- **Payload size limit**: 7800 bytes (PostgreSQL NOTIFY limit)
+- **Fallback mechanism**: Falls back to local delivery if PubSub fails  
+- **Automatic restart**: Listener restarts on connection errors
+- **Graceful shutdown**: Proper cleanup on process exit
+
+## Requirements
+
+**This gem is an extension for Rails applications using FastMcp and requires:**
+
+- **[FastMcp gem](https://github.com/yjacquin/fast-mcp)** ~> 1.5.0 (the base MCP server this gem extends)
+- **Rails 7.0+** (required for Railtie integration)
+- **PostgreSQL database** (for NOTIFY/LISTEN functionality)
+- **Puma web server** in cluster mode (multi-worker setup)
+
+**Important Notes**:
+- This gem will not work in standalone Ruby applications or non-Rails frameworks, as it relies heavily on Rails infrastructure (ActiveRecord, Railtie, Rails.logger, etc.)
+- **PostgreSQL is mandatory** - this gem will NOT work with MySQL, SQLite, or other databases as it requires PostgreSQL's NOTIFY/LISTEN functionality. Support for other databases would require significant additional development.
+
+## Thread Safety
+
+All operations are thread-safe and designed for multi-worker environments:
+
+- Connection pooling for database operations
+- Proper thread lifecycle management  
+- Automatic cleanup on process termination
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup      # Install dependencies
+rake test      # Run tests
+bin/console    # Interactive prompt
+```
+
+To install locally:
+
+```bash
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jchsoft/fast_mcp_pubsub.
+
+## 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,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/fast_mcp_pubsub/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  # Configuration class for FastMcpPubsub gem settings
+  class Configuration
+    attr_accessor :enabled, :channel_name, :auto_start, :connection_pool_size
+
+    def initialize
+      @enabled = true
+      @channel_name = "mcp_broadcast"
+      @auto_start = true
+      @connection_pool_size = 5
+    end
+  end
+end

data/lib/fast_mcp_pubsub/rack_transport_patch.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Monkey patch for FastMcp::Transports::RackTransport
+# Adds PostgreSQL PubSub support for cluster mode
+
+module FastMcpPubsub
+  # Lazy patch application - applies patch when FastMcp transport is first accessed
+  module RackTransportPatch
+    @patch_applied = false
+
+    def self.apply_patch!
+      if @patch_applied
+        FastMcpPubsub.logger.debug "FastMcpPubsub: RackTransport patch already applied, skipping"
+        return
+      end
+
+      unless defined?(FastMcp::Transports::RackTransport)
+        FastMcpPubsub.logger.debug "FastMcpPubsub: FastMcp::Transports::RackTransport not defined yet, skipping patch"
+        return
+      end
+
+      FastMcpPubsub.logger.info "FastMcpPubsub: Patching FastMcp::Transports::RackTransport for PostgreSQL PubSub support"
+
+      patch_transport_class
+      @patch_applied = true
+      FastMcpPubsub.logger.info "FastMcpPubsub: RackTransport patch applied successfully"
+    end
+
+    def self.patch_transport_class
+      add_basic_methods
+      add_send_message_override
+      add_fallback_method
+    end
+
+    def self.add_basic_methods
+      FastMcp::Transports::RackTransport.class_eval do
+        alias_method :send_local_message, :send_message unless method_defined?(:send_local_message)
+        define_method(:running?) { @running } unless method_defined?(:running?)
+      end
+    end
+
+    def self.add_send_message_override
+      FastMcp::Transports::RackTransport.class_eval do
+        return if method_defined?(:send_message_with_pubsub)
+
+        alias_method :send_message_original, :send_message if method_defined?(:send_message)
+
+        define_method(:send_message) do |message|
+          FastMcpPubsub.config.enabled ? broadcast_with_fallback(message) : send_local_message(message)
+        end
+
+        alias_method :send_message_with_pubsub, :send_message
+      end
+    end
+
+    def self.add_fallback_method
+      FastMcp::Transports::RackTransport.class_eval do
+        return if method_defined?(:broadcast_with_fallback)
+
+        define_method(:broadcast_with_fallback) do |message|
+          FastMcpPubsub.logger.debug "RackTransport: Broadcasting message via PostgreSQL PubSub"
+          FastMcpPubsub::Service.broadcast(message)
+        rescue StandardError => e
+          FastMcpPubsub.logger.error "RackTransport: Error broadcasting message: #{e.message}"
+          send_local_message(message)
+        end
+      end
+    end
+
+    def self.patch_applied?
+      @patch_applied
+    end
+  end
+end
+
+# NOTE: Patch is automatically applied by Railtie initializer when Rails loads

data/lib/fast_mcp_pubsub/railtie.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  # Rails integration for automatic FastMcpPubsub setup and Puma cluster mode hooks
+  class Railtie < Rails::Railtie
+    # Start listener when Rails is ready
+    initializer "fast_mcp_pubsub.start_listener" do |app|
+      railtie = self
+      app.config.to_prepare do
+        # Non-cluster mode initialization (rails server)
+        # Only start if we're in a web server environment
+        Rails.logger.info "FastMcpPubsub: Checking listener startup conditions - cluster_mode: #{railtie.send(:cluster_mode?)}, should_start: #{railtie.send(:should_start_listener?)}"
+
+        if railtie.send(:should_start_listener?)
+          Rails.logger.info "FastMcpPubsub: Starting listener for non-cluster mode"
+          FastMcpPubsub::Service.start_listener
+          railtie.instance_variable_set(:@listener_started, true)
+        else
+          Rails.logger.info "FastMcpPubsub: Not starting listener in master process (cluster mode detected or conditions not met)"
+        end
+      end
+    end
+
+    # Apply patch to FastMcp::Transports::RackTransport after all initializers are loaded
+    initializer "fast_mcp_pubsub.apply_patch", after: :load_config_initializers do
+      FastMcpPubsub.logger.debug "FastMcpPubsub: Attempting to apply RackTransport patch"
+      FastMcpPubsub::RackTransportPatch.apply_patch!
+    end
+
+    # NOTE: For cluster mode, add FastMcpPubsub::Service.start_listener to your
+    # on_worker_boot hook in config/puma/production.rb
+
+    private
+
+    def should_start_listener?
+      web_server_environment? &&
+        !cluster_mode? &&
+        FastMcpPubsub.config.enabled &&
+        FastMcpPubsub.config.auto_start &&
+        !instance_variable_get(:@listener_started)
+    end
+
+    def web_server_environment?
+      defined?(Rails::Server) || defined?(Puma) || ENV["MCP_SERVER_AUTO_START"] == "true"
+    end
+
+    def cluster_mode?
+      # Check if Puma is running in cluster mode (multiple workers)
+      defined?(Puma.cli_config) &&
+        Puma.cli_config&.options&.[](:workers).to_i > 1
+    end
+  end
+end

data/lib/fast_mcp_pubsub/service.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module FastMcpPubsub
+  # Core PostgreSQL NOTIFY/LISTEN service for broadcasting MCP messages across Puma workers
+  class Service
+    MAX_PAYLOAD_SIZE = 7800 # PostgreSQL NOTIFY limit is 8000 bytes, leave some margin
+
+    class << self
+      attr_reader :listener_thread
+
+      def broadcast(message)
+        payload = message.to_json
+
+        payload_too_large?(payload) ? send_error_response(message, payload) : send_payload(payload)
+      rescue StandardError => e
+        FastMcpPubsub.logger.error "FastMcpPubsub: Error broadcasting message: #{e.message}"
+        raise
+      end
+
+      def start_listener
+        unless FastMcpPubsub.config.enabled
+          FastMcpPubsub.logger.info "FastMcpPubsub: Not starting listener - disabled in config for PID #{Process.pid}"
+          return
+        end
+
+        if @listener_thread&.alive?
+          FastMcpPubsub.logger.info "FastMcpPubsub: Listener already running for PID #{Process.pid}"
+          return
+        end
+
+        FastMcpPubsub.logger.info "FastMcpPubsub: Starting listener thread for PID #{Process.pid}"
+
+        @listener_thread = Thread.new do
+          Thread.current.name = "fast-mcp-pubsub-listener"
+          listen_loop
+        end
+
+        # Register shutdown hook
+        at_exit { stop_listener }
+      end
+
+      def stop_listener
+        return unless @listener_thread&.alive?
+
+        FastMcpPubsub.logger.info "FastMcpPubsub: Stopping listener thread for PID #{Process.pid}"
+        @listener_thread.kill
+        @listener_thread.join(5) # Wait max 5 seconds
+        @listener_thread = nil
+      end
+
+      private
+
+      def send_payload(payload)
+        channel = FastMcpPubsub.config.channel_name
+        FastMcpPubsub.logger.debug "FastMcpPubsub: Broadcasting message to #{channel}: #{payload.bytesize} bytes"
+
+        ActiveRecord::Base.connection.execute(
+          "NOTIFY #{channel}, #{ActiveRecord::Base.connection.quote(payload)}"
+        )
+      end
+
+      def payload_too_large?(payload)
+        payload.bytesize > MAX_PAYLOAD_SIZE
+      end
+
+      def send_error_response(message, payload)
+        FastMcpPubsub.logger.error "FastMcpPubsub: Payload too large (#{payload.bytesize} bytes > #{MAX_PAYLOAD_SIZE} bytes)"
+
+        error_message = {
+          jsonrpc: "2.0",
+          id: message[:id],
+          error: {
+            code: -32_001,
+            message: "Response too large for PostgreSQL NOTIFY. Try requesting smaller page size."
+          }
+        }
+
+        send_payload(error_message.to_json)
+      end
+
+      def listen_loop
+        channel = FastMcpPubsub.config.channel_name
+
+        begin
+          ActiveRecord::Base.connection_pool.with_connection do |conn|
+            raw_conn = conn.raw_connection
+
+            FastMcpPubsub.logger.info "FastMcpPubsub: Listening on #{channel} for PID #{Process.pid}"
+            raw_conn.async_exec("LISTEN #{channel}")
+
+            begin
+              loop do
+                raw_conn.wait_for_notify do |channel, pid, payload|
+                  handle_notification(channel, pid, payload)
+                end
+              end
+            ensure
+              begin
+                raw_conn.async_exec("UNLISTEN #{channel}")
+              rescue StandardError => e
+                FastMcpPubsub.logger.error "FastMcpPubsub: Error during UNLISTEN: #{e.message}"
+              end
+            end
+          end
+        rescue StandardError => e
+          FastMcpPubsub.logger.error "FastMcpPubsub: Listener error: #{e.message}"
+          FastMcpPubsub.logger.error e.backtrace.join("\n")
+
+          # Restart after error
+          sleep 1
+          retry
+        end
+      end
+
+      def handle_notification(_channel, pid, payload)
+        FastMcpPubsub.logger.debug "FastMcpPubsub: Received notification from PID #{pid}: #{payload}"
+
+        begin
+          message = JSON.parse(payload)
+
+          # Find active RackTransport instances and send to local clients
+          if defined?(FastMcp::Transports::RackTransport)
+            transports = transport_instances
+            FastMcpPubsub.logger.debug "FastMcpPubsub: Found #{transports.size} transport instances"
+
+            transports.each do |transport|
+              FastMcpPubsub.logger.debug "FastMcpPubsub: Sending message to transport #{transport.object_id}"
+              transport.send_local_message(message)
+            end
+          end
+        rescue JSON::ParserError => e
+          FastMcpPubsub.logger.error "FastMcpPubsub: Invalid JSON payload: #{e.message}"
+        rescue StandardError => e
+          FastMcpPubsub.logger.error "FastMcpPubsub: Error handling notification: #{e.message}"
+        end
+      end
+
+      def transport_instances
+        # Find all RackTransport instances - don't filter by running? since it's not reliably implemented
+        ObjectSpace.each_object(FastMcp::Transports::RackTransport).to_a
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/fast_mcp_pubsub/version.rb

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

data/lib/fast_mcp_pubsub.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "fast_mcp_pubsub/version"
+require_relative "fast_mcp_pubsub/configuration"
+require_relative "fast_mcp_pubsub/service"
+
+# PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport.
+# Enables FastMcp RackTransport to work in cluster mode by broadcasting messages
+# via PostgreSQL NOTIFY/LISTEN across multiple Puma workers.
+module FastMcpPubsub
+  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
+end
+
+# Load patch after module is fully defined
+require_relative "fast_mcp_pubsub/rack_transport_patch"
+require_relative "fast_mcp_pubsub/railtie" if defined?(Rails)

data/sig/fast_mcp_pubsub.rbs

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

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: fast_mcp_pubsub
+version: !ruby/object:Gem::Version
+  version: 1.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: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !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: 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 work in cluster mode by broadcasting
+  messages via PostgreSQL NOTIFY/LISTEN across multiple Puma workers
+email:
+- chmel@jchsoft.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".mcp.json"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/.DS_Store
+- lib/fast_mcp_pubsub.rb
+- lib/fast_mcp_pubsub/configuration.rb
+- lib/fast_mcp_pubsub/rack_transport_patch.rb
+- lib/fast_mcp_pubsub/railtie.rb
+- lib/fast_mcp_pubsub/service.rb
+- lib/fast_mcp_pubsub/version.rb
+- sig/fast_mcp_pubsub.rbs
+homepage: https://github.com/jchsoft/fast_mcp_pubsub
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/jchsoft/fast_mcp_pubsub
+  source_code_uri: https://github.com/jchsoft/fast_mcp_pubsub
+  changelog_uri: https://github.com/jchsoft/fast_mcp_pubsub/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: PostgreSQL NOTIFY/LISTEN clustering support for FastMcp RackTransport
+test_files: []