mcp_on_ruby 0.3.0 → 1.0.0

data/lib/mcp_on_ruby/errors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Base error class for MCP-related errors
+  class Error < StandardError
+    attr_reader :code, :data
+
+    def initialize(message, code: nil, data: nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+
+    # Convert error to JSON-RPC error format
+    def to_json_rpc
+      {
+        code: @code || default_error_code,
+        message: message,
+        data: @data
+      }.compact
+    end
+
+    private
+
+    def default_error_code
+      -32603 # Internal error
+    end
+  end
+
+  # JSON-RPC parsing error
+  class ParseError < Error
+    private
+
+    def default_error_code
+      -32700
+    end
+  end
+
+  # Invalid JSON-RPC request
+  class InvalidRequestError < Error
+    private
+
+    def default_error_code
+      -32600
+    end
+  end
+
+  # Method not found
+  class MethodNotFoundError < Error
+    private
+
+    def default_error_code
+      -32601
+    end
+  end
+
+  # Invalid method parameters
+  class InvalidParamsError < Error
+    private
+
+    def default_error_code
+      -32602
+    end
+  end
+
+  # Tool or resource not found
+  class NotFoundError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+
+  # Authorization/authentication failed
+  class AuthorizationError < Error
+    private
+
+    def default_error_code
+      -32600
+    end
+  end
+
+  # Validation error for tool arguments or resource parameters
+  class ValidationError < Error
+    private
+
+    def default_error_code
+      -32602
+    end
+  end
+
+  # Tool execution error
+  class ToolExecutionError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+
+  # Resource read error
+  class ResourceReadError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+
+  # Rate limiting error
+  class RateLimitError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+
+  # Configuration error
+  class ConfigurationError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+
+  # Transport error
+  class TransportError < Error
+    private
+
+    def default_error_code
+      -32603
+    end
+  end
+end

data/lib/mcp_on_ruby/generators/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module McpOnRuby
+  module Generators
+    # Generator for installing MCP server in Rails application
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Install MCP server in Rails application"
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/mcp_on_ruby.rb'
+      end
+
+      def create_application_classes
+        template 'application_tool.rb', 'app/tools/application_tool.rb'
+        template 'application_resource.rb', 'app/resources/application_resource.rb'
+      end
+
+      def create_example_tool
+        template 'sample_tool.rb', 'app/tools/sample_tool.rb'
+      end
+
+      def create_example_resource
+        template 'sample_resource.rb', 'app/resources/sample_resource.rb'
+      end
+
+      def add_route
+        say "MCP server will be available at /mcp via middleware", :green
+        say "No route configuration needed - handled by Railtie", :blue
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+
+      private
+
+      def readme(path)
+        say IO.read(File.join(self.class.source_root, path)), :green if File.exist?(File.join(self.class.source_root, path))
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/generators/resource_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module McpOnRuby
+  module Generators
+    # Generator for creating MCP resources
+    class ResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc "Generate an MCP resource class"
+
+      argument :name, type: :string, desc: "Name of the resource"
+      
+      class_option :uri, type: :string, desc: "URI pattern for the resource"
+      class_option :description, type: :string, desc: "Description of the resource"
+      class_option :mime_type, type: :string, default: 'application/json', desc: "MIME type of the resource"
+      class_option :template, type: :boolean, default: false, desc: "Create a templated resource with parameters"
+
+      def create_resource_file
+        template 'resource.rb', File.join('app/resources', "#{file_name}_resource.rb")
+      end
+
+      def create_spec_file
+        return unless File.exist?(Rails.root.join('spec'))
+        
+        template 'resource_spec.rb', File.join('spec/resources', "#{file_name}_resource_spec.rb")
+      end
+
+      private
+
+      def resource_name
+        name.underscore
+      end
+
+      def resource_class_name
+        "#{name.camelize}Resource"
+      end
+
+      def resource_uri
+        options[:uri] || (options[:template] ? "#{resource_name}/{id}" : resource_name)
+      end
+
+      def resource_description
+        options[:description] || "#{name.humanize} resource"
+      end
+
+      def resource_mime_type
+        options[:mime_type]
+      end
+
+      def is_template?
+        options[:template] || resource_uri.include?('{')
+      end
+
+      def template_params
+        return [] unless is_template?
+        
+        resource_uri.scan(/\{([^}]+)\}/).flatten
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/generators/templates/README

@@ -0,0 +1,31 @@
+MCP on Ruby has been installed successfully!
+
+Next steps:
+
+1. Configure your MCP server in config/initializers/mcp_on_ruby.rb
+2. Create tools in app/tools/ using: rails generate mcp_on_ruby:tool ToolName
+3. Create resources in app/resources/ using: rails generate mcp_on_ruby:resource ResourceName
+4. Start your Rails server and access MCP at http://localhost:3000/mcp
+
+Example tool generation:
+  rails generate mcp_on_ruby:tool UserManager --description "Manage users"
+
+Example resource generation:
+  rails generate mcp_on_ruby:resource UserData --uri "users/{id}" --template
+
+Your MCP server will automatically discover and register all tools and resources
+in app/tools/ and app/resources/ that inherit from ApplicationTool and ApplicationResource.
+
+For manual setup, you can configure tools and resources in the initializer:
+
+McpOnRuby.mount_in_rails(Rails.application) do |server|
+  server.tool 'custom_tool', 'Description' do |args|
+    { result: 'Custom logic here' }
+  end
+  
+  server.resource 'custom_resource' do
+    { data: 'Custom resource data' }
+  end
+end
+
+Visit the documentation for more advanced usage patterns!

data/lib/mcp_on_ruby/generators/templates/application_resource.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Base class for all MCP resources in this application
+class ApplicationResource < McpOnRuby::Resource
+  # Common functionality for all resources can be added here
+  
+  # Example: Add common authorization logic
+  # def authorize(context)
+  #   # Check if user is authenticated
+  #   context[:authenticated] == true
+  # end
+  
+  # Example: Add caching for all resource reads
+  # def read(params = {}, context = {})
+  #   cache_key = "mcp:resource:#{uri}:#{params.to_json}"
+  #   Rails.cache.fetch(cache_key, expires_in: 5.minutes) do
+  #     super
+  #   end
+  # end
+end

data/lib/mcp_on_ruby/generators/templates/application_tool.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Base class for all MCP tools in this application
+class ApplicationTool < McpOnRuby::Tool
+  # Common functionality for all tools can be added here
+  
+  # Example: Add common authorization logic
+  # def authorize(context)
+  #   # Check if user is authenticated
+  #   context[:authenticated] == true
+  # end
+  
+  # Example: Add logging for all tool executions
+  # def call(arguments = {}, context = {})
+  #   Rails.logger.info("Tool #{name} called with: #{arguments.inspect}")
+  #   super
+  # end
+end

data/lib/mcp_on_ruby/generators/templates/initializer.rb

@@ -0,0 +1,41 @@
+# MCP on Ruby configuration
+McpOnRuby.configure do |config|
+  # Logging level
+  config.log_level = Rails.logger.level
+  
+  # MCP endpoint path
+  config.path = '/mcp'
+  
+  # Authentication (set to true for production)
+  config.authentication_required = false
+  config.authentication_token = ENV['MCP_AUTH_TOKEN']
+  
+  # Security settings
+  config.allowed_origins = []  # Empty means allow all origins
+  config.localhost_only = Rails.env.development?
+  config.dns_rebinding_protection = true
+  
+  # Rate limiting (requests per minute per IP)
+  config.rate_limit_per_minute = 60
+  
+  # Features
+  config.enable_sse = true
+  config.cors_enabled = true
+end
+
+# Enable MCP server in Rails
+Rails.application.configure do
+  config.mcp.enabled = true
+  config.mcp.auto_register_tools = true
+  config.mcp.auto_register_resources = true
+end
+
+# Mount MCP server (alternative to route-based mounting)
+# Rails.application.config.after_initialize do
+#   McpOnRuby.mount_in_rails(Rails.application) do |server|
+#     # Manual tool/resource registration if needed
+#     # server.tool 'custom_tool', 'Description' do |args|
+#     #   { result: 'Custom logic here' }
+#     # end
+#   end
+# end

data/lib/mcp_on_ruby/generators/templates/resource.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# <%= resource_description %>
+class <%= resource_class_name %> < ApplicationResource
+  def initialize
+    super(
+      uri: '<%= resource_uri %>',
+      name: '<%= name.humanize %>',
+      description: '<%= resource_description %>',
+      mime_type: '<%= resource_mime_type %>',
+      metadata: {
+        category: 'custom',
+        version: '1.0.0'
+      },
+      tags: ['<%= resource_name %>']
+    )
+  end
+
+  protected
+
+  def fetch_content(params, context)
+    <% if is_template? -%>
+    # This is a templated resource with parameters: <%= template_params.join(', ') %>
+    # Access parameters via params hash:
+    <% template_params.each do |param| -%>
+    # <%= param %> = params['<%= param %>']
+    <% end -%>
+    <% end -%>
+    
+    # Implement your resource content fetching logic here
+    # Return data that will be serialized according to mime_type
+    
+    {
+      resource: '<%= resource_name %>',
+      <% if is_template? -%>
+      parameters: params,
+      <% end -%>
+      data: {
+        # Your resource data here
+      },
+      generated_at: Time.current.iso8601
+    }
+  end
+
+  # Optional: Add authorization logic
+  # def authorize(context)
+  #   # Return true/false based on context (user, permissions, etc.)
+  #   true
+  # end
+end

data/lib/mcp_on_ruby/generators/templates/resource_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= resource_class_name %>, type: :model do
+  subject(:resource) { described_class.new }
+
+  describe '#read' do
+    <% if is_template? -%>
+    let(:params) { { <%= template_params.map { |p| "'#{p}' => 'test_#{p}'" }.join(', ') %> } }
+    <% else -%>
+    let(:params) { {} }
+    <% end -%>
+    let(:context) { { remote_ip: '127.0.0.1' } }
+
+    it 'returns resource content' do
+      result = resource.read(params, context)
+      
+      expect(result).to be_a(Hash)
+      expect(result).to have_key(:contents)
+      expect(result[:contents]).to be_an(Array)
+      
+      content = result[:contents].first
+      expect(content).to include(:uri, :mimeType, :text)
+    end
+
+    <% if is_template? -%>
+    it 'uses template parameters' do
+      result = resource.read(params, context)
+      content = JSON.parse(result[:contents].first[:text])
+      
+      expect(content['parameters']).to eq(params.stringify_keys)
+    end
+    <% end -%>
+  end
+
+  describe '#authorize' do
+    let(:context) { { authenticated: true } }
+
+    it 'returns true for authorized context' do
+      expect(resource.authorized?(context)).to be true
+    end
+  end
+
+  describe '#to_schema' do
+    it 'returns valid schema' do
+      schema = resource.to_schema
+      
+      expect(schema).to include(:uri, :mimeType)
+      expect(schema[:uri]).to eq('<%= resource_uri %>')
+    end
+  end
+
+  <% if is_template? -%>
+  describe '#template?' do
+    it 'returns true' do
+      expect(resource.template?).to be true
+    end
+  end
+
+  describe '#template_params' do
+    it 'returns parameter names' do
+      expect(resource.template_params).to match_array(<%= template_params.inspect %>)
+    end
+  end
+  <% end -%>
+end

data/lib/mcp_on_ruby/generators/templates/sample_resource.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Sample resource demonstrating MCP resource creation
+class SampleResource < ApplicationResource
+  def initialize
+    super(
+      uri: 'sample_data',
+      name: 'Sample Data',
+      description: 'A sample resource that provides application statistics',
+      mime_type: 'application/json',
+      metadata: {
+        category: 'sample',
+        version: '1.0.0'
+      },
+      tags: ['sample', 'stats']
+    )
+  end
+
+  protected
+
+  def fetch_content(params, context)
+    # Example: Fetch data from Rails models
+    {
+      application: {
+        name: Rails.application.class.module_parent_name,
+        environment: Rails.env,
+        version: '1.0.0'
+      },
+      statistics: {
+        # users_count: User.count,
+        # posts_count: Post.count,
+        uptime: uptime_info
+      },
+      timestamp: Time.current.iso8601,
+      request_info: {
+        remote_ip: context[:remote_ip],
+        user_agent: context[:user_agent]
+      }
+    }
+  end
+
+  # Optional: Add authorization logic
+  # def authorize(context)
+  #   # Example: Only allow authenticated users to read this resource
+  #   context[:authenticated] == true
+  # end
+
+  private
+
+  def uptime_info
+    load_avg = `uptime`.strip rescue 'unavailable'
+    {
+      server_uptime: load_avg,
+      rails_uptime: Time.current - Rails.application.config.time_zone.parse('2024-01-01')
+    }
+  end
+end

data/lib/mcp_on_ruby/generators/templates/sample_tool.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Sample tool demonstrating MCP tool creation
+class SampleTool < ApplicationTool
+  def initialize
+    super(
+      name: 'sample_tool',
+      description: 'A sample tool that demonstrates basic functionality',
+      input_schema: {
+        type: 'object',
+        properties: {
+          message: {
+            type: 'string',
+            description: 'Message to process'
+          },
+          count: {
+            type: 'integer',
+            description: 'Number of times to repeat',
+            minimum: 1,
+            maximum: 10,
+            default: 1
+          }
+        },
+        required: ['message']
+      },
+      metadata: {
+        category: 'sample',
+        version: '1.0.0'
+      },
+      tags: ['sample', 'demo']
+    )
+  end
+
+  protected
+
+  def execute(arguments, context)
+    message = arguments['message']
+    count = arguments['count'] || 1
+    
+    # Example: Access Rails models or services
+    # user_count = User.count
+    
+    {
+      success: true,
+      result: message * count,
+      processed_at: Time.current.iso8601,
+      context_info: {
+        remote_ip: context[:remote_ip],
+        user_agent: context[:user_agent]
+      }
+    }
+  end
+
+  # Optional: Add authorization logic
+  # def authorize(context)
+  #   # Example: Only allow authenticated users
+  #   context[:authenticated] == true
+  # end
+end

data/lib/mcp_on_ruby/generators/templates/tool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# <%= tool_description %>
+class <%= tool_class_name %> < ApplicationTool
+  def initialize
+    super(
+      name: '<%= tool_name %>',
+      description: '<%= tool_description %>',
+      <%= input_schema_code %>,
+      metadata: {
+        category: 'custom',
+        version: '1.0.0'
+      },
+      tags: ['<%= tool_name %>']
+    )
+  end
+
+  protected
+
+  def execute(arguments, context)
+    # Implement your tool logic here
+    # Arguments are validated according to input_schema
+    # Context contains request information (IP, headers, etc.)
+    
+    {
+      success: true,
+      result: "Tool <%= tool_name %> executed successfully",
+      arguments: arguments,
+      processed_at: Time.current.iso8601
+    }
+  end
+
+  # Optional: Add authorization logic
+  # def authorize(context)
+  #   # Return true/false based on context (user, permissions, etc.)
+  #   true
+  # end
+end

data/lib/mcp_on_ruby/generators/templates/tool_spec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= tool_class_name %>, type: :model do
+  subject(:tool) { described_class.new }
+
+  describe '#execute' do
+    let(:arguments) { {} }
+    let(:context) { { remote_ip: '127.0.0.1' } }
+
+    it 'executes successfully' do
+      result = tool.call(arguments, context)
+      
+      expect(result).to be_a(Hash)
+      expect(result[:success]).to be true
+    end
+
+    # Add more specific tests based on your tool's functionality
+    # context 'with valid arguments' do
+    #   let(:arguments) { { param: 'value' } }
+    #   
+    #   it 'returns expected result' do
+    #     result = tool.call(arguments, context)
+    #     
+    #     expect(result[:result]).to eq('expected_value')
+    #   end
+    # end
+    
+    # context 'with invalid arguments' do
+    #   let(:arguments) { { invalid: 'param' } }
+    #   
+    #   it 'raises validation error' do
+    #     expect { tool.call(arguments, context) }.to raise_error(McpOnRuby::ValidationError)
+    #   end
+    # end
+  end
+
+  describe '#authorize' do
+    let(:context) { { authenticated: true } }
+
+    it 'returns true for authorized context' do
+      expect(tool.authorized?(context)).to be true
+    end
+  end
+
+  describe '#to_schema' do
+    it 'returns valid schema' do
+      schema = tool.to_schema
+      
+      expect(schema).to include(:name, :description, :inputSchema)
+      expect(schema[:name]).to eq('<%= tool_name %>')
+    end
+  end
+end