fast-mcp 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94b9b8af1c648e0637ad0dc3d0118c8354392bac61b0f8c30d4eb264bc7a8fda
-  data.tar.gz: 728c09e7b7848fcc1f9296e42fed083933b8c8bb9cf08d02c8708009a378f0c1
+  metadata.gz: bedabe91d57ecb3800b625ad786389c7e842b73e5bcd9df621f8f31b401fe93f
+  data.tar.gz: b8711a78f8f8928e5f66d94a1f271f9f6e6a5e101e0386eff81ed62e7153d2ae
 SHA512:
-  metadata.gz: 1e26886cc6c006df64e913b7d517fbcffd1c2c4e6a27787e8fccbb3e0d5c172ec1e337ada9928cff1821fca96e2fcd173e4bf7bc4f492fc9eb4404463ed3e0a8
-  data.tar.gz: c91ea6f439f68ae5f301f4cd5adb24aaebc1939cfe8f2458ec038310b294293b2eaf6b5f8518972fdef5f1bf6acdbda59ec14997d1a01cf46171d4605152cf93
+  metadata.gz: 564cadd64c076e784bc0779a3f697d82d50eed14c77b1403f03abeee0935972103e68bf82bb94ec7cd3443b90ddfa75d739dd6a5a0bda32590e8b31d8a708869
+  data.tar.gz: 731cc93d551842dfcec399d7d75d86c59d4a6af88d415925757a3ced8c5947dda7ae26eafc12b71423af496c6669a084cdbaabdc05cbbacef68476d39925991e

data/CHANGELOG.md

@@ -5,13 +5,49 @@ 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.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
+- Sample generator templates for resources and tools
+- MCP Client configuration documentation as reported by [#8 @sivag-csod](https://github.com/yjacquin/fast-mcp/issues/8)
+- Example Ruby on Rails app in the documentation
+- `FastMcp.server` now exposes the MCP server to apps that may need it to access resources
+- 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
+- Improved error handling in client reconnection scenarios
+- 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
+  ...
+    def content
+      User.order(score: :desc).last(5).map(&:as_json)
+    end
+  end
+  ```
+- More robust SSE connection lifecycle management
+- Optimized test suite with faster execution times
+- Better logging for debugging connection issues
+- Documentation had outdated examples
+
 ## [0.1.0] - 2025-03-12
 
 ### Added
 
 - Initial release of the Fast MCP library
-- MCP::Tool class with multiple definition styles
-- MCP::Server class with STDIO transport and HTTP / SSE transport
+- FastMcp::Tool class with multiple definition styles
+- FastMcp::Server class with STDIO transport and HTTP / SSE transport
 - Rack Integration with authenticated and standard middleware options
 - Resource management with subscription capabilities
 - Binary resource support

data/README.md

@@ -28,44 +28,49 @@ Fast MCP solves all these problems by providing a clean, Ruby-focused implementa
 - 🛠️ **Tools API** - Let AI models call your Ruby functions securely, with in-depth argument validation through [Dry-Schema](https://github.com/dry-rb/dry-schema).
 - 📚 **Resources API** - Share data between your app and AI models
 - 🔄 **Multiple Transports** - Choose from STDIO, HTTP, or SSE based on your needs
-- 🧩 **Framework Integration** - Works seamlessly with Rails, Sinatra, and Hanami
-- 🔒 **Authentication Support** - Secure your AI endpoints with ease
+- 🧩 **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
 
-## 💎 What Makes FastMCP Great
 
+## 💎 What Makes FastMCP Great
 ```ruby
 # Define tools for AI models to use
-server = MCP::Server.new(name: 'recipe-ai', version: '1.0.0')
+server = FastMcp::Server.new(name: 'recipe-ai', version: '1.0.0')
 
-# Define a tool by inheriting from MCP::Tool
-class GetRecipesTool < MCP::Tool
+# Define a tool by inheriting from FastMcp::Tool
+class CreateUserTool < FastMcp::Tool
   description "Find recipes based on ingredients"
   
-  arguments do
     # These arguments will generate the needed JSON to be presented to the MCP Client
-    # And they will be vaidated at run time.
+    # And they will be validated at run time.
     # The validation is based off Dry-Schema, with the addition of the description.
-    required(:ingredients).array(:string).description("List of ingredients")
-    optional(:cuisine).filled(:string).description("Type of cuisine")
+  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)
+    end
   end
   
-  def call(ingredients:, cuisine: nil)
-    Recipe.find_by_ingredients(ingredients, cuisine: cuisine)
+  def call(first_name:, age: nil, address: {})
+    User.create!(first_name:, age:, address:)
   end
 end
 
 # Register the tool with the server
-server.register_tool(GetRecipesTool)
+server.register_tool(CreateUserTool)
 
-# Share data resources with AI models by inheriting from MCP::Resource
-class IngredientsResource < MCP::Resource
-  uri "food/popular_ingredients"
-  name "Popular Ingredients"
+# Share data resources with AI models by inheriting from FastMcp::Resource
+class PopularUsers < FastMcp::Resource
+  uri "file://popular_users.json"
+  resource_name "Popular Users"
   mime_type "application/json"
   
-  def default_content
-    JSON.generate(Ingredient.popular.as_json)
+  def content
+    JSON.generate(User.popular.limit(5).as_json)
   end
 end
 
@@ -73,88 +78,109 @@ end
 server.register_resource(IngredientsResource)
 
 # Accessing the resource through the server
-server.read_resource("food/popular_ingredients")
+server.read_resource(IngredientsResource.uri)
 
-# Updating the resource content through the server
-server.update_resource("food/popular_ingredients", JSON.generate({id: 1, name: 'tomato'}))
+# Notify the resource content has been updated to clients
+server.notify_resource_updated(IngredientsResource.uri)
+```
 
+### 🚂 Fast Ruby on Rails implementation
+```shell
+bundle add fast-mcp
+bin/rails generate fast_mcp:install
+```
 
-# Easily integrate with web frameworks
-# config/application.rb (Rails)
-config.middleware.use MCP::RackMiddleware.new(
-  name: 'recipe-ai', 
-  version: '1.0.0'
-) do |server|
-  # Register tools and resources here
-  server.register_tool(GetRecipesTool)
-end
+This will add a configurable `fast_mcp.rb` initializer
 
-# Secure your AI endpoints
-config.middleware.use MCP::AuthenticatedRackMiddleware.new(
-  name: 'recipe-ai',
-  version: '1.0.0',
-  token: ENV['MCP_AUTH_TOKEN']
-)
+```ruby
+require 'fast_mcp'
 
-# Build real-time applications
-server.on_resource_update do |resource|
-  ActionCable.server.broadcast("recipe_updates", resource.metadata)
+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
+  # authenticate: true,       # Uncomment to enable authentication
+  # auth_token: 'your-token', # Required if authenticate: true
+) do |server|
+  Rails.application.config.after_initialize do
+    # FastMcp will automatically discover and register:
+    # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
+    # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
+    server.register_tools(*ApplicationTool.descendants)
+    server.register_resources(*ApplicationResource.descendants)
+    # alternatively, you can register tools and resources manually:
+    # server.register_tool(MyTool)
+    # server.register_resource(MyResource)
+  end
 end
 ```
+The install script will also:
+- add app/resources folder
+- add app/tools folder
+- add app/tools/sample_tool.rb
+- add app/resources/sample_resource.rb
+- add ApplicationTool to inherit from
+- add ApplicationResource to inherit from as well
 
-## 📦 Installation
+#### Rails-friendly class naming conventions
 
-```ruby
-# In your Gemfile
-gem 'fast-mcp'
+For Rails applications, FastMCP provides Rails-style class names to better fit with Rails conventions:
 
-# Then run
-bundle install
+- `ActionTool::Base` - An alias for `FastMcp::Tool`
+- `ActionResource::Base` - An alias for `FastMcp::Resource`
 
-# Or install it yourself
-gem install fast-mcp
-```
+These are automatically set up in Rails applications. You can use either naming convention in your code:
 
-## 🚀 Quick Start
+```ruby
+# 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
+end
 
-### Testing with the inspector
+# Using standard FastMcp naming:
+class AnotherTool < FastMcp::Tool
+  # Both styles work interchangeably in Rails apps
+end
+```
 
-MCP has developed a very [useful inspector](https://github.com/modelcontextprotocol/inspector).
-You can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate.
-Clone this project, then give it a go !
+When creating new tools or resources, the generators will use the Rails naming convention by default:
 
-```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
-```
+```ruby
+# app/tools/application_tool.rb
+class ApplicationTool < ActionTool::Base
+  # Base methods for all tools
+end
 
-Or to test over SSE with an authenticated rack middleware:
-```shell
-npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb
+# app/resources/application_resource.rb
+class ApplicationResource < ActionResource::Base
+  # Base methods for all resources
+end
 ```
 
-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
+### Easy Sinatra setup
+I'll let you check out the dedicated [sinatra integration docs](./docs/sinatra_integration.md).
 
-# Test with an HTTP / SSE server. In the UI select SSE and input your address.
-npx @modelcontextprotocol/inspector
-```
+## 🚀 Quick Start
 
-### Create a Server with Tools and Resources
+### Create a Server with Tools and Resources and STDIO transport
 
 ```ruby
 require 'fast_mcp'
 
 # Create an MCP server
-server = MCP::Server.new(name: 'my-ai-server', version: '1.0.0')
+server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')
 
-# Define a tool by inheriting from MCP::Tool
-class SummarizeTool < MCP::Tool
+# Define a tool by inheriting from FastMcp::Tool
+class SummarizeTool < FastMcp::Tool
   description "Summarize a given text"
   
   arguments do
@@ -171,14 +197,14 @@ end
 # Register the tool with the server
 server.register_tool(SummarizeTool)
 
-# Create a resource by inheriting from MCP::Resource
-class StatisticsResource < MCP::Resource
+# Create a resource by inheriting from FastMcp::Resource
+class StatisticsResource < FastMcp::Resource
   uri "data/statistics"
-  name "Usage Statistics"
+  resource_name "Usage Statistics"
   description "Current system statistics"
   mime_type "application/json"
   
-  def default_content
+  def content
     JSON.generate({
       users_online: 120,
       queries_per_minute: 250,
@@ -188,30 +214,38 @@ class StatisticsResource < MCP::Resource
 end
 
 # Register the resource with the server
-server.register_resource(StatisticsResource.new)
+server.register_resource(StatisticsResource)
 
 # Start the server
 server.start
 ```
 
-### Integrate with Web Frameworks
+## 🧪 Testing with the inspector
 
-#### Rails
+MCP has developed a very [useful inspector](https://github.com/modelcontextprotocol/inspector).
+You can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate.
+Clone this project, then give it a go !
 
-```ruby
-# config/application.rb
-module YourApp
-  class Application < Rails::Application
-    # ...
-    config.middleware.use MCP::RackMiddleware.new(
-      name: 'my-ai-server', 
-      version: '1.0.0'
-    ) do |server|
-      # Register tools and resources here
-      server.register_tool(SummarizeTool)
-    end
-  end
-end
+```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
+
+# Test with an HTTP / SSE server. In the UI select SSE and input your address.
+npx @modelcontextprotocol/inspector
 ```
 
 #### Sinatra
@@ -221,7 +255,7 @@ end
 require 'sinatra'
 require 'fast_mcp'
 
-use MCP::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
+use FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
   # Register tools and resources here
   server.register_tool(SummarizeTool)
 end
@@ -250,6 +284,9 @@ Add your server to your Claude Desktop configuration at:
 }
 ```
 
+## 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 |
@@ -276,11 +313,8 @@ Add your server to your Claude Desktop configuration at:
 - [🧩 Integration Guide](docs/integration_guide.md)
 - [🛤️ Rails Integration](docs/rails_integration.md)
 - [🌐 Sinatra Integration](docs/sinatra_integration.md)
-- [🌸 Hanami Integration](docs/hanami_integration.md)
 - [📚 Resources](docs/resources.md)
 - [🛠️ Tools](docs/tools.md)
-- [🔌 Transports](docs/transports.md)
-- [📘 API Reference](docs/api_reference.md)
 
 ## 💻 Examples
 

data/lib/fast_mcp.rb

@@ -4,13 +4,20 @@
 # https://modelcontextprotocol.io/introduction
 
 # Define the MCP module
-module MCP
+module FastMcp
+  class << self
+    attr_accessor :server
+  end
 end
 
 # Require the core components
 require_relative 'mcp/tool'
 require_relative 'mcp/server'
 require_relative 'mcp/resource'
+require_relative 'mcp/railtie' if defined?(Rails::Railtie)
+
+# Load generators if Rails is available
+require_relative 'generators/fast_mcp/install/install_generator' if defined?(Rails::Generators)
 
 # Require all transport files
 require_relative 'mcp/transports/base_transport'
@@ -22,7 +29,7 @@ end
 require_relative 'mcp/version'
 
 # Convenience method to create a Rack middleware
-module MCP
+module FastMcp
   # Create a Rack middleware for the MCP server
   # @param app [#call] The Rack application
   # @param options [Hash] Options for the middleware
@@ -31,19 +38,22 @@ module MCP
   # @option options [String] :path_prefix The path prefix for the MCP endpoints
   # @option options [Logger] :logger The logger to use
   # @yield [server] A block to configure the server
-  # @yieldparam server [MCP::Server] The server to configure
+  # @yieldparam server [FastMcp::Server] The server to configure
   # @return [#call] The Rack middleware
   def self.rack_middleware(app, options = {})
     name = options.delete(:name) || 'mcp-server'
     version = options.delete(:version) || '1.0.0'
     logger = options.delete(:logger) || Logger.new
 
-    server = MCP::Server.new(name: name, version: version, logger: logger)
+    server = FastMcp::Server.new(name: name, version: version, logger: logger)
     yield server if block_given?
 
     # Store the server in the Sinatra settings if available
     app.settings.set(:mcp_server, server) if app.respond_to?(:settings) && app.settings.respond_to?(:mcp_server=)
 
+    # Store the server in the FastMcp module
+    self.server = server
+
     server.start_rack(app, options)
   end
 
@@ -54,16 +64,93 @@ module MCP
   # @option options [String] :version The version of the server
   # @option options [String] :auth_token The authentication token
   # @yield [server] A block to configure the server
-  # @yieldparam server [MCP::Server] The server to configure
+  # @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 = MCP::Server.new(name: name, version: version, logger: logger)
+    server = FastMcp::Server.new(name: name, version: version, logger: logger)
     yield server if block_given?
 
+    # Store the server in the FastMcp module
+    self.server = server
+
     server.start_authenticated_rack(app, options)
   end
+
+  # Register a tool with the MCP server
+  # @param tool [FastMcp::Tool] The tool to register
+  # @return [FastMcp::Tool] The registered tool
+  def self.register_tool(tool)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_tool(tool)
+  end
+
+  # Register multiple tools at once
+  # @param tools [Array<FastMcp::Tool>] The tools to register
+  # @return [Array<FastMcp::Tool>] The registered tools
+  def self.register_tools(*tools)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_tools(*tools)
+  end
+
+  # Register a resource with the MCP server
+  # @param resource [FastMcp::Resource] The resource to register
+  # @return [FastMcp::Resource] The registered resource
+  def self.register_resource(resource)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_resource(resource)
+  end
+
+  # Register multiple resources at once
+  # @param resources [Array<FastMcp::Resource>] The resources to register
+  # @return [Array<FastMcp::Resource>] The registered resources
+  def self.register_resources(*resources)
+    self.server ||= FastMcp::Server.new(name: 'mcp-server', version: '1.0.0')
+    self.server.register_resources(*resources)
+  end
+
+  # Mount the MCP middleware in a Rails application
+  # @param app [Rails::Application] The Rails application
+  # @param options [Hash] Options for the middleware
+  # @option options [String] :name The name of the server
+  # @option options [String] :version The version of the server
+  # @option options [String] :path_prefix The path prefix for the MCP endpoints
+  # @option options [Logger] :logger The logger to use
+  # @option options [Boolean] :authenticate Whether to use authentication
+  # @option options [String] :auth_token The authentication token
+  # @yield [server] A block to configure the server
+  # @yieldparam server [FastMcp::Server] The server to configure
+  # @return [#call] The Rack middleware
+  def self.mount_in_rails(app, options = {})
+    # Default options
+    name = options.delete(:name) || app.class.module_parent_name.underscore.dasherize
+    version = options.delete(:version) || '1.0.0'
+    logger = options[:logger] || Rails.logger
+    path_prefix = options.delete(:path_prefix) || '/mcp'
+    authenticate = options.delete(:authenticate) || false
+
+    options[:logger] = logger
+    # Create or get the server
+    self.server = FastMcp::Server.new(name: name, version: version, logger: logger)
+    yield self.server if block_given?
+
+    # Choose the right middleware based on authentication
+    self.server.transport_klass = if authenticate
+                                    FastMcp::Transports::AuthenticatedRackTransport
+                                  else
+                                    FastMcp::Transports::RackTransport
+                                  end
+
+    # Insert the middleware in the Rails middleware stack
+    app.middleware.use self.server.transport_klass, self.server, options.merge(path_prefix: path_prefix)
+  end
+
+  # Notify the server that a resource has been updated
+  # @param uri [String] The URI of the resource
+  def self.notify_resource_updated(uri)
+    self.server.notify_resource_updated(uri)
+  end
 end

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

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

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

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

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

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# FastMcp - Model Context Protocol for Rails
+# This initializer sets up the MCP middleware in your Rails application.
+#
+# In Rails applications, you can use:
+# - ActionTool::Base as an alias for FastMcp::Tool
+# - ActionResource::Base as an alias for FastMcp::Resource
+#
+# All your tools should inherit from ApplicationTool which already uses ActionTool::Base,
+# and all your resources should inherit from ApplicationResource which uses ActionResource::Base.
+
+# Mount the MCP middleware in your Rails application
+# You can customize the options below to fit your needs.
+require 'fast_mcp'
+
+FastMcp.mount_in_rails(
+  Rails.application,
+  name: Rails.application.class.module_parent_name.underscore.dasherize,
+  version: '1.0.0',
+  path_prefix: '/mcp' # This is the default path prefix
+  # authenticate: true,       # Uncomment to enable authentication
+  # auth_token: 'your-token', # Required if authenticate: true
+) do |server|
+  Rails.application.config.after_initialize do
+    # FastMcp will automatically discover and register:
+    # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
+    # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
+    server.register_tools(*ApplicationTool.descendants)
+    server.register_resources(*ApplicationResource.descendants)
+    # alternatively, you can register tools and resources manually:
+    # server.register_tool(MyTool)
+    # server.register_resource(MyResource)
+  end
+end

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

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

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class SampleTool < ApplicationTool
+  description 'Greet a user'
+
+  arguments do
+    required(:id).filled(:integer).description('ID of the user to greet')
+    optional(:prefix).filled(:string).description('Prefix to add to the greeting')
+  end
+
+  def call(id:, prefix: 'Hey')
+    user = User.find(id)
+
+    "#{prefix} #{user.first_name} !"
+  end
+end

data/lib/mcp/logger.rb

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

data/lib/mcp/railtie.rb

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

data/lib/mcp/resource.rb

@@ -5,11 +5,13 @@ require 'base64'
 require 'mime/types'
 require 'singleton'
 
-module MCP
+module FastMcp
   # Resource class for MCP Resources feature
   # Represents a resource that can be exposed to clients
   class Resource
     class << self
+      attr_accessor :server
+
       # Define URI for this resource
       # @param value [String, nil] The URI for this resource
       # @return [String] The URI for this resource
@@ -74,7 +76,7 @@ module MCP
           end
 
           # Override content method to load from file
-          define_method :default_content do
+          define_method :content do
             if binary?
               File.binread(file_path)
             else
@@ -87,13 +89,6 @@ module MCP
 
     include Singleton
 
-    attr_accessor :content
-
-    # Initialize a resource singleton instance
-    def initialize
-      @content = default_content
-    end
-
     # URI of the resource - delegates to class method
     # @return [String, nil] The URI for this resource
     def uri
@@ -120,7 +115,7 @@ module MCP
 
     # Method to be overridden by subclasses to dynamically generate content
     # @return [String, nil] Generated content for this resource
-    def default_content
+    def content
       raise NotImplementedError, 'Subclasses must implement content'
     end
 

data/lib/mcp/server.rb

@@ -9,9 +9,9 @@ require_relative 'transports/rack_transport'
 require_relative 'transports/authenticated_rack_transport'
 require_relative 'logger'
 
-module MCP
+module FastMcp
   class Server
-    attr_reader :name, :version, :tools, :resources, :logger, :transport, :capabilities
+    attr_reader :name, :version, :tools, :resources, :capabilities
 
     DEFAULT_CAPABILITIES = {
       resources: {
@@ -23,7 +23,7 @@ module MCP
       }
     }.freeze
 
-    def initialize(name:, version:, logger: MCP::Logger.new, capabilities: {})
+    def initialize(name:, version:, logger: FastMcp::Logger.new, capabilities: {})
       @name = name
       @version = version
       @tools = {}
@@ -32,13 +32,17 @@ module MCP
       @logger = logger
       @logger.level = Logger::INFO
       @request_id = 0
+      @transport_klass = nil
       @transport = nil
       @capabilities = DEFAULT_CAPABILITIES.dup
 
       # Merge with provided capabilities
       @capabilities.merge!(capabilities) if capabilities.is_a?(Hash)
     end
+    attr_accessor :transport, :transport_klass, :logger
 
+    # Register multiple tools at once
+    # @param tools [Array<Tool>] Tools to register
     def register_tools(*tools)
       tools.each do |tool|
         register_tool(tool)
@@ -49,6 +53,7 @@ module MCP
     def register_tool(tool)
       @tools[tool.tool_name] = tool
       @logger.info("Registered tool: #{tool.tool_name}")
+      tool.server = self
     end
 
     # Register multiple resources at once
@@ -63,7 +68,7 @@ module MCP
     def register_resource(resource)
       @resources[resource.uri] = resource
       @logger.info("Registered resource: #{resource.name} (#{resource.uri})")
-
+      resource.server = self
       # Notify subscribers about the list change
       notify_resource_list_changed if @transport
 
@@ -93,7 +98,8 @@ module MCP
       @logger.info("Available resources: #{@resources.keys.join(', ')}")
 
       # Use STDIO transport by default
-      @transport = MCP::Transports::StdioTransport.new(self, logger: @logger)
+      @transport_klass = FastMcp::Transports::StdioTransport
+      @transport = @transport_klass.new(self, logger: @logger)
       @transport.start
     end
 
@@ -104,7 +110,8 @@ module MCP
       @logger.info("Available resources: #{@resources.keys.join(', ')}")
 
       # Use Rack transport
-      @transport = MCP::Transports::RackTransport.new(self, app, options.merge(logger: @logger))
+      transport_klass = FastMcp::Transports::RackTransport
+      @transport = transport_klass.new(app, self, options.merge(logger: @logger))
       @transport.start
 
       # Return the transport as middleware
@@ -117,7 +124,8 @@ module MCP
       @logger.info("Available resources: #{@resources.keys.join(', ')}")
 
       # Use Rack transport
-      @transport = MCP::Transports::AuthenticatedRackTransport.new(self, app, options.merge(logger: @logger))
+      transport_klass = FastMcp::Transports::AuthenticatedRackTransport
+      @transport = transport_klass.new(app, self, options.merge(logger: @logger))
       @transport.start
 
       # Return the transport as middleware
@@ -180,47 +188,6 @@ module MCP
       end
     end
 
-    # Register a callback for resource updates
-    def on_resource_update(&block)
-      @resource_update_callbacks ||= []
-      callback_id = SecureRandom.uuid
-      @resource_update_callbacks << { id: callback_id, callback: block }
-      callback_id
-    end
-
-    # Remove a resource update callback
-    def remove_resource_update_callback(callback_id)
-      @resource_update_callbacks ||= []
-      @resource_update_callbacks.reject! { |cb| cb[:id] == callback_id }
-    end
-
-    # Update a resource and notify subscribers
-    def update_resource(uri, content)
-      return false unless @resources.key?(uri)
-
-      resource = @resources[uri]
-      resource.instance.content = content
-
-      # Notify subscribers
-      notify_resource_updated(uri) if @transport && @resource_subscriptions.key?(uri)
-
-      # Notify resource update callbacks
-      if @resource_update_callbacks && !@resource_update_callbacks.empty?
-        @resource_update_callbacks.each do |cb|
-          cb[:callback].call(
-            {
-              uri: uri,
-              name: resource.name,
-              mime_type: resource.mime_type,
-              content: content
-            }
-          )
-        end
-      end
-
-      true
-    end
-
     # Read a resource directly
     def read_resource(uri)
       resource = @resources[uri]
@@ -229,13 +196,32 @@ module MCP
       resource
     end
 
+    # Notify subscribers about a resource update
+    def notify_resource_updated(uri)
+      @logger.warn("Notifying subscribers about resource update: #{uri}, #{@resource_subscriptions.inspect}")
+      return unless @client_initialized && @resource_subscriptions.key?(uri)
+
+      resource = @resources[uri]
+      notification = {
+        jsonrpc: '2.0',
+        method: 'notifications/resources/updated',
+        params: {
+          uri: uri,
+          name: resource.name,
+          mimeType: resource.mime_type
+        }
+      }
+
+      @transport.send_message(notification)
+    end
+
     private
 
     PROTOCOL_VERSION = '2024-11-05'
 
     def handle_initialize(params, id)
-      params['protocolVersion']
-      client_capabilities = params['capabilities'] || {}
+      # Store client capabilities for later use
+      @client_capabilities = params['capabilities'] || {}
       client_info = params['clientInfo'] || {}
 
       # Log client information
@@ -254,9 +240,6 @@ module MCP
 
       @logger.info("Server response: #{response.inspect}")
 
-      # Store client capabilities for later use
-      @client_capabilities = client_capabilities
-
       send_result(response, id)
     end
 
@@ -290,8 +273,9 @@ module MCP
       # The client is now ready for normal operation
       # No response needed for notifications
       @client_initialized = true
-      @logger.set_client_initialized
       @logger.info('Client initialized, beginning normal operation')
+
+      nil
     end
 
     # Handle tools/list request
@@ -324,7 +308,7 @@ module MCP
 
         # Format and send the result
         send_formatted_result(result, id)
-      rescue MCP::Tool::InvalidArgumentsError => e
+      rescue FastMcp::Tool::InvalidArgumentsError => e
         @logger.error("Invalid arguments for tool #{tool_name}: #{e.message}")
         send_error_result(e.message, id)
       rescue StandardError => e
@@ -410,24 +394,6 @@ module MCP
       send_result({ unsubscribed: true }, id)
     end
 
-    # Notify subscribers about a resource update
-    def notify_resource_updated(uri)
-      return unless @client_initialized && @resource_subscriptions.key?(uri)
-
-      resource = @resources[uri]
-      notification = {
-        jsonrpc: '2.0',
-        method: 'notifications/resources/updated',
-        params: {
-          uri: uri,
-          name: resource.name,
-          mimeType: resource.mime_type
-        }
-      }
-
-      @transport.send_message(notification)
-    end
-
     # Notify clients about resource list changes
     def notify_resource_list_changed
       return unless @client_initialized
@@ -470,10 +436,10 @@ module MCP
     def send_response(response)
       if @transport
         @logger.info("Sending response: #{response.inspect}")
-        @logger.info("Transport: #{@transport.inspect}")
         @transport.send_message(response)
       else
         @logger.warn("No transport available to send response: #{response.inspect}")
+        @logger.warn("Transport: #{@transport.inspect}, transport_klass: #{@transport_klass.inspect}")
       end
     end
 

data/lib/mcp/tool.rb

@@ -62,12 +62,14 @@ module Dry
   end
 end
 
-module MCP
+module FastMcp
   # Main Tool class that represents an MCP Tool
   class Tool
     class InvalidArgumentsError < StandardError; end
 
     class << self
+      attr_accessor :server
+
       def arguments(&block)
         @input_schema = Dry::Schema.JSON(&block)
       end
@@ -100,6 +102,10 @@ module MCP
       end
     end
 
+    def notify_resource_updated(uri)
+      self.class.server.notify_resource_updated(uri)
+    end
+
     def call_with_schema_validation!(**args)
       arg_validation = self.class.input_schema.call(args)
       raise InvalidArgumentsError, arg_validation.errors.to_h.to_json if arg_validation.errors.any?
@@ -788,7 +794,7 @@ module MCP
 end
 
 # Example
-# class ExampleTool < MCP::Tool
+# class ExampleTool < FastMcp::Tool
 #   description 'An example tool'
 
 #   arguments do

data/lib/mcp/transports/authenticated_rack_transport.rb

@@ -2,10 +2,10 @@
 
 require_relative 'rack_transport'
 
-module MCP
+module FastMcp
   module Transports
     class AuthenticatedRackTransport < RackTransport
-      def initialize(server, app, options = {})
+      def initialize(app, server, options = {})
         super
 
         @auth_token = options[:auth_token]

data/lib/mcp/transports/base_transport.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module MCP
+module FastMcp
   module Transports
     # Base class for all MCP transports
     # This defines the interface that all transports must implement

data/lib/mcp/transports/rack_transport.rb

@@ -5,7 +5,7 @@ require 'securerandom'
 require 'rack'
 require_relative 'base_transport'
 
-module MCP
+module FastMcp
   module Transports
     # Rack middleware transport for MCP
     # This transport can be mounted in any Rack-compatible web framework
@@ -14,7 +14,7 @@ module MCP
 
       attr_reader :app, :path_prefix, :sse_clients
 
-      def initialize(server, app, options = {})
+      def initialize(app, server, options = {}, &_block)
         super(server, logger: options[:logger])
         @app = app
         @path_prefix = options[:path_prefix] || DEFAULT_PATH_PREFIX
@@ -24,13 +24,13 @@ module MCP
 
       # Start the transport
       def start
-        @logger.info("Starting Rack transport with path prefix: #{@path_prefix}")
+        @logger.debug("Starting Rack transport with path prefix: #{@path_prefix}")
         @running = true
       end
 
       # Stop the transport
       def stop
-        @logger.info('Stopping Rack transport')
+        @logger.debug('Stopping Rack transport')
         @running = false
 
         # Close all SSE connections
@@ -45,7 +45,7 @@ module MCP
       # Send a message to all connected SSE clients
       def send_message(message)
         json_message = message.is_a?(String) ? message : JSON.generate(message)
-        @logger.info("Broadcasting message to #{@sse_clients.size} SSE clients: #{json_message}")
+        @logger.debug("Broadcasting message to #{@sse_clients.size} SSE clients: #{json_message}")
 
         clients_to_remove = []
 
@@ -85,10 +85,12 @@ module MCP
       def call(env)
         request = Rack::Request.new(env)
         path = request.path
-        @logger.info("Rack request path: #{path}")
+        @logger.debug("Rack request path: #{path}")
 
         # Check if the request is for our MCP endpoints
         if path.start_with?(@path_prefix)
+          @logger.debug('Setting server transport to RackTransport')
+          @server.transport = self
           handle_mcp_request(request, env)
         else
           # Pass through to the main application
@@ -107,7 +109,6 @@ module MCP
         when '/sse'
           handle_sse_request(request, env)
         when '/messages'
-          @logger.info('Received message request')
           handle_message_request(request)
         else
           @logger.info('Received unknown request')
@@ -270,11 +271,11 @@ module MCP
       # Handle SSE with Rack hijacking (e.g., Puma)
       def handle_rack_hijack_sse(env, headers)
         client_id = extract_client_id(env)
-        @logger.info("Setting up Rack hijack SSE connection for client #{client_id}")
+        @logger.debug("Setting up Rack hijack SSE connection for client #{client_id}")
 
         env['rack.hijack'].call
         io = env['rack.hijack_io']
-        @logger.info("Obtained hijack IO for client #{client_id}")
+        @logger.debug("Obtained hijack IO for client #{client_id}")
 
         setup_sse_connection(client_id, io, headers)
         start_keep_alive_thread(client_id, io)
@@ -286,7 +287,7 @@ module MCP
       # Set up the SSE connection
       def setup_sse_connection(client_id, io, headers)
         # Send headers
-        @logger.info("Sending HTTP headers for SSE connection #{client_id}")
+        @logger.debug("Sending HTTP headers for SSE connection #{client_id}")
         io.write("HTTP/1.1 200 OK\r\n")
         headers.each { |k, v| io.write("#{k}: #{v}\r\n") }
         io.write("\r\n")
@@ -300,7 +301,7 @@ module MCP
 
         # Send endpoint information as the first message
         endpoint = "#{@path_prefix}/messages"
-        @logger.info("Sending endpoint information to client #{client_id}: #{endpoint}")
+        @logger.debug("Sending endpoint information to client #{client_id}: #{endpoint}")
         io.write("event: endpoint\ndata: #{endpoint}\n\n")
 
         # Send a retry directive with a very short reconnect time
@@ -332,6 +333,7 @@ module MCP
         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
@@ -357,13 +359,13 @@ module MCP
 
         # Only send actual ping events every 5 counts to reduce overhead
         if (ping_count % 5).zero?
-          @logger.info("Sending ping ##{ping_count} to SSE client #{client_id}")
+          @logger.debug("Sending ping ##{ping_count} to SSE client #{client_id}")
           send_ping_event(io)
         end
 
         # If we've reached the max ping count, force a reconnection
         if ping_count >= max_ping_count
-          @logger.info("Reached max ping count (#{max_ping_count}) for client #{client_id}, forcing reconnection")
+          @logger.debug("Reached max ping count (#{max_ping_count}) for client #{client_id}, forcing reconnection")
           send_reconnect_event(io)
         end
 
@@ -414,7 +416,7 @@ module MCP
 
       # Handle message POST request
       def handle_message_request(request)
-        @logger.info('Received message request')
+        @logger.debug('Received message request')
         return method_not_allowed_response unless request.post?
 
         begin
@@ -431,9 +433,10 @@ module MCP
         # Parse the request body
         body = request.body.read
 
-        response = process_message(body)
+        response = process_message(body) || ''
         @logger.info("Response: #{response}")
-        [200, { 'Content-Type' => 'application/json' }, [response]]
+
+        [200, { 'Content-Type' => 'application/json' }, response]
       end
 
       # Return a method not allowed error response

data/lib/mcp/transports/stdio_transport.rb

@@ -2,7 +2,7 @@
 
 require_relative 'base_transport'
 
-module MCP
+module FastMcp
   module Transports
     # STDIO transport for MCP
     # This transport uses standard input/output for communication

data/lib/mcp/version.rb

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

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: fast-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Yorick Jacquin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-23 00:00:00.000000000 Z
+date: 2025-03-30 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: dry-schema
   requirement: !ruby/object:Gem::Requirement
@@ -64,7 +78,14 @@ files:
 - LICENSE
 - README.md
 - lib/fast_mcp.rb
+- lib/generators/fast_mcp/install/install_generator.rb
+- lib/generators/fast_mcp/install/templates/application_resource.rb
+- lib/generators/fast_mcp/install/templates/application_tool.rb
+- lib/generators/fast_mcp/install/templates/fast_mcp_initializer.rb
+- lib/generators/fast_mcp/install/templates/sample_resource.rb
+- lib/generators/fast_mcp/install/templates/sample_tool.rb
 - lib/mcp/logger.rb
+- lib/mcp/railtie.rb
 - lib/mcp/resource.rb
 - lib/mcp/server.rb
 - lib/mcp/tool.rb
@@ -80,6 +101,7 @@ metadata:
   homepage_uri: https://github.com/yjacquin/fast_mcp
   source_code_uri: https://github.com/yjacquin/fast_mcp
   changelog_uri: https://github.com/yjacquin/fast_mcp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: