active_mcp 0.3.11 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67338ce686da0dee13981737b87274009ff6e333e0cf06274469b03f6b066c11
-  data.tar.gz: 86f3916c8df7848adea802a736f117f37f9a3c2a92f1aca811984b2782562a12
+  metadata.gz: 1891356bb19d256dcbd11f7d441fb9c5f668fc9cc0b115ea17eec44aef99ee54
+  data.tar.gz: 8031f7e13bfd5a837cf84ff3ca069bd5c56b46901e7e04c861d6c15eabcf2c94
 SHA512:
-  metadata.gz: 5a58ff5874317b91aa79f84e373e57b04a0f11378ebe4299a9ce9408f930051038c5b86a1faa3c2e8e0b4a42463850d5e662112e48fae4876812b2c6e8aedafe
-  data.tar.gz: c64a85603d69a0e15c1cf8e0a42209a7f424e7f95bd0f064fcb785cf9e5b2d70c2ab0b1bb8fd36d8aa0af5dd2367ff767c3f431fbada308a23714f181c98bd6e
+  metadata.gz: 20438f69b5a08fa089187a1eb11c0f0e8ccc5525809439e45da36105411b7c62187a981f0a73deda52fdb292ede1ffc429aaa26d0a21f2a5a369b9601bd2306d
+  data.tar.gz: cf9c750474af01cc72c1a8480c568c36a29d271b7c7a9f5a2bf5ecdec8cc42e1fc0fe70493ae6e9a82d3f431445aca068a881fc89c71c6181f976384c8b0e2ca

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,101 @@ 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
+  def initialize(id:, auth_info: nil)
+    @user = User.find(id)
+    @auth_info = auth_info
+  end
+
+  def name
+    @user.name
+  end
+
+  def uri
+    "data://localhost/users/#{@user.id}"
+  end
+
+  def mime_type
+    "application/json"
+  end
+
+  def description
+    @user.profile
+  end
+
+  def text
+    # 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
+  # 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
+  def name
+    "image"
+  end
+
+  def uri
+    "data://localhost/image"
+  end
+
+  def mime_type
+    "image/png"
+  end
+
+  def description
+    "Profile image"
+  end
+
+  def blob
+    # 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 visible?
+  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/active_mcp/base_controller.rb

@@ -2,6 +2,7 @@
 
 module ActiveMcp
   class BaseController < ActionController::Base
-    include RequestHandler
+    include RequestHandlable
+    include ResourceReadable
   end
 end

data/app/controllers/concerns/active_mcp/{request_handler.rb → request_handlable.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module ActiveMcp
-  module RequestHandler
+  module RequestHandlable
     extend ActiveSupport::Concern
 
     included do
@@ -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 = resources_list
+        @format = :jsonrpc
+        render 'active_mcp/resources_list', formats: :json
+      when Method::RESOURCES_READ
+        @resource = read_resource(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 = resources_list
+        @format = :json
+        render 'active_mcp/resources_list', formats: :json
+      when Method::RESOURCES_READ
+        @resource = read_resource(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/controllers/concerns/active_mcp/resource_readable.rb

@@ -0,0 +1,84 @@
+module ActiveMcp
+  module ResourceReadable
+    extend ActiveSupport::Concern
+
+    private
+
+    def resources_list
+      []
+    end
+
+    def read_resource(params:, auth_info:)
+      if params[:jsonrpc].present?
+        uri = params[:params][:uri]
+      else
+        uri = params[:uri]
+      end
+
+      unless uri
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+
+      resource = resources_list.find do |r|
+        r.uri == uri
+      end
+
+      unless resource
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+
+      if resource.respond_to?(:visible?) && !resource.visible?
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+
+      begin
+        if content = resource.text
+          return {
+            contents: [
+              {
+                uri:,
+                mimeType: resource.mime_type,
+                text: formatted(content)
+              }
+            ]
+          }
+        elsif content = resource.blob
+          return {
+            contents: [
+              {
+                uri:,
+                mimeType: resource.mime_type,
+                blob: Base64.strict_encode64(content)
+              }
+            ]
+          }
+        end
+      rescue
+        return {
+          isError: true,
+          contents: []
+        }
+      end
+    end
+    
+    def 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,24 @@
+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 do
+      json.array!(@resources) do |resource|
+        json.name resource.name
+        json.uri resource.uri
+        json.mimeType resource.mime_type
+        json.description resource.description
+      end
+    end
+  end
+else
+  json.result do
+    json.array!(@resources) do |resource|
+      json.name resource.name
+      json.uri resource.uri
+      json.mimeType resource.mime_type
+      json.description resource.description
+    end
+  end
+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/app/views/active_mcp/tools_list.json.jbuilder

@@ -7,4 +7,4 @@ if @format == :jsonrpc
   end
 else
   json.result @tools
-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/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.5.0"
 end

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,51 @@
+class <%= class_name %>
+  def initialize(auth_info:)
+    @auth_info = auth_info
+
+    # 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" }
+  end
+
+  def name
+    "<%= file_name %>"
+  end
+
+  def uri
+    "data://localhost/<%= file_name %>"
+  end
+
+  def mime_type
+    "application/json"
+  end
+  
+  def description
+    "<%= file_name.humanize %>"
+  end
+
+  # Uncomment and modify this method to implement authorization control
+  # This controls who can see and use this tool
+  # def visible?
+  #   # 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
+    # Return a string, hash, or any JSON-serializable object
+    { foo: "bar" }
+  end
+
+  # def blob
+  #   File.read("/path/to/file")
+  # end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_mcp
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.5.0
 platform: ruby
 authors:
 - Moeki Kawakami
 bindir: exe
 cert_chain: []
-date: 2025-04-06 00:00:00.000000000 Z
+date: 2025-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -68,12 +68,15 @@ files:
 - README.md
 - Rakefile
 - app/controllers/active_mcp/base_controller.rb
-- app/controllers/concerns/active_mcp/request_handler.rb
+- app/controllers/concerns/active_mcp/request_handlable.rb
+- app/controllers/concerns/active_mcp/resource_readable.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
@@ -82,14 +85,17 @@ files:
 - lib/active_mcp/engine.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