fast-mcp-annotations 1.5.0

data/lib/fast_mcp.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# Fast MCP - A Ruby Implementation of the Model Context Protocol (Server-side)
+# https://modelcontextprotocol.io/introduction
+
+# Define the MCP module
+module FastMcp
+  class << self
+    attr_accessor :server
+  end
+end
+
+# Require the core components
+require_relative 'mcp/tool'
+require_relative 'mcp/server'
+require_relative 'mcp/resource'
+require_relative 'mcp/railtie' if defined?(Rails::Railtie)
+
+# Load generators if Rails is available
+require_relative 'generators/fast_mcp/install/install_generator' if defined?(Rails::Generators)
+
+# Require all transport files
+require_relative 'mcp/transports/base_transport'
+Dir[File.join(File.dirname(__FILE__), 'mcp/transports', '*.rb')].each do |file|
+  require file
+end
+
+# Version information
+require_relative 'mcp/version'
+
+# Convenience method to create a Rack middleware
+module FastMcp
+  # Create a Rack middleware for the MCP server
+  # @param app [#call] The Rack application
+  # @param options [Hash] Options for the middleware
+  # @option options [String] :name The name of the server
+  # @option options [String] :version The version of the server
+  # @option options [String] :path_prefix The path prefix for the MCP endpoints
+  # @option options [String] :messages_route The route for the messages endpoint
+  # @option options [String] :sse_route The route for the SSE endpoint
+  # @option options [Logger] :logger The logger to use
+  # @option options [Array<String,Regexp>] :allowed_origins List of allowed origins for DNS rebinding protection
+  # @yield [server] A block to configure the server
+  # @yieldparam server [FastMcp::Server] The server to configure
+  # @return [#call] The Rack middleware
+  def self.rack_middleware(app, options = {})
+    name = options.delete(:name) || 'mcp-server'
+    version = options.delete(:version) || '1.0.0'
+    logger = options.delete(:logger) || Logger.new
+
+    server = FastMcp::Server.new(name: name, version: version, logger: logger)
+    yield server if block_given?
+
+    # Store the server in the Sinatra settings if available
+    app.settings.set(:mcp_server, server) if app.respond_to?(:settings) && app.settings.respond_to?(:mcp_server=)
+
+    # Store the server in the FastMcp module
+    self.server = server
+
+    server.start_rack(app, options)
+  end
+
+  # Create a Rack middleware for the MCP server with authentication
+  # @param app [#call] The Rack application
+  # @param options [Hash] Options for the middleware
+  # @option options [String] :name The name of the server
+  # @option options [String] :version The version of the server
+  # @option options [String] :auth_token The authentication token
+  # @option options [Array<String,Regexp>] :allowed_origins List of allowed origins for DNS rebinding protection
+  # @yield [server] A block to configure the server
+  # @yieldparam server [FastMcp::Server] The server to configure
+  # @return [#call] The Rack middleware
+  def self.authenticated_rack_middleware(app, options = {})
+    name = options.delete(:name) || 'mcp-server'
+    version = options.delete(:version) || '1.0.0'
+    logger = options.delete(:logger) || Logger.new
+
+    server = FastMcp::Server.new(name: name, version: version, logger: logger)
+    yield server if block_given?
+
+    # Store the server in the FastMcp module
+    self.server = server
+
+    server.start_authenticated_rack(app, options)
+  end
+
+  # Register a tool with the MCP server
+  # @param tool [FastMcp::Tool] The tool to register
+  # @return [FastMcp::Tool] The registered tool
+  def self.register_tool(tool)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_tool(tool)
+  end
+
+  # Register multiple tools at once
+  # @param tools [Array<FastMcp::Tool>] The tools to register
+  # @return [Array<FastMcp::Tool>] The registered tools
+  def self.register_tools(*tools)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_tools(*tools)
+  end
+
+  # Register a resource with the MCP server
+  # @param resource [FastMcp::Resource] The resource to register
+  # @return [FastMcp::Resource] The registered resource
+  def self.register_resource(resource)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_resource(resource)
+  end
+
+  # Register multiple resources at once
+  # @param resources [Array<FastMcp::Resource>] The resources to register
+  # @return [Array<FastMcp::Resource>] The registered resources
+  def self.register_resources(*resources)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_resources(*resources)
+  end
+
+  # Mount the MCP middleware in a Rails application
+  # @param app [Rails::Application] The Rails application
+  # @param options [Hash] Options for the middleware
+  # @option options [String] :name The name of the server
+  # @option options [String] :version The version of the server
+  # @option options [String] :path_prefix The path prefix for the MCP endpoints
+  # @option options [String] :messages_route The route for the messages endpoint
+  # @option options [String] :sse_route The route for the SSE endpoint
+  # @option options [Logger] :logger The logger to use
+  # @option options [Boolean] :authenticate Whether to use authentication
+  # @option options [String] :auth_token The authentication token
+  # @option options [Array<String,Regexp>] :allowed_origins List of allowed origins for DNS rebinding protection
+  # @yield [server] A block to configure the server
+  # @yieldparam server [FastMcp::Server] The server to configure
+  # @return [#call] The Rack middleware
+  def self.mount_in_rails(app, options = {})
+    # Default options
+    name = options.delete(:name) || app.class.module_parent_name.underscore.dasherize
+    version = options.delete(:version) || '1.0.0'
+    logger = options[:logger] || Rails.logger
+    path_prefix = options.delete(:path_prefix) || '/mcp'
+    messages_route = options.delete(:messages_route) || 'messages'
+    sse_route = options.delete(:sse_route) || 'sse'
+    authenticate = options.delete(:authenticate) || false
+    allowed_origins = options[:allowed_origins] || default_rails_allowed_origins(app)
+    allowed_ips = options[:allowed_ips] || FastMcp::Transports::RackTransport::DEFAULT_ALLOWED_IPS
+
+    options[:localhost_only] = Rails.env.local? if options[:localhost_only].nil?
+    options[:allowed_ips] = allowed_ips
+    options[:logger] = logger
+    options[:allowed_origins] = allowed_origins
+
+    # Create or get the server
+    self.server = FastMcp::Server.new(name: name, version: version, logger: logger)
+    yield self.server if block_given?
+
+    # Choose the right middleware based on authentication
+    self.server.transport_klass = if authenticate
+                                    FastMcp::Transports::AuthenticatedRackTransport
+                                  else
+                                    FastMcp::Transports::RackTransport
+                                  end
+
+    # Insert the middleware in the Rails middleware stack
+    app.middleware.use(
+      self.server.transport_klass,
+      self.server,
+      options.merge(path_prefix: path_prefix, messages_route: messages_route, sse_route: sse_route)
+    )
+  end
+
+  def self.default_rails_allowed_origins(rail_app)
+    hosts = rail_app.config.hosts
+
+    hosts.map do |host|
+      if host.is_a?(String) && host.start_with?('.')
+        # Convert .domain to domain and *.domain
+        host_without_dot = host[1..]
+        [host_without_dot, Regexp.new(".*\.#{host_without_dot}")] # rubocop:disable Style/RedundantStringEscape
+      else
+        host
+      end
+    end.flatten.compact
+  end
+
+  # Notify the server that a resource has been updated
+  # @param uri [String] The URI of the resource
+  def self.notify_resource_updated(uri)
+    self.server.notify_resource_updated(uri)
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module FastMcp
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a FastMcp initializer for Rails applications'
+
+      def copy_initializer
+        template 'fast_mcp_initializer.rb', 'config/initializers/fast_mcp.rb'
+      end
+
+      def create_directories
+        empty_directory 'app/tools'
+        empty_directory 'app/resources'
+      end
+
+      def copy_application_tool
+        template 'application_tool.rb', 'app/tools/application_tool.rb'
+      end
+
+      def copy_application_resource
+        template 'application_resource.rb', 'app/resources/application_resource.rb'
+      end
+
+      def copy_sample_tool
+        template 'sample_tool.rb', 'app/tools/sample_tool.rb'
+      end
+
+      def copy_sample_resource
+        template 'sample_resource.rb', 'app/resources/sample_resource.rb'
+      end
+
+      def display_post_install_message
+        say "\n========================================================="
+        say 'FastMcp was successfully installed! 🎉'
+        say "=========================================================\n"
+        say 'You can now create:'
+        say '  • Tools in app/tools/'
+        say '  • Resources in app/resources/'
+        say "\n"
+        say 'Check config/initializers/fast_mcp.rb to configure the middleware.'
+        say "=========================================================\n"
+      end
+    end
+  end
+end

data/lib/generators/fast_mcp/install/templates/application_resource.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationResource < ActionResource::Base
+  # write your custom logic to be shared across all resources here
+end

data/lib/generators/fast_mcp/install/templates/application_tool.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationTool < ActionTool::Base
+  # write your custom logic to be shared across all tools here
+end

data/lib/generators/fast_mcp/install/templates/fast_mcp_initializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# FastMcp - Model Context Protocol for Rails
+# This initializer sets up the MCP middleware in your Rails application.
+#
+# In Rails applications, you can use:
+# - ActionTool::Base as an alias for FastMcp::Tool
+# - ActionResource::Base as an alias for FastMcp::Resource
+#
+# All your tools should inherit from ApplicationTool which already uses ActionTool::Base,
+# and all your resources should inherit from ApplicationResource which uses ActionResource::Base.
+
+# Mount the MCP middleware in your Rails application
+# You can customize the options below to fit your needs.
+require 'fast_mcp'
+
+FastMcp.mount_in_rails(
+  Rails.application,
+  name: Rails.application.class.module_parent_name.underscore.dasherize,
+  version: '1.0.0',
+  path_prefix: '/mcp', # This is the default path prefix
+  messages_route: 'messages', # This is the default route for the messages endpoint
+  sse_route: 'sse' # This is the default route for the SSE endpoint
+  # Add allowed origins below, it defaults to Rails.application.config.hosts
+  # allowed_origins: ['localhost', '127.0.0.1', '[::1]', 'example.com', /.*\.example\.com/],
+  # localhost_only: true, # Set to false to allow connections from other hosts
+  # whitelist specific ips to if you want to run on localhost and allow connections from other IPs
+  # allowed_ips: ['127.0.0.1', '::1']
+  # authenticate: true,       # Uncomment to enable authentication
+  # auth_token: 'your-token', # Required if authenticate: true
+) do |server|
+  Rails.application.config.after_initialize do
+    # FastMcp will automatically discover and register:
+    # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
+    # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
+    server.register_tools(*ApplicationTool.descendants)
+    server.register_resources(*ApplicationResource.descendants)
+    # alternatively, you can register tools and resources manually:
+    # server.register_tool(MyTool)
+    # server.register_resource(MyResource)
+  end
+end

data/lib/generators/fast_mcp/install/templates/sample_resource.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class SampleResource < ApplicationResource
+  uri 'examples/users'
+  resource_name 'Users'
+  description 'A user resource for demonstration'
+  mime_type 'application/json'
+
+  def content
+    JSON.generate(User.all.as_json)
+  end
+end

data/lib/generators/fast_mcp/install/templates/sample_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class SampleTool < ApplicationTool
+  description 'Greet a user'
+
+  # Optional: Add annotations to provide hints about the tool's behavior
+  # annotations(
+  #   title: 'User Greeting',
+  #   read_only_hint: true,      # This tool only reads data
+  #   open_world_hint: false     # This tool only accesses the local database
+  # )
+
+  arguments do
+    required(:id).filled(:integer).description('ID of the user to greet')
+    optional(:prefix).filled(:string).description('Prefix to add to the greeting')
+  end
+
+  def call(id:, prefix: 'Hey')
+    user = User.find(id)
+
+    "#{prefix} #{user.first_name} !"
+  end
+end

data/lib/mcp/logger.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# This class is not used yet.
+module FastMcp
+  class Logger < Logger
+    def initialize(transport: :stdio)
+      @client_initialized = false
+      @transport = transport
+
+      # we don't want to log to stdout if we're using the stdio transport
+      super($stdout) unless stdio_transport?
+    end
+
+    attr_accessor :transport, :client_initialized
+    alias client_initialized? client_initialized
+
+    def stdio_transport?
+      transport == :stdio
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      return if stdio_transport? # we don't want to log to stdout if we're using the stdio transport
+
+      # TODO: implement logging as the specification requires
+      super
+    end
+
+    def rack_transport?
+      transport == :rack
+    end
+  end
+end

data/lib/mcp/railtie.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'fileutils'
+require_relative '../mcp/server'
+
+# Create ActionTool and ActionResource modules at load time
+unless defined?(ActionTool)
+  module ::ActionTool
+    Base = FastMcp::Tool
+  end
+end
+
+unless defined?(ActionResource)
+  module ::ActionResource
+    Base = FastMcp::Resource
+  end
+end
+
+module FastMcp
+  # Railtie for integrating Fast MCP with Rails applications
+  class Railtie < Rails::Railtie
+    # Add tools and resources directories to autoload paths
+    initializer 'fast_mcp.setup_autoload_paths' do |app|
+      app.config.autoload_paths += %W[
+        #{app.root}/app/tools
+        #{app.root}/app/resources
+      ]
+    end
+
+    # Auto-register all tools and resources after the application is fully loaded
+    config.after_initialize do
+      # Load all files in app/tools and app/resources directories
+      Dir[Rails.root.join('app', 'tools', '**', '*.rb')].each { |f| require f }
+      Dir[Rails.root.join('app', 'resources', '**', '*.rb')].each { |f| require f }
+    end
+
+    # Add rake tasks
+    rake_tasks do
+      # Path to the tasks directory in the gem
+      path = File.expand_path('../tasks', __dir__)
+      Dir.glob("#{path}/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/mcp/resource.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+require 'mime/types'
+require 'addressable/template'
+
+module FastMcp
+  # Resource class for MCP Resources feature
+  # Represents a resource that can be exposed to clients
+  class Resource
+    class << self
+      attr_accessor :server
+
+      # Define URI for this resource
+      # @param value [String, nil] The URI for this resource
+      # @return [String] The URI for this resource
+      def uri(value = nil)
+        @uri = value if value
+
+        @uri || (superclass.respond_to?(:uri) ? superclass.uri : nil)
+      end
+
+      # Variabilize the URI with the given params
+      # @param params [Hash] The parameters to variabilize the URI with
+      # @return [String] The variabilized URI
+      def variabilized_uri(params = {})
+        addressable_template.partial_expand(params).pattern
+      end
+
+      # Get the Addressable::Template for this resource
+      # @return [Addressable::Template] The Addressable::Template for this resource
+      def addressable_template
+        @addressable_template ||= Addressable::Template.new(uri)
+      end
+
+      # Get the template variables for this resource
+      # @return [Array] The template variables for this resource
+      def template_variables
+        addressable_template.variables
+      end
+
+      # Check if this resource has a templated URI
+      # @return [Boolean] true if the URI contains template parameters
+      def templated?
+        template_variables.any?
+      end
+
+      # Check if this resource has a non-templated URI
+      # @return [Boolean] true if the URI does not contain template parameters
+      def non_templated?
+        !templated?
+      end
+
+      # Match the given URI against the resource's addressable template
+      # @param uri [String] The URI to match
+      # @return [Addressable::Template::MatchData, nil] The match data if the URI matches, nil otherwise
+      def match(uri)
+        addressable_template.match(uri)
+      end
+
+      # Initialize a new instance from the given URI
+      # @param uri [String] The URI to initialize from
+      # @return [Resource] A new resource instance
+      def initialize_from_uri(uri)
+        new(params_from_uri(uri))
+      end
+
+      # Get the parameters from the given URI
+      # @param uri [String] The URI to get the parameters from
+      # @return [Hash] The parameters from the URI
+      def params_from_uri(uri)
+        match(uri).mapping.transform_keys(&:to_sym)
+      end
+
+      # Define name for this resource
+      # @param value [String, nil] The name for this resource
+      # @return [String] The name for this resource
+      def resource_name(value = nil)
+        @name = value if value
+        @name || (superclass.respond_to?(:resource_name) ? superclass.resource_name : nil)
+      end
+
+      alias original_name name
+      def name
+        return resource_name if resource_name
+
+        original_name
+      end
+
+      # Define description for this resource
+      # @param value [String, nil] The description for this resource
+      # @return [String] The description for this resource
+      def description(value = nil)
+        @description = value if value
+        @description || (superclass.respond_to?(:description) ? superclass.description : nil)
+      end
+
+      # Define MIME type for this resource
+      # @param value [String, nil] The MIME type for this resource
+      # @return [String] The MIME type for this resource
+      def mime_type(value = nil)
+        @mime_type = value if value
+        @mime_type || (superclass.respond_to?(:mime_type) ? superclass.mime_type : nil)
+      end
+
+      # Get the resource metadata (without content)
+      # @return [Hash] Resource metadata
+      def metadata
+        if templated?
+          {
+            uriTemplate: uri,
+            name: resource_name,
+            description: description,
+            mimeType: mime_type
+          }.compact
+        else
+          {
+            uri: uri,
+            name: resource_name,
+            description: description,
+            mimeType: mime_type
+          }.compact
+        end
+      end
+
+      # Load content from a file (class method)
+      # @param file_path [String] Path to the file
+      # @return [Resource] New resource instance with content loaded from file
+      def from_file(file_path, name: nil, description: nil)
+        file_uri = "file://#{File.absolute_path(file_path)}"
+        file_name = name || File.basename(file_path)
+
+        # Create a resource subclass on the fly
+        Class.new(self) do
+          uri file_uri
+          resource_name file_name
+          description description if description
+
+          # Auto-detect mime type
+          extension = File.extname(file_path)
+          unless extension.empty?
+            detected_types = MIME::Types.type_for(extension)
+            mime_type detected_types.first.to_s unless detected_types.empty?
+          end
+
+          # Override content method to load from file
+          define_method :content do
+            if binary?
+              File.binread(file_path)
+            else
+              File.read(file_path)
+            end
+          end
+        end
+      end
+    end
+
+    # Initialize with instance variables
+    # @param params [Hash] The parameters for this resource instance
+    def initialize(params = {})
+      @params = params
+    end
+
+    # URI of the resource - delegates to class method
+    # @return [String, nil] The URI for this resource
+    def uri
+      self.class.uri
+    end
+
+    # Name of the resource - delegates to class method
+    # @return [String, nil] The name for this resource
+    def name
+      self.class.resource_name
+    end
+
+    # Description of the resource - delegates to class method
+    # @return [String, nil] The description for this resource
+    def description
+      self.class.description
+    end
+
+    # MIME type of the resource - delegates to class method
+    # @return [String, nil] The MIME type for this resource
+    def mime_type
+      self.class.mime_type
+    end
+
+    # Get parameters from the URI template
+    # @return [Hash] The parameters extracted from the URI
+    attr_reader :params
+
+    # Method to be overridden by subclasses to dynamically generate content
+    # @return [String, nil] Generated content for this resource
+    def content
+      raise NotImplementedError, 'Subclasses must implement content'
+    end
+
+    # Check if the resource is binary
+    # @return [Boolean] true if the resource is binary, false otherwise
+    def binary?
+      return false if mime_type.nil?
+
+      !(mime_type.start_with?('text/') ||
+        mime_type == 'application/json' ||
+        mime_type == 'application/xml' ||
+        mime_type == 'application/javascript')
+    end
+  end
+end