fast-mcp 1.3.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 247f36763da6fd88d9c9e454d5d63eaeb351d08a72de8c2e5dc65919d9e2a9f1
-  data.tar.gz: 846d3427bb33357cfdc6c5387d153d393449792455beab413e36eeb8d0f1bf1d
+  metadata.gz: 1a99f230c0ff73568287d0812e53c266dffca1bd46de3c0308000d5658b5b9a4
+  data.tar.gz: 38fb4275c6cf123691ed02145687c70f5251be28e784f71b42a00c85b5fbee3d
 SHA512:
-  metadata.gz: 8917675ff31b47cd67ddc5171a0c1e853cca9ba8a5853a7a9314ab5b794c9868c7c48b2db17dbd2edb580e81e9b12de8a0318151239babc2a5971cc2d4b10d72
-  data.tar.gz: 926a58cda786415804f88bb7d2cbabe91fe90b6ae84964be9452070f0ac4de7a29705eedd69af79c641c4e4086865b5dda3438108f1cb068457b1b9c2930472e
+  metadata.gz: f3863d28ed426ef2274475d0ba39630dcc673ef91a416a3ae4b76833cdb87dac3d40d6f01806dddf32572e0d0fa7ab5f5b0a5dd0c5619c6c73202dcfbfa4ccf5
+  data.tar.gz: 246ee983dc56d22708261681f5df1f0150e1376f19a18e373024ed5ecd12c1a54f592998a9738fb8d0aabb7194fe937ce98304a145f7bbf12efc1555d0b7d794

data/CHANGELOG.md

@@ -5,6 +5,26 @@ 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)
+- Metadata to tool call results (#69) [#69 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/69)
+- Link to official Discord Server in README.md
+
 ## [1.3.2] - 2025-05-08
 ### Changed
 - Logs are now less verbose by default [#64 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/64)

data/README.md

@@ -10,6 +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/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 !
@@ -31,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
@@ -64,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"
 
@@ -73,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
@@ -299,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 |
@@ -352,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,10 +317,16 @@ module FastMcp
       begin
         # Convert string keys to symbols for Ruby
         symbolized_args = symbolize_keys(arguments)
-        result = 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)
+        send_formatted_result(result, id, metadata)
       rescue FastMcp::Tool::InvalidArgumentsError => e
         @logger.error("Invalid arguments for tool #{tool_name}: #{e.message}")
         send_error_result(e.message, id)
@@ -318,18 +337,18 @@ module FastMcp
     end
 
     # Format and send successful result
-    def send_formatted_result(result, id)
+    def send_formatted_result(result, id, metadata)
       # Check if the result is already in the expected format
       if result.is_a?(Hash) && result.key?(:content)
-        # Result is already in the correct format
-        send_result(result, id)
+        send_result(result, id, metadata: metadata)
       else
         # Format the result according to the MCP specification
         formatted_result = {
           content: [{ type: 'text', text: result.to_s }],
           isError: false
         }
-        send_result(formatted_result, id)
+
+        send_result(formatted_result, id, metadata: metadata)
       end
     end
 
@@ -340,16 +359,25 @@ module FastMcp
         content: [{ type: 'text', text: "Error: #{message}" }],
         isError: true
       }
+
       send_result(error_result, id)
     end
 
     # 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
@@ -361,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] ||= []
@@ -408,7 +433,9 @@ module FastMcp
     end
 
     # Send a JSON-RPC result response
-    def send_result(result, id)
+    def send_result(result, id, metadata: {})
+      result[:_meta] = metadata if metadata.is_a?(Hash) && !metadata.empty?
+
       response = {
         jsonrpc: '2.0',
         id: id,
@@ -429,6 +456,7 @@ module FastMcp
         },
         id: id
       }
+
       send_response(response)
     end