fast-mcp 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50141727429ea7f39887b8a0f6ec2da8515cc3c35803a1c3e328287931bebcae
-  data.tar.gz: 518a481ba94b59f339b4e4957c54971866a76835e54833fd408efdb12e97c0e8
+  metadata.gz: 1a99f230c0ff73568287d0812e53c266dffca1bd46de3c0308000d5658b5b9a4
+  data.tar.gz: 38fb4275c6cf123691ed02145687c70f5251be28e784f71b42a00c85b5fbee3d
 SHA512:
-  metadata.gz: 76f1f6136bc4f1041021f5a3522f230ae1f044bb19e2e0d8f0871249aac222740b3907229db4b7d482812396f03d492cd6ea414206008f3737361e4346cbb5ca
-  data.tar.gz: 1ac14395b264d76b826feb2612a0ceae18933c8b37695ba8e5c673c6c5b29045f241617a2196409267f1c4c58b1fef0b3ff9865d92fae759306a6b17e2795db2
+  metadata.gz: f3863d28ed426ef2274475d0ba39630dcc673ef91a416a3ae4b76833cdb87dac3d40d6f01806dddf32572e0d0fa7ab5f5b0a5dd0c5619c6c73202dcfbfa4ccf5
+  data.tar.gz: 246ee983dc56d22708261681f5df1f0150e1376f19a18e373024ed5ecd12c1a54f592998a9738fb8d0aabb7194fe937ce98304a145f7bbf12efc1555d0b7d794

data/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.5.0] - 2025-06-01
+### Added
+- Handle filtering tools and resources [#85 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/85)
+- Support for resource templates 🥳 Big thanks to @danielcooper for the contribution [#84 co-authored by @danielcooper and @yjacquin](https://github.com/yjacquin/fast-mcp/pull/84)
+- Possibility to authorize requests before tool calls [#79 @EuanEdgar](https://github.com/yjacquin/fast-mcp/pull/79)
+- Possibility to read request headers in tool calls [#78 @EuanEdgar](https://github.com/yjacquin/fast-mcp/pull/78)
+### Changed
+- Bump Dependencies [#86 @aothelal](https://github.com/yjacquin/fast-mcp/pull/86)
+- ⚠️ Resources are now stateless, meaning that in-memory resources won't work anymore, they require an external data source such as database, file to read and write too, etc. This was needed for a refactoring of the resource class for the [resource template PR](https://github.com/yjacquin/fast-mcp/pull/84)
+### Fixed
+- Stop overriding log level to info [#91 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/91)
+- Properly handle ping request responses from clients [#89 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/89)
+- Add Thread Safety to RackTransport sse_clients [#82 @Kevin-K](https://github.com/yjacquin/fast-mcp/pull/82)
+
 ## [1.4.0] - 2025-05-10
 ### Added
 - Conditionnally hidden properties for tool calls (#70) [#70 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/70)

data/README.md

@@ -10,7 +10,7 @@
   <a href="https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg"><img src="https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg" alt="CI Status" /></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
   <a href="code_of_conduct.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg" alt="Contributor Covenant" /></a>
-  <a href="https://discord.gg/ayu8ZKvz"><img src = "https://dcbadge.limes.pink/api/server/https://discord.gg/ayu8ZKvz?style=flat" alt="Discord invite link" /></a>
+  <a href="https://discord.gg/9HHfAtY3HF"><img src = "https://dcbadge.limes.pink/api/server/https://discord.gg/9HHfAtY3HF?style=flat" alt="Discord invite link" /></a>
 </p>
 
 ## 🌟 Interface your Servers with LLMs in minutes !
@@ -32,6 +32,7 @@ Fast MCP solves all these problems by providing a clean, Ruby-focused implementa
 - 🧩 **Framework Integration** - Works seamlessly with Rails, Sinatra or any Rack app.
 - 🔒 **Authentication Support** - Secure your AI-powered endpoints with ease
 - 🚀 **Real-time Updates** - Subscribe to changes for interactive applications
+- 🎯 **Dynamic Filtering** - Control tool/resource access based on request context (permissions, API versions, etc.)
 
 
 ## 💎 What Makes FastMCP Great
@@ -65,7 +66,7 @@ server.register_tool(CreateUserTool)
 
 # Share data resources with AI models by inheriting from FastMcp::Resource
 class PopularUsers < FastMcp::Resource
-  uri "file://popular_users.json"
+  uri "myapp:///users/popular"
   resource_name "Popular Users"
   mime_type "application/json"
 
@@ -74,14 +75,59 @@ class PopularUsers < FastMcp::Resource
   end
 end
 
+class User < FastMcp::Resource
+  uri "myapp:///users/{id}" # This is a resource template
+  resource_name "user"
+  mime_type "application/json"
+
+  def content
+    id = params[:id] # params are computed from the uri pattern
+
+    JSON.generate(User.find(id).as_json)
+  end
+end
+
 # Register the resource with the server
-server.register_resource(PopularUsers)
+server.register_resources(PopularUsers, User)
 
 # Accessing the resource through the server
 server.read_resource(PopularUsers.uri)
 
 # Notify the resource content has been updated to clients
-server.notify_resource_updated(PopularUsers.uri)
+server.notify_resource_updated(PopularUsers.variabilized_uri)
+
+# Notifiy the content of a resource from a template has been updated to clients
+server.notify_resource_updated(User.variabilized_uri(id: 1))
+```
+
+### 🎯 Dynamic Tool Filtering
+
+Control which tools and resources are available based on request context:
+
+```ruby
+# Tag your tools for easy filtering
+class AdminTool < FastMcp::Tool
+  tags :admin, :dangerous
+  description "Perform admin operations"
+  
+  def call
+    # Admin only functionality
+  end
+end
+
+# Filter tools based on user permissions
+server.filter_tools do |request, tools|
+  user_role = request.params['role']
+  
+  case user_role
+  when 'admin'
+    tools # Admins see all tools
+  when 'user'
+    tools.reject { |t| t.tags.include?(:admin) }
+  else
+    tools.select { |t| t.tags.include?(:public) }
+  end
+end
 ```
 
 ### 🚂 Fast Ruby on Rails implementation
@@ -300,7 +346,7 @@ Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
 |---------|--------|
 | ✅ **JSON-RPC 2.0** | Full implementation for communication |
 | ✅ **Tool Definition & Calling** | Define and call tools with rich argument types |
-| ✅ **Resource Management** | Create, read, update, and subscribe to resources |
+| ✅ **Resource & Resource Templates Management** | Create, read, update, and subscribe to resources |
 | ✅ **Transport Options** | STDIO, HTTP, and SSE for flexible integration |
 | ✅ **Framework Integration** | Rails, Sinatra, Hanami, and any Rack-compatible framework |
 | ✅ **Authentication** | Secure your AI endpoints with token authentication |
@@ -353,6 +399,7 @@ FastMcp.authenticated_rack_middleware(app,
 - [📚 Resources](docs/resources.md)
 - [🛠️ Tools](docs/tools.md)
 - [🔒 Security](docs/security.md)
+- [🎯 Dynamic Filtering](docs/filtering.md)
 
 ## 💻 Examples
 

data/lib/mcp/resource.rb

@@ -3,7 +3,7 @@
 require 'json'
 require 'base64'
 require 'mime/types'
-require 'singleton'
+require 'addressable/template'
 
 module FastMcp
   # Resource class for MCP Resources feature
@@ -17,9 +17,62 @@ module FastMcp
       # @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
@@ -28,6 +81,13 @@ module FastMcp
         @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
@@ -47,12 +107,21 @@ module FastMcp
       # Get the resource metadata (without content)
       # @return [Hash] Resource metadata
       def metadata
-        {
-          uri: uri,
-          name: resource_name,
-          description: description,
-          mimeType: mime_type
-        }.compact
+        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)
@@ -87,7 +156,11 @@ module FastMcp
       end
     end
 
-    include Singleton
+    # 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
@@ -98,7 +171,7 @@ module FastMcp
     # Name of the resource - delegates to class method
     # @return [String, nil] The name for this resource
     def name
-      self.class.name
+      self.class.resource_name
     end
 
     # Description of the resource - delegates to class method
@@ -113,6 +186,10 @@ module FastMcp
       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
@@ -129,25 +206,5 @@ module FastMcp
         mime_type == 'application/xml' ||
         mime_type == 'application/javascript')
     end
-
-    # Get the resource contents
-    # @return [Hash] Resource contents
-    def contents
-      result = {
-        uri: uri,
-        mimeType: mime_type
-      }
-
-      content_value = content
-      if content_value
-        if binary?
-          result[:blob] = Base64.strict_encode64(content_value)
-        else
-          result[:text] = content_value
-        end
-      end
-
-      result
-    end
   end
 end

data/lib/mcp/server.rb

@@ -8,9 +8,12 @@ require_relative 'transports/stdio_transport'
 require_relative 'transports/rack_transport'
 require_relative 'transports/authenticated_rack_transport'
 require_relative 'logger'
+require_relative 'server_filtering'
 
 module FastMcp
   class Server
+    include ServerFiltering
+
     attr_reader :name, :version, :tools, :resources, :capabilities
 
     DEFAULT_CAPABILITIES = {
@@ -27,14 +30,15 @@ module FastMcp
       @name = name
       @version = version
       @tools = {}
-      @resources = {}
+      @resources = []
       @resource_subscriptions = {}
       @logger = logger
-      @logger.level = Logger::INFO
       @request_id = 0
       @transport_klass = nil
       @transport = nil
       @capabilities = DEFAULT_CAPABILITIES.dup
+      @tool_filters = []
+      @resource_filters = []
 
       # Merge with provided capabilities
       @capabilities.merge!(capabilities) if capabilities.is_a?(Hash)
@@ -66,8 +70,9 @@ module FastMcp
 
     # Register a resource with the server
     def register_resource(resource)
-      @resources[resource.uri] = resource
-      @logger.debug("Registered resource: #{resource.name} (#{resource.uri})")
+      @resources << resource
+
+      @logger.debug("Registered resource: #{resource.resource_name} (#{resource.uri})")
       resource.server = self
       # Notify subscribers about the list change
       notify_resource_list_changed if @transport
@@ -77,8 +82,10 @@ module FastMcp
 
     # Remove a resource from the server
     def remove_resource(uri)
-      if @resources.key?(uri)
-        resource = @resources.delete(uri)
+      resource = @resources.find { |r| r.uri == uri }
+
+      if resource
+        @resources.delete(resource)
         @logger.debug("Removed resource: #{resource.name} (#{uri})")
 
         # Notify subscribers about the list change
@@ -95,7 +102,7 @@ module FastMcp
       @logger.transport = :stdio
       @logger.info("Starting MCP server: #{@name} v#{@version}")
       @logger.info("Available tools: #{@tools.keys.join(', ')}")
-      @logger.info("Available resources: #{@resources.keys.join(', ')}")
+      @logger.info("Available resources: #{@resources.map(&:resource_name).join(', ')}")
 
       # Use STDIO transport by default
       @transport_klass = FastMcp::Transports::StdioTransport
@@ -107,7 +114,7 @@ module FastMcp
     def start_rack(app, options = {})
       @logger.info("Starting MCP server as Rack middleware: #{@name} v#{@version}")
       @logger.info("Available tools: #{@tools.keys.join(', ')}")
-      @logger.info("Available resources: #{@resources.keys.join(', ')}")
+      @logger.info("Available resources: #{@resources.map(&:resource_name).join(', ')}")
 
       # Use Rack transport
       transport_klass = FastMcp::Transports::RackTransport
@@ -121,7 +128,7 @@ module FastMcp
     def start_authenticated_rack(app, options = {})
       @logger.info("Starting MCP server as Authenticated Rack middleware: #{@name} v#{@version}")
       @logger.info("Available tools: #{@tools.keys.join(', ')}")
-      @logger.info("Available resources: #{@resources.keys.join(', ')}")
+      @logger.info("Available resources: #{@resources.map(&:resource_name).join(', ')}")
 
       # Use Rack transport
       transport_klass = FastMcp::Transports::AuthenticatedRackTransport
@@ -132,8 +139,15 @@ module FastMcp
       @transport
     end
 
+    # Handle a JSON-RPC request and return the response as a JSON string
+    def handle_json_request(request, headers: {})
+      request_str = request.is_a?(String) ? request : JSON.generate(request)
+
+      handle_request(request_str, headers: headers)
+    end
+
     # Handle incoming JSON-RPC request
-    def handle_request(json_str) # rubocop:disable Metrics/MethodLength
+    def handle_request(json_str, headers: {}) # rubocop:disable Metrics/MethodLength
       begin
         request = JSON.parse(json_str)
       rescue JSON::ParserError, TypeError
@@ -142,15 +156,13 @@ module FastMcp
 
       @logger.debug("Received request: #{request.inspect}")
 
-      # Check if it's a valid JSON-RPC 2.0 request
-      unless request['jsonrpc'] == '2.0' && request['method']
-        return send_error(-32_600, 'Invalid Request', request['id'])
-      end
-
       method = request['method']
       params = request['params'] || {}
       id = request['id']
 
+      # Check if it's a valid JSON-RPC 2.0 request
+      return send_error(-32_600, 'Invalid Request', id) unless request['jsonrpc'] == '2.0'
+
       case method
       when 'ping'
         send_result({}, id)
@@ -161,39 +173,26 @@ module FastMcp
       when 'tools/list'
         handle_tools_list(id)
       when 'tools/call'
-        handle_tools_call(params, id)
+        handle_tools_call(params, headers, id)
       when 'resources/list'
         handle_resources_list(id)
+      when 'resources/templates/list'
+        handle_resources_templates_list(id)
       when 'resources/read'
         handle_resources_read(params, id)
       when 'resources/subscribe'
         handle_resources_subscribe(params, id)
       when 'resources/unsubscribe'
         handle_resources_unsubscribe(params, id)
+      when nil
+        # This is a notification response, we don't need to handle it
+        nil
       else
         send_error(-32_601, "Method not found: #{method}", id)
       end
     rescue StandardError => e
       @logger.error("Error handling request: #{e.message}, #{e.backtrace.join("\n")}")
-      send_error(-32_600, "Internal error: #{e.message}", id)
-    end
-
-    # Handle a JSON-RPC request and return the response as a JSON string
-    def handle_json_request(request)
-      # Process the request
-      if request.is_a?(String)
-        handle_request(request)
-      else
-        handle_request(JSON.generate(request))
-      end
-    end
-
-    # Read a resource directly
-    def read_resource(uri)
-      resource = @resources[uri]
-      raise "Resource not found: #{uri}" unless resource
-
-      resource
+      send_error(-32_600, "Internal error: #{e.message}, #{e.backtrace.join("\n")}", id)
     end
 
     # Notify subscribers about a resource update
@@ -215,6 +214,10 @@ module FastMcp
       @transport.send_message(notification)
     end
 
+    def read_resource(uri)
+      @resources.find { |r| r.match(uri) }
+    end
+
     private
 
     PROTOCOL_VERSION = '2024-11-05'
@@ -249,24 +252,34 @@ module FastMcp
 
       return send_error(-32_602, 'Invalid params: missing resource URI', id) unless uri
 
-      resource = @resources[uri]
-      return send_error(-32_602, "Resource not found: #{uri}", id) unless resource
+      @logger.debug("Looking for resource with URI: #{uri}")
 
-      base_content = { uri: resource.uri }
-      base_content[:mimeType] = resource.mime_type if resource.mime_type
-      resource_instance = resource.instance
-      # Format the response according to the MCP specification
-      result = if resource_instance.binary?
-                 {
-                   contents: [base_content.merge(blob: Base64.strict_encode64(resource_instance.content))]
-                 }
-               else
-                 {
-                   contents: [base_content.merge(text: resource_instance.content)]
-                 }
-               end
-
-      send_result(result, id)
+      begin
+        resource = read_resource(uri)
+        return send_error(-32_602, "Resource not found: #{uri}", id) unless resource
+
+        @logger.debug("Found resource: #{resource.resource_name}, templated: #{resource.templated?}")
+
+        base_content = { uri: uri }
+        base_content[:mimeType] = resource.mime_type if resource.mime_type
+        resource_instance = resource.initialize_from_uri(uri)
+        @logger.debug("Resource instance params: #{resource_instance.params.inspect}")
+
+        result = if resource_instance.binary?
+                   {
+                     contents: [base_content.merge(blob: Base64.strict_encode64(resource_instance.content))]
+                   }
+                 else
+                   {
+                     contents: [base_content.merge(text: resource_instance.content)]
+                   }
+                 end
+
+        # # rescue StandardError => e
+        # @logger.error("Error reading resource: #{e.message}")
+        # @logger.error(e.backtrace.join("\n"))
+        send_result(result, id)
+      end
     end
 
     def handle_initialized_notification
@@ -292,7 +305,7 @@ module FastMcp
     end
 
     # Handle tools/call request
-    def handle_tools_call(params, id)
+    def handle_tools_call(params, headers, id)
       tool_name = params['name']
       arguments = params['arguments'] || {}
 
@@ -304,7 +317,13 @@ module FastMcp
       begin
         # Convert string keys to symbols for Ruby
         symbolized_args = symbolize_keys(arguments)
-        result, metadata = tool.new.call_with_schema_validation!(**symbolized_args)
+
+        tool_instance = tool.new(headers: headers)
+        authorized = tool_instance.authorized?(**symbolized_args)
+
+        return send_error(-32_602, 'Unauthorized', id) unless authorized
+
+        result, metadata = tool_instance.call_with_schema_validation!(**symbolized_args)
 
         # Format and send the result
         send_formatted_result(result, id, metadata)
@@ -346,11 +365,19 @@ module FastMcp
 
     # Handle resources/list request
     def handle_resources_list(id)
-      resources_list = @resources.values.map(&:metadata)
+      resources_list = @resources.select(&:non_templated?).map(&:metadata)
 
       send_result({ resources: resources_list }, id)
     end
 
+    # Handle resources/templates/list request
+    def handle_resources_templates_list(id)
+      # Collect templated resources
+      templated_resources_list = @resources.select(&:templated?).map(&:metadata)
+
+      send_result({ resourceTemplates: templated_resources_list }, id)
+    end
+
     # Handle resources/subscribe request
     def handle_resources_subscribe(params, id)
       return unless @client_initialized
@@ -362,11 +389,8 @@ module FastMcp
         return
       end
 
-      resource = @resources[uri]
-      unless resource
-        send_error(-32_602, "Resource not found: #{uri}", id)
-        return
-      end
+      resource = @resources.find { |r| r.match(uri) }
+      return send_error(-32_602, "Resource not found: #{uri}", id) unless resource
 
       # Add to subscriptions
       @resource_subscriptions[uri] ||= []

data/lib/mcp/server_filtering.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FastMcp
+  # Module for handling server filtering functionality
+  module ServerFiltering
+    # Add filter for tools
+    def filter_tools(&block)
+      @tool_filters << block if block_given?
+    end
+
+    # Add filter for resources
+    def filter_resources(&block)
+      @resource_filters << block if block_given?
+    end
+
+    # Check if filters are configured
+    def contains_filters?
+      @tool_filters.any? || @resource_filters.any?
+    end
+
+    # Create a filtered copy for a specific request
+    def create_filtered_copy(request)
+      filtered_server = self.class.new(
+        name: @name,
+        version: @version,
+        logger: @logger,
+        capabilities: @capabilities
+      )
+
+      # Copy transport settings
+      filtered_server.transport_klass = @transport_klass
+
+      # Apply filters and register items
+      register_filtered_tools(filtered_server, request)
+      register_filtered_resources(filtered_server, request)
+
+      filtered_server
+    end
+
+    private
+
+    # Apply tool filters and register filtered tools
+    def register_filtered_tools(filtered_server, request)
+      filtered_tools = apply_tool_filters(request)
+
+      # Register filtered tools
+      filtered_tools.each do |tool|
+        filtered_server.register_tool(tool)
+      end
+    end
+
+    # Apply resource filters and register filtered resources
+    def register_filtered_resources(filtered_server, request)
+      filtered_resources = apply_resource_filters(request)
+
+      # Register filtered resources
+      filtered_resources.each do |resource|
+        filtered_server.register_resource(resource)
+      end
+    end
+
+    # Apply all tool filters to the tools collection
+    def apply_tool_filters(request)
+      filtered_tools = @tools.values
+      @tool_filters.each do |filter|
+        filtered_tools = filter.call(request, filtered_tools)
+      end
+      filtered_tools
+    end
+
+    # Apply all resource filters to the resources collection
+    def apply_resource_filters(request)
+      filtered_resources = @resources
+      @resource_filters.each do |filter|
+        filtered_resources = filter.call(request, filtered_resources)
+      end
+      filtered_resources
+    end
+  end
+end

data/lib/mcp/tool.rb

@@ -94,6 +94,27 @@ module FastMcp
     class << self
       attr_accessor :server
 
+      # Add tagging support for tools
+      def tags(*tag_list)
+        if tag_list.empty?
+          @tags || []
+        else
+          @tags = tag_list.flatten.map(&:to_sym)
+        end
+      end
+
+      # Add metadata support for tools
+      def metadata(key = nil, value = nil)
+        @metadata ||= {}
+        if key.nil?
+          @metadata
+        elsif value.nil?
+          @metadata[key]
+        else
+          @metadata[key] = value
+        end
+      end
+
       def arguments(&block)
         @input_schema = Dry::Schema.JSON(&block)
       end
@@ -114,6 +135,11 @@ module FastMcp
         @description = description
       end
 
+      def authorize(&block)
+        @authorization_blocks ||= []
+        @authorization_blocks.push block
+      end
+
       def call(**args)
         raise NotImplementedError, 'Subclasses must implement the call method'
       end
@@ -126,11 +152,33 @@ module FastMcp
       end
     end
 
-    def initialize
+    def initialize(headers: {})
       @_meta = {}
+      @headers = headers
+    end
+
+    def authorized?(**args)
+      auth_checks = self.class.ancestors.filter_map do |ancestor|
+        ancestor.ancestors.include?(FastMcp::Tool) &&
+          ancestor.instance_variable_get(:@authorization_blocks)
+      end.flatten
+
+      return true if auth_checks.empty?
+
+      arg_validation = self.class.input_schema.call(args)
+      raise InvalidArgumentsError, arg_validation.errors.to_h.to_json if arg_validation.errors.any?
+
+      auth_checks.all? do |auth_check|
+        if auth_check.parameters.empty?
+          instance_exec(&auth_check)
+        else
+          instance_exec(**args, &auth_check)
+        end
+      end
     end
 
     attr_accessor :_meta
+    attr_reader :headers
 
     def notify_resource_updated(uri)
       self.class.server.notify_resource_updated(uri)

data/lib/mcp/transports/base_transport.rb

@@ -32,8 +32,8 @@ module FastMcp
 
       # Process an incoming message
       # This is a helper method that can be used by subclasses
-      def process_message(message)
-        server.handle_json_request(message)
+      def process_message(message, headers: {})
+        server.handle_request(message, headers: headers)
       end
     end
   end

data/lib/mcp/transports/rack_transport.rb

@@ -13,6 +13,7 @@ module FastMcp
       DEFAULT_PATH_PREFIX = '/mcp'
       DEFAULT_ALLOWED_ORIGINS = ['localhost', '127.0.0.1', '[::1]'].freeze
       DEFAULT_ALLOWED_IPS = ['127.0.0.1', '::1', '::ffff:127.0.0.1'].freeze
+      SERVER_ENV_KEY = 'fast_mcp.server'
 
       SSE_HEADERS = {
         'Content-Type' => 'text/event-stream',
@@ -40,8 +41,10 @@ module FastMcp
         @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 = {}
+        @sse_clients = Concurrent::Hash.new
+        @sse_clients_mutex = Mutex.new
         @running = false
+        @filtered_servers_cache = {}
       end
 
       # Start the transport
@@ -57,12 +60,14 @@ module FastMcp
         @running = false
 
         # Close all SSE connections
-        @sse_clients.each_value do |client|
-          client[:stream].close if client[:stream].respond_to?(:close) && !client[:stream].closed?
-        rescue StandardError => e
-          @logger.error("Error closing SSE connection: #{e.message}")
+        @sse_clients_mutex.synchronize do
+          @sse_clients.each_value do |client|
+            client[:stream].close if client[:stream].respond_to?(:close) && !client[:stream].closed?
+          rescue StandardError => e
+            @logger.error("Error closing SSE connection: #{e.message}")
+          end
+          @sse_clients.clear
         end
-        @sse_clients.clear
       end
 
       # Send a message to all connected SSE clients
@@ -71,21 +76,25 @@ module FastMcp
         @logger.debug("Broadcasting message to #{@sse_clients.size} SSE clients: #{json_message}")
 
         clients_to_remove = []
-
-        @sse_clients.each do |client_id, client|
-          stream = client[:stream]
-          next if stream.nil? || (stream.respond_to?(:closed?) && stream.closed?)
-
-          stream.write("data: #{json_message}\n\n")
-          stream.flush if stream.respond_to?(:flush)
-        rescue Errno::EPIPE, IOError => e
-          # Broken pipe or IO error - client disconnected
-          @logger.info("Client #{client_id} disconnected: #{e.message}")
-          clients_to_remove << client_id
-        rescue StandardError => e
-          @logger.error("Error sending message to client #{client_id}: #{e.message}")
-          # Remove the client if we can't send to it
-          clients_to_remove << client_id
+        @sse_clients_mutex.synchronize do
+          @sse_clients.each do |client_id, client|
+            stream = client[:stream]
+            mutex = client[:mutex]
+            next if stream.nil? || (stream.respond_to?(:closed?) && stream.closed?) || mutex.nil?
+
+            begin
+              mutex.synchronize do
+                stream.write("data: #{json_message}\n\n")
+                stream.flush if stream.respond_to?(:flush)
+              end
+            rescue Errno::EPIPE, IOError => e
+              @logger.info("Client #{client_id} disconnected: #{e.message}")
+              clients_to_remove << client_id
+            rescue StandardError => e
+              @logger.error("Error sending message to client #{client_id}: #{e.message}")
+              clients_to_remove << client_id
+            end
+          end
         end
 
         # Remove disconnected clients outside the loop to avoid modifying the hash during iteration
@@ -93,15 +102,19 @@ module FastMcp
       end
 
       # Register a new SSE client
-      def register_sse_client(client_id, stream)
-        @logger.info("Registering SSE client: #{client_id}")
-        @sse_clients[client_id] = { stream: stream, connected_at: Time.now }
+      def register_sse_client(client_id, stream, mutex = nil)
+        @sse_clients_mutex.synchronize do
+          @logger.info("Registering SSE client: #{client_id}")
+          @sse_clients[client_id] = { stream: stream, connected_at: Time.now, mutex: mutex || Mutex.new }
+        end
       end
 
       # Unregister an SSE client
       def unregister_sse_client(client_id)
-        @logger.info("Unregistering SSE client: #{client_id}")
-        @sse_clients.delete(client_id)
+        @sse_clients_mutex.synchronize do
+          @logger.info("Unregistering SSE client: #{client_id}")
+          @sse_clients.delete(client_id)
+        end
       end
 
       # Rack call method
@@ -196,19 +209,33 @@ module FastMcp
         # Validate Origin header to prevent DNS rebinding attacks
         return forbidden_response('Forbidden: Origin validation failed') unless validate_origin(request, env)
 
+        # Get the appropriate server for this request
+        request_server = get_server_for_request(request, env)
+
+        # Store the current transport temporarily if using a filtered server
+        if request_server != @server
+          original_transport = request_server.transport
+          request_server.transport = self
+        end
+
         subpath = request.path[@path_prefix.length..]
         @logger.debug("MCP request subpath: '#{subpath.inspect}'")
 
-        case subpath
-        when "/#{@sse_route}"
-          handle_sse_request(request, env)
-        when "/#{@messages_route}"
-          handle_message_request(request)
-        else
-          @logger.error('Received unknown request')
-          # Return 404 for unknown MCP endpoints
-          endpoint_not_found_response
-        end
+        result = case subpath
+                 when "/#{@sse_route}"
+                   handle_sse_request(request, env)
+                 when "/#{@messages_route}"
+                   handle_message_request_with_server(request, request_server)
+                 else
+                   @logger.error('Received unknown request')
+                   # Return 404 for unknown MCP endpoints
+                   endpoint_not_found_response
+                 end
+
+        # Restore original transport if needed
+        request_server.transport = original_transport if request_server != @server && original_transport
+
+        result
       end
 
       def forbidden_response(message)
@@ -265,7 +292,7 @@ module FastMcp
         else
           # Fallback for servers that don't support streaming
           @logger.info('Falling back to default SSE')
-          [200, headers, [":ok\n\n"]]
+          [200, SSE_HEADERS.dup, [":ok\n\n"]]
         end
       end
 
@@ -366,18 +393,24 @@ module FastMcp
 
       # Set up the SSE connection
       def setup_sse_connection(client_id, io, env)
+        # Handle for reconnection, if the client_id is already registered we reuse the mutex
+        # If not a reconnection, generate a new mutex used in registration
+        client = @sse_clients[client_id]
+        mutex = client ? client[:mutex] : Mutex.new
         # Send headers
         @logger.debug("Sending HTTP headers for SSE connection #{client_id}")
-        io.write("HTTP/1.1 200 OK\r\n")
-        SSE_HEADERS.each { |k, v| io.write("#{k}: #{v}\r\n") }
-        io.write("\r\n")
-        io.flush
+        mutex.synchronize do
+          io.write("HTTP/1.1 200 OK\r\n")
+          SSE_HEADERS.each { |k, v| io.write("#{k}: #{v}\r\n") }
+          io.write("\r\n")
+          io.flush
+        end
 
-        # Register client
-        register_sse_client(client_id, io)
+        # Register client (will overwrite if already present)
+        register_sse_client(client_id, io, mutex)
 
         # Send an initial comment to keep the connection alive
-        io.write(": SSE connection established\n\n")
+        mutex.synchronize { io.write(": SSE connection established\n\n") }
 
         # Extract query parameters from the request
         query_string = env['QUERY_STRING']
@@ -386,12 +419,14 @@ module FastMcp
         endpoint = "#{@path_prefix}/#{@messages_route}"
         endpoint += "?#{query_string}" if query_string
         @logger.debug("Sending endpoint information to client #{client_id}: #{endpoint}")
-        io.write("event: endpoint\ndata: #{endpoint}\n\n")
+        mutex.synchronize { io.write("event: endpoint\ndata: #{endpoint}\n\n") }
 
         # Send a retry directive with a very short reconnect time
         # This helps browsers reconnect quickly if the connection is lost
-        io.write("retry: 100\n\n") # 100ms reconnect time
-        io.flush
+        mutex.synchronize do
+          io.write("retry: 100\n\n")
+          io.flush
+        end
       rescue StandardError => e
         @logger.error("Error setting up SSE connection for client #{client_id}: #{e.message}")
         @logger.error(e.backtrace.join("\n")) if e.backtrace
@@ -417,11 +452,10 @@ module FastMcp
         ping_count = 0
         ping_interval = 1 # Send a ping every 1 second
         @running = true
-
+        mutex = @sse_clients[client_id] && @sse_clients[client_id][:mutex]
         while @running && !io.closed?
           begin
-            ping_count = send_keep_alive_ping(io, client_id, ping_count)
-
+            mutex.synchronize { ping_count = send_keep_alive_ping(io, client_id, ping_count) }
             sleep ping_interval
           rescue Errno::EPIPE, IOError => e
             # Broken pipe or IO error - client disconnected
@@ -434,7 +468,6 @@ module FastMcp
       # Send a keep-alive ping and return the updated 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
         io.write(": keep-alive #{ping_count}\n\n")
         io.flush
@@ -444,7 +477,6 @@ module FastMcp
           @logger.debug("Sending ping ##{ping_count} to SSE client #{client_id}")
           send_ping_event(io)
         end
-
         ping_count
       end
 
@@ -462,9 +494,14 @@ module FastMcp
       # Clean up SSE connection
       def cleanup_sse_connection(client_id, io)
         @logger.info("Cleaning up SSE connection for client #{client_id}")
+        mutex = @sse_clients[client_id] && @sse_clients[client_id][:mutex]
         unregister_sse_client(client_id)
         begin
-          io.close unless io.closed?
+          if mutex
+            mutex.synchronize { io.close unless io.closed? }
+          else
+            io.close unless io.closed?
+          end
           @logger.info("Successfully closed IO for client #{client_id}")
         rescue StandardError => e
           @logger.error("Error closing IO for client #{client_id}: #{e.message}")
@@ -484,13 +521,13 @@ module FastMcp
         [200, SSE_HEADERS, []]
       end
 
-      # Handle message POST request
-      def handle_message_request(request)
+      # Handle message POST request with specific server
+      def handle_message_request_with_server(request, server)
         @logger.debug('Received message request')
         return method_not_allowed_response unless request.post?
 
         begin
-          process_json_request(request)
+          process_json_request_with_server(request, server)
         rescue JSON::ParserError => e
           handle_parse_error(e)
         rescue StandardError => e
@@ -498,14 +535,19 @@ module FastMcp
         end
       end
 
-      # Process a JSON-RPC request
-      def process_json_request(request)
+      def process_json_request_with_server(request, server)
         # Parse the request body
         body = request.body.read
+        @logger.debug("Request body: #{body}")
+
+        # Extract headers that might be relevant
+        headers = request.env.select { |k, _v| k.start_with?('HTTP_') }
+                         .transform_keys { |k| k.sub('HTTP_', '').downcase.tr('_', '-') }
 
-        response = process_message(body) || []
-        @logger.info("Response: #{response}")
+        # Let the specific server handle the JSON request directly
+        response = server.handle_request(body, headers: headers) || []
 
+        # Return the JSON response
         [200, { 'Content-Type' => 'application/json' }, response]
       end
 
@@ -536,6 +578,50 @@ module FastMcp
            }
          )]]
       end
+
+      # Get the appropriate server for this request
+      def get_server_for_request(request, env)
+        # 1. Check for explicit server in env (highest priority)
+        if env[SERVER_ENV_KEY]
+          @logger.debug("Using server from env[#{SERVER_ENV_KEY}]")
+          return env[SERVER_ENV_KEY]
+        end
+
+        # 2. Apply filters if configured
+        if @server.contains_filters?
+          @logger.debug('Server has filters, creating filtered copy')
+          # Cache filtered servers to avoid recreating them
+          cache_key = generate_cache_key(request)
+
+          @filtered_servers_cache[cache_key] ||= @server.create_filtered_copy(request)
+          return @filtered_servers_cache[cache_key]
+        end
+
+        # 3. Use the default server
+        @logger.debug('Using default server')
+        @server
+      end
+
+      # Generate a cache key based on filter-relevant request attributes
+      def generate_cache_key(request)
+        # Generate a cache key based on filter-relevant request attributes
+        # This is a simple example - real implementation would be more sophisticated
+        {
+          path: request.path,
+          params: request.params.sort.to_h,
+          headers: extract_relevant_headers(request)
+        }.hash
+      end
+
+      # Extract headers that might be relevant for filtering
+      def extract_relevant_headers(request)
+        relevant_headers = {}
+        ['X-User-Role', 'X-API-Version', 'X-Tenant-ID', 'Authorization'].each do |header|
+          header_key = "HTTP_#{header.upcase.tr('-', '_')}"
+          relevant_headers[header] = request.env[header_key] if request.env[header_key]
+        end
+        relevant_headers
+      end
     end
   end
 end

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastMcp
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: fast-mcp
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Yorick Jacquin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-10 00:00:00.000000000 Z
+date: 2025-06-01 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
@@ -102,6 +116,7 @@ files:
 - lib/mcp/railtie.rb
 - lib/mcp/resource.rb
 - lib/mcp/server.rb
+- lib/mcp/server_filtering.rb
 - lib/mcp/tool.rb
 - lib/mcp/transports/authenticated_rack_transport.rb
 - lib/mcp/transports/base_transport.rb