rails_mcp_engine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53d474e90f159408325d95bf24d519e93a5f82b2b00258dc756300dd6ae04365
+  data.tar.gz: f38095e894a2ae6b3aba6744aadfaf529d8aa9029f7f1b0f0c4992516e2beb93
+SHA512:
+  metadata.gz: 67040a2d30ec66489b8dd99f7d995f7f93e36f353e935384d8205b51d8d4103438f3ea83f8ead1397ef8afd0f54b823f76f513f3d5fe4613a0316de380d8b5a4
+  data.tar.gz: 75e1d06bb502e402beb4f8aa85c5ede2ab741017526cd7ed413130ab6c12edeb20a77ce3fdb7cccaf859103de82d24389d029a041271b90bf79fa8938835217b

data/README.md

@@ -0,0 +1,134 @@
+# Rails MCP Engine
+
+Rails MCP Engine provides a unified tool-definition pipeline for Rails 8 applications. Service classes declare Sorbet-typed signatures and metadata once, and the engine auto-generates both RubyLLM and FastMCP tool classes at boot.
+
+## Core Dependencies
+
+This engine is built on top of these powerful libraries:
+
+- **[RubyLLM](https://github.com/crmne/ruby_llm)**: For generating LLM-compatible tool definitions.
+- **[FastMCP](https://github.com/yjacquin/fast-mcp)**: For creating Model Context Protocol (MCP) servers.
+- **[Sorbet](https://github.com/sorbet/sorbet)**: For static type checking and signature definitions.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_mcp_engine'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## How it works
+
+- **Service classes** live under the `Tools::` namespace, extend `ToolMeta`, and expose a single Sorbet-signed entrypoint (defaults to `#call`).
+- **ToolMeta DSL** captures names, descriptions, and parameter metadata, while Sorbet signatures provide the type source of truth.
+- The **ToolSchema pipeline** merges Sorbet type information with metadata, producing a unified schema AST.
+- **Factories** (`ToolSchema::RubyLlmFactory` and `ToolSchema::FastMcpFactory`) transform the AST into RubyLLM tools and FastMCP `ApplicationTool` subclasses, respectively.
+- The **Engine** automatically iterates through registered service classes and generates both tool types during Rails initialization (`to_prepare`).
+
+## Defining a tool service
+
+Create a service that extends `ToolMeta` and uses Sorbet for the entrypoint signature. Only business logic belongs here; tool wrappers are generated.
+
+```ruby
+# app/services/tools/book_meeting_service.rb
+class Tools::BookMeetingService
+  extend T::Sig
+  extend ToolMeta
+
+  tool_name "book_meeting"
+  tool_description "Books a meeting."
+  tool_param :window, description: "Start/finish window"
+  tool_param :participants, description: "Email recipients"
+
+  sig do
+    params(
+      window: T::Hash[Symbol, String],
+      participants: T::Array[String]
+    ).returns(T::Hash[Symbol, T.untyped])
+  end
+  def call(window:, participants:)
+    # ... business logic ...
+  end
+end
+```
+
+On boot, the engine generates:
+- `Tools::BookMeeting < RubyLLM::Tool` with a matching `params` block.
+- `Mcp::BookMeetingTool < ApplicationTool` with a matching `arguments` block.
+
+## Default meta tool
+
+`Tools::MetaToolService` is included by default to explore and execute registered tools at runtime. It exposes a single `action` argument with supporting keywords:
+
+- `list`: return full tool details (name, description, params, return type).
+- `list_summary`: return only names and descriptions.
+- `search`: provide `query` to fuzzy-match name/description.
+- `get`: provide `tool_name` to fetch a full schema payload.
+- `run`: provide `tool_name` and `arguments` to invoke a tool through its service class.
+
+> **Note:** The `register` action is not available via the tool interface for security reasons. Developers can manually register tools using `Tools::MetaToolService.new.register_tool("ClassName")` in their code.
+
+Example invocation from a console:
+
+```ruby
+Tools::MetaToolService.new.call(action: 'run', tool_name: 'book_meeting', arguments: { window: { start: '...', finish: '...' }, participants: ['a@example.com'] })
+```
+
+## Tool Registration Hooks
+
+You can attach `before_call` and `after_call` hooks when manually registering tools. These hooks are useful for logging, tracing, or other side effects.
+
+```ruby
+Tools::MetaToolService.new.register_tool(
+  'Tools::BookMeetingService',
+  before_call: ->(args) { Rails.logger.info("Calling tool with #{args}") },
+  after_call: ->(result) { Rails.logger.info("Tool returned #{result}") }
+)
+```
+
+- `before_call`: A `Proc` that receives the arguments hash.
+- `after_call`: A `Proc` that receives the result.
+
+These hooks are executed around the tool's entrypoint method for both RubyLLM and FastMCP wrappers.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rails test` to run the tests.
+
+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).
+
+### Playground & Chat
+
+The engine includes a built-in playground and chat interface for testing your tools.
+
+1.  **Mount the engine**: Ensure the engine is mounted in your `config/routes.rb` (e.g., `mount RailsMcpEngine::Engine => '/rails_mcp_engine'`).
+2.  **Access the Playground**: Navigate to `/rails_mcp_engine/playground` to register and test tools individually.
+3.  **Access the Chat**: Navigate to `/rails_mcp_engine/chat` to test tools within a conversational interface using OpenAI models.
+
+The playground allows you to:
+- Register tool services dynamically by pasting Ruby code.
+- Run registered tools with JSON arguments.
+- View tool schemas and details.
+
+The chat interface allows you to:
+- Chat with OpenAI models (e.g., gpt-4o).
+- Automatically invoke registered tools during the conversation.
+- View tool calls and results within the chat history.
+
+Screenshots:
+
+| Playground | Chat |
+| --- | --- | 
+| ![Playground](docs/rails_gem_engine_screenshot_tools.png) | ![Chat](docs/rails_gem_engine_screenshot_chat.png) |
+
+## 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,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = false
+end
+
+task default: :test

data/app/controllers/rails_mcp_engine/application_controller.rb

@@ -0,0 +1,5 @@
+module RailsMcpEngine
+  class ApplicationController < ::ApplicationController
+    include RailsMcpEngine::Engine.routes.url_helpers
+  end
+end

data/app/controllers/rails_mcp_engine/chat_controller.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RailsMcpEngine
+  class ChatController < ApplicationController
+    def show
+      @tools = schemas
+      @models = [
+        # OpenAI
+        'gpt-5-nano',
+        'gpt-4.1',
+        'gpt-4o',
+        'gpt-4o-mini',
+        # Google
+        'gemini-2.5-pro',
+        'gemini-2.0-pro-exp',
+        # Anthropic
+        'claude-sonnet-4-5',
+        'claude-3-7-sonnet-20250219',
+        'claude-3-5-haiku-20241022',
+        'claude-3-haiku-20240307'
+      ]
+    end
+
+    def send_message
+      user_message = params[:message].to_s
+      model = params[:model].to_s
+      conversation_history = JSON.parse(params[:conversation_history] || '[]', symbolize_names: true)
+
+      if user_message.strip.empty?
+        render json: { error: 'Message is required' }, status: :bad_request
+        return
+      end
+
+      provider = if model.start_with?('gemini')
+                   :gemini
+                 elsif model.start_with?('claude')
+                   :anthropic
+                 else
+                   :openai
+                 end
+
+      # Create RubyLLM chat instance with configuration
+      chat = RubyLLM.chat(
+        provider: provider,
+        model: model
+      )
+
+      # Register all available tools
+      tool_classes = get_tool_classes
+      chat = tool_classes.reduce(chat) { |c, tool_class| c.with_tool(tool_class) }
+
+      # Prepare the message with conversation history context
+      if conversation_history.empty?
+        # First message: just send as-is
+        full_message = user_message
+      else
+        # Include conversation history for context
+        context_parts = ['Previous conversation:']
+        conversation_history.each do |msg|
+          role_label = msg[:role] == 'user' ? 'User' : 'Assistant'
+          context_parts << "#{role_label}: #{msg[:content]}"
+        end
+        context_parts << "\nCurrent question:"
+        context_parts << user_message
+        full_message = context_parts.join("\n\n")
+      end
+
+      # Ask the question and capture response
+      begin
+        # Ruby LLM handles tool calling automatically
+        response = chat.ask(full_message)
+        assistant_content = response.content
+
+        # Build conversation history manually since Ruby LLM manages it internally
+        # Add user message
+        conversation_history << { role: 'user', content: user_message }
+        # Add assistant response
+        conversation_history << { role: 'assistant', content: assistant_content }
+
+        # Tool results are handled transparently by Ruby LLM
+        # We don't have direct access to them, so return empty array
+        tool_results = []
+
+        render json: {
+          conversation_history: conversation_history,
+          tool_results: tool_results
+        }
+      rescue StandardError => e
+        render json: { error: e.message }, status: :bad_request
+      end
+    end
+
+    private
+
+    def schemas
+      ToolMeta.registry.map { |service_class| ToolSchema::Builder.build(service_class) }
+    end
+
+    def get_tool_classes
+      # Get all RubyLLM tool classes that were generated
+      schemas.map do |schema|
+        tool_constant = ToolSchema::RubyLlmFactory.tool_class_name(schema[:service_class])
+        # Accessing Tools from global namespace
+        ::Tools.const_get(tool_constant)
+      end
+    end
+  end
+end

data/app/controllers/rails_mcp_engine/playground_controller.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RailsMcpEngine
+  class PlaygroundController < ApplicationController
+    def show
+      @register_result = flash[:register_result]
+      @test_result = flash[:test_result]
+      @tools = schemas
+    end
+
+    def register
+      source = params[:source].to_s
+      class_name = extract_class_name(source)
+
+      result = if source.strip.empty?
+                 { error: 'Tool source code is required' }
+               elsif class_name.nil?
+                 { error: 'Could not infer class name from the provided source' }
+               else
+                 register_source(source, class_name)
+               end
+
+      flash[:register_result] = result
+      redirect_to playground_path
+    end
+
+    def run
+      tool_name = params[:tool_name].to_s
+      parsed_arguments = parse_arguments(params[:arguments])
+      schema = schemas.find { |s| s[:name] == tool_name }
+
+      result = if schema.nil?
+                 { error: "Tool not found: #{tool_name}" }
+               elsif parsed_arguments.is_a?(String)
+                 { error: parsed_arguments }
+               else
+                 invoke_tool(schema, parsed_arguments)
+               end
+
+      flash[:test_result] = result
+      redirect_to playground_path
+    end
+
+    def delete_tool
+      tool_name = params[:tool_name].to_s
+      schema = schemas.find { |s| s[:name] == tool_name }
+
+      result = if schema.nil?
+                 { error: "Tool not found: #{tool_name}" }
+               else
+                 delete_tool_from_registry(schema[:service_class])
+               end
+
+      flash[:register_result] = result
+      redirect_to playground_path
+    end
+
+    private
+
+    def schemas
+      ToolMeta.registry.map { |service_class| ToolSchema::Builder.build(service_class) }
+    end
+
+    def extract_class_name(source)
+      require 'ripper'
+      sexp = Ripper.sexp(source)
+      return nil unless sexp
+
+      # sexp is [:program, statements]
+      statements = sexp[1]
+      find_class(statements, [])
+    end
+
+    def find_class(statements, namespace)
+      return nil unless statements.is_a?(Array)
+
+      statements.each do |stmt|
+        next unless stmt.is_a?(Array)
+
+        case stmt.first
+        when :module
+          # [:module, const_ref, body]
+          # body is [:bodystmt, statements, ...]
+          const_node = stmt[1]
+          const_name = get_const_name(const_node)
+
+          body_stmt = stmt[2]
+          inner_statements = body_stmt[1]
+
+          result = find_class(inner_statements, namespace + [const_name])
+          return result if result
+        when :class
+          # [:class, const_ref, superclass, body]
+          const_node = stmt[1]
+          const_name = get_const_name(const_node)
+
+          return (namespace + [const_name]).join('::')
+        end
+      end
+      nil
+    end
+
+    def get_const_name(node)
+      return nil unless node.is_a?(Array)
+
+      type = node.first
+      if type == :const_ref
+        # [:const_ref, [:@const, "Name", ...]]
+        node[1][1]
+      elsif type == :const_path_ref
+        # [:const_path_ref, parent, child]
+        parent = node[1]
+        child = node[2] # [:@const, "Name", ...]
+
+        parent_name = if parent.first == :var_ref
+                        parent[1][1]
+                      else
+                        get_const_name(parent)
+                      end
+
+        "#{parent_name}::#{child[1]}"
+      else
+        nil
+      end
+    end
+
+    def register_source(source, class_name)
+      Object.class_eval(source)
+      # Use the engine's namespace or ensure Tools is available.
+      # Assuming Tools module is defined in the host app or globally.
+      # If Tools is not defined, we might need to define it or use a different namespace.
+      # For now, keeping it as is, assuming host app environment.
+
+      # However, since we are in an engine, we should check if we need to be more careful.
+      # The original code used Tools::MetaToolService.
+      # Let's check if Tools is defined in the engine or expected from host.
+      # The engine.rb defines ApplicationTool.
+
+      # Re-using the logic from ManualController but adapting for Engine.
+      ::Tools::MetaToolService.new.register_tool(
+        class_name,
+        before_call: ->(args) { Rails.logger.info("  [MCP] Request #{class_name}: #{args.inspect}") },
+        after_call: ->(result) { Rails.logger.info("  [MCP] Response #{class_name}: #{result.inspect}") }
+      )
+    rescue StandardError => e
+      { error: e.message }
+    end
+
+    def parse_arguments(raw_value)
+      return {} if raw_value.to_s.strip.empty?
+
+      JSON.parse(raw_value, symbolize_names: true)
+    rescue JSON::ParserError => e
+      e.message
+    end
+
+    def invoke_tool(schema, arguments)
+      tool_constant = ToolSchema::RubyLlmFactory.tool_class_name(schema[:service_class])
+      # Accessing Tools from global namespace
+      tool_class = ::Tools.const_get(tool_constant)
+      result = tool_class.new.execute(**arguments.symbolize_keys)
+
+      { tool: { name: schema[:name], description: schema[:description] }, result: result }
+    rescue StandardError => e
+      Rails.logger.error("Error invoking tool #{schema[:name]}: #{e.message}")
+      { error: e.message }
+    end
+
+    def delete_tool_from_registry(service_class)
+      ToolMeta.registry.delete(service_class)
+
+      # Also remove the RubyLLM tool class constant
+      tool_constant = ToolSchema::RubyLlmFactory.tool_class_name(service_class)
+      ::Tools.send(:remove_const, tool_constant) if ::Tools.const_defined?(tool_constant, false)
+
+      { success: 'Tool deleted successfully' }
+    rescue StandardError => e
+      { error: e.message }
+    end
+  end
+end

data/app/lib/tool_meta.rb

@@ -0,0 +1,91 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+# ToolMeta defines a DSL for annotating service classes that represent tools.
+# The metadata collected here becomes the source of truth for non-type
+# attributes such as names, descriptions, and examples.
+module ToolMeta
+  extend T::Sig
+
+  ParamMetadata = T.type_alias do
+    T::Hash[Symbol, T.untyped]
+  end
+
+  class MissingSignatureError < StandardError; end
+
+  sig { params(base: T.class_of(Object)).void }
+  def self.extended(base)
+    registry << base unless registry.include?(base)
+    base.instance_variable_set(:@tool_params, T.let([], T::Array[ParamMetadata]))
+    base.instance_variable_set(:@tool_name, nil)
+    base.instance_variable_set(:@tool_description, nil)
+  end
+
+  sig { returns(T::Array[T.class_of(Object)]) }
+  def self.registry
+    @registry ||= []
+  end
+
+  sig { void }
+  def self.clear_registry
+    @registry = []
+  end
+
+  sig { params(name: String).void }
+  def tool_name(name)
+    @tool_name = name
+  end
+
+  sig { params(description: String).void }
+  def tool_description(description)
+    @tool_description = description
+  end
+
+  sig do
+    params(
+      name: T.any(String, Symbol),
+      description: T.nilable(String),
+      required: T::Boolean,
+      example: T.untyped,
+      enum: T.nilable(T::Array[T.untyped])
+    ).void
+  end
+  def tool_param(name, description: nil, required: true, example: nil, enum: nil)
+    @tool_params << {
+      name: name.to_sym,
+      description: description,
+      required: required,
+      example: example,
+      enum: enum
+    }
+  end
+
+  sig { returns(String) }
+  def tool_entrypoint
+    'call'
+  end
+
+  sig { returns(T::Hash[Symbol, T.untyped]) }
+  def tool_metadata
+    {
+      name: @tool_name || default_tool_name,
+      description: @tool_description || '',
+      params: @tool_params,
+      entrypoint: tool_entrypoint
+    }
+  end
+
+  private
+
+  sig { returns(String) }
+  def default_tool_name
+    return '' unless respond_to?(:name) && name
+
+    name.split('::').last
+        .gsub(/Service$/, '')
+        .gsub(/([a-z0-9])([A-Z])/, '\\1_\\2')
+        .downcase
+  end
+end

data/app/lib/tool_schema/builder.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require_relative '../tool_meta'
+require_relative 'sorbet_type_mapper'
+
+module ToolSchema
+  class Builder
+    extend T::Sig
+
+    SchemaAst = T.type_alias do
+      T::Hash[Symbol, T.untyped]
+    end
+
+    sig { params(service_class: T.class_of(Object)).returns(SchemaAst) }
+    def self.build(service_class)
+      metadata = T.let(service_class.tool_metadata, T::Hash[Symbol, T.untyped])
+      entrypoint = metadata[:entrypoint]&.to_sym || :call
+      method = service_class.instance_method(entrypoint)
+      type_info = SorbetTypeMapper.map_signature(method)
+
+      params_ast = type_info[:params].map do |param_ast|
+        merge_param(param_ast, metadata[:params])
+      end
+
+      {
+        name: metadata[:name],
+        description: metadata[:description],
+        params: params_ast,
+        return_type: type_info[:return_type],
+        entrypoint: entrypoint,
+        service_class: service_class
+      }
+    end
+
+    sig do
+      params(
+        param_ast: T::Hash[Symbol, T.untyped],
+        metadata_params: T.nilable(T::Array[T::Hash[Symbol, T.untyped]])
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def self.merge_param(param_ast, metadata_params)
+      meta = metadata_params&.find { |p| p[:name].to_sym == param_ast[:name].to_sym }
+      description = meta ? meta[:description] : nil
+      example = meta ? meta[:example] : nil
+      enum = meta ? meta[:enum] : nil
+      required_from_meta = meta.nil? ? true : (meta[:required].nil? ? true : meta[:required])
+      required = param_ast[:required] && required_from_meta
+
+      param_ast.merge(
+        description: description,
+        example: example,
+        enum: enum,
+        required: required,
+        children: merge_children(param_ast[:children], metadata_params)
+      )
+    end
+
+    sig do
+      params(children: T.untyped, metadata_params: T.nilable(T::Array[T::Hash[Symbol, T.untyped]])).returns(T.untyped)
+    end
+    def self.merge_children(children, metadata_params)
+      return [] unless children.is_a?(Array)
+
+      children.map do |child|
+        merge_param(child, metadata_params)
+      end
+    end
+  end
+end

data/app/lib/tool_schema/fast_mcp_builder.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ToolSchema
+  module FastMcpBuilder
+    extend T::Sig
+
+    sig { params(params_ast: T::Array[T::Hash[Symbol, T.untyped]]).returns(Proc) }
+    def self.arguments_block(params_ast)
+      proc do
+        params_ast.each do |param|
+          FastMcpBuilder.build_param(self, param)
+        end
+      end
+    end
+
+    sig { params(ctx: BasicObject, param: T::Hash[Symbol, T.untyped]).void }
+    def self.build_param(ctx, param)
+      wrapper = param[:required] ? ctx.required(param[:name]) : ctx.optional(param[:name])
+
+      node = case param[:type]
+             when :object
+               wrapper.hash do
+                 (param[:children] || []).each do |child|
+                   FastMcpBuilder.build_param(self, child)
+                 end
+               end
+             when :array
+               item = param[:item_type]
+               if item && scalar_type?(item[:type])
+                 wrapper.array(scalar_symbol(item[:type]))
+               elsif item&.dig(:type) == :object
+                 wrapper.array(:hash) do
+                   (item[:children] || []).each do |child|
+                     FastMcpBuilder.build_param(self, child)
+                   end
+                 end
+               else
+                 wrapper.array(:any)
+               end
+             else
+               wrapper.value(scalar_symbol(param[:type]))
+             end
+
+      node.description(param[:description]) if param[:description]
+    end
+
+    sig { params(type: T.untyped).returns(T::Boolean) }
+    def self.scalar_type?(type)
+      %i[string integer float boolean any].include?(type)
+    end
+
+    sig { params(type: T.untyped).returns(Symbol) }
+    def self.scalar_symbol(type)
+      case type
+      when :string then :string
+      when :integer then :integer
+      when :float then :float
+      when :boolean then :bool
+      else :any
+      end
+    end
+  end
+end