fast-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94b9b8af1c648e0637ad0dc3d0118c8354392bac61b0f8c30d4eb264bc7a8fda
+  data.tar.gz: 728c09e7b7848fcc1f9296e42fed083933b8c8bb9cf08d02c8708009a378f0c1
+SHA512:
+  metadata.gz: 1e26886cc6c006df64e913b7d517fbcffd1c2c4e6a27787e8fccbb3e0d5c172ec1e337ada9928cff1821fca96e2fcd173e4bf7bc4f492fc9eb4404463ed3e0a8
+  data.tar.gz: c91ea6f439f68ae5f301f4cd5adb24aaebc1939cfe8f2458ec038310b294293b2eaf6b5f8518972fdef5f1bf6acdbda59ec14997d1a01cf46171d4605152cf93

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+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).
+
+## [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
+- Rack Integration with authenticated and standard middleware options
+- Resource management with subscription capabilities
+- Binary resource support
+- Examples with STDIO Transport, HTTP & SSE, Rack app
+- Initialize lifecycle with capabilities 
+- Comprehensive test suite with RSpec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yorick Jacquin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,321 @@
+# Fast MCP 🚀
+
+<div align="center">
+  <h3>Connect AI models to your Ruby applications with ease</h3>
+  <p>No complex protocols, no integration headaches, no compatibility issues – just beautiful, expressive Ruby code.</p>
+</div>
+
+<p align="center">
+  <a href="https://badge.fury.io/rb/fast-mcp"><img src="https://badge.fury.io/rb/fast-mcp.svg" alt="Gem Version" /></a>
+  <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>
+</p>
+
+## 🌟 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:
+
+- 🔄 Complex communication protocols and custom JSON formats
+- 🔌 Integration challenges with different model providers
+- 🧩 Compatibility issues between your app and AI tools
+- 🧠 Managing the state between AI interactions and your data
+
+Fast MCP solves all these problems by providing a clean, Ruby-focused implementation of the [Model Context Protocol](https://github.com/modelcontextprotocol), making AI integration a joy, not a chore.
+
+## ✨ Features
+
+- 🛠️ **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
+- 🚀 **Real-time Updates** - Subscribe to changes for interactive applications
+
+## 💎 What Makes FastMCP Great
+
+```ruby
+# Define tools for AI models to use
+server = MCP::Server.new(name: 'recipe-ai', version: '1.0.0')
+
+# Define a tool by inheriting from MCP::Tool
+class GetRecipesTool < MCP::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.
+    # 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")
+  end
+  
+  def call(ingredients:, cuisine: nil)
+    Recipe.find_by_ingredients(ingredients, cuisine: cuisine)
+  end
+end
+
+# Register the tool with the server
+server.register_tool(GetRecipesTool)
+
+# Share data resources with AI models by inheriting from MCP::Resource
+class IngredientsResource < MCP::Resource
+  uri "food/popular_ingredients"
+  name "Popular Ingredients"
+  mime_type "application/json"
+  
+  def default_content
+    JSON.generate(Ingredient.popular.as_json)
+  end
+end
+
+# Register the resource with the server
+server.register_resource(IngredientsResource)
+
+# Accessing the resource through the server
+server.read_resource("food/popular_ingredients")
+
+# Updating the resource content through the server
+server.update_resource("food/popular_ingredients", JSON.generate({id: 1, name: 'tomato'}))
+
+
+# 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
+
+# Secure your AI endpoints
+config.middleware.use MCP::AuthenticatedRackMiddleware.new(
+  name: 'recipe-ai',
+  version: '1.0.0',
+  token: ENV['MCP_AUTH_TOKEN']
+)
+
+# Build real-time applications
+server.on_resource_update do |resource|
+  ActionCable.server.broadcast("recipe_updates", resource.metadata)
+end
+```
+
+## 📦 Installation
+
+```ruby
+# In your Gemfile
+gem 'fast-mcp'
+
+# Then run
+bundle install
+
+# Or install it yourself
+gem install fast-mcp
+```
+
+## 🚀 Quick Start
+
+### Testing with the inspector
+
+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 !
+
+```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
+```
+
+### Create a Server with Tools and Resources
+
+```ruby
+require 'fast_mcp'
+
+# Create an MCP server
+server = MCP::Server.new(name: 'my-ai-server', version: '1.0.0')
+
+# Define a tool by inheriting from MCP::Tool
+class SummarizeTool < MCP::Tool
+  description "Summarize a given text"
+  
+  arguments do
+    required(:text).filled(:string).description("Text to summarize")
+    optional(:max_length).filled(:integer).description("Maximum length of summary")
+  end
+  
+  def call(text:, max_length: 100)
+    # Your summarization logic here
+    text.split('.').first(3).join('.') + '...'
+  end
+end
+
+# Register the tool with the server
+server.register_tool(SummarizeTool)
+
+# Create a resource by inheriting from MCP::Resource
+class StatisticsResource < MCP::Resource
+  uri "data/statistics"
+  name "Usage Statistics"
+  description "Current system statistics"
+  mime_type "application/json"
+  
+  def default_content
+    JSON.generate({
+      users_online: 120,
+      queries_per_minute: 250,
+      popular_topics: ["Ruby", "AI", "WebDev"]
+    })
+  end
+end
+
+# Register the resource with the server
+server.register_resource(StatisticsResource.new)
+
+# Start the server
+server.start
+```
+
+### Integrate with Web Frameworks
+
+#### Rails
+
+```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
+```
+
+#### Sinatra
+
+```ruby
+# app.rb
+require 'sinatra'
+require 'fast_mcp'
+
+use MCP::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
+  # Register tools and resources here
+  server.register_tool(SummarizeTool)
+end
+
+get '/' do
+  'Hello World!'
+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`
+
+```json
+{
+  "mcpServers": {
+    "my-great-server": {
+      "command": "ruby",
+      "args": [
+        "/Users/path/to/your/awesome/fast-mcp/server.rb"
+      ]
+    }
+  }
+}
+```
+
+## 📊 Supported Specifications
+
+| Feature | Status |
+|---------|--------|
+| ✅ **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 |
+| ✅ **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
+
+- 🤖 **AI-powered Applications**: Connect LLMs to your Ruby app's functionality
+- 📊 **Real-time Dashboards**: Build dashboards with live AI-generated insights
+- 🔗 **Microservice Communication**: Use MCP as a clean protocol between services
+- 📚 **Interactive Documentation**: Create AI-enhanced API documentation
+- 💬 **Chatbots and Assistants**: Build AI assistants with access to your app's data
+
+## 📖 Documentation
+
+- [🚀 Getting Started Guide](docs/getting_started.md)
+- [🧩 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
+
+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)
+
+- **🌐 Web Integration**:
+  - [Rack Middleware](examples/rack_middleware.rb)
+  - [Authenticated Endpoints](examples/authenticated_rack_middleware.rb)
+
+## 🧪 Requirements
+
+- Ruby 3.2+
+
+## 👥 Contributing
+
+We welcome contributions to Fast MCP! Here's how you can help:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Please read our [Contributing Guide](CONTRIBUTING.md) for more details.
+
+## 📄 License
+
+This project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🙏 Acknowledgments
+
+- The [Model Context Protocol](https://github.com/modelcontextprotocol) team for creating the specification
+- The [Dry-Schema](https://github.com/dry-rb/dry-schema) team for the argument validation.
+- All contributors to this project

data/lib/fast_mcp.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Fast MCP - A Ruby Implementation of the Model Context Protocol (Server-side)
+# https://modelcontextprotocol.io/introduction
+
+# Define the MCP module
+module MCP
+end
+
+# Require the core components
+require_relative 'mcp/tool'
+require_relative 'mcp/server'
+require_relative 'mcp/resource'
+
+# Require all transport files
+require_relative 'mcp/transports/base_transport'
+Dir[File.join(File.dirname(__FILE__), 'mcp/transports', '*.rb')].each do |file|
+  require file
+end
+
+# Version information
+require_relative 'mcp/version'
+
+# Convenience method to create a Rack middleware
+module MCP
+  # Create a Rack middleware for the MCP server
+  # @param app [#call] The Rack 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
+  # @yield [server] A block to configure the server
+  # @yieldparam server [MCP::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)
+    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=)
+
+    server.start_rack(app, options)
+  end
+
+  # Create a Rack middleware for the MCP server with authentication
+  # @param app [#call] The Rack 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] :auth_token The authentication token
+  # @yield [server] A block to configure the server
+  # @yieldparam server [MCP::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)
+    yield server if block_given?
+
+    server.start_authenticated_rack(app, options)
+  end
+end

data/lib/mcp/logger.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# This class is not used yet.
+module MCP
+  class Logger < Logger
+    def initialize
+      @client_initialized = false
+      @transport = nil
+
+      super($stdout)
+    end
+
+    attr_accessor :transport, :client_initialized
+
+    def client_initialized?
+      client_initialized
+    end
+
+    def stdio_transport?
+      transport == :stdio
+    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/resource.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+require 'mime/types'
+require 'singleton'
+
+module MCP
+  # Resource class for MCP Resources feature
+  # Represents a resource that can be exposed to clients
+  class Resource
+    class << self
+      # Define URI for this resource
+      # @param value [String, nil] The URI for this resource
+      # @return [String] The URI for this resource
+      def uri(value = nil)
+        @uri = value if value
+        @uri || (superclass.respond_to?(:uri) ? superclass.uri : nil)
+      end
+
+      # Define name for this resource
+      # @param value [String, nil] The name for this resource
+      # @return [String] The name for this resource
+      def resource_name(value = nil)
+        @name = value if value
+        @name || (superclass.respond_to?(:resource_name) ? superclass.resource_name : nil)
+      end
+
+      # Define description for this resource
+      # @param value [String, nil] The description for this resource
+      # @return [String] The description for this resource
+      def description(value = nil)
+        @description = value if value
+        @description || (superclass.respond_to?(:description) ? superclass.description : nil)
+      end
+
+      # Define MIME type for this resource
+      # @param value [String, nil] The MIME type for this resource
+      # @return [String] The MIME type for this resource
+      def mime_type(value = nil)
+        @mime_type = value if value
+        @mime_type || (superclass.respond_to?(:mime_type) ? superclass.mime_type : nil)
+      end
+
+      # Get the resource metadata (without content)
+      # @return [Hash] Resource metadata
+      def metadata
+        {
+          uri: uri,
+          name: resource_name,
+          description: description,
+          mimeType: mime_type
+        }.compact
+      end
+
+      # Load content from a file (class method)
+      # @param file_path [String] Path to the file
+      # @return [Resource] New resource instance with content loaded from file
+      def from_file(file_path, name: nil, description: nil)
+        file_uri = "file://#{File.absolute_path(file_path)}"
+        file_name = name || File.basename(file_path)
+
+        # Create a resource subclass on the fly
+        Class.new(self) do
+          uri file_uri
+          resource_name file_name
+          description description if description
+
+          # Auto-detect mime type
+          extension = File.extname(file_path)
+          unless extension.empty?
+            detected_types = MIME::Types.type_for(extension)
+            mime_type detected_types.first.to_s unless detected_types.empty?
+          end
+
+          # Override content method to load from file
+          define_method :default_content do
+            if binary?
+              File.binread(file_path)
+            else
+              File.read(file_path)
+            end
+          end
+        end
+      end
+    end
+
+    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
+      self.class.uri
+    end
+
+    # Name of the resource - delegates to class method
+    # @return [String, nil] The name for this resource
+    def name
+      self.class.name
+    end
+
+    # Description of the resource - delegates to class method
+    # @return [String, nil] The description for this resource
+    def description
+      self.class.description
+    end
+
+    # MIME type of the resource - delegates to class method
+    # @return [String, nil] The MIME type for this resource
+    def mime_type
+      self.class.mime_type
+    end
+
+    # Method to be overridden by subclasses to dynamically generate content
+    # @return [String, nil] Generated content for this resource
+    def default_content
+      raise NotImplementedError, 'Subclasses must implement content'
+    end
+
+    # Check if the resource is binary
+    # @return [Boolean] true if the resource is binary, false otherwise
+    def binary?
+      return false if mime_type.nil?
+
+      !(mime_type.start_with?('text/') ||
+        mime_type == 'application/json' ||
+        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