Understanding Model-Context-Protocol (MCP) in Ruby

What is the Model-Context-Protocol (MCP) Pattern?

The Model-Context-Protocol (MCP) pattern is an architectural design pattern offering a structured approach to organizing application logic, particularly beneficial in systems with complex business rules and requirements. Unlike the widely known Model-View-Controller (MVC) pattern, which primarily focuses on separating user interface concerns, MCP concentrates on organizing the domain logic – the core business rules and processes of your application – into distinct, manageable components.

Think of MCP as a way to bring clarity and structure within the "M" (Model) layer of a traditional MVC, or as a standalone pattern for organizing backend services or libraries where UI separation isn't the main concern.

Core Components of MCP

MCP achieves its structure through three key components:

1. Model: Represents the data structures and their inherent attributes. Models in MCP are intentionally kept simple, acting as data carriers with minimal behavior, often resembling Data Transfer Objects (DTOs) or plain structs.

2. Context: Encapsulates specific use cases, business processes, or application workflows. Contexts orchestrate operations, manipulate models according to business rules, and contain the bulk of the application's domain logic.

3. Protocol: Defines the contracts, interfaces, or APIs between different parts of the system, particularly how Contexts interact with external dependencies (like databases, external APIs) or even with each other. Protocols promote loose coupling and enhance testability by defining clear interaction boundaries.

Let's delve deeper into each component:

Models: The Data Structures

In MCP, Models are stripped down to their essential data-holding role. They typically:

• Represent domain entities (e.g., User, Order, Product).
• Contain attributes and potentially basic validation related to data integrity (e.g., presence, format), but not business rules.
• Are focused on structure and state, not complex behavior. Methods on models are usually limited to data formatting or simple calculations based only on the model's own attributes.
• Are easily serializable/deserializable, facilitating data transfer and persistence.

Key Idea: Keep models lean and focused on what data represents, not how it's manipulated in business processes.

Contexts: The Business Logic Hubs

Contexts are the heart of the business logic implementation. They:

• Implement specific application use cases (e.g., AuthenticateUser, CreateOrder, ProcessPayment).
• Orchestrate interactions between Models, Repositories (via Protocols), and potentially other Contexts.
• Contain the business rules, decision-making logic, and workflow steps.
• Are designed to be cohesive, focusing on a single responsibility or use case.
• Can be composed – complex workflows can be built by having one Context utilize others, promoting reusability.

Key Idea: Contexts encapsulate how the application achieves a specific business goal, acting on Models based on defined rules.

Protocols: The Contracts and Interfaces

Protocols define the "how-to-talk" rules between components. In Ruby, these are often implemented using Modules, but the concept emphasizes the contract itself. They:

• Specify the methods and signatures required for interactions (e.g., how to fetch a user, how to charge a credit card).
• Define the expected inputs, outputs, and potential errors for operations.
• Enable Dependency Inversion: Contexts depend on the abstract Protocol, not concrete implementations (like a specific database adapter or payment gateway). This is crucial for flexibility and testing.
• Make testing easier by allowing mock implementations (stubs, fakes) that adhere to the Protocol during unit tests.

Key Idea: Protocols define stable interfaces, decoupling the business logic (Contexts) from the implementation details of infrastructure concerns (data access, external services).

Implementing MCP in Ruby

Ruby's dynamic nature and strong support for modules make it a natural fit for MCP.

Directory Structure Suggestion

A common way to organize an MCP application in Ruby:

app/
├── models/                    # Data structures
│   ├── user.rb
│   └── order.rb
├── contexts/                  # Business logic / Use cases
│   ├── authentication/
│   │   ├── login_context.rb
│   │   └── registration_context.rb
│   └── orders/
│       ├── create_order_context.rb
│       └── process_payment_context.rb
├── protocols/                 # Interfaces / Contracts (often Modules)
│   ├── user_repository_protocol.rb  # More specific than just 'authentication'
│   ├── order_repository_protocol.rb
│   ├── payment_gateway_protocol.rb
│   └── notification_protocol.rb
├── repositories/              # Concrete implementations for data access
│   ├── active_record_user_repository.rb
│   └── memory_order_repository.rb
└── services/                  # Concrete implementations for external services
    ├── stripe_payment_gateway.rb
    └── email_notification_service.rb

(Note: Repositories and Services implement the defined Protocols)

Example Implementation

1. Models (Keeping them simple)

# app/models/user.rb
class User
  attr_accessor :id, :username, :email, :password_digest

  def initialize(attributes = {})
    @id = attributes[:id]
    @username = attributes[:username]
    @email = attributes[:email]
    @password_digest = attributes[:password_digest] # Store hashed password
  end

  # Basic validation (presence check)
  def valid?
    !username.to_s.empty? && !email.to_s.empty? && !password_digest.to_s.empty?
  end

  # Simple serialization, excluding sensitive data
  def to_h
    { id: id, username: username, email: email }
  end
end

# app/models/order.rb
class Order
  attr_accessor :id, :user_id, :items, :total_amount, :status
  VALID_STATUSES = ['pending', 'paid', 'shipped', 'cancelled', 'refunded'].freeze

  def initialize(attributes = {})
    @id = attributes[:id]
    @user_id = attributes[:user_id]
    @items = attributes[:items] || [] # Expecting array of hashes like { product_id:, price:, quantity: }
    @total_amount = attributes[:total_amount] || calculate_total
    @status = attributes[:status] || 'pending'
  end

  def calculate_total
    items.sum { |item| (item[:price] || 0) * (item[:quantity] || 0) }
  end

  def valid?
    !user_id.nil? && !items.empty? && VALID_STATUSES.include?(status)
  end

  def to_h
    { id: id, user_id: user_id, items: items, total_amount: total_amount, status: status }
  end
end

2. Protocols (Defining contracts)

# app/protocols/user_repository_protocol.rb
module UserRepositoryProtocol
  # Finds a user by their unique ID
  # @param id [Integer]
  # @return [User, nil]
  def find(id)
    raise NotImplementedError, "#{self.class}#find"
  end

  # Finds a user by their email address
  # @param email [String]
  # @return [User, nil]
  def find_by_email(email)
    raise NotImplementedError, "#{self.class}#find_by_email"
  end

  # Saves a user (either creates or updates)
  # @param user [User]
  # @return [User] The saved user, potentially with an assigned ID
  # @raise [PersistenceError] if saving fails
  def save(user)
    raise NotImplementedError, "#{self.class}#save"
  end
end

# app/protocols/payment_gateway_protocol.rb
module PaymentGatewayProtocol
  # Processes a payment charge
  # @param amount [Float] Amount to charge
  # @param payment_details [Hash] Details like card number, expiry, etc.
  # @param order_id [Integer] Reference order ID
  # @return [Hash] { success: true, transaction_id: '...' } or { success: false, message: '...' }
  def charge(amount:, payment_details:, order_id:)
    raise NotImplementedError, "#{self.class}#charge"
  end

  # Processes a refund
  # @param transaction_id [String] The original transaction ID to refund
  # @param amount [Float, nil] Amount to refund (optional, might default to full)
  # @return [Hash] { success: true, refund_id: '...' } or { success: false, message: '...' }
  def refund(transaction_id:, amount: nil)
    raise NotImplementedError, "#{self.class}#refund"
  end
end

(OrderRepositoryProtocol and NotificationProtocol would be similar)

3. Contexts (Implementing use cases)

# app/contexts/authentication/registration_context.rb
require_relative '../../protocols/user_repository_protocol'
require_relative '../../models/user'
# Assume BCrypt is available for password hashing
require 'bcrypt'

class RegistrationContext
  # Inject the dependency adhering to the protocol
  def initialize(user_repository)
    # Type check (optional but good practice)
    unless user_repository.is_a?(UserRepositoryProtocol)
      raise ArgumentError, "user_repository must implement UserRepositoryProtocol"
    end
    @user_repository = user_repository
  end

  # Implement the registration use case
  def register(username:, email:, password:)
    # Check for existing user
    if @user_repository.find_by_email(email)
      return { success: false, error_code: 'EMAIL_TAKEN', message: "Email already registered" }
    end

    # Create and validate the new user model
    user = User.new(
      username: username,
      email: email,
      password_digest: hash_password(password) # Hash password immediately
    )

    unless user.valid?
      # Ideally, collect specific validation errors from the model
      return { success: false, error_code: 'INVALID_DATA', message: "Invalid user data provided" }
    end

    # Attempt to save the user via the repository
    begin
      saved_user = @user_repository.save(user)
      { success: true, user: saved_user }
    rescue => e # Catch potential persistence errors
      # Log the error e
      { success: false, error_code: 'REGISTRATION_FAILED', message: "Could not register user due to a system error." }
    end
  end

  private

  def hash_password(password)
    # Use a strong hashing library in a real application
    BCrypt::Password.create(password)
  end
end

# app/contexts/orders/process_payment_context.rb
require_relative '../../protocols/order_repository_protocol'
require_relative '../../protocols/payment_gateway_protocol'

class ProcessPaymentContext
  def initialize(order_repository, payment_gateway)
    # Add checks to ensure dependencies implement their protocols
    @order_repository = order_repository
    @payment_gateway = payment_gateway
  end

  def process_payment(order_id:, payment_details:)
    order = @order_repository.find(order_id)
    return { success: false, message: "Order not found" } unless order
    return { success: false, message: "Order already paid" } if order.status == 'paid'
    return { success: false, message: "Cannot pay for cancelled order" } if order.status == 'cancelled'

    # Use the injected payment gateway (adhering to PaymentGatewayProtocol)
    payment_result = @payment_gateway.charge(
      amount: order.total_amount,
      payment_details: payment_details,
      order_id: order.id
    )

    if payment_result[:success]
      order.status = 'paid'
      # Persist the change - potentially wrap in a transaction with payment
      begin
        @order_repository.update(order) # Assume update method exists
        # Store payment_result[:transaction_id] associated with the order if needed
        { success: true, order: order, transaction_id: payment_result[:transaction_id] }
      rescue => e
        # Log error e
        # IMPORTANT: Consider refunding/voiding payment if order update fails
        { success: false, message: "Payment succeeded but failed to update order status. Please contact support." }
      end
    else
      { success: false, message: "Payment failed: #{payment_result[:message]}" }
    end
  end

  # refund_payment implementation would follow similarly...
end

4. Repository & Gateway Implementations (Concrete Details)

These classes would implement the methods defined in their respective protocols, interacting with databases (e.g., ActiveRecord, Sequel) or external APIs (e.g., using HTTP clients like Faraday or HTTParty).

# app/repositories/memory_user_repository.rb
# (Implements UserRepositoryProtocol - useful for testing or simple cases)
require_relative '../protocols/user_repository_protocol'

class MemoryUserRepository
  include UserRepositoryProtocol # Declare implementation

  def initialize
    @users = {}
    @id_counter = 1
  end

  def find(id)
    @users[id]&.clone # Return a copy to prevent mutation issues
  end

  def find_by_email(email)
    @users.values.find { |user| user.email == email }&.clone
  end

  def save(user)
    unless user.is_a?(User) && user.valid?
      raise ArgumentError, "Invalid user object provided"
    end

    # Simulate persistence error possibility
    # raise "Simulated DB Error" if rand(10) == 0

    if user.id.nil? # New user
      user.id = @id_counter
      @id_counter += 1
    end

    @users[user.id] = user.clone # Store a copy
    user # Return the original user with ID assigned
  end

  # Add update, delete etc. as needed by protocol/contexts
end

# app/services/mock_payment_gateway.rb
# (Implements PaymentGatewayProtocol - useful for testing)
require_relative '../protocols/payment_gateway_protocol'
require 'securerandom'

class MockPaymentGateway
  include PaymentGatewayProtocol

  def charge(amount:, payment_details:, order_id:)
    puts "[MockGateway] Charging #{amount} for order #{order_id}"

    # Simulate basic validation or failure conditions
    if payment_details[:card_number].to_s.end_with?('9999')
      puts "[MockGateway] Charge FAILED (Simulated Decline)"
      { success: false, message: "Card declined" }
    else
      puts "[MockGateway] Charge SUCCESSFUL"
      { success: true, transaction_id: "txn_#{SecureRandom.uuid}" }
    end
  end

  def refund(transaction_id:, amount: nil)
    puts "[MockGateway] Refunding transaction #{transaction_id}"
    { success: true, refund_id: "ref_#{SecureRandom.uuid}" }
  end
end

Testing in MCP

Testing becomes significantly easier because components are decoupled via protocols.

• Models: Test their simple validations and data handling in isolation.
• Contexts: Unit test contexts by providing mock implementations of the protocols they depend on (e.g., mock repositories, mock payment gateways). This allows testing the business logic without hitting real databases or external services.
• Protocols: While you don't "test" a module directly, you test the implementations of that protocol to ensure they adhere to the contract. You can also create shared examples/tests (like RSpec's shared_examples_for) to verify that different implementations of the same protocol behave consistently.
• Repositories/Services: Test these concrete implementations against their real counterparts (e.g., integration tests hitting a test database or a sandbox API).

# test/contexts/authentication/registration_context_test.rb
require 'minitest/autorun'
require_relative '../../../app/contexts/authentication/registration_context'
require_relative '../../../app/models/user'
require_relative '../../../app/protocols/user_repository_protocol'

# Create a mock repository for testing the context
class MockUserRepository
  include UserRepositoryProtocol # Ensure it adheres to the contract

  def initialize
    @users_by_email = {}
    @saved_users = []
  end

  # Mock implementation
  def find_by_email(email)
    @users_by_email[email]
  end

  # Mock implementation
  def save(user)
    # Simulate potential error
    raise "DB Error" if user.username == "fail_save"

    # Simulate saving
    user.id ||= @saved_users.size + 1
    @users_by_email[user.email] = user
    @saved_users << user
    user
  end

  # Helper for test setup
  def add_existing_user(user)
    @users_by_email[user.email] = user
  end
end

class RegistrationContextTest < Minitest::Test
  def setup
    @mock_repo = MockUserRepository.new
    @context = RegistrationContext.new(@mock_repo) # Inject the mock
  end

  def test_successful_registration
    result = @context.register(username: 'new_user', email: '[e-mail]', password: 'password123')

    assert result[:success], "Registration should be successful"
    assert_instance_of User, result[:user], "Should return a user object"
    assert_equal '[e-mail]', result[:user].email
    assert @mock_repo.find_by_email('[e-mail]'), "User should be findable in repo after save"
  end

  def test_registration_fails_if_email_taken
    existing_user = User.new(email: '[e-mail]', username: 'existing', password_digest: 'hashed')
    @mock_repo.add_existing_user(existing_user)

    result = @context.register(username: 'another_user', email: '[e-mail]', password: 'password123')

    refute result[:success], "Registration should fail"
    assert_equal 'EMAIL_TAKEN', result[:error_code]
  end

  def test_registration_fails_on_invalid_data
    # Assuming User model validation fails for blank username
    result = @context.register(username: '', email: '[e-mail]', password: 'password123')

    refute result[:success], "Registration should fail"
    assert_equal 'INVALID_DATA', result[:error_code]
  end

  def test_registration_fails_on_repository_error
    result = @context.register(username: 'fail_save', email: '[e-mail]', password: 'password123')

    refute result[:success], "Registration should fail on repo error"
    assert_equal 'REGISTRATION_FAILED', result[:error_code]
  end
end

Benefits of Using MCP in Ruby

1. Enhanced Separation of Concerns: Business logic (Contexts) is clearly isolated from data structures (Models) and infrastructure details (implementations behind Protocols).

2. Improved Testability: Contexts can be unit-tested easily by mocking dependencies defined by Protocols. Models are simple to test. Infrastructure layers can be tested separately.

3. Increased Maintainability: Changes to business logic within a Context are less likely to impact unrelated areas. Swapping infrastructure (e.g., changing database, payment provider) only requires a new implementation of the relevant Protocol, leaving Contexts untouched.

4. Greater Flexibility & Reusability: Protocols allow easy swapping of implementations. Contexts, representing specific use cases, can often be reused across different entry points (e.g., web controller, API endpoint, background job).

5. Scalability of Development: Different teams or developers can work on different Contexts or infrastructure implementations more independently once Protocols are defined.

6. Clearer Domain Modeling: Encourages developers to think explicitly about use cases (Contexts) and the contracts (Protocols) needed to fulfill them.

Potential Drawbacks and Considerations

1. Increased Boilerplate: Defining Protocols and separating logic into distinct Context classes can introduce more files and code compared to simpler patterns, especially for basic CRUD operations.

2. Learning Curve: Developers need to understand the roles of M, C, and P and the importance of dependency inversion. It requires discipline to maintain the separation.

3. Over-Engineering Risk: For very simple applications, MCP might be overkill, leading to unnecessary complexity.

4. Protocol Design: Defining effective Protocols requires careful thought. They should be stable and represent logical boundaries. Poorly designed protocols can negate the benefits.

When to Choose MCP

MCP is particularly well-suited for:

• Applications with complex, evolving business logic.
• Systems where high testability is a critical requirement.
• Long-term projects where maintainability and adaptability are paramount.
• Teams where clear boundaries between different parts of the application are needed.
• Situations where you might need to swap out underlying infrastructure (databases, external services) in the future.

It might be less suitable for:

• Very small applications or simple CRUD APIs where the overhead isn't justified.
• Rapid prototyping where initial speed is valued over long-term structure (though refactoring towards MCP later is possible).

Common Pitfalls

• Fat Models: Allowing business logic to creep back into Models.
• Fat Contexts: Contexts trying to do too much; they should ideally represent a single use case or a cohesive set of related operations. Consider composing contexts if one becomes too large.
• Leaky Protocols: Protocols exposing implementation details or being too tightly coupled to a specific implementation.
• Ignoring Dependency Injection: Directly instantiating concrete repository/service classes within Contexts negates the benefits of Protocols and hinders testing. Always inject dependencies.
• Inconsistent Error Handling: Contexts returning errors in different formats. Establish a standard way (e.g., Result objects, consistent hash structures, custom error classes) to report success or failure.

MCP vs Other Patterns

MCP vs MVC (e.g., Ruby on Rails default)

• Focus: MVC is UI-centric; MCP is domain-logic-centric.
• Controller Role: MVC Controllers often handle request parsing, business logic orchestration, and response preparation. In an MCP-integrated approach, the Controller becomes thinner, delegating the core work to Contexts.
• Model Role: MVC Models (especially ActiveRecord) often mix data structure, persistence logic, callbacks, and sometimes business rules. MCP pushes for leaner Models, moving logic to Contexts and persistence details behind Protocols.
• Explicitness: MCP uses explicit Protocols for dependencies, whereas MVC often relies on implicit conventions or direct coupling.

MCP vs Service Objects / Interactors

• These patterns are very similar to MCP's Contexts. They also aim to encapsulate single use cases.
• MCP adds the explicit concepts of lean Models and formal Protocols, providing a more complete architectural picture than just focusing on the service/interactor object itself. MCP emphasizes the interaction contracts more formally via Protocols.

MCP vs Hexagonal Architecture (Ports and Adapters)

• Goal: Both aim for separation of concerns and isolating the core domain logic from external dependencies.
• Mechanism: Hexagonal uses "Ports" (interfaces defined by the core application, similar to MCP Protocols) and "Adapters" (implementations of those ports for specific technologies, like MCP Repository/Service implementations).
• Focus: Hexagonal architecture is often more focused on the boundary between the application core and the outside world (UI, database, external APIs). MCP provides a specific structure (within the core) for organizing the domain logic itself using Models, Contexts, and Protocols. They are complementary concepts.

MCP vs Clean Architecture

• Clean Architecture is a broader set of principles emphasizing dependency rules (dependencies flow inwards), layers, and separating entities, use cases (interactors), interface adapters, and frameworks/drivers.
• MCP aligns well with Clean Architecture principles. MCP's Models correspond roughly to Entities, Contexts to Use Cases/Interactors, and Protocols define the boundaries that the Dependency Rule governs. MCP can be seen as a specific way to implement the core layers of Clean Architecture.

Integrating MCP with Web Frameworks (e.g., Rails)

MCP can be effectively integrated into frameworks like Rails:

# app/controllers/orders_controller.rb (Rails Example)
class OrdersController < ApplicationController
  # Inject contexts (could use a DI container or manual instantiation)
  def initialize(create_order_context = nil, process_payment_context = nil)
    # In a real Rails app, you might use dependency injection frameworks
    # or service locators rather than direct instantiation here.
    # For simplicity:
    @create_order_context = create_order_context || build_create_order_context
    @process_payment_context = process_payment_context || build_process_payment_context
    super()
  end

  def create
    items = params.require(:order).permit(items: [:product_id, :quantity, :price])[:items]

    # Use the context to handle the business logic
    result = @create_order_context.create_order(user_id: current_user.id, items: items)

    if result[:success]
      render json: result[:order].to_h, status: :created
    else
      render json: { error: result[:message], code: result[:error_code] }, status: :unprocessable_entity
    end
  end

  def pay
    order = Order.find(params[:id]) # Or use a repository via protocol
    payment_details = params.require(:payment).permit(:card_number, :expiry, :cvv)

    # Use the context
    result = @process_payment_context.process_payment(order_id: order.id, payment_details: payment_details.to_h.symbolize_keys)

    if result[:success]
      render json: result[:order].to_h, status: :ok
    else
      render json: { error: result[:message] }, status: :payment_required # Or other appropriate status
    end
  end

  private

  # Helper methods to build contexts with their dependencies
  # In a real app, this would be handled by a DI setup
  def build_create_order_context
    # Instantiate concrete repository implementing the protocol
    order_repo = ActiveRecordOrderRepository.new # Implements OrderRepositoryProtocol
    user_repo = ActiveRecordUserRepository.new # Implements UserRepositoryProtocol
    CreateOrderContext.new(order_repo, user_repo)
  end

  def build_process_payment_context
    order_repo = ActiveRecordOrderRepository.new
    payment_gateway = StripePaymentGateway.new # Implements PaymentGatewayProtocol
    ProcessPaymentContext.new(order_repo, payment_gateway)
  end

  def current_user
    # Standard Rails current_user logic
    @current_user ||= User.find(session[:user_id]) if session[:user_id]
  end
end

Key Idea: Controllers become thin layers responsible for HTTP concerns (parsing requests, rendering responses, authentication/authorization checks), delegating the actual work to Contexts.

Conclusion

The Model-Context-Protocol (MCP) pattern offers a robust framework for structuring domain logic in Ruby applications, especially as complexity grows. By enforcing a clear separation between data (Models), behavior (Contexts), and contracts (Protocols), MCP leads to code that is significantly more testable, maintainable, and adaptable to change.

While it introduces a degree of structural overhead compared to simpler approaches, the investment pays off in larger projects by promoting clarity, reducing coupling, and enabling parallel development. Understanding and applying MCP principles can be a valuable tool in a Ruby developer's toolkit for building high-quality, long-lasting applications.