active_mcp 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6663bc950db47a5719e93db048f5601acb9dd58b87421fe0eb94e2c78cec2333
-  data.tar.gz: ffacf7506cc82ad8fc680dd57f3f74ee50875e8bb7053ff460dc28e59c232cfa
+  metadata.gz: c9367d905ac3b7dfa87f27063c41f24f1ed93de9d88a5fc009010ed35bfafa85
+  data.tar.gz: 7b1ed7d1f79ad9487c92a4e0595727cc60125c3584ae7029be8d3e86f9c2537b
 SHA512:
-  metadata.gz: 6631c864d9b2fbf566f5202eb31c16a4cb0154a0bcac33b23165c365adab03a01b7ee54da8996dd87660c78046457d2baa6c23f1e1e4dd5a57ea6c06601d84ca
-  data.tar.gz: b3f85f31d012218cafba456a4ebe9b50de9261686aec9b40d1f48a783e74bf6dba9506e113fb0d4372f8e5f82b6000911ec40016151063759d1b2865b68c7abe
+  metadata.gz: 5f429c060c395a06e9e146c68ea859a1750a00add2b28ba5fe3a968b20b8b335fcc3908a1f89b63aeaf24f092942af9edd4979eec2a3b380d431519ee35623d4
+  data.tar.gz: 1a0bff75ee866fbba70a5549ee867f6260cd8e925a592b9a044b3769a91ba9955487e3798647c7fa6b356e4c9cbfbd3610550a713aa4cee97dfff896c7514c15

data/README.md

@@ -17,8 +17,6 @@ A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelconte
   - [✨ Features](#-features)
   - [📦 Installation](#-installation)
   - [🚀 Setup](#-setup)
-    - [Using the Install Generator (Recommended)](#using-the-install-generator-recommended)
-    - [Manual Setup](#manual-setup)
   - [🔌 MCP Connection Methods](#-mcp-connection-methods)
     - [1. Direct HTTP Connection](#1-direct-http-connection)
     - [2. Standalone MCP Server](#2-standalone-mcp-server)
@@ -36,8 +34,8 @@ A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelconte
   - [📦 MCP Resources](#-mcp-resources)
     - [Creating Resources](#creating-resources)
     - [Resource Types](#resource-types)
-  - [⚙️ Advanced Configuration](#️-advanced-configuration)
-    - [Custom Controller](#custom-controller)
+  - [📦 MCP Resource Templates](#-mcp-resource-templates)
+    - [Creating Resource Templates](#creating-resource-templates)
   - [💡 Best Practices](#-best-practices)
     - [1. Create Specific Tool Classes](#1-create-specific-tool-classes)
     - [2. Validate and Sanitize Inputs](#2-validate-and-sanitize-inputs)
@@ -76,7 +74,7 @@ $ gem install active_mcp
 
 ## 🚀 Setup
 
-### Using the Install Generator (Recommended)
+1. Initialize
 
 The easiest way to set up Active MCP in your Rails application is to use the install generator:
 
@@ -84,46 +82,61 @@ The easiest way to set up Active MCP in your Rails application is to use the ins
 $ rails generate active_mcp:install
 ```
 
-This generator will:
+This generator will create a configuration initializer at `config/initializers/active_mcp.rb`
 
-1. Create a configuration initializer at `config/initializers/active_mcp.rb`
-2. Mount the ActiveMcp engine in your routes
-3. Create an MCP server script at `script/mcp_server.rb`
-4. Show instructions for next steps
+2. Create a tool by inheriting from `ActiveMcp::Tool::Base`:
 
-After running the generator, follow the displayed instructions to create and configure your MCP tools.
+```bash
+$ rails generate active_mcp:tool create_note
+```
 
-### Manual Setup
+```ruby
+class CreateNoteTool < ActiveMcp::Tool::Base
+  def name
+    "Create Note"
+  end
 
-If you prefer to set up manually:
+  def description
+    "Create Note"
+  end
 
-1. Mount the ActiveMcp engine in your `config/routes.rb`:
+  argument :title, :string, required: true
+  argument :content, :string, required: true
 
-```ruby
-Rails.application.routes.draw do
-  mount ActiveMcp::Engine, at: "/mcp"
+  def call(title:, content:, context:)
+    note = Note.create(title: title, content: content)
 
-  # Your other routes
+    "Created note with ID: #{note.id}"
+  end
 end
 ```
 
-2. Create a tool by inheriting from `ActiveMcp::Tool`:
+3. Create schema for your application:
 
 ```ruby
-class CreateNoteTool < ActiveMcp::Tool
-  description "Create Note"
-
-  argument :title, :string, required: true
-  argument :content, :string, required: true
+class MySchema < ActiveMcp::Schema::Base
+  tool CreateNoteTool.new
+end
+```
 
-  def call(title:, content:)
-    note = Note.create(title: title, content: content)
+4. Create controller ans set up routing:
 
-    "Created note with ID: #{note.id}"
+```ruby
+class MyMcpController < ActiveMcp::Controller::Base
+  def schema
+    MySchema.new(context:)
   end
 end
 ```
 
+```ruby
+Rails.application.routes.draw do
+  post "/mcp", to: "my_mcp#index"
+
+  # Your other routes
+end
+```
+
 ## 🔌 MCP Connection Methods
 
 Active MCP supports two connection methods:
@@ -182,7 +195,7 @@ Create new MCP tools quickly:
 $ 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.
+This creates a new tool file at `app/mcp/tools/search_users_tool.rb` with ready-to-customize starter code.
 
 ### Resource Generator
 
@@ -192,21 +205,27 @@ Generate new MCP resources to share data with AI:
 $ 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.
+This creates a new resource file at `app/mcp/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:
+MCP tools are Ruby classes that inherit from `ActiveMcp::Tool::Base` and define an interface for AI to interact with your application:
 
 ```ruby
-class SearchUsersTool < ActiveMcp::Tool
-  description 'Search users by criteria'
+class SearchUsersTool < ActiveMcp::Tool::Base
+  def name
+    "Search Users"
+  end
+
+  def description
+    'Search users by criteria'
+  end
 
   argument :email, :string, required: false, description: 'Email to search for'
   argument :name, :string, required: false, description: 'Name to search for'
   argument :limit, :integer, required: false, description: 'Maximum number of records to return'
 
-  def call(email: nil, name: nil, limit: 10)
+  def call(email: nil, name: nil, limit: 10, context: {})
     criteria = {}
     criteria[:email] = email if email.present?
     criteria[:name] = name if name.present?
@@ -248,21 +267,27 @@ Supported types:
 Control access to tools by overriding the `visible?` class method:
 
 ```ruby
-class AdminOnlyTool < ActiveMcp::Tool
-  description "Admin-only tool"
+class AdminOnlyTool < ActiveMcp::Tool::Base
+  def name
+    "Admin-only tool"
+  end
+
+  def description
+    "Admin-only tool"
+  end
 
   argument :command, :string, required: true, description: "Admin command"
 
   # Only allow admins to access this tool
-  def self.visible?(auth_info)
-    return false unless auth_info
-    return false unless auth_info[:type] == :bearer
+  def visible?(context:)
+    return false unless context
+    return false unless context[:auth_info][:type] == :bearer
 
     # Check if the token belongs to an admin
-    auth_info[:token] == "admin-token" || User.find_by_token(auth_info[:token])&.admin?
+    context[:auth_info] == "admin-token" || User.find_by_token(context[:auth_info])&.admin?
   end
 
-  def call(command:, auth_info: nil)
+  def call(command:, context: {})
     # Tool implementation
   end
 end
@@ -287,14 +312,14 @@ server.start
 #### 2. Token Verification in Tools
 
 ```ruby
-def call(resource_id:, auth_info: nil, **args)
+def call(resource_id:, context: {})
   # Check if authentication is provided
-  unless auth_info.present?
+  unless context[:auth_info].present?
     raise "Authentication required"
   end
 
   # Verify the token
-  user = User.authenticate_with_token(auth_info[:token])
+  user = User.authenticate_with_token(context[:auth_info][:token])
 
   unless user
     raise "Invalid authentication token"
@@ -311,11 +336,11 @@ MCP Resources allow you to share data and files with AI assistants. Resources ha
 
 ### Creating Resources
 
-Resources are Ruby classes that inherit from `ActiveMcp::Resource`:
+Resources are Ruby classes `**Resource`:
 
 ```ruby
 class UserResource
-  def initialize(id:, auth_info: nil)
+  def initialize(id:)
     @user = User.find(id)
     @auth_info = auth_info
   end
@@ -336,6 +361,10 @@ class UserResource
     @user.profile
   end
 
+  def visible?(context:)
+    # Your logic...
+  end
+
   def text
     # Return JSON data
     {
@@ -348,6 +377,14 @@ class UserResource
 end
 ```
 
+```ruby
+class MySchema < ActiveMcp::Schema::Base
+  User.all.each do |user|
+    resource UserResource.new(id: user.id)
+  end
+end
+```
+
 ### Resource Types
 
 Resources can return two types of content:
@@ -366,7 +403,7 @@ end
 ```ruby
 class ImageResource
   def name
-    "image"
+    "Profile Image"
   end
 
   def uri
@@ -391,32 +428,50 @@ 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
+def visible?(context: {})
+  return false unless context
+  return false unless context[:auth_info][:type] == :bearer
 
   # Check if the token belongs to an admin
-  User.find_by_token(auth_info[:token])&.admin?
+  User.find_by_token(context[:auth_info][:token])&.admin?
 end
 ```
 
-## ⚙️ Advanced Configuration
+## 📦 MCP Resource Templates
+
+MCP Resource Teamplates allow you to define template of resources.
 
-### Custom Controller
+### Creating Resource Templates
 
-Create a custom controller for advanced needs:
+Resources are Ruby classes `**ResourceTemplates`:
 
 ```ruby
-class CustomMcpController < ActiveMcp::BaseController
-  # Custom MCP handling logic
+class UserResourceTemplate
+  def name
+    "Users"
+  end
+
+  def uri_template
+    "data://localhost/users/{id}"
+  end
+
+  def mime_type
+    "application/json"
+  end
+
+  def description
+    "This is a test."
+  end
+
+  def visible?(context:)
+    # Your logic...
+  end
 end
 ```
 
-Update routes:
-
 ```ruby
-Rails.application.routes.draw do
-  post "/mcp", to: "custom_mcp#index"
+class MySchema < ActiveMcp::Schema::Base
+  resource_template UserResourceTemplate.new
 end
 ```
 
@@ -428,12 +483,12 @@ Create dedicated tool classes for each model or operation instead of generic too
 
 ```ruby
 # ✅ GOOD: Specific tool for a single purpose
-class SearchUsersTool < ActiveMcp::Tool
+class SearchUsersTool < ActiveMcp::Tool::Base
   # ...specific implementation
 end
 
 # ❌ BAD: Generic tool that dynamically loads models
-class GenericSearchTool < ActiveMcp::Tool
+class GenericSearchTool < ActiveMcp::Tool::Base
   # Avoid this pattern - security and maintainability issues
 end
 ```
@@ -443,7 +498,7 @@ end
 Always validate and sanitize inputs in your tool implementations:
 
 ```ruby
-def call(user_id:, **args)
+def call(user_id:, **args, context: {})
   # Validate input
   unless user_id.is_a?(Integer) || user_id.to_s.match?(/^\d+$/)
     raise "Invalid user ID format"
@@ -460,7 +515,7 @@ end
 Return structured responses that are easy for AI to parse:
 
 ```ruby
-def call(query:, **args)
+def call(query:, context: {})
   results = User.search(query)
 
   {

data/app/controllers/active_mcp/base_controller.rb

@@ -1,9 +1,33 @@
 # frozen_string_literal: true
 
+require_relative "../concerns/active_mcp/authenticatable"
+require_relative "../concerns/active_mcp/request_handlable"
+require_relative "../concerns/active_mcp/resource_readable"
+require_relative "../concerns/active_mcp/tool_executable"
+
 module ActiveMcp
   class BaseController < ActionController::Base
-    include RequestHandlable
-    include ResourceReadable
-    include ToolExecutable
+    include ::ActiveMcp::RequestHandlable
+    include ::ActiveMcp::ResourceReadable
+    include ::ActiveMcp::ToolExecutable
+    include ::ActiveMcp::Authenticatable
+
+    protect_from_forgery with: :null_session
+    skip_before_action :verify_authenticity_token
+    before_action :authenticate, only: [:index]
+
+    def index
+      if json_rpc_request?
+        handle_mcp_client_request
+      else
+        handle_mcp_server_request
+      end
+    end
+
+    private
+
+    def schema
+      nil
+    end
   end
 end

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

@@ -0,0 +1,29 @@
+module ActiveMcp
+  module Authenticatable
+    extend ActiveSupport::Concern
+
+    private
+
+    def authenticate
+      auth_header = request.headers["Authorization"]
+      if auth_header.present?
+        @context ||= {}
+        @context[:auth_info] = {
+          header: auth_header,
+          type: if auth_header.start_with?("Bearer ")
+                  :bearer
+                elsif auth_header.start_with?("Basic ")
+                  :basic
+                else
+                  :unknown
+                end,
+          token: auth_header.split(" ").last
+        }
+      end
+    end
+
+    def context
+      @context
+    end
+  end
+end

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

@@ -4,20 +4,6 @@ module ActiveMcp
   module RequestHandlable
     extend ActiveSupport::Concern
 
-    included do
-      protect_from_forgery with: :null_session
-      skip_before_action :verify_authenticity_token
-      before_action :authenticate, only: [:index]
-    end
-
-    def index
-      if json_rpc_request?
-        handle_mcp_client_request
-      else
-        handle_mcp_server_request
-      end
-    end
-
     private
 
     def json_rpc_request?
@@ -26,7 +12,6 @@ module ActiveMcp
 
     def handle_mcp_client_request
       @id = params[:id]
-      @auth_info = auth_info
       
       case params[:method]
       when Method::INITIALIZE
@@ -36,19 +21,23 @@ module ActiveMcp
       when Method::CANCELLED
         render 'active_mcp/cancelled', formats: :json
       when Method::RESOURCES_LIST
-        @resources = resources_list
+        @resources = schema.resources
         @format = :jsonrpc
         render 'active_mcp/resources_list', formats: :json
+      when Method::RESOURCES_TEMPLATES_LIST
+        @resource_templates = schema.resource_templates
+        @format = :jsonrpc
+        render 'active_mcp/resource_templates_list', formats: :json
       when Method::RESOURCES_READ
-        @resource = read_resource(params:, auth_info:)
+        @resource = read_resource(params:, context:)
         @format = :jsonrpc
         render 'active_mcp/resources_read', formats: :json
       when Method::TOOLS_LIST
-        @tools = ActiveMcp::Tool.authorized_tools(auth_info)
+        @tools = schema.tools
         @format = :jsonrpc
         render 'active_mcp/tools_list', formats: :json
       when Method::TOOLS_CALL
-        @tool_result = execute_tool(params: params, auth_info: auth_info)
+        @tool_result = execute_tool(params:, context:)
         @format = :jsonrpc
         render 'active_mcp/tools_call', formats: :json
       else
@@ -58,23 +47,25 @@ module ActiveMcp
     end
 
     def handle_mcp_server_request
-      @auth_info = auth_info
-      
       case params[:method]
       when Method::RESOURCES_LIST
-        @resources = resources_list
+        @resources = schema.resources
         @format = :json
         render 'active_mcp/resources_list', formats: :json
       when Method::RESOURCES_READ
-        @resource = read_resource(params:, auth_info:)
+        @resource = read_resource(params:, context:)
         @format = :json
         render 'active_mcp/resources_read', formats: :json
+      when Method::RESOURCES_TEMPLATES_LIST
+        @resource_templates = schema.resource_templates
+        @format = :json
+        render 'active_mcp/resource_templates_list', formats: :json
       when Method::TOOLS_LIST
-        @tools = ActiveMcp::Tool.authorized_tools(auth_info)
+        @tools = schema.tools
         @format = :json
         render 'active_mcp/tools_list', formats: :json
       when Method::TOOLS_CALL
-        @tool_result = execute_tool(params: params, auth_info: auth_info)
+        @tool_result = execute_tool(params:, context:)
         @format = :json
         render 'active_mcp/tools_call', formats: :json
       else
@@ -83,25 +74,8 @@ module ActiveMcp
       end
     end
 
-    def authenticate
-      auth_header = request.headers["Authorization"]
-      if auth_header.present?
-        @auth_info = {
-          header: auth_header,
-          type: if auth_header.start_with?("Bearer ")
-                  :bearer
-                elsif auth_header.start_with?("Basic ")
-                  :basic
-                else
-                  :unknown
-                end,
-          token: auth_header.split(" ").last
-        }
-      end
-    end
-
-    def auth_info
-      @auth_info
+    def context
+      @context ||= {}
     end
   end
 end

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

@@ -4,11 +4,7 @@ module ActiveMcp
 
     private
 
-    def resources_list
-      []
-    end
-
-    def read_resource(params:, auth_info:)
+    def read_resource(params:, context:)
       if params[:jsonrpc].present?
         uri = params[:params][:uri]
       else
@@ -22,7 +18,7 @@ module ActiveMcp
         }
       end
 
-      resource = resources_list.find do |r|
+      resource = schema.resources.find do |r|
         r.uri == uri
       end
 
@@ -33,7 +29,7 @@ module ActiveMcp
         }
       end
 
-      if resource.respond_to?(:visible?) && !resource.visible?
+      if resource.respond_to?(:visible?) && !resource.visible?(context:)
         return {
           isError: true,
           contents: []

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

@@ -4,7 +4,7 @@ module ActiveMcp
 
     private
 
-    def execute_tool(params:, auth_info:)
+    def execute_tool(params:, context: {})
       if params[:jsonrpc].present?
         tool_name = params[:params][:name]
         tool_params = params[:params][:arguments]
@@ -25,11 +25,11 @@ module ActiveMcp
         }
       end
 
-      tool_class = Tool.registered_tools.find do |tc|
-        tc.tool_name == tool_name
+      tool = schema.tools.find do |tc|
+        tc.name == tool_name
       end
       
-      unless tool_class
+      unless tool
         return {
           isError: true,
           content: [
@@ -41,7 +41,7 @@ module ActiveMcp
         }
       end
       
-      unless tool_class.visible?(auth_info)
+      unless tool.visible?(context:)
         return {
           isError: true,
           content: [
@@ -69,7 +69,6 @@ module ActiveMcp
         end
       end
 
-      tool = tool_class.new
       validation_result = tool.validate_arguments(arguments)
 
       if validation_result.is_a?(Hash) && validation_result[:error]
@@ -86,13 +85,11 @@ module ActiveMcp
       
       # Execute the tool
       begin
-        arguments[:auth_info] = auth_info if auth_info.present?
-        
         return {
           content: [
             {
               type: "text",
-              text: formatted(tool.call(**arguments.symbolize_keys))
+              text: formatted(tool.call(**arguments, context:))
             }
           ]
         }

data/app/views/active_mcp/resource_templates_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.resourceTemplates do
+      json.array!(@resource_templates) do |resource|
+        json.name resource.name
+        json.uriTemplate resource.uri_template
+        json.mimeType resource.mime_type
+        json.description resource.description
+      end
+    end
+  end
+else
+  json.result do
+    json.array!(@resource_templates) do |resource|
+      json.name resource.name
+      json.uriTemplate resource.uri_template
+      json.mimeType resource.mime_type
+      json.description resource.description
+    end
+  end
+end

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

@@ -3,8 +3,20 @@ json.id @id if @format == :jsonrpc && @id.present?
 
 if @format == :jsonrpc
   json.result do
-    json.tools @tools
+    json.tools do
+      json.array!(@tools) do |tool|
+        json.name tool.name
+        json.description tool.description
+        json.inputSchema tool.class.schema
+      end
+    end
   end
 else
-  json.result @tools
+  json.result do
+    json.array!(@tools) do |tool|
+      json.name tool.name
+      json.description tool.description
+      json.inputSchema tool.class.schema
+    end
+  end
 end

data/lib/active_mcp/controller/base.rb

@@ -0,0 +1,7 @@
+require_relative "../../../app/controllers/active_mcp/base_controller"
+
+module ActiveMcp
+  module Controller
+    Base = ActiveMcp::BaseController
+  end
+end