mcp-rails 0.4.11

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6e405c23ef4fae7964591eb567ee9f383b436f3d602cd02b2f2d088ba5c256a
+  data.tar.gz: 55ee2b62e45a44c2b6f9a1a9b172414c8bfbb5c98db5e0b68132594df81b9f87
+SHA512:
+  metadata.gz: 88491aab2b61efd838a5e32ee9da92eebef4c642fd294200a125071d853916d3e97dcf2d983ef373321ca9cee2a10ab010b1fa945fb8438a19185dcb13e4ef94
+  data.tar.gz: 03aa0d2516a2144794fc9b6c6328734a45f23debc92ef6b19ee926db2a13b942262dbc2cc9902a883dd8facc6dd9512d6fba7e9065f712568fa1903231aebe26

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Tonksthebear
+
+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,403 @@
+# MCP-Rails
+
+**Enhance Rails routing and parameter handling for LLM agents with MCP (Machine Control Protocol) integration.**
+
+`mcp-rails` is a Ruby on Rails gem that builds on top of the [mcp-rb](https://github.com/funwarioisii/mcp-rb) library to seamlessly integrate MCP (Model Context Protocol) servers into your Rails application. It enhances Rails routes by allowing you to tag them with MCP-specific metadata and generates a valid Ruby MCP server (in `tmp/server.rb`) that LLM agents, such as Goose, can connect to. Additionally, it provides a powerful way to define and manage strong parameters in your controllers, which doubles as both MCP server configuration and Rails strong parameter enforcement.
+
+This was inspired during the creation of [Gaggle](https://github.com/Tonksthebear/gaggle).
+
+---
+
+## Features
+
+- **Tagged Routes**: Tag Rails routes with `mcp: true` or specific actions (e.g., `mcp: [:index, :create]`) to expose them to an MCP server.
+- **Automatic MCP Server Generation**: Generates a Ruby MCP server in `tmp/server.rb` for LLM agents to interact with your application.
+- **Parameter Definition**: Define permitted parameters in controllers with rich metadata (e.g., types, examples, required flags) that are used for both MCP server generation and Rails strong parameters.
+- **HTTP Bridge for LLM Agents**: Generates a ruby based MCP server to interact with your application through HTTP requests, ensuring LLM agents follow the same paths as human users.
+- **Environment Variable Integration**: Automatically includes specified environment variables in MCP tool calls.
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'mcp-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Ensure you also have the `mcp-rb` gem installed, as `mcp-rails` depends on it:
+
+```ruby
+gem 'mcp-rb'
+```
+
+---
+
+## Configuration
+
+MCP-Rails can be configured in an initializer file. Create `config/initializers/mcp_rails.rb`:
+
+```ruby
+MCP::Rails.configure do |config|
+  # Server Configuration
+  config.server_name = "my-app-server"      # Default: 'mcp-server'
+  config.server_version = "2.0.0"           # Default: '1.0.0'
+  
+  # Output Configuration
+  config.output_directory = Rails.root.join("tmp/mcp")  # Default: Rails.root.join('tmp', 'mcp')
+  config.bypass_key_path = Rails.root.join("tmp/mcp/bypass_key.txt")  # Default: Rails.root.join('tmp', 'mcp', 'bypass_key.txt')
+  
+  # Environment Variables
+  config.env_vars = ["API_KEY", "ORGANIZATION_ID"]  # Default: ['API_KEY', 'ORGANIZATION_ID']
+  
+  # Base URL Configuration
+  config.base_url = "http://localhost:3000"  # Default: Uses action_mailer.default_url_options
+end
+```
+
+If you are an engine developer, you can register your engine's configuration with MCP-Rails:
+
+```ruby
+MCP::Rails.configure do |config|
+  config.register_engine(YourEngine, env_vars: ["YOUR_ENGINE_KEY"])
+end
+```
+
+### Environment Variables
+
+The `env_vars` configuration option specifies which environment variables should be automatically included in every MCP tool call. For example, if you configure:
+
+```ruby
+config.env_vars = ["API_KEY", "ORGANIZATION_ID"]
+```
+
+Then every MCP tool call will automatically include these environment variables as parameters:
+
+```ruby
+# If ENV['API_KEY'] = 'xyz123' and ENV['ORGANIZATION_ID'] = '456'
+# A tool call like:
+create_channel(name: "General")
+# Will effectively become:
+create_channel(name: "General", api_key: "xyz123", organization_id: "456")
+```
+
+This is useful for automatically including authentication tokens, organization IDs, or other environment-specific values in your MCP tool calls without explicitly defining them in your controller parameters.
+
+### Base URL
+
+The base URL for API requests is determined in the following order:
+1. Custom configuration via `config.base_url = "http://example.com"`
+2. Rails `action_mailer.default_url_options` settings
+3. Default fallback to `"http://localhost:3000"`
+
+---
+
+## Usage
+
+### 1. Tagging Routes
+
+In your `config/routes.rb`, tag routes that should be exposed to the MCP server:
+
+```ruby
+Rails.application.routes.draw do
+  resources :channels, mcp: true # Exposes all RESTful actions to MCP
+  # OR
+  resources :channels, mcp: [:index, :create] # Exposes only specified actions
+end
+```
+
+### 2. Defining Parameters
+
+In your controllers, use the `permitted_params_for` DSL to define parameters for MCP actions. These definitions serve a dual purpose: they configure the MCP server and enable strong parameter enforcement in Rails.
+
+Example:
+
+```ruby
+class ChannelsController < ApplicationController
+  # Define parameters for the :create action
+  permitted_params_for :create do
+    param :channel, required: true do
+      param :name, type: :string, example: "Channel Name", required: true
+      param :user_ids, type: :array, item_type: :string, example: ["1", "2"]
+    end
+  end
+
+  def create
+    @channel = Channel.new(resource_params) # Automatically uses the defined params
+    if @channel.save
+      render json: @channel, status: :created
+    else
+      render json: @channel.errors, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+The LLM will now provide the exact parameters you're used to with default rails routes, inluding the nesting of resources. For example, the LLM will create a channel with the following params
+```
+  { channel: { name: "Channel Name", user_ids: ["1", "2"] } }
+```
+
+- **MCP Server**: The generated `tmp/server.rb` will include these parameters, making them available to LLM agents.
+- **Rails Strong Parameters**: Calling `resource_params` in your controller action automatically permits and fetches the defined parameters.
+
+### 3. MCP Response Format
+
+MCP-Rails registers a custom MIME type `application/vnd.mcp+json` for MCP-specific responses. This enables:
+- Automatic key camelization for MCP protocol compatibility
+- Standardized response wrapping with status and data
+- View template fallbacks
+
+#### View Templates
+
+You can create MCP-specific views using the `.mcp.jbuilder` extension:
+
+```ruby
+# app/views/channels/show.mcp.jbuilder
+json.name @channel.name
+json.user_ids @channel.user_ids
+```
+
+If an MCP view doesn't exist, it will automatically fall back to the corresponding `.json.jbuilder` view:
+
+```ruby
+# app/views/channels/show.json.jbuilder
+json.name @channel.name
+json.user_ids @channel.user_ids
+```
+
+#### Explicit Rendering
+
+You can also render MCP responses directly in your controllers:
+
+```ruby
+class ChannelsController < ApplicationController
+  def show
+    @channel = Channel.find(params[:id])
+    
+    respond_to do |format|
+      format.json { render json: @channel }
+      format.mcp  { render mcp: @channel }  # Keys will be automatically camelized
+    end
+  end
+end
+```
+
+#### Response Format
+
+All MCP responses are automatically wrapped in a standardized format:
+
+```json
+{
+  "status": 200,
+  "data": {
+    "name": "General",
+    "userIds": ["1", "2"]  # Note: automatically camelized
+  }
+}
+```
+
+This format ensures compatibility with the generated MCP server
+
+### 4. Customizing Tool Descriptions
+
+By default, MCP-Rails generates tool descriptions in the format "Handles [action] for [controller]". You can customize these descriptions to be more specific and informative using the `tool_description_for` method in your controllers:
+
+```ruby
+class ChannelsController < ApplicationController
+  tool_description_for :create, "Create a new channel with the specified name and members"
+  tool_description_for :index, "List all available channels"
+  tool_description_for :show, "Get detailed information about a specific channel"
+
+  # ... rest of controller code
+end
+```
+
+These descriptions will be used when generating the MCP server, making it clearer to LLM agents what each endpoint does.
+
+### 5. Running the MCP Server
+
+After tagging routes and defining parameters, run 
+
+```bash
+  bin/rails mcp:rails:generate_server
+```
+The MCP server will be generated in `tmp/server.rb`. The server.rb is an executable that attempts to find the closest Gemfile to the file and executes the server using that Gemfile.
+
+If any engines are registered, the server will be generated for each engine as well.
+
+LLM agents can now connect to this server and interact with your application via HTTP requests.
+
+For an agent like Goose, you can use this new server with
+```
+goose session --with-extension "path_to/tmp/server.rb"
+```
+---
+
+## Testing Your MCP Server
+
+MCP-Rails provides a test helper module that makes it easy to integration test your MCP server responses. The helper automatically handles server generation, initialization, and cleanup while providing convenient methods to simulate MCP tool calls.
+
+### Setup
+
+Include the test helper in your test class:
+
+```ruby
+require "mcp/rails/test_helper"
+
+class MCPChannelTest < ActionDispatch::IntegrationTest
+  include MCP::Rails::TestHelper
+end
+```
+
+The helper automatically:
+- Creates a temporary directory for server files
+- Configures MCP-Rails to use this directory
+- Generates the MCP server files
+- Cleans up after each test
+
+### Available Methods
+
+- `mcp_servers`: Returns all generated MCP servers (main app and engines)
+- `mcp_server(name: "mcp-server")`: Returns a specific server by name
+- `mcp_response_body`: Returns the body of the last MCP response
+- `mcp_tool_list(server)`: Gets the list of available tools from a server
+- `mcp_tool_call(server, name, arguments = {})`: Makes a tool call to the server
+
+### Example Usage
+
+```ruby
+class MCPChannelTest < ActionDispatch::IntegrationTest
+  include MCP::Rails::TestHelper
+  
+  test "creates a channel via MCP" do
+    server = mcp_server
+    
+    mcp_tool_call(
+      server,
+      "create_channel",
+      channel: { name: "General", user_ids: ["1", "2"] }
+    )
+    
+    assert_equal false, mcp_response_body.dig(:result, :isError)
+    assert_equal "Channel created successfully", mcp_response_body.dig(:result, :message)
+  end
+end
+```
+
+This approach allows you to verify that your MCP server correctly handles requests and integrates properly with your Rails application.
+
+---
+
+## How It Works
+
+1. **Route Tagging**: The `mcp` option in your routes tells `mcp-rails` which endpoints to expose to the MCP server.
+2. **Parameter Definition**: The `permitted_params_for` block defines the structure and metadata of parameters, which are used to generate the MCP server's API and enforce strong parameters in Rails.
+3. **Server Generation**: `mcp-rails` leverages `mcp-rb` to create a Ruby MCP server in `tmp/server.rb`, translating tagged routes and parameters into an interface for LLM agents.
+4. **HTTP Integration**: The generated server converts MCP tool calls into HTTP requests, allowing you to reuse all of the same logic for interacting with your application.
+
+---
+
+## Bypassing CSRF Protection
+
+The MCP server generates new HTTP requests on the fly. In standard Rails applications, this is protected by a CSRF (Cross-Site Request Forgery) key that is provided to the client during normal interactions. Since we can't leverage this, `mcp-rails` will generate a unique key to bypass this protection. This is a rudementary way to provide protection and should not be depended upon in production. As such, the gem will not automatically skip this protection on your behalf. You will have to add the following to your `ApplicationController`:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+    skip_before_action :verify_authenticity_token, if: :mcp_invocation?
+end
+```
+
+The server adds a `X-Bypass-CSRF` header to all requests. This token gets regenerated and re-applied every time the server is generated. The key is stored in `/tmp/mcp/bypass_key.txt`
+
+## Example
+
+### Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :channels, only: [:index, :create], mcp: true
+
+  resources :posts, mcp: [:create]
+end
+```
+
+### Controller
+
+```ruby
+# app/controllers/channels_controller.rb
+class ChannelsController < ApplicationController
+  permitted_params_for :create do
+    param :channel, required: true do
+      param :name, type: :string, example: "General Chat", required: true
+      param :goose_ids, type: :array, example: ["goose-123", "goose-456"]
+    end
+  end
+
+  def index
+    @channels = Channel.all
+    render json: @channels
+  end
+
+  def create
+    @channel = Channel.new(resource_params)
+    if @channel.save
+      render json: @channel, status: :created
+    else
+      render json: @channel.errors, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+### Generated MCP Server
+
+The `tmp/server.rb` file will include an MCP server that exposes `/channels` (GET) and `/channels` (POST) with the defined parameters, allowing an LLM agent to interact with your app.
+
+For use with something like [Goose](https://github.com/block/goose):
+```
+goose session --with-extension "ruby path_to/tmp/server.rb"
+```
+---
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Rails 7.0 or higher
+- `mcp-rb` gem
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome! Please submit them to the [GitHub repository](https://github.com/yourusername/mcp-rails).
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b my-new-feature`).
+3. Commit your changes (`git commit -am 'Add some feature'`).
+4. Push to the branch (`git push origin my-new-feature`).
+5. Create a new pull request.
+
+---
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## Acknowledgments
+
+- Built on top of the excellent `mcp-rb` library.
+- Designed with LLM agents like Goose in mind.
+
+---

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/controllers/concerns/mcp/rails/error_handling.rb

@@ -0,0 +1,25 @@
+module MCP::Rails::ErrorHandling
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from StandardError, with: :handle_mcp_error
+  end
+
+  private
+
+  def handle_mcp_error(exception)
+    if mcp_request?
+      render json: {
+        status: "error",
+        message: exception.message,
+        code: exception.class.name.underscore
+      }, status: :unprocessable_entity
+    else
+      raise exception # Re-raise the exception for non-mcp requests
+    end
+  end
+
+  def mcp_request?
+    request.format == :mcp || request.accept.include?("application/vnd.mcp+json")
+  end
+end

data/app/controllers/concerns/mcp/rails/parameters.rb

@@ -0,0 +1,163 @@
+module MCP::Rails::Parameters
+  extend ActiveSupport::Concern
+
+  def self.included(base)
+    base.extend ClassMethods
+    base.class_eval do
+      # Initialize instance variables for each class
+      @shared_params_defs = {}
+      @action_params_defs = {}
+
+      # Define class-level accessors
+      def self.shared_params_defs
+        @shared_params_defs ||= {}
+      end
+
+      def self.action_params_defs
+        @action_params_defs ||= {}
+      end
+
+      # Optionally, define setters if needed
+      def self.shared_params_defs=(value)
+        @shared_params_defs = value
+      end
+
+      def self.action_params_defs=(value)
+        @action_params_defs = value
+      end
+
+      # Ensure subclasses get their own fresh instances
+      def self.inherited(subclass)
+        super
+        subclass.instance_variable_set(:@shared_params_defs, {})
+        subclass.instance_variable_set(:@action_params_defs, {})
+      end
+    end
+
+    def mcp_invocation?
+      bypass_key = request.headers["X-Bypass-CSRF"]
+      stored_key = File.read(MCP::Rails.configuration.bypass_key_path).strip rescue nil
+      bypass_key.present? && bypass_key == stored_key
+    end
+  end
+
+  class_methods do
+    # Define shared parameters
+    def shared_params(name, &block)
+      builder = ParamsBuilder.new
+      builder.instance_eval(&block)
+      shared_params_defs[name] = builder.params
+    end
+
+    # Define parameters for an action
+    def permitted_params_for(action, shared: [], &block)
+      # Gather shared params
+      shared_params = shared.map { |name| shared_params_defs[name] }.flatten.compact
+      # Build action-specific params
+      action_builder = ParamsBuilder.new
+      action_builder.instance_eval(&block) if block_given?
+      action_params = action_builder.params
+      # Merge, with action-specific overriding shared
+      merged_params = merge_params(shared_params, action_params)
+      action_params_defs[action.to_sym] = merged_params
+    end
+
+    # Get permitted parameters for an action
+    def permitted_params(action)
+      action_params_defs[action.to_sym] || []
+    end
+
+    def mcp_hash(action)
+      extract_permitted_mcp_hash(permitted_params(action))
+    end
+
+    def extract_permitted_mcp_hash(params_def)
+      param_hash = {}
+      params_def.each do |param|
+        param_hash[param[:name]] = {
+          type: param[:type],
+          required: param[:required]
+        }
+        if param[:nested]
+          param_hash[param[:name]][:type] = "object"
+          param_hash[param[:name]][:properties] = extract_permitted_mcp_hash(param[:nested])
+        end
+      end
+      param_hash
+    end
+
+    private
+
+    # Merge shared and action-specific params, with action-specific taking precedence
+    def merge_params(shared, specific)
+      specific_keys = specific.map { |p| p[:name] }
+      shared.reject { |p| specific_keys.include?(p[:name]) } + specific
+    end
+  end
+
+  # Instance method to get strong parameters, keeping controller clean
+  def resource_params
+    permitted = extract_permitted_keys(self.class.permitted_params(action_name))
+    if (model_hash = permitted.select { |p| p.is_a?(Hash) }) && model_hash.length == 1
+      params.require(model_hash.first.keys.first).permit(*model_hash.first.values)
+    else
+      params.permit(permitted)
+    end
+  end
+
+  private
+
+
+  # Helper to extract permitted keys for strong parameters
+  def extract_permitted_keys(params_def)
+    params_def.map do |param|
+      if param[:type] == :array
+        if param[:item_type]
+          { param[:name] => [] }  # Scalar array
+        elsif param[:nested]
+          { param[:name] => extract_permitted_keys(param[:nested]) }  # Array of hashes
+        else
+          raise "Invalid array parameter definition"
+        end
+      elsif param[:nested]
+        { param[:name] => extract_permitted_keys(param[:nested]) }  # Nested object
+      else
+        param[:name]  # Scalar
+      end
+    end
+  end
+
+  # Builder class for parameter definitions
+  class ParamsBuilder
+    attr_reader :params
+
+    def initialize
+      @params = []
+    end
+
+    def param(name, type: nil, item_type: nil, example: nil, required: false, &block)
+      param_def = { name: name, required: required }
+      if type == :array
+        param_def[:type] = :array
+        if block_given?
+          nested_builder = ParamsBuilder.new
+          nested_builder.instance_eval(&block)
+          param_def[:nested] = nested_builder.params
+        elsif item_type
+          param_def[:item_type] = item_type
+        else
+          raise ArgumentError, "Must provide item_type or a block for array type"
+        end
+      elsif block_given?
+        param_def[:type] = :object
+        nested_builder = ParamsBuilder.new
+        nested_builder.instance_eval(&block)
+        param_def[:nested] = nested_builder.params
+      else
+        param_def[:type] = type if type
+      end
+      param_def[:example] = example if example
+      @params << param_def
+    end
+  end
+end

data/app/controllers/concerns/mcp/rails/renderer.rb

@@ -0,0 +1,69 @@
+# lib/mcp/rails/renderer.rb
+module MCP
+  module Rails
+    module Renderer
+      extend ActiveSupport::Concern
+
+      included do
+        alias_method :original_render, :render
+        alias_method :render, :mcp_render
+      end
+
+      def mcp_render(*args)
+        return original_render(*args) unless request.format.mcp?
+
+        options = args.extract_options!
+        if implicit_jbuilder_render?(options)
+          process_implicit_jbuilder_render(options)
+        elsif options[:json] || options[:mcp]
+          process_explicit_render(options)
+        end
+        original_render(*args, options)
+      end
+
+      private
+
+      def implicit_jbuilder_render?(options)
+        options.empty? &&
+        lookup_context.exists?(action_name, lookup_context.prefixes, false, [], formats: [ :mcp, :json ], handlers: [ :jbuilder ])
+      end
+
+      def process_implicit_jbuilder_render(options)
+        template = lookup_context.find(action_name, lookup_context.prefixes, false, [], formats: [ :mcp, :json ], handlers: [ :jbuilder ])
+        data = JbuilderTemplate.new(view_context, key_format: :camelize) do |json|
+          json.key_format! camelize: :lower
+          view_context.instance_exec(json) do |j|
+            eval(template.source, binding, template.identifier)
+          end
+        end.attributes!
+        # Wrap in status/data structure
+        options[:json] = {
+          status: Rack::Utils.status_code(response.status || :ok),
+          data: data
+        }
+      end
+
+      def process_explicit_render(options)
+        status_code = Rack::Utils.status_code(options[:status] || :ok)
+        data = options.delete(:mcp) || options.delete(:json)
+
+        # Wrap in status/data structure
+        options[:json] = {
+          status: status_code,
+          data: format_keys(data)
+        }
+      end
+
+      def format_keys(data)
+        case data
+        when Hash
+          data.deep_transform_keys { |k| k.to_s.camelize(:lower) }
+        when Array
+          data.map { |item| format_keys(item) }
+        else
+          data
+        end
+      end
+    end
+  end
+end