fast-mcp 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bedabe91d57ecb3800b625ad786389c7e842b73e5bcd9df621f8f31b401fe93f
-  data.tar.gz: b8711a78f8f8928e5f66d94a1f271f9f6e6a5e101e0386eff81ed62e7153d2ae
+  metadata.gz: e9a99e9fd2c611e1645bfda1cd3d4c924f86b4284e1018e53d8f55c7612c6d48
+  data.tar.gz: bc9def81c86fb8db4ecdb32091209050a7d860c64d7204158ecfb98e27d01156
 SHA512:
-  metadata.gz: 564cadd64c076e784bc0779a3f697d82d50eed14c77b1403f03abeee0935972103e68bf82bb94ec7cd3443b90ddfa75d739dd6a5a0bda32590e8b31d8a708869
-  data.tar.gz: 731cc93d551842dfcec399d7d75d86c59d4a6af88d415925757a3ced8c5947dda7ae26eafc12b71423af496c6669a084cdbaabdc05cbbacef68476d39925991e
+  metadata.gz: 44ba180b84383e3f0cff990136551101cea90181cb384634abecf72ab96ae0316ab53cf9e05eb09626642f647dac8cf2039edc808339dd11c579cd14a0333d13
+  data.tar.gz: 03b61251ec444d33748a23c1a786f70fea8d54228017b2b1dec0eeae93cb1900afc9af8b19d3fb3c55bbfba26a8e52e2d5ddc266fd6a19f72de692b3ef880382

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - UNRELEASED
+### Added
+- Security enhancement: Bing only to localhost by default [#44 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/44)
+- Prevent AuthenticatedRackMiddleware from blocking other rails routes[#35 @JulianPasquale](https://github.com/yjacquin/fast-mcp/pull/35)
+- Stop Forcing reconnections after 30 pings [#42 @zoedsoupe](https://github.com/yjacquin/fast-mcp/pull/42)
+
+
+## [1.1.0] - 2025-04-13
+### Added
+- Security enhancement: Added DNS rebinding protection by validating Origin headers [#32 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/32/files)
+- Added configuration options for allowed origins in rack middleware [#32 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/32/files)
+- Allow to change the SSE and Messages route [#23 @pedrofurtado](https://github.com/yjacquin/fast-mcp/pull/23)
+- Fix invalid return value when processing notifications/initialized request [#31 @abMatGit](https://github.com/yjacquin/fast-mcp/pull/31)
+
+
 ## [1.0.0] - 2025-03-30
 
 ### Added
@@ -52,5 +67,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Resource management with subscription capabilities
 - Binary resource support
 - Examples with STDIO Transport, HTTP & SSE, Rack app
-- Initialize lifecycle with capabilities 
+- Initialize lifecycle with capabilities
 - Comprehensive test suite with RSpec

data/README.md

@@ -36,12 +36,11 @@ Fast MCP solves all these problems by providing a clean, Ruby-focused implementa
 ## 💎 What Makes FastMCP Great
 ```ruby
 # Define tools for AI models to use
-server = FastMcp::Server.new(name: 'recipe-ai', version: '1.0.0')
+server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')
 
 # Define a tool by inheriting from FastMcp::Tool
 class CreateUserTool < FastMcp::Tool
-  description "Find recipes based on ingredients"
-  
+  description "Create a user"
     # These arguments will generate the needed JSON to be presented to the MCP Client
     # And they will be validated at run time.
     # The validation is based off Dry-Schema, with the addition of the description.
@@ -54,7 +53,7 @@ class CreateUserTool < FastMcp::Tool
       optional(:zipcode).filled(:string)
     end
   end
-  
+
   def call(first_name:, age: nil, address: {})
     User.create!(first_name:, age:, address:)
   end
@@ -68,20 +67,20 @@ class PopularUsers < FastMcp::Resource
   uri "file://popular_users.json"
   resource_name "Popular Users"
   mime_type "application/json"
-  
+
   def content
     JSON.generate(User.popular.limit(5).as_json)
   end
 end
 
 # Register the resource with the server
-server.register_resource(IngredientsResource)
+server.register_resource(PopularUsers)
 
 # Accessing the resource through the server
-server.read_resource(IngredientsResource.uri)
+server.read_resource(PopularUsers.uri)
 
 # Notify the resource content has been updated to clients
-server.notify_resource_updated(IngredientsResource.uri)
+server.notify_resource_updated(PopularUsers.uri)
 ```
 
 ### 🚂 Fast Ruby on Rails implementation
@@ -99,9 +98,16 @@ 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
+  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', '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
+  # auth_token: 'your-token' # Required if authenticate: true
 ) do |server|
   Rails.application.config.after_initialize do
     # FastMcp will automatically discover and register:
@@ -136,11 +142,11 @@ These are automatically set up in Rails applications. You can use either naming
 # Using Rails-style naming:
 class MyTool < ActionTool::Base
   description "My awesome tool"
-  
+
   arguments do
     required(:input).filled(:string)
   end
-  
+
   def call(input:)
     # Your implementation
   end
@@ -182,12 +188,12 @@ server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')
 # Define a tool by inheriting from FastMcp::Tool
 class SummarizeTool < FastMcp::Tool
   description "Summarize a given text"
-  
+
   arguments do
     required(:text).filled(:string).description("Text to summarize")
     optional(:max_length).filled(:integer).description("Maximum length of summary")
   end
-  
+
   def call(text:, max_length: 100)
     # Your summarization logic here
     text.split('.').first(3).join('.') + '...'
@@ -203,7 +209,7 @@ class StatisticsResource < FastMcp::Resource
   resource_name "Usage Statistics"
   description "Current system statistics"
   mime_type "application/json"
-  
+
   def content
     JSON.generate({
       users_online: 120,
@@ -307,6 +313,36 @@ Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
 - 📚 **Interactive Documentation**: Create AI-enhanced API documentation
 - 💬 **Chatbots and Assistants**: Build AI assistants with access to your app's data
 
+## 🔒 Security Features
+
+Fast MCP includes built-in security features to protect your applications:
+
+### DNS Rebinding Protection
+
+The HTTP/SSE transport validates the Origin header on all incoming connections to prevent DNS rebinding attacks, which could allow malicious websites to interact with local MCP servers.
+
+```ruby
+# Configure allowed origins (defaults to ['localhost', '127.0.0.1'])
+FastMcp.rack_middleware(app,
+  allowed_origins: ['localhost', '127.0.0.1', 'your-domain.com', /.*\.your-domain\.com/],
+  localhost_only: false,
+  allowed_ips: ['192.168.1.1', '10.0.0.1'],
+  # other options...
+)
+```
+
+### Authentication
+
+Fast MCP supports token-based authentication for all connections:
+
+```ruby
+# Enable authentication
+FastMcp.authenticated_rack_middleware(app,
+  auth_token: 'your-secret-token',
+  # other options...
+)
+```
+
 ## 📖 Documentation
 
 - [🚀 Getting Started Guide](docs/getting_started.md)
@@ -315,6 +351,7 @@ Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
 - [🌐 Sinatra Integration](docs/sinatra_integration.md)
 - [📚 Resources](docs/resources.md)
 - [🛠️ Tools](docs/tools.md)
+- [🔒 Security](docs/security.md)
 
 ## 💻 Examples
 

data/lib/fast_mcp.rb

@@ -36,7 +36,10 @@ module FastMcp
   # @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
@@ -63,6 +66,7 @@ module FastMcp
   # @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
@@ -118,9 +122,12 @@ module FastMcp
   # @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
@@ -130,9 +137,17 @@ module FastMcp
     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?
@@ -145,7 +160,25 @@ module FastMcp
                                   end
 
     # Insert the middleware in the Rails middleware stack
-    app.middleware.use self.server.transport_klass, self.server, options.merge(path_prefix: path_prefix)
+    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

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

@@ -18,7 +18,14 @@ 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
+  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|

data/lib/mcp/server.rb

@@ -275,7 +275,7 @@ module FastMcp
       @client_initialized = true
       @logger.info('Client initialized, beginning normal operation')
 
-      nil
+      send_result({}, nil)
     end
 
     # Handle tools/list request

data/lib/mcp/transports/authenticated_rack_transport.rb

@@ -14,9 +14,7 @@ module FastMcp
         @auth_enabled = !@auth_token.nil?
       end
 
-      def call(env)
-        request = Rack::Request.new(env)
-
+      def handle_mcp_request(request, env)
         if auth_enabled? && !exempt_from_auth?(request.path)
           auth_header = request.env["HTTP_#{@auth_header_name.upcase.gsub('-', '_')}"]
           token = auth_header&.gsub('Bearer ', '')
@@ -42,6 +40,7 @@ module FastMcp
       end
 
       def unauthorized_response(request)
+        @logger.error('Unauthorized request: Invalid or missing authentication token')
         body = JSON.generate(
           {
             jsonrpc: '2.0',

data/lib/mcp/transports/rack_transport.rb

@@ -9,15 +9,22 @@ module FastMcp
   module Transports
     # Rack middleware transport for MCP
     # This transport can be mounted in any Rack-compatible web framework
-    class RackTransport < BaseTransport
+    class RackTransport < BaseTransport # rubocop:disable Metrics/ClassLength
       DEFAULT_PATH_PREFIX = '/mcp'
-
-      attr_reader :app, :path_prefix, :sse_clients
+      DEFAULT_ALLOWED_ORIGINS = ['localhost', '127.0.0.1', '[::1]'].freeze
+      DEFAULT_ALLOWED_IPS = ['127.0.0.1', '::1'].freeze
+      attr_reader :app, :path_prefix, :sse_clients, :messages_route, :sse_route, :allowed_origins, :localhost_only,
+                  :allowed_ips
 
       def initialize(app, server, options = {}, &_block)
         super(server, logger: options[:logger])
         @app = app
         @path_prefix = options[:path_prefix] || DEFAULT_PATH_PREFIX
+        @messages_route = options[:messages_route] || 'messages'
+        @sse_route = options[:sse_route] || 'sse'
+        @allowed_origins = options[:allowed_origins] || DEFAULT_ALLOWED_ORIGINS
+        @localhost_only = options.fetch(:localhost_only, true) # Default to localhost-only mode
+        @allowed_ips = options[:allowed_ips] || DEFAULT_ALLOWED_IPS
         @sse_clients = {}
         @running = false
       end
@@ -25,6 +32,7 @@ module FastMcp
       # Start the transport
       def start
         @logger.debug("Starting Rack transport with path prefix: #{@path_prefix}")
+        @logger.info("DNS rebinding protection enabled. Allowed origins: #{allowed_origins.join(', ')}")
         @running = true
       end
 
@@ -100,15 +108,86 @@ module FastMcp
 
       private
 
+      def validate_client_ip(request)
+        client_ip = request.ip
+
+        # Check if we're in localhost-only mode
+        if @localhost_only && !@allowed_ips.include?(client_ip)
+          @logger.warn("Blocked connection from non-localhost IP: #{client_ip}")
+          return false
+        end
+
+        true
+      end
+
+      # Validate the Origin header to prevent DNS rebinding attacks
+      def validate_origin(request, env)
+        origin = env['HTTP_ORIGIN']
+
+        # If no origin header is present, check the referer or host
+        origin = env['HTTP_REFERER'] || request.host if origin.nil? || origin.empty?
+
+        # Extract hostname from the origin
+        hostname = extract_hostname(origin)
+
+        # If we have a hostname and allowed_origins is not empty
+        if hostname && !allowed_origins.empty?
+          @logger.debug("Validating origin: #{hostname}")
+
+          # Check if the hostname matches any allowed origin
+          is_allowed = allowed_origins.any? do |allowed|
+            if allowed.is_a?(Regexp)
+              hostname.match?(allowed)
+            else
+              hostname == allowed
+            end
+          end
+
+          unless is_allowed
+            @logger.warn("Blocked request with origin: #{hostname}")
+            return false
+          end
+        end
+
+        true
+      end
+
+      # Extract hostname from a URL
+      def extract_hostname(url)
+        return nil if url.nil? || url.empty?
+
+        begin
+          # Check if the URL has a scheme, if not, add http:// as a prefix
+          has_scheme = url.match?(%r{^[a-zA-Z][a-zA-Z0-9+.-]*://})
+          parsing_url = has_scheme ? url : "http://#{url}"
+
+          uri = URI.parse(parsing_url)
+
+          # Return nil for invalid URLs where host is empty
+          return nil if uri.host.nil? || uri.host.empty?
+
+          uri.host
+        rescue URI::InvalidURIError
+          # If standard parsing fails, try to extract host with a regex for host:port format
+          url.split(':').first if url.match?(%r{^([^:/]+)(:\d+)?$})
+        end
+      end
+
       # Handle MCP-specific requests
       def handle_mcp_request(request, env)
+        # Validate client IP to ensure it's connecting from allowed sources
+        return forbidden_response('Forbidden: Remote IP not allowed') unless validate_client_ip(request)
+
+        # Validate Origin header to prevent DNS rebinding attacks
+        return forbidden_response('Forbidden: Origin validation failed') unless validate_origin(request, env)
+
         subpath = request.path[@path_prefix.length..]
         @logger.info("MCP request subpath: '#{subpath.inspect}'")
 
         case subpath
-        when '/sse'
+        when "/#{@sse_route}"
           handle_sse_request(request, env)
-        when '/messages'
+        when "/#{@messages_route}"
           handle_message_request(request)
         else
           @logger.info('Received unknown request')
@@ -117,6 +196,20 @@ module FastMcp
         end
       end
 
+      def forbidden_response(message)
+        [403, { 'Content-Type' => 'application/json' },
+         [JSON.generate(
+           {
+             jsonrpc: '2.0',
+             error: {
+               code: -32_600,
+               message: message
+             },
+             id: nil
+           }
+         )]]
+      end
+
       # Return a 404 endpoint not found response
       def endpoint_not_found_response
         [404, { 'Content-Type' => 'application/json' },
@@ -213,9 +306,6 @@ module FastMcp
         browser_type = detect_browser_type(user_agent)
         @logger.info("Client connection from: #{user_agent} (#{browser_type})")
 
-        # Handle MCP inspector with fixed client ID
-        @logger.info("MCP Inspector detected, using fixed client ID: #{client_id}") if mcp_inspector?(user_agent, env)
-
         # Handle reconnection
         if client_id && @sse_clients.key?(client_id)
           handle_client_reconnection(client_id, browser_type)
@@ -248,11 +338,6 @@ module FastMcp
         end
       end
 
-      # Check if client is MCP inspector
-      def mcp_inspector?(user_agent, env)
-        user_agent.include?('mcp-inspector') || (env['mcp.client_name'] == 'mcp-inspector')
-      end
-
       # Handle client reconnection
       def handle_client_reconnection(client_id, browser_type)
         @logger.info("Client #{client_id} is reconnecting (#{browser_type})")
@@ -300,7 +385,7 @@ module FastMcp
         io.write(": SSE connection established\n\n")
 
         # Send endpoint information as the first message
-        endpoint = "#{@path_prefix}/messages"
+        endpoint = "#{@path_prefix}/#{@messages_route}"
         @logger.debug("Sending endpoint information to client #{client_id}: #{endpoint}")
         io.write("event: endpoint\ndata: #{endpoint}\n\n")
 
@@ -332,13 +417,11 @@ module FastMcp
         @logger.info("Starting keep-alive loop for SSE connection #{client_id}")
         ping_count = 0
         ping_interval = 1 # Send a ping every 1 second
-        max_ping_count = 30 # Reset connection after 30 pings (about 30 seconds)
         @running = true
 
         while @running && !io.closed?
           begin
-            ping_count = send_keep_alive_ping(io, client_id, ping_count, max_ping_count)
-            break if ping_count >= max_ping_count
+            ping_count = send_keep_alive_ping(io, client_id, ping_count)
 
             sleep ping_interval
           rescue Errno::EPIPE, IOError => e
@@ -350,7 +433,7 @@ module FastMcp
       end
 
       # Send a keep-alive ping and return the updated ping count
-      def send_keep_alive_ping(io, client_id, ping_count, max_ping_count)
+      def send_keep_alive_ping(io, client_id, ping_count)
         ping_count += 1
 
         # Send a comment before each ping to keep the connection alive
@@ -363,12 +446,6 @@ module FastMcp
           send_ping_event(io)
         end
 
-        # If we've reached the max ping count, force a reconnection
-        if ping_count >= max_ping_count
-          @logger.debug("Reached max ping count (#{max_ping_count}) for client #{client_id}, forcing reconnection")
-          send_reconnect_event(io)
-        end
-
         ping_count
       end
 
@@ -377,18 +454,12 @@ module FastMcp
         ping_message = {
           jsonrpc: '2.0',
           method: 'ping',
-          id: SecureRandom.uuid
+          id: rand(1_000_000)
         }
         io.write("event: ping\ndata: #{JSON.generate(ping_message)}\n\n")
         io.flush
       end
 
-      # Send a reconnect event
-      def send_reconnect_event(io)
-        io.write("event: reconnect\ndata: {\"reason\":\"timeout prevention\"}\n\n")
-        io.flush
-      end
-
       # Clean up SSE connection
       def cleanup_sse_connection(client_id, io)
         @logger.info("Cleaning up SSE connection for client #{client_id}")

data/lib/mcp/version.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# Version information
 module FastMcp
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fast-mcp
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Yorick Jacquin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-30 00:00:00.000000000 Z
+date: 2025-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64