solid_mcp 0.0.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29d6d3f0a1664e3251f979c1b7101118bcbebfe8d3d9527dcaa882d21fe4e5b8
-  data.tar.gz: e82f187470b4f1000c636762923500d416824ba22dc03271867d23326591edb3
+  metadata.gz: 3aa4d7472deba4836dde19ecd8f77ddf711078e1e67653e217234e68db7e8aba
+  data.tar.gz: 980e352ee18764b440a56cad8c8201e9158288ba617812181b72fc04af2c1405
 SHA512:
-  metadata.gz: 3ec8873e380d109bce8aeae2765ebf7f9a3d5038279ffd665632fafd5afaf18f78f5b74260fd66f63e617b89ddc6dcb3cdcfe7563f7d85b1a9c13c9c1894e470
-  data.tar.gz: adc942e4024067f9d99b3cf3089ed5e064a6451a33d170b12214dc3a24de4b95ef8b10122df6997f2a30beda86c6c1bcc36c6df01e641b1547766bf058b684b6
+  metadata.gz: ec42aab4269af5a30ae4bf9378cdbbbd0e3e00fc52fdf000ecd05367d520f59dc275e4d4ec536d887508e8fbf93c3de915aeed505a8a31d95439fa3e61f0dd4b
+  data.tar.gz: a9804075acc655457b4e857d154278ef3125706478048ec822ce42a8da29e335777017666831ef3b9793cc4bbf7add35d90fb2ae8ff6e74914f78e716ba5cccd

data/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.1"}

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [0.2.1](https://github.com/seuros/solid_mcp/compare/solid_mcp/v0.2.0...solid_mcp/v0.2.1) (2025-07-01)
+
+
+### Bug Fixes
+
+* add issues permission to release workflow ([dd6d90d](https://github.com/seuros/solid_mcp/commit/dd6d90d5d3e87987c80215401bc422abf02da1b0))
+* add issues permission to release workflow ([1105f92](https://github.com/seuros/solid_mcp/commit/1105f926d1266f107dad80839c1ae7bd178f8bd0))
+
+## [0.2.0](https://github.com/seuros/solid_mcp/compare/solid_mcp-v0.1.0...solid_mcp/v0.2.0) (2025-07-01)
+
+
+### Features
+
+* initial implementation of SolidMCP ([6123b7a](https://github.com/seuros/solid_mcp/commit/6123b7a04a7a726892f04da9e33147ce2bfcfeb5))
+
 ## [0.1.0] - 2025-05-20
 
 - Initial release

data/Gemfile.lock

@@ -0,0 +1,140 @@
+PATH
+  remote: .
+  specs:
+    solid_mcp (0.2.1)
+      activejob (>= 8.0)
+      activerecord (>= 8.0)
+      concurrent-ruby (~> 1.0)
+      railties (>= 8.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (8.0.2)
+      actionview (= 8.0.2)
+      activesupport (= 8.0.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actionview (8.0.2)
+      activesupport (= 8.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.3.6)
+    activemodel (8.0.2)
+      activesupport (= 8.0.2)
+    activerecord (8.0.2)
+      activemodel (= 8.0.2)
+      activesupport (= 8.0.2)
+      timeout (>= 0.4.0)
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.3)
+    crass (1.0.6)
+    date (3.4.1)
+    drb (2.2.1)
+    erb (5.0.1)
+    erubi (1.13.1)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    minitest (5.25.5)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.2.6)
+      date
+      stringio
+    racc (1.8.1)
+    rack (3.1.15)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.14.0)
+      erb
+      psych (>= 4.0.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    securerandom (0.4.1)
+    sqlite3 (2.7.0-arm64-darwin)
+    sqlite3 (2.7.0-x86_64-linux-gnu)
+    stringio (3.1.7)
+    thor (1.3.2)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    zeitwerk (2.7.3)
+
+PLATFORMS
+  arm64-darwin-24
+  x86_64-linux
+
+DEPENDENCIES
+  irb
+  minitest (~> 5.16)
+  rake (~> 13.0)
+  solid_mcp!
+  sqlite3 (~> 2.0)
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -1,39 +1,328 @@
-# SolidMcp
+# SolidMCP
 
-TODO: Delete this and the text below, and describe your gem
+SolidMCP is a high-performance, database-backed pub/sub engine specifically designed for ActionMCP (Model Context Protocol for Rails). It provides reliable message delivery for MCP's Server-Sent Events (SSE) with support for SQLite, PostgreSQL, and MySQL.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/solid_mcp`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Features
+
+- **Database-agnostic**: Works with SQLite, PostgreSQL, and MySQL
+- **Session-based routing**: Optimized for MCP's point-to-point messaging pattern
+- **Batched writes**: Handles SQLite's single-writer limitation efficiently
+- **Automatic cleanup**: Configurable retention periods for delivered/undelivered messages
+- **Thread-safe**: Dedicated writer thread with in-memory queuing
+- **SSE resumability**: Supports reconnection with last-event-id
+- **Rails Engine**: Seamless integration with Rails applications
+- **Multiple backends**: Database backend by default, Redis backend coming soon
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 8.0+
+- ActiveRecord 8.0+
+- SQLite, PostgreSQL, or MySQL database
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'solid_mcp'
+```
 
-Install the gem and add to the application's Gemfile by executing:
+And then execute:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Run the installation generator:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bin/rails generate solid_mcp:install
+bin/rails db:migrate
+```
+
+This will:
+- Create a migration for the `solid_mcp_messages` table
+- Create an initializer with default configuration
+
+## Configuration
+
+Configure SolidMCP in your Rails application:
+
+```ruby
+# config/initializers/solid_mcp.rb
+SolidMcp.configure do |config|
+  # Number of messages to write in a single batch
+  config.batch_size = 200
+  
+  # Seconds between batch flushes
+  config.flush_interval = 0.05
+  
+  # Polling interval for checking new messages
+  config.polling_interval = 0.1
+  
+  # Maximum time to wait for messages before timeout
+  config.max_wait_time = 30
+  
+  # How long to keep delivered messages
+  config.delivered_retention = 1.hour
+  
+  # How long to keep undelivered messages
+  config.undelivered_retention = 24.hours
+end
 ```
 
-## Usage
+## Usage with ActionMCP
+
+In your `config/mcp.yml`:
+
+```yaml
+production:
+  adapter: solid_mcp
+  polling_interval: 0.5.seconds
+  batch_size: 200
+  flush_interval: 0.05
+```
+
+## Architecture
+
+SolidMCP is implemented as a Rails Engine with the following components:
+
+### Core Components
+
+1. **SolidMCP::MessageWriter**: Singleton that handles batched writes to the database
+   - Non-blocking enqueue operation
+   - Dedicated writer thread per Rails process
+   - Automatic batching and flushing
+   - Graceful shutdown with pending message delivery
+
+2. **SolidMCP::PubSub**: Main interface for publishing and subscribing to messages
+   - Session-based subscriptions (not channel-based)
+   - Automatic listener management per session
+   - Thread-safe operations
+
+3. **SolidMCP::Subscriber**: Handles polling for new messages
+   - Efficient database queries using indexes
+   - Automatic message delivery tracking
+   - Configurable polling intervals
 
-TODO: Write usage instructions here
+4. **SolidMCP::Message**: ActiveRecord model for message storage
+   - Optimized indexes for polling and cleanup
+   - Scopes for message filtering
+   - Built-in cleanup methods
+
+### Message Flow
+
+1. Publisher calls `broadcast(session_id, event_type, data)`
+2. MessageWriter queues the message in memory
+3. Writer thread batches messages and writes to database
+4. Subscriber polls for new messages for its session
+5. Messages are marked as delivered after successful processing
+
+## Database Schema
+
+The gem creates a `solid_mcp_messages` table:
+
+```ruby
+create_table :solid_mcp_messages do |t|
+  t.string :session_id, null: false, limit: 36      # MCP session identifier
+  t.string :event_type, null: false, limit: 50      # SSE event type
+  t.text :data                                       # Message payload (usually JSON)
+  t.datetime :created_at, null: false                # Message creation time
+  t.datetime :delivered_at                           # Delivery timestamp
+  
+  t.index [:session_id, :id], name: 'idx_solid_mcp_messages_on_session_and_id'
+  t.index [:delivered_at, :created_at], name: 'idx_solid_mcp_messages_on_delivered_and_created'
+end
+```
+
+## Performance Considerations
+
+### SQLite
+- Single writer thread prevents "database is locked" errors
+- Batching reduces write frequency
+- Consider WAL mode for better concurrency
+
+### PostgreSQL/MySQL
+- Benefits from batching to reduce transaction overhead
+- Can handle multiple writers but single writer is maintained for consistency
+- Consider partitioning for high-volume applications
+
+## Maintenance
+
+### Automatic Cleanup
+
+Old messages are automatically cleaned up based on retention settings:
+
+```ruby
+# Run periodically (e.g., with whenever gem or solid_queue)
+SolidMCP::CleanupJob.perform_later
+
+# Or directly:
+SolidMCP::Message.cleanup
+```
+
+### Manual Cleanup
+
+```ruby
+# Clean up delivered messages older than 1 hour
+SolidMCP::Message.old_delivered(1.hour).delete_all
+
+# Clean up undelivered messages older than 24 hours
+SolidMCP::Message.old_undelivered(24.hours).delete_all
+```
+
+### Monitoring
+
+```ruby
+# Check message queue size
+SolidMCP::Message.undelivered.count
+
+# Check messages for a specific session
+SolidMCP::Message.for_session(session_id).count
+
+# Find stuck messages
+SolidMCP::Message.undelivered.where('created_at < ?', 1.hour.ago)
+```
+
+## Testing
+
+The gem includes a test implementation for use in test environments:
+
+```ruby
+# In test environment, SolidMCP::PubSub automatically uses TestPubSub
+# which provides immediate delivery without database persistence
+```
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+### Testing in Your Application
+
+```ruby
+# test/test_helper.rb
+class ActiveSupport::TestCase
+  setup do
+    SolidMCP::Message.delete_all
+  end
+end
+
+# In your tests
+test "broadcasts message to session" do
+  pubsub = SolidMCP::PubSub.new
+  messages = []
+  
+  pubsub.subscribe("test-session") do |msg|
+    messages << msg
+  end
+  
+  pubsub.broadcast("test-session", "test_event", { data: "test" })
+  
+  assert_equal 1, messages.size
+  assert_equal "test_event", messages.first[:event_type]
+end
+```
+
+## SSE Integration
+
+SolidMCP is designed to work seamlessly with Server-Sent Events:
+
+```ruby
+# In your SSE controller
+def sse_endpoint
+  response.headers['Content-Type'] = 'text/event-stream'
+  
+  pubsub = SolidMCP::PubSub.new
+  last_event_id = request.headers['Last-Event-ID']
+  
+  # Resume from last event if reconnecting
+  if last_event_id
+    missed_messages = SolidMCP::Message
+      .for_session(session_id)
+      .after_id(last_event_id)
+      .undelivered
+    
+    missed_messages.each do |msg|
+      response.stream.write "id: #{msg.id}\n"
+      response.stream.write "event: #{msg.event_type}\n"
+      response.stream.write "data: #{msg.data}\n\n"
+    end
+  end
+  
+  # Subscribe to new messages
+  pubsub.subscribe(session_id) do |message|
+    response.stream.write "id: #{message[:id]}\n"
+    response.stream.write "event: #{message[:event_type]}\n"
+    response.stream.write "data: #{message[:data]}\n\n"
+  end
+ensure
+  pubsub&.unsubscribe(session_id)
+  response.stream.close
+end
+```
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+bundle exec ruby test/solid_mcp/message_test.rb
+```
+
+## Roadmap
+
+### Redis Backend (Coming Soon)
+
+Future versions will support Redis as an alternative backend:
+
+```ruby
+# config/initializers/solid_mcp.rb
+SolidMCP.configure do |config|
+  config.backend = :redis
+  config.redis_url = ENV['REDIS_URL']
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+This will provide:
+- Lower latency for high-traffic applications
+- Pub/Sub without polling
+- Automatic expiration of old messages
+- Better horizontal scaling
+
+## Comparison with Other Solutions
+
+| Feature | SolidMCP | ActionCable + Redis | Custom Polling |
+|---------|----------|-------------------|----------------|
+| No Redis Required | ✅ | ❌ | ✅ |
+| SSE Resumability | ✅ | ❌ | Manual |
+| Horizontal Scaling | ✅ (with DB) | ✅ | ❌ |
+| Message Persistence | ✅ | ❌ | Manual |
+| Batch Writing | ✅ | N/A | ❌ |
+| SQLite Support | ✅ | ❌ | ✅ |
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/solid_mcp.
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/solid_mcp.
+
+### Development Setup
+
+1. Fork the repository
+2. Clone your fork
+3. Install dependencies: `bundle install`
+4. Create a feature branch: `git checkout -b my-feature`
+5. Make your changes and add tests
+6. Run tests: `bundle exec rake test`
+7. Push to your fork and submit a pull request
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/solid_mcp/message.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  class Message < Record
+    self.table_name = "solid_mcp_messages"
+
+    scope :for_session, ->(session_id) { where(session_id: session_id) }
+    scope :undelivered, -> { where(delivered_at: nil) }
+    scope :delivered, -> { where.not(delivered_at: nil) }
+    scope :after_id, ->(id) { where("id > ?", id) }
+    scope :old_delivered, ->(age) { delivered.where("delivered_at < ?", age.ago) }
+    scope :old_undelivered, ->(age) { undelivered.where("created_at < ?", age.ago) }
+
+    # Mark messages as delivered
+    def self.mark_delivered(ids)
+      where(id: ids).update_all(delivered_at: Time.current)
+    end
+
+    # Cleanup old messages
+    def self.cleanup(delivered_retention: 1.hour, undelivered_retention: 24.hours)
+      old_delivered(delivered_retention).delete_all
+      old_undelivered(undelivered_retention).delete_all
+    end
+  end
+end

data/app/models/solid_mcp/record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module SolidMCP
+  class Record < ActiveRecord::Base
+    self.abstract_class = true
+
+    # Use primary database connection by default
+    # Can be overridden with connects_to in production if needed
+  end
+end

data/bin/rails

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path('..', __dir__)
+APP_PATH = File.expand_path('../test/dummy/config/application', __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails/all'
+require 'rails/engine/commands'

data/bin/test

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "minitest/autorun"
+
+# Load all test files
+Dir[File.expand_path("../test/**/*_test.rb", __dir__)].each { |f| require f }

data/db/migrate/20250624000001_create_solid_mcp_messages.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class CreateSolidMCPMessages < ActiveRecord::Migration[7.0]
+  def change
+    create_table :solid_mcp_messages do |t|
+      # Session this message belongs to
+      t.string :session_id, null: false, limit: 36
+      
+      # Type of event (e.g., 'message', 'ping', 'connection_closed')
+      t.string :event_type, null: false, limit: 50
+      
+      # The actual data payload
+      t.text :data
+      
+      # Timestamp when message was created
+      t.datetime :created_at, null: false
+      
+      # Timestamp when message was delivered
+      t.datetime :delivered_at
+      
+      # Composite index for efficient polling
+      t.index [:session_id, :id], name: 'idx_solid_mcp_messages_on_session_and_id'
+      
+      # Index for cleanup
+      t.index [:delivered_at, :created_at], name: 'idx_solid_mcp_messages_on_delivered_and_created'
+    end
+  end
+end

data/lib/generators/solid_mcp/install/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module SolidMCP
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "create_solid_mcp_messages.rb.erb", "db/migrate/create_solid_mcp_messages.rb"
+      end
+
+      def add_initializer
+        template "solid_mcp.rb", "config/initializers/solid_mcp.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/solid_mcp/install/templates/create_solid_mcp_messages.rb.erb

@@ -0,0 +1,26 @@
+class CreateSolidMCPMessages < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :solid_mcp_messages do |t|
+      # Session this message belongs to
+      t.string :session_id, null: false, limit: 36
+      
+      # Type of event (e.g., 'message', 'ping', 'connection_closed')
+      t.string :event_type, null: false, limit: 50
+      
+      # The actual data payload
+      t.text :data
+      
+      # Timestamp when message was created
+      t.datetime :created_at, null: false
+      
+      # Timestamp when message was delivered
+      t.datetime :delivered_at
+      
+      # Composite index for efficient polling
+      t.index [:session_id, :id], name: 'idx_solid_mcp_messages_on_session_and_id'
+      
+      # Index for cleanup
+      t.index [:delivered_at, :created_at], name: 'idx_solid_mcp_messages_on_delivered_and_created'
+    end
+  end
+end

data/lib/generators/solid_mcp/install/templates/solid_mcp.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Initialize SolidMCP message writer
+Rails.application.config.to_prepare do
+  # Ensure the writer thread is started
+  SolidMCP::MessageWriter.instance
+end
+
+# Gracefully shutdown on exit
+at_exit do
+  SolidMCP::MessageWriter.instance.shutdown if defined?(SolidMCP::MessageWriter)
+end
+
+# Configure SolidMCP
+SolidMCP.configure do |config|
+  config.batch_size = 200
+  config.flush_interval = 0.05
+  config.delivered_retention = 1.hour
+  config.undelivered_retention = 24.hours
+end