fast-mcp 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a99f230c0ff73568287d0812e53c266dffca1bd46de3c0308000d5658b5b9a4
-  data.tar.gz: 38fb4275c6cf123691ed02145687c70f5251be28e784f71b42a00c85b5fbee3d
+  metadata.gz: 37917d61ab02f9d3a42e8980b9007bdb0003f2b91847b5cfe6e6a5f0043550cd
+  data.tar.gz: 476fa4ea8a2c022c255edcf3e5b3d101748fddaa8643569d2bc999ef8ec74eee
 SHA512:
-  metadata.gz: f3863d28ed426ef2274475d0ba39630dcc673ef91a416a3ae4b76833cdb87dac3d40d6f01806dddf32572e0d0fa7ab5f5b0a5dd0c5619c6c73202dcfbfa4ccf5
-  data.tar.gz: 246ee983dc56d22708261681f5df1f0150e1376f19a18e373024ed5ecd12c1a54f592998a9738fb8d0aabb7194fe937ce98304a145f7bbf12efc1555d0b7d794
+  metadata.gz: f12f0d7bf4a4f36b4a5d6c642160c01ccf40d5b799020cbc2c16646c7332b51083bc525c867f38cd2d5a68b3757f51f2fb0f632c35e004c7fcd7a8cb0f571cdf
+  data.tar.gz: 559edc8f334fcf49c16b001c8e36e4ea7aa664b2f53e2fa5f83edd171442dfe927cdd42cbbfaeb5572a174347729b193ec6b000f6b43ffd6850021365967f913

data/CHANGELOG.md

@@ -5,64 +5,109 @@ 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.6.0] - 2025-09-28
+
+### Added
+
+- Tool annotations support for providing hints about tool behavior (readOnlyHint, destructiveHint, etc.) [#96 @pauloarruda](https://github.com/yjacquin/fast-mcp/pull/96)
+- GitHub Discussions link in README [#139 @jeznicholson](https://github.com/yjacquin/fast-mcp/pull/139)
+- GitHub Sponsors funding configuration [#3d5a7e5 @yjacquin](https://github.com/yjacquin/fast-mcp/commit/3d5a7e5)
+- Server hook `on_error_result` for handling tool execution errors [#129 @yannickutard](https://github.com/yjacquin/fast-mcp/pull/129)
+- Support for transport option in rack_middleware [#149 @josevalim](https://github.com/yjacquin/fast-mcp/pull/149)
+
+### Fixed
+
+- Tool name validation and override for invalid names [#100 @abdelrahmanothman](https://github.com/yjacquin/fast-mcp/pull/100)
+- Typo fixes in sinatra_integration.md [#131 @ilyakamenko](https://github.com/yjacquin/fast-mcp/pull/131) [#102 @anton](https://github.com/yjacquin/fast-mcp/pull/102)
+- Add trailing comma to generated initializer template for better Ruby style [#123 @zachhaitz](https://github.com/yjacquin/fast-mcp/pull/123)
+- Fix missing commas for params hash [#121 @FanaHOVA](https://github.com/yjacquin/fast-mcp/pull/121)
+- RuboCop linting issues resolution [fa6af0b @yjacquin](https://github.com/yjacquin/fast-mcp/commit/fa6af0b)
+
+### Changed
+
+- Updated GitHub Actions dependencies: checkout v4→v5, download-artifact v4→v5 [#141 #142 @dependabot](https://github.com/yjacquin/fast-mcp/pull/141)
+- Relax Rack version requirements for better compatibility (>= 2.0, < 4.0) [#133 @eproulx](https://github.com/yjacquin/fast-mcp/pull/133)
+- Load generators only when necessary for improved performance [#153 @josevalim](https://github.com/yjacquin/fast-mcp/pull/153)
+- Drop schema compiler to use Dry's built-in functionality [#152 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/152), thanks @redox for the help !
+
 ## [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)
+
 ### Fixed
+
 - Fix undefined method `call' for an instance of String error log [#61 @radwo](https://github.com/yjacquin/fast-mcp/pull/61)
 
 ## [1.3.1] - 2025-04-30
+
 ### Fixed
--  Allow ipv4 mapped to ipv6 (#56) [#56 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
--  Add items to array (#55) [#55 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
--  Ping is a regular message event (#54) [#56 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
+
+- Allow ipv4 mapped to ipv6 (#56) [#56 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
+- Add items to array (#55) [#55 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
+- Ping is a regular message event (#54) [#56 @josevalim](https://github.com/yjacquin/fast-mcp/pull/56)
 
 ## [1.3.0] - 2025-04-28
+
 ### Added
+
 - Added automatic forwarding of query params from to the messages endpoint [@yjacquin](https://github.com/yjacquin/fast-mcp/commit/011d968ac982d0b0084f7753dcac5789f66339ee)
 
 ### Fixed
+
 - Declare rack as an explicit dependency [#49 @subelsky](https://github.com/yjacquin/fast-mcp/pull/49)
 - Fix notifications/initialized response [#51 @yjacquin](https://github.com/yjacquin/fast-mcp/pull/51)
 
 ## [1.2.0] - 2025-04-21
+
 ### 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
+
 - Rails integration improvements via enhanced Railtie support
 - Automatic tool and resource registration in Rails applications
 - Extended Rails autoload paths for tools and resources directories
@@ -73,6 +118,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Automated Github Releases through Github Workflow
 
 ### Fixed
+
 - Fixed bug with Rack middlewares not being initialized properly.
 - Fixed bug with STDIO logging preventing a proper connection with clients [# 11 @cs3b](https://github.com/yjacquin/fast-mcp/issues/11)
 - Fixed Rails SSE streaming detection and handling
@@ -80,9 +126,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Namespace consistency correction (FastMCP -> FastMcp) throughout the codebase
 
 ### Improved
+
 - ⚠️ [Breaking] Resource content declaration changes
+
   - Now resources implement `content` over `default_content`
   - `content` is dynamically called when calling a resource, this implies we can declare dynamic resource contents like:
+
   ```ruby
   class HighestScoringUsersResource < FastMcp::Resource
   ...
@@ -91,6 +140,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     end
   end
   ```
+
 - More robust SSE connection lifecycle management
 - Optimized test suite with faster execution times
 - Better logging for debugging connection issues

data/README.md

@@ -13,7 +13,7 @@
   <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 !
+## 🌟 Interface your Servers with LLMs in minutes
 
 AI models are powerful, but they need to interact with your applications to be truly useful. Traditional approaches mean wrestling with:
 
@@ -34,8 +34,8 @@ Fast MCP solves all these problems by providing a clean, Ruby-focused implementa
 - 🚀 **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
+
 ```ruby
 # Define tools for AI models to use
 server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')
@@ -49,10 +49,10 @@ class CreateUserTool < FastMcp::Tool
   arguments do
     required(:first_name).filled(:string).description("First name of the user")
     optional(:age).filled(:integer).description("Age of the user")
-    required(:address).hash do
-      optional(:street).filled(:string)
-      optional(:city).filled(:string)
-      optional(:zipcode).filled(:string)
+    required(:address).description("The shipping address").hash do
+      required(:street).filled(:string).description("Street address")
+      optional(:city).filled(:string).description("City name")
+      optional(:zipcode).maybe(:string).description("Postal code")
     end
   end
 
@@ -109,7 +109,7 @@ Control which tools and resources are available based on request context:
 class AdminTool < FastMcp::Tool
   tags :admin, :dangerous
   description "Perform admin operations"
-  
+
   def call
     # Admin only functionality
   end
@@ -118,7 +118,7 @@ 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
@@ -131,6 +131,7 @@ end
 ```
 
 ### 🚂 Fast Ruby on Rails implementation
+
 ```shell
 bundle add fast-mcp
 bin/rails generate fast_mcp:install
@@ -168,7 +169,9 @@ FastMcp.mount_in_rails(
   end
 end
 ```
+
 The install script will also:
+
 - add app/resources folder
 - add app/tools folder
 - add app/tools/sample_tool.rb
@@ -220,6 +223,7 @@ end
 ```
 
 ### Easy Sinatra setup
+
 I'll let you check out the dedicated [sinatra integration docs](./docs/sinatra_integration.md).
 
 ## 🚀 Quick Start
@@ -282,17 +286,21 @@ Clone this project, then give it a go !
 ```shell
 npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb
 ```
+
 Or to test with an SSE transport using a rack middleware:
+
 ```shell
 npx @modelcontextprotocol/inspector examples/rack_middleware.rb
 ```
 
 Or to test over SSE with an authenticated rack middleware:
+
 ```shell
 npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb
 ```
 
 You can test your custom implementation with the official MCP inspector by using:
+
 ```shell
 # Test with a stdio transport:
 npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb
@@ -321,6 +329,7 @@ end
 ### Integrating with Claude Desktop
 
 Add your server to your Claude Desktop configuration at:
+
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
@@ -329,28 +338,27 @@ Add your server to your Claude Desktop configuration at:
   "mcpServers": {
     "my-great-server": {
       "command": "ruby",
-      "args": [
-        "/Users/path/to/your/awesome/fast-mcp/server.rb"
-      ]
+      "args": ["/Users/path/to/your/awesome/fast-mcp/server.rb"]
     }
   }
 }
 ```
 
 ## How to add a MCP server to Claude, Cursor, or other MCP clients?
+
 Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
 
 ## 📊 Supported Specifications
 
-| Feature | Status |
-|---------|--------|
-| ✅ **JSON-RPC 2.0** | Full implementation for communication |
-| ✅ **Tool Definition & Calling** | Define and call tools with rich argument types |
-| ✅ **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 |
-| ✅ **Schema Support** | Full JSON Schema for tool arguments with validation |
+| Feature                                         | Status                                                    |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| ✅ **JSON-RPC 2.0**                             | Full implementation for communication                     |
+| ✅ **Tool Definition & Calling**                | Define and call tools with rich argument types            |
+| ✅ **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        |
+| ✅ **Schema Support**                           | Full JSON Schema for tool arguments with validation       |
 
 ## 🗺️ Use Cases
 
@@ -406,6 +414,7 @@ FastMcp.authenticated_rack_middleware(app,
 Check out the [examples directory](examples) for more detailed examples:
 
 - **🔨 Basic Examples**:
+
   - [Simple Server](examples/server_with_stdio_transport.rb)
   - [Tool Examples](examples/tool_examples.rb)
 

data/lib/fast_mcp.rb

@@ -16,9 +16,6 @@ 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|
@@ -39,6 +36,7 @@ module FastMcp
   # @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 [Class] :transport The transport class 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
@@ -71,17 +69,8 @@ module FastMcp
   # @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)
+    options[:transport] ||= FastMcp::Transports::AuthenticatedRackTransport
+    rack_middleware(app, options)
   end
 
   # Register a tool with the MCP server

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

@@ -20,12 +20,12 @@ FastMcp.mount_in_rails(
   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
+  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']
+  # 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/generators/fast_mcp/install/templates/sample_tool.rb

@@ -3,6 +3,13 @@
 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')

data/lib/mcp/railtie.rb

@@ -41,5 +41,9 @@ module FastMcp
       path = File.expand_path('../tasks', __dir__)
       Dir.glob("#{path}/**/*.rake").each { |f| load f }
     end
+
+    generators do
+      require 'generators/fast_mcp/install/install_generator'
+    end
   end
 end

data/lib/mcp/server.rb

@@ -39,6 +39,7 @@ module FastMcp
       @capabilities = DEFAULT_CAPABILITIES.dup
       @tool_filters = []
       @resource_filters = []
+      @on_error_result = nil
 
       # Merge with provided capabilities
       @capabilities.merge!(capabilities) if capabilities.is_a?(Hash)
@@ -80,6 +81,10 @@ module FastMcp
       resource
     end
 
+    def on_error_result(&block)
+      @on_error_result = block
+    end
+
     # Remove a resource from the server
     def remove_resource(uri)
       resource = @resources.find { |r| r.uri == uri }
@@ -112,27 +117,14 @@ module FastMcp
 
     # Start the server as a Rack middleware
     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.map(&:resource_name).join(', ')}")
-
-      # Use Rack transport
-      transport_klass = FastMcp::Transports::RackTransport
-      @transport = transport_klass.new(app, self, options.merge(logger: @logger))
-      @transport.start
+      @transport_klass = options.delete(:transport) || FastMcp::Transports::RackTransport
+      transport_name = @transport_klass.name.split('::').last
 
-      # Return the transport as middleware
-      @transport
-    end
-
-    def start_authenticated_rack(app, options = {})
-      @logger.info("Starting MCP server as Authenticated Rack middleware: #{@name} v#{@version}")
+      @logger.info("Starting MCP server with #{transport_name}: #{@name} v#{@version}")
       @logger.info("Available tools: #{@tools.keys.join(', ')}")
       @logger.info("Available resources: #{@resources.map(&:resource_name).join(', ')}")
 
-      # Use Rack transport
-      transport_klass = FastMcp::Transports::AuthenticatedRackTransport
-      @transport = transport_klass.new(app, self, options.merge(logger: @logger))
+      @transport = @transport_klass.new(app, self, options.merge(logger: @logger))
       @transport.start
 
       # Return the transport as middleware
@@ -294,11 +286,25 @@ module FastMcp
     # Handle tools/list request
     def handle_tools_list(id)
       tools_list = @tools.values.map do |tool|
-        {
+        tool_info = {
           name: tool.tool_name,
           description: tool.description || '',
           inputSchema: tool.input_schema_to_json || { type: 'object', properties: {}, required: [] }
         }
+
+        # Add annotations if they exist
+        annotations = tool.annotations
+        unless annotations.empty?
+          # Convert snake_case keys to camelCase for MCP protocol
+          camel_case_annotations = {}
+          annotations.each do |key, value|
+            camel_key = key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }.to_sym
+            camel_case_annotations[camel_key] = value
+          end
+          tool_info[:annotations] = camel_case_annotations
+        end
+
+        tool_info
       end
 
       send_result({ tools: tools_list }, id)
@@ -354,6 +360,8 @@ module FastMcp
 
     # Format and send error result
     def send_error_result(message, id)
+      @on_error_result&.call(message)
+
       # Format error according to the MCP specification
       error_result = {
         content: [{ type: 'text', text: "Error: #{message}" }],