active_mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ecbb60485be256f7d033221a79ff3cae7d113bbd1876e5b6f191f2aeeff393
-  data.tar.gz: a7d32577afebf477e230adbac59116f8f3b92331aeac111a9c129bfac83b132b
+  metadata.gz: 051dd51506aaadb0c6bf460f1f001049b5d70dc950a060a663d2256050224de7
+  data.tar.gz: e70d63d1618f882dd9d459de896a5ba086e29cbef9acbdf897f800a76266850e
 SHA512:
-  metadata.gz: c94ad9b53bbfc8e9e6104f0e8ae76dbc9b1b54c1f153e55eab3c2be02c6f5f54ae40fec89c4b55a39505d1a8d9e42e1bb2d3c65868bd6c711b0fbad72e4d069d
-  data.tar.gz: 7ba6697d22894f9c5166623ae176319885d4fc050c462c8ccaf18322b119b53ec858d20de75fc91feacc87554037de2e7157cae7a4b32dd55d1a5da03ba17491
+  metadata.gz: 7b5c6aaa00d5f9138d2186f2ea4c988f621f5f231674f4c01eeda64418187e0502999b1385c9417824bd99b888a9252f2833c5f5f42026e8943ce07d8a8952a4
+  data.tar.gz: 31d7ea0b9f9cd7b6385a30ced3a9caf14d2105f366d614c1ae8fc5c227f617c547f1f86c63084e4816265cb838ed8e089a4997e9cd1d3e757f8304cd197717a7

data/README.md

@@ -2,8 +2,6 @@
 
 A Ruby on Rails engine that provides [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) capabilities to Rails applications. This gem allows you to easily create and expose MCP-compatible tools from your Rails application.
 
-![Active MCP](./docs/active_mcp.png)
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -26,6 +24,25 @@ $ gem install active_mcp
 
 ## Setup
 
+### Using the Install Generator (Recommended)
+
+The easiest way to set up Active MCP in your Rails application is to use the install generator:
+
+```bash
+$ rails generate active_mcp:install
+```
+
+This generator will:
+
+1. Create a configuration initializer at `config/initializers/active_mcp.rb`
+2. Mount the ActiveMcp engine in your routes
+
+After running the generator, follow the displayed instructions to create and configure your MCP tools.
+
+### Manual Setup
+
+If you prefer to set up manually:
+
 1. Mount the ActiveMcp engine in your `config/routes.rb`:
 
 ```ruby
@@ -53,7 +70,13 @@ class CreateNoteTool < ActiveMcp::Tool
 end
 ```
 
-3. Start the MCP server:
+#### with streamable HTTP
+
+Set MCP destination as `https:your-app.example.com/mcp`
+
+#### with independent MCP Server
+
+Start the MCP server:
 
 ```ruby
 # server.rb
@@ -64,7 +87,7 @@ server = ActiveMcp::Server.new(
 server.start
 ```
 
-4. Set up MCP Client
+Set up MCP Client
 
 ```json
 {
@@ -79,14 +102,28 @@ server.start
 
 ## Rails Generators
 
-MCP Rails provides generators to help you quickly create new MCP tools:
+Active MCP provides generators to help you quickly set up and extend your MCP integration:
+
+### Install Generator
+
+Initialize Active MCP in your Rails application:
+
+```bash
+$ rails generate active_mcp:install
+```
+
+This sets up all necessary configuration files and mounts the MCP engine in your routes.
+
+### Tool Generator
+
+Create new MCP tools quickly:
 
 ```bash
 # Generate a new MCP tool
 $ rails generate active_mcp:tool search_users
 ```
 
-This creates a new tool file at `app/models/tools/search_users_tool.rb` with the following starter code:
+This creates a new tool file at `app/tools/search_users_tool.rb` with the following starter code:
 
 ```ruby
 class SearchUsersTool < ActiveMcp::Tool
@@ -136,7 +173,44 @@ http://your-app.example.com/mcp
 
 Clients will discover the available tools and their input schemas automatically through the MCP protocol.
 
-## Authentication Flow
+## Authorization & Authentication
+
+ActiveMcp supports both authentication (verifying who a user is) and authorization (controlling what resources they can access).
+
+### Authorization for Tools
+
+You can control which tools are visible and accessible to different users by overriding the `authorized?` class method:
+
+```ruby
+class AdminOnlyTool < ActiveMcp::Tool
+  description "This tool is only accessible by admins"
+
+  property :command, :string, required: true, description: "Admin command to execute"
+
+  # Define authorization logic - only admin tokens can access this tool
+  def self.authorized?(auth_info)
+    return false unless auth_info
+    return false unless 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?
+  end
+
+  def call(command:, auth_info: nil)
+    # Tool implementation
+  end
+end
+```
+
+When a user makes a request to the MCP server:
+
+1. Only tools that return `true` from their `authorized?` method will be included in the tools list
+2. Users can only call tools that they're authorized to use
+3. Unauthorized access attempts will return a 403 Forbidden response
+
+This makes it easy to create role-based access control for your MCP tools.
+
+### Authentication Flow
 
 ActiveMcp supports receiving authentication credentials from MCP clients and forwarding them to your Rails application. There are two ways to handle authentication:
 

data/app/controllers/active_mcp/base_controller.rb

@@ -8,10 +8,30 @@ module ActiveMcp
 
     def index
       case params[:method]
+      when Method::INITIALIZE
+        render_initialize
+      when Method::INITIALIZED
+        render json: {
+          jsonrpc: "2.0",
+          method: "notifications/initialized"
+        }
+      when Method::CANCELLED
+        render json: {
+          jsonrpc: "2.0",
+          method: "notifications/cancelled"
+        }
       when Method::TOOLS_LIST
-        render_tools_list
+        if params[:jsonrpc]
+          render_tools_list_as_jsonrpc
+        else
+          render_tools_list
+        end
       when Method::TOOLS_CALL
-        call_tool(params)
+        if params[:jsonrpc]
+          call_tool_as_jsonrpc
+        else
+          render json: call_tool(params)
+        end
       else
         render json: {error: "Method not found: #{params[:method]}"}, status: 404
       end
@@ -19,6 +39,29 @@ module ActiveMcp
 
     private
 
+    def render_tools_list_as_jsonrpc
+      render json: {
+        jsonrpc: "2.0",
+        id: params[:id],
+        result: {tools:}
+      }
+    end
+
+    def call_tool_as_jsonrpc
+      render json: {
+        jsonrpc: "2.0",
+        id: params[:id],
+        result: {
+          content: [
+            {
+              type: "text",
+              text: call_tool(params[:params])[:result]
+            }
+          ]
+        }
+      }
+    end
+
     def process_authentication
       auth_header = request.headers["Authorization"]
       if auth_header.present?
@@ -36,25 +79,53 @@ module ActiveMcp
       end
     end
 
+    def render_initialize
+      render json: {
+          jsonrpc: "2.0",
+          id: params[:id],
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              logging: {},
+              capabilities: {
+                resources: {
+                  subscribe: false,
+                  listChanged: false
+                },
+                tools: {
+                  listChanged: false
+                }
+              },
+            },
+            serverInfo: {
+              name: ActiveMcp::Configuration.config.server_name,
+              version: ActiveMcp::Configuration.config.server_version
+            }
+          }
+        }
+    end
+
     def render_tools_list
-      tools = Tool.registered_tools.map do |tool_class|
+      render json: {result: tools}
+    end
+
+    def tools
+      Tool.registered_tools.select do |tool_class|
+        tool_class.authorized?(@auth_info)
+      end.map do |tool_class|
         {
           name: tool_class.tool_name,
           description: tool_class.desc,
           inputSchema: tool_class.schema
         }
       end
-
-      render json: {result: tools}
     end
 
     def call_tool(params)
       tool_name = params[:name]
-      arguments = JSON.parse(params[:arguments] || "{}")
 
       unless tool_name
-        render json: {error: "Invalid params: missing tool name"}, status: 422
-        return
+        return {error: "Invalid params: missing tool name"}
       end
 
       tool_class = Tool.registered_tools.find do |tc|
@@ -62,25 +133,34 @@ module ActiveMcp
       end
 
       unless tool_class
-        render json: {error: "Tool not found: #{tool_name}"}, status: 404
-        return
+        return {error: "Tool not found: #{tool_name}"}
+      end
+
+      unless tool_class.authorized?(@auth_info)
+        return {error: "Unauthorized: Access to tool '#{tool_name}' denied"}
+      end
+
+      if params[:arguments].is_a?(Hash)
+        arguments = params[:arguments].symbolize_keys
+      else
+        arguments = params[:arguments].permit!.to_hash.symbolize_keys.transform_values { _1.match(/^\d+$/) ? _1.to_i : _1 }
       end
 
       tool = tool_class.new
       validation_result = tool.validate_arguments(arguments)
 
       if validation_result.is_a?(Hash) && validation_result[:error]
-        render json: {result: validation_result[:error]}
-        return
+        return {result: validation_result[:error]}
       end
 
       begin
         arguments[:auth_info] = @auth_info if @auth_info.present?
 
         result = tool.call(**arguments.symbolize_keys)
-        render json: {result: result}
+
+        return {result: result}
       rescue => e
-        render json: {error: "Error: #{e.message}"}
+        return {error: "Error: #{e.message}"}
       end
     end
   end

data/lib/active_mcp/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveMcp
+  class Configuration
+    attr_accessor :server_name, :server_version
+
+    def initialize
+      @server_name = "MCP Server"
+      @server_version = "1.0.0"
+    end
+  end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/lib/active_mcp/server/methods.rb

@@ -4,6 +4,7 @@ module ActiveMcp
   module Method
     INITIALIZE = "initialize"
     INITIALIZED = "notifications/initialized"
+    CANCELLED = "notifications/cancelled"
     PING = "ping"
     TOOLS_LIST = "tools/list"
     TOOLS_CALL = "tools/call"

data/lib/active_mcp/server/protocol_handler.rb

@@ -173,7 +173,7 @@ module ActiveMcp
         if defined?(Rails)
           Rails.logger.error(error_details)
         else
-          # Fallback to standard error output if Rails is not available
+          # Fresallback to standard error output if Rails is not available
           $stderr.puts(error_details)
         end
       end

data/lib/active_mcp/server/tool_manager.rb

@@ -76,7 +76,7 @@ module ActiveMcp
         request.body = JSON.generate({
           method: "tools/call",
           name:,
-          arguments: arguments.to_json
+          arguments: arguments
         })
         request["Content-Type"] = "application/json"
         request["Authorization"] = @auth_header

data/lib/active_mcp/tool.rb

@@ -34,6 +34,10 @@ module ActiveMcp
       def inherited(subclass)
         registered_tools << subclass
       end
+
+      def authorized?(auth_info)
+        true
+      end
     end
 
     def initialize

data/lib/active_mcp/version.rb

@@ -1,3 +1,3 @@
 module ActiveMcp
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/active_mcp.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "active_mcp/version"
+require_relative "active_mcp/config"
 require_relative "active_mcp/tool"
 require_relative "active_mcp/server"
 

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

@@ -0,0 +1,17 @@
+module ActiveMcp
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      
+      desc "Creates an Active MCP initializer and mounts the engine in your routes"
+      
+      def create_initializer_file
+        template "initializer.rb", "config/initializers/active_mcp.rb"
+      end
+      
+      def update_routes
+        route "mount ActiveMcp::Engine, at: '/mcp'"
+      end
+    end
+  end
+end

data/lib/generators/active_mcp/install/templates/initializer.rb

@@ -0,0 +1,5 @@
+# Active MCP configuration
+ActiveMcp.configure do |config|
+  config.server_name = 'MCP Server'
+  config.server_version = '1.0.0'
+end

data/lib/generators/active_mcp/install/templates/mcp_server.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# MCP Server script for Active MCP
+require 'active_mcp'
+
+# Load Rails application
+ENV['RAILS_ENV'] ||= 'development'
+require File.expand_path('../config/environment', __dir__)
+
+# Initialize MCP server
+server = ActiveMcp::Server.new(
+  name: "<%= Rails.application.class.module_parent_name %> MCP Server",
+  uri: '<%= Rails.application.config.action_controller.default_url_options&.fetch(:host, 'http://localhost:3000') %>/mcp'
+)
+
+# Optional authentication
+<% if ActiveMcp.config.auth_enabled %>
+server.auth = {
+  type: :bearer,
+  token: ENV['MCP_AUTH_TOKEN'] || '<%= ActiveMcp.config.auth_token %>'
+}
+<% end %>
+
+# Start the server
+puts "Starting MCP server for <%= Rails.application.class.module_parent_name %>..."
+puts "Connect to this server in MCP clients using the following configuration:"
+puts
+puts "   Command: #{File.expand_path(__FILE__)}"
+puts "   Args: []"
+puts
+puts "Press Ctrl+C to stop the server"
+server.start

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

@@ -5,6 +5,23 @@ class <%= class_name %> < ActiveMcp::Tool
   property :param2, :string, required: false, description: "Second parameter description"
   # Add more parameters as needed
   
+  # Uncomment and modify this method to implement authorization control
+  # This controls who can see and use this tool
+  # def self.authorized?(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 call(param1:, param2: nil, auth_info: nil, **args)
     # Authentication information can be accessed via _auth_info parameter
     # auth_info = { type: :bearer, token: "xxx", header: "Bearer xxx" }

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Your Name
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 2025-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,6 +56,7 @@ files:
 - app/controllers/active_mcp/base_controller.rb
 - config/routes.rb
 - lib/active_mcp.rb
+- lib/active_mcp/config.rb
 - lib/active_mcp/engine.rb
 - lib/active_mcp/server.rb
 - lib/active_mcp/server/error_codes.rb
@@ -65,6 +66,9 @@ files:
 - 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/install/templates/mcp_server.rb
 - lib/generators/active_mcp/tool/templates/tool.rb.erb
 - lib/generators/active_mcp/tool/tool_generator.rb
 homepage: https://github.com/moekiorg/active_mcp