active_mcp 0.3.11 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67338ce686da0dee13981737b87274009ff6e333e0cf06274469b03f6b066c11
-  data.tar.gz: 86f3916c8df7848adea802a736f117f37f9a3c2a92f1aca811984b2782562a12
+  metadata.gz: acd47906160af7e22cbfa3fe974288e7d16639898b026ef6288ab91444e799be
+  data.tar.gz: 0bc89e6d457537dbe75450f1ad9ec525ed37b9168df48f08c10adbbcb2aebc5f
 SHA512:
-  metadata.gz: 5a58ff5874317b91aa79f84e373e57b04a0f11378ebe4299a9ce9408f930051038c5b86a1faa3c2e8e0b4a42463850d5e662112e48fae4876812b2c6e8aedafe
-  data.tar.gz: c64a85603d69a0e15c1cf8e0a42209a7f424e7f95bd0f064fcb785cf9e5b2d70c2ab0b1bb8fd36d8aa0af5dd2367ff767c3f431fbada308a23714f181c98bd6e
+  metadata.gz: ea4c71409b27eb65027b33fa0e43ddbaf4e3924768625d28788a2d23e9604099fc14eb6de3c962066a260a96bac8415605066ad05c4cc3ff63f31a33a47fbbc3
+  data.tar.gz: 4960bc1dee62aa05245159e0d53cf618583739e63aecbbdaf581db3cbed6133317a2537ec9f1d12313956c5e00facb24a6f1fefa32899d685061671fe529adfc

data/README.md

@@ -25,6 +25,7 @@ A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelconte
   - [🛠 Rails Generators](#-rails-generators)
     - [Install Generator](#install-generator)
     - [Tool Generator](#tool-generator)
+    - [Resource Generator](#resource-generator)
   - [🧰 Creating MCP Tools](#-creating-mcp-tools)
   - [📋 Input Schema](#-input-schema)
   - [🔐 Authorization \& Authentication](#-authorization--authentication)
@@ -32,6 +33,9 @@ A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelconte
     - [Authentication Options](#authentication-options)
       - [1. Server Configuration](#1-server-configuration)
       - [2. Token Verification in Tools](#2-token-verification-in-tools)
+  - [📦 MCP Resources](#-mcp-resources)
+    - [Creating Resources](#creating-resources)
+    - [Resource Types](#resource-types)
   - [⚙️ Advanced Configuration](#️-advanced-configuration)
     - [Custom Controller](#custom-controller)
   - [💡 Best Practices](#-best-practices)
@@ -45,7 +49,8 @@ A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelconte
 ## ✨ Features
 
 - **Simple Integration**: Easily expose Rails functionality as MCP tools
-- **Powerful Generators**: Quickly scaffold MCP tools with Rails generators
+- **Resource Support**: Share files and data with AI assistants through MCP resources
+- **Powerful Generators**: Quickly scaffold MCP tools and resources with Rails generators
 - **Authentication Support**: Built-in authentication and authorization capabilities
 - **Flexible Configuration**: Multiple deployment and connection options
 
@@ -179,6 +184,16 @@ $ rails generate active_mcp:tool search_users
 
 This creates a new tool file at `app/tools/search_users_tool.rb` with ready-to-customize starter code.
 
+### Resource Generator
+
+Generate new MCP resources to share data with AI:
+
+```bash
+$ rails generate active_mcp:resource profile_image
+```
+
+This creates a new resource file at `app/resources/profile_image_resource.rb` that you can customize to provide various types of content to AI assistants.
+
 ## 🧰 Creating MCP Tools
 
 MCP tools are Ruby classes that inherit from `ActiveMcp::Tool` and define an interface for AI to interact with your application:
@@ -290,6 +305,75 @@ def call(resource_id:, auth_info: nil, **args)
 end
 ```
 
+## 📦 MCP Resources
+
+MCP Resources allow you to share data and files with AI assistants. Resources have a URI, MIME type, and can return either text or binary data.
+
+### Creating Resources
+
+Resources are Ruby classes that inherit from `ActiveMcp::Resource`:
+
+```ruby
+class UserResource < ActiveMcp::Resource
+  uri "data://localhost/user"
+  mime_type "application/json"
+  description "User profile data"
+
+  def text(auth_info: nil)
+    # Authenticate if needed
+    user = User.find_by(id: 1)
+
+    # Return JSON data
+    {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      created_at: user.created_at
+    }
+  end
+end
+```
+
+### Resource Types
+
+Resources can return two types of content:
+
+1. **Text Content** - Use the `text` method to return structured data:
+
+```ruby
+def text(auth_info: nil)
+  # Return strings, arrays, hashes, or any JSON-serializable object
+  { items: Product.all.map(&:attributes) }
+end
+```
+
+2. **Binary Content** - Use the `blob` method to return binary files:
+
+```ruby
+class ImageResource < ActiveMcp::Resource
+  uri "data://localhost/image"
+  mime_type "image/png"
+  description "Profile image"
+
+  def blob(auth_info: nil)
+    # Return binary file content
+    File.read(Rails.root.join("public", "profile.png"))
+  end
+end
+```
+
+Resources can be protected using the same authorization mechanism as tools:
+
+```ruby
+def self.visible?(auth_info)
+  return false unless auth_info
+  return false unless auth_info[:type] == :bearer
+
+  # Check if the token belongs to an admin
+  User.find_by_token(auth_info[:token])&.admin?
+end
+```
+
 ## ⚙️ Advanced Configuration
 
 ### Custom Controller

data/app/controllers/concerns/active_mcp/request_handler.rb

@@ -35,6 +35,14 @@ module ActiveMcp
         render 'active_mcp/initialized', formats: :json
       when Method::CANCELLED
         render 'active_mcp/cancelled', formats: :json
+      when Method::RESOURCES_LIST
+        @resources = ActiveMcp::Resource.authorized_resources(auth_info)
+        @format = :jsonrpc
+        render 'active_mcp/resources_list', formats: :json
+      when Method::RESOURCES_READ
+        @resource = ActiveMcp::ResourceReader.read(params:, auth_info:)
+        @format = :jsonrpc
+        render 'active_mcp/resources_read', formats: :json
       when Method::TOOLS_LIST
         @tools = ActiveMcp::Tool.authorized_tools(auth_info)
         @format = :jsonrpc
@@ -53,6 +61,14 @@ module ActiveMcp
       @auth_info = auth_info
       
       case params[:method]
+      when Method::RESOURCES_LIST
+        @resources = ActiveMcp::Resource.authorized_resources(auth_info)
+        @format = :json
+        render 'active_mcp/resources_list', formats: :json
+      when Method::RESOURCES_READ
+        @resource = ActiveMcp::ResourceReader.read(params:, auth_info:)
+        @format = :json
+        render 'active_mcp/resources_read', formats: :json
       when Method::TOOLS_LIST
         @tools = ActiveMcp::Tool.authorized_tools(auth_info)
         @format = :json

data/app/models/active_mcp/resource_reader.rb

@@ -0,0 +1,78 @@
+module ActiveMcp
+  class ResourceReader
+    def self.read(params:, auth_info:)
+      if params[:jsonrpc].present?
+        uri = params[:params][:uri]
+      else
+        uri = params[:uri]
+      end
+      
+      unless uri
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+
+      resource_class = Resource.registered_resources.find do |r|
+        r._uri == uri
+      end
+      
+      unless resource_class
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+      
+      unless resource_class.visible?(auth_info)
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+
+      resource = resource_class.new
+
+      begin
+        if content = resource.text(auth_info:)
+          return {
+            contents: [
+              {
+                uri:,
+                mimeType: resource_class._mime_type,
+                text: formatted(content)
+              }
+            ]
+          }
+        elsif content = resource.blob(auth_info:)
+          return {
+            contents: [
+              {
+                uri:,
+                mimeType: resource_class._mime_type,
+                blob: Base64.strict_encode64(content)
+              }
+            ]
+          }
+        end
+      rescue
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+    end
+    
+    def self.formatted(object)
+      case object
+      when String
+        object
+      when Hash
+        object.to_json
+      else
+        object.to_s
+      end
+    end
+  end
+end

data/app/views/active_mcp/resources_list.json.jbuilder

@@ -0,0 +1,10 @@
+json.jsonrpc ActiveMcp::JSON_RPC_VERSION if @format == :jsonrpc
+json.id @id if @format == :jsonrpc && @id.present?
+
+if @format == :jsonrpc
+  json.result do
+    json.resources @resources
+  end
+else
+  json.result @resources
+end

data/app/views/active_mcp/resources_read.json.jbuilder

@@ -0,0 +1,16 @@
+json.jsonrpc ActiveMcp::JSON_RPC_VERSION if @format == :jsonrpc
+json.id @id if @format == :jsonrpc && @id.present?
+
+if @format == :jsonrpc
+  json.result @resource
+else
+  json.isError @resource[:isError] if @resource[:isError]
+  json.contents do
+    json.array!(@resource[:contents]) do |content|
+      json.uri content[:uri]
+      json.mimeType raw content[:mimeType]
+      json.text raw content[:text] if content[:text]
+      json.blob content[:blob] if content[:blob]
+    end
+  end
+end

data/lib/active_mcp/engine.rb

@@ -10,5 +10,14 @@ module ActiveMcp
         end
       end
     end
+
+    initializer "active_mcp.eager_load_resources" do |app|
+      tools_path = Rails.root.join("app", "resources")
+      if Dir.exist?(tools_path)
+        Dir[tools_path.join("*.rb")].sort.each do |file|
+          require_dependency file
+        end
+      end
+    end
   end
 end

data/lib/active_mcp/resource.rb

@@ -0,0 +1,64 @@
+require "json-schema"
+
+module ActiveMcp
+  class Resource
+    class << self
+      attr_reader :_description, :schema, :_uri, :_mime_type
+
+      def resource_name
+        name ? name.underscore.sub(/_resource$/, "") : ""
+      end
+
+      def uri(value)
+        @_uri = value
+      end
+
+      def description(value)
+        @_description = value
+      end
+
+      def mime_type(value)
+        @_mime_type = value
+      end
+
+      def registered_resources
+        @registered_resources ||= []
+      end
+
+      attr_writer :registered_resources
+
+      def inherited(subclass)
+        registered_resources << subclass
+      end
+
+      def visible?(auth_info)
+        if respond_to?(:authorized?)
+          authorized?(auth_info)
+        else
+          true
+        end
+      end
+
+      def authorized_resources(auth_info = nil)
+        registered_resources.select do |tool_class|
+          tool_class.visible?(auth_info)
+        end.map do |tool_class|
+          {
+            uri: tool_class._uri,
+            name: tool_class.resource_name,
+            mimeType: tool_class._mime_type,
+            description: tool_class._description
+          }
+        end
+      end
+    end
+
+    def text(auth_info:)
+      nil
+    end
+
+    def blob(auth_info:)
+      nil
+    end
+  end
+end

data/lib/active_mcp/server/protocol_handler.rb

@@ -48,12 +48,12 @@ module ActiveMcp
           handle_initialized(request)
         when Method::PING
           handle_ping(request)
+        when Method::RESOURCES_LIST
+          handle_list_resources(request)
         when Method::TOOLS_LIST
           handle_list_tools(request)
         when Method::TOOLS_CALL
           handle_use_tool(request)
-        when Method::RESOURCES_LIST
-          handle_list_resources(request)
         when Method::RESOURCES_READ
           handle_read_resource(request)
         else
@@ -112,6 +112,10 @@ module ActiveMcp
         success_response(request[:id], {})
       end
 
+      def handle_list_resources(request)
+        success_response(request[:id], {resources: @server.resource_manager.resources})
+      end
+
       def handle_list_tools(request)
         success_response(request[:id], {tools: @server.tool_manager.tools})
       end
@@ -130,19 +134,16 @@ module ActiveMcp
         end
       end
 
-      def handle_list_resources(request)
-        success_response(
-          request[:id],
-          {
-            resources: [],
-            nextCursor: "0"
-          }
-        )
-      end
-
       def handle_read_resource(request)
         uri = request.dig(:params, :uri)
-        error_response(request[:id], ErrorCode::INVALID_REQUEST, "Resource not found", {uri: uri})
+        begin
+          result = @server.resource_manager.read_resource(uri)
+
+          success_response(request[:id], result)
+        rescue => e
+          log_error("Error reading resource #{uri}", e)
+          error_response(request[:id], ErrorCode::INTERNAL_ERROR, "An error occurred while reading the resource")
+        end
       end
 
       def success_response(id, result)

data/lib/active_mcp/server/resource_manager.rb

@@ -0,0 +1,150 @@
+require "json"
+
+module ActiveMcp
+  class Server
+    class ResourceManager
+      attr_reader :resources
+
+      def initialize(uri: nil, auth: nil)
+        @resources = {}
+        @base_uri = uri
+
+        if auth
+          @auth_header = "#{auth[:type] == :bearer ? "Bearer" : "Basic"} #{auth[:token]}"
+        end
+      end
+
+      def load_registered_resources
+        fetch_resources
+      end
+
+      def read_resource(uri)
+        require "net/http"
+        
+        unless @base_uri.is_a?(URI) || @base_uri.is_a?(String)
+          log_error("Invalid URI type", StandardError.new("URI must be a String or URI object"))
+          return {
+            isError: true,
+            content: [{type: "text", text: "Invalid URI configuration"}]
+          }
+        end
+        
+        begin
+          base_uri = URI.parse(@base_uri.to_s)
+          
+          unless base_uri.scheme =~ /\Ahttps?\z/ && !base_uri.host.nil?
+            log_error("Invalid URI", StandardError.new("URI must have a valid scheme and host"))
+            return {
+              isError: true,
+              content: [{type: "text", text: "Invalid URI configuration"}]
+            }
+          end
+          
+          if defined?(Rails) && Rails.env.production? && base_uri.scheme != "https"
+            return {
+              isError: true,
+              content: [{type: "text", text: "HTTPS is required in production environment"}]
+            }
+          end
+        rescue URI::InvalidURIError => e
+          log_error("Invalid URI format", e)
+          return {
+            isError: true,
+            content: [{type: "text", text: "Invalid URI format"}]
+          }
+        end
+        
+        request = Net::HTTP::Post.new(base_uri)
+        request.body = JSON.generate({
+          method: Method::RESOURCES_READ,
+          uri:,
+        })
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = @auth_header
+
+        begin
+          response = Net::HTTP.start(base_uri.hostname, base_uri.port) do |http|
+            http.request(request)
+          end
+
+          if response.code == "200"
+            JSON.parse(response.body, symbolize_names: true)
+          else
+            $stderr.puts(response.body)
+            {
+              isError: true,
+              contents: []
+            }
+          end
+        rescue => e
+          log_error("Error calling tool", e)
+          {
+            isError: true,
+            contents: []
+          }
+        end
+      end
+
+      private
+
+      def fetch_resources
+        return unless @base_uri
+
+        require "net/http"
+        
+        unless @base_uri.is_a?(URI) || @base_uri.is_a?(String)
+          log_error("Invalid URI type", StandardError.new("URI must be a String or URI object"))
+          return
+        end
+        
+        begin
+          uri = URI.parse(@base_uri.to_s)
+          
+          unless uri.scheme =~ /\Ahttps?\z/ && !uri.host.nil?
+            log_error("Invalid URI", StandardError.new("URI must have a valid scheme and host"))
+            return
+          end
+          
+          if defined?(Rails) && Rails.env.production? && uri.scheme != "https"
+            log_error("HTTPS is required in production environment", StandardError.new("Non-HTTPS URI in production"))
+            return
+          end
+        rescue URI::InvalidURIError => e
+          log_error("Invalid URI format", e)
+          return
+        end
+        
+        request = Net::HTTP::Post.new(uri)
+        request.body = JSON.generate({
+          method: "resources/list",
+          arguments: "{}"
+        })
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = @auth_header
+
+        begin
+          response = Net::HTTP.start(uri.hostname, uri.port) do |http|
+            http.request(request)
+          end
+
+          result = JSON.parse(response.body, symbolize_names: true)
+          @resources = result[:result]
+        rescue => e
+          log_error("Error fetching resources", e)
+          @resources = []
+        end
+      end
+      
+      def log_error(message, error)
+        error_details = "#{message}: #{error.message}\n"
+        error_details += error.backtrace.join("\n") if error.backtrace
+        
+        if defined?(Rails)
+          Rails.logger.error(error_details)
+        else
+          $stderr.puts(error_details)
+        end
+      end
+    end
+  end
+end

data/lib/active_mcp/server.rb

@@ -1,14 +1,15 @@
 require "json"
 require "English"
-require_relative "server/methods"
+require_relative "server/method"
 require_relative "server/error_codes"
 require_relative "server/stdio_connection"
+require_relative "server/resource_manager"
 require_relative "server/tool_manager"
 require_relative "server/protocol_handler"
 
 module ActiveMcp
   class Server
-    attr_reader :name, :version, :uri, :tool_manager, :protocol_handler
+    attr_reader :name, :version, :uri, :tool_manager, :protocol_handler, :resource_manager
 
     def initialize(
       version: ActiveMcp::VERSION,
@@ -19,9 +20,11 @@ module ActiveMcp
       @name = name
       @version = version
       @uri = uri
+      @resource_manager = ResourceManager.new(uri:, auth:)
       @tool_manager = ToolManager.new(uri: uri, auth:)
       @protocol_handler = ProtocolHandler.new(self)
       @tool_manager.load_registered_tools
+      @resource_manager.load_registered_resources
     end
 
     def start

data/lib/active_mcp/version.rb

@@ -1,3 +1,3 @@
 module ActiveMcp
-  VERSION = "0.3.11"
+  VERSION = "0.4.0"
 end

data/lib/active_mcp.rb

@@ -4,6 +4,7 @@ require "jbuilder"
 require_relative "active_mcp/version"
 require_relative "active_mcp/configuration"
 require_relative "active_mcp/tool"
+require_relative "active_mcp/resource"
 require_relative "active_mcp/server"
 
 if defined? ::Rails

data/lib/generators/active_mcp/resource/resource_generator.rb

@@ -0,0 +1,17 @@
+module ActiveMcp
+  module Generators
+    class ResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_resource_file
+        template "resource.rb.erb", File.join("app/resources", "#{file_name}_resource.rb")
+      end
+
+      private
+
+      def class_name
+        "#{file_name.camelize}Resource"
+      end
+    end
+  end
+end

data/lib/generators/active_mcp/resource/templates/resource.rb.erb

@@ -0,0 +1,37 @@
+class <%= class_name %> < ActiveMcp::Resource
+  uri "data://localhost/<%= file_name %>"
+  mime_type "application/json"
+  description "<%= file_name.humanize %>"
+
+  # Uncomment and modify this method to implement authorization control
+  # This controls who can see and use this tool
+  # def self.visible?(auth_info)
+  #   # Example: require authentication
+  #   # return false unless auth_info
+  #   
+  #   # Example: require a specific authentication type
+  #   # return false unless auth_info[:type] == :bearer
+  #   
+  #   # Example: check for admin permissions
+  #   # admin_tokens = ["admin-token"]
+  #   # return admin_tokens.include?(auth_info[:token])
+  #   
+  #   # Default: allow all access
+  #   true
+  # end
+  
+  def text(auth_info: nil)
+    # Authentication information can be accessed via _auth_info parameter
+    # auth_info = { type: :bearer, token: "xxx", header: "Bearer xxx" }
+    # or { type: :basic, token: "base64encoded", header: "Basic base64encoded" }
+
+    # Implement tool logic here
+
+    # Return a string, hash, or any JSON-serializable object
+    { foo: "bar" }
+  end
+
+  # def blob(auth_info: nil)
+  #   File.read("/path/to/file")
+  # end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.4.0
 platform: ruby
 authors:
 - Moeki Kawakami
@@ -69,27 +69,34 @@ files:
 - Rakefile
 - app/controllers/active_mcp/base_controller.rb
 - app/controllers/concerns/active_mcp/request_handler.rb
+- app/models/active_mcp/resource_reader.rb
 - app/models/active_mcp/tool_executor.rb
 - app/views/active_mcp/cancelled.json.jbuilder
 - app/views/active_mcp/initialize.json.jbuilder
 - app/views/active_mcp/initialized.json.jbuilder
 - app/views/active_mcp/no_method.json.jbuilder
+- app/views/active_mcp/resources_list.json.jbuilder
+- app/views/active_mcp/resources_read.json.jbuilder
 - app/views/active_mcp/tools_call.json.jbuilder
 - app/views/active_mcp/tools_list.json.jbuilder
 - config/routes.rb
 - lib/active_mcp.rb
 - lib/active_mcp/configuration.rb
 - lib/active_mcp/engine.rb
+- lib/active_mcp/resource.rb
 - lib/active_mcp/server.rb
 - lib/active_mcp/server/error_codes.rb
-- lib/active_mcp/server/methods.rb
+- lib/active_mcp/server/method.rb
 - lib/active_mcp/server/protocol_handler.rb
+- lib/active_mcp/server/resource_manager.rb
 - lib/active_mcp/server/stdio_connection.rb
 - lib/active_mcp/server/tool_manager.rb
 - lib/active_mcp/tool.rb
 - lib/active_mcp/version.rb
 - lib/generators/active_mcp/install/install_generator.rb
 - lib/generators/active_mcp/install/templates/initializer.rb
+- lib/generators/active_mcp/resource/resource_generator.rb
+- lib/generators/active_mcp/resource/templates/resource.rb.erb
 - lib/generators/active_mcp/tool/templates/tool.rb.erb
 - lib/generators/active_mcp/tool/tool_generator.rb
 homepage: https://github.com/moekiorg/active_mcp