actionmcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1183f05df43cca3948c84aa105f6e38c5f7cd414c1b38619cfb6c9afa528d442
+  data.tar.gz: 02bdfed4f0a3b26d04203430c4b62183c615fb0a47a3b28d281b42f07928e5a8
+SHA512:
+  metadata.gz: 77b9a85435b5e19a35268db9fbcc3139222c01abc7c67e5af61a44a460d55fe5ec6b9819209fa8bfd493a3d0c648ba7d7fa5c440f889871556880f5f961a1da0
+  data.tar.gz: e77783308752dbbe95498ca9d3548471b44bafbfe72a130f6e070c906220eeeecd48fb8d719f150d2f69a14a416d7f0cba19c3fd33b6479eab54f564633eed73

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Abdelkader Boudih 2024
+
+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,57 @@
+# ActionMCP
+
+**ActionMCP** is a Ruby gem that provides essential tooling for building Model Context Protocol (MCP) capable servers. 
+It offers base classes and helpers for creating MCP applications, making it easier to integrate your Ruby/Rails application with the MCP standard. 
+With ActionMCP, you can focus on your app's logic while it handles the boilerplate for MCP compliance.
+
+## Introduction
+
+**Model Context Protocol (MCP)** is an open protocol that standardizes how applications provide context to large language models (LLMs) ([Introduction - Model Context Protocol](https://modelcontextprotocol.io/introduction#:~:text=MCP%20is%20an%20open%20protocol,different%20data%20sources%20and%20tools)). 
+
+Think of it as a universal interface for connecting AI assistants to external data sources and tools. 
+
+MCP allows AI systems to plug into various resources in a consistent, secure way, enabling two-way integration between your data and AI-powered applications ([Introducing the Model Context Protocol \ Anthropic](https://www.anthropic.com/news/model-context-protocol#:~:text=The%20Model%20Context%20Protocol%20is,that%20connect%20to%20these%20servers)). 
+
+This means an AI (like an LLM) can request information or actions from your application through a well-defined protocol, and your app can provide context or perform tasks for the AI in return.
+
+**ActionMCP** is targeted at developers building MCP-enabled applications. 
+It simplifies the process of integrating Ruby and Rails apps with the MCP standard by providing a set of base classes and an easy-to-use server interface. 
+
+Instead of implementing MCP support from scratch, you can subclass and configure the provided **Prompt**, **Tool**, and **Resource** classes to expose your app’s functionality to LLMs. 
+
+ActionMCP handles the underlying MCP message format and routing, so you can adhere to the open standard with minimal effort. 
+
+In short, ActionMCP helps you build an MCP server (the component that exposes capabilities to AI) more quickly and with fewer mistakes.
+
+## Installation
+
+To start using ActionMCP, add it to your project:
+
+- **Using Bundler (Rails or Ruby projects):** Add the gem to your Gemfile and run bundle install:
+  
+  execute:
+  ```
+  $ bundle add actionmcp
+  ```
+
+After installing, include the gem in your code by requiring it:
+
+This will load the ActionMCP library so you can start defining MCP prompts, tools, and resources in your application.
+
+## Core Components
+
+ActionMCP provides three core abstractions to streamline MCP server development: **Prompt**, **Tool**, and **Resource**. 
+These correspond to key MCP concepts and let you define what context or capabilities your server exposes to LLMs. 
+Below is an overview of each component and how you might use it:
+
+### ActionMCP::Prompt
+
+Make Rails Say Sexy stuff 
+
+### ActionMCP::Tool
+
+Make Rails Do Sexy stuff and serve beer to Clients.
+
+### ActionMCP::Resource
+
+I dont need this for now

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'

data/lib/action_mcp/content/audio.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Content
+    # Audio content includes a base64-encoded audio clip and its MIME type.
+    class Audio < Base
+      attr_reader :data, :mime_type
+
+      def initialize(data, mime_type)
+        super("audio")
+        @data = data
+        @mime_type = mime_type
+      end
+
+      def to_h
+        super.merge(data: @data, mimeType: @mime_type)
+      end
+    end
+  end
+end

data/lib/action_mcp/content/image.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Content
+    # Image content includes a base64-encoded image and its MIME type.
+    class Image < Base
+      attr_reader :data, :mime_type
+
+      def initialize(data, mime_type)
+        super("image")
+        @data = data
+        @mime_type = mime_type
+      end
+
+      def to_h
+        super.merge(data: @data, mimeType: @mime_type)
+      end
+    end
+  end
+end

data/lib/action_mcp/content/resource.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Content
+    # Resource content references a server-managed resource.
+    # It includes a URI, MIME type, and optionally text content or a base64-encoded blob.
+    class Resource < Base
+      attr_reader :uri, :mime_type, :text, :blob
+
+      def initialize(uri, mime_type, text: nil, blob: nil)
+        super("resource")
+        @uri = uri
+        @mime_type = mime_type
+        @text = text
+        @blob = blob
+      end
+
+      def to_h
+        resource_data = { uri: @uri, mimeType: @mime_type }
+        resource_data[:text] = @text if @text
+        resource_data[:blob] = @blob if @blob
+
+        super.merge(resource: resource_data)
+      end
+    end
+  end
+end

data/lib/action_mcp/content/text.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module Content
+    # Text content represents plain text messages.
+    class Text < Base
+      attr_reader :text
+
+      def initialize(text)
+        super("text")
+        @text = text
+      end
+
+      def to_h
+        super.merge(text: @text)
+      end
+    end
+  end
+end

data/lib/action_mcp/content.rb

@@ -0,0 +1,21 @@
+module ActionMCP
+  module Content
+    extend ActiveSupport::Autoload
+    # Base class for MCP content items.
+    class Base
+      attr_reader :type
+
+      def initialize(type)
+        @type = type
+      end
+
+      def to_h
+        { type: @type }
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+  end
+end

data/lib/action_mcp/gem_version.rb

@@ -0,0 +1,6 @@
+module ActionMCP
+  # Returns the currently loaded version of Active MCP as a +Gem::Version+.
+  def self.gem_version
+    Gem::Version.new VERSION
+  end
+end

data/lib/action_mcp/json_rpc/base.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+    private
+
+    def validate_id(id)
+      raise Error, "ID must be a string or number" unless id.is_a?(String) || id.is_a?(Numeric)
+      raise Error, "ID must not be null" if id.nil?
+    end
+  end
+end

data/lib/action_mcp/json_rpc/json_rpc_error.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+    class JsonRpcError < StandardError
+      # Define the standard JSON-RPC 2.0 error codes
+      ERROR_CODES = {
+        parse_error: {
+          code: -32_700,
+          message: "Parse error"
+        },
+        invalid_request: {
+          code: -32_600,
+          message: "Invalid request"
+        },
+        method_not_found: {
+          code: -32_601,
+          message: "Method not found"
+        },
+        invalid_params: {
+          code: -32_602,
+          message: "Invalid params"
+        },
+        internal_error: {
+          code: -32_603,
+          message: "Internal error"
+        },
+        server_error: {
+          code: -32_000,
+          message: "Server error"
+        }
+      }.freeze
+
+      attr_reader :code, :data
+
+      # Retrieve error details by symbol.
+      def self.[](symbol)
+        ERROR_CODES[symbol] or raise ArgumentError, "Unknown error code: #{symbol}"
+      end
+
+      # Build an error hash, allowing custom message or data to override defaults.
+      def self.build(symbol, message: nil, data: nil)
+        error = self[symbol].dup
+        error[:message] = message if message
+        error[:data] = data if data
+        error
+      end
+
+      # Initialize the error using a symbol key, with optional custom message and data.
+      def initialize(symbol, message: nil, data: nil)
+        error_details = self.class.build(symbol, message: message, data: data)
+        @code = error_details[:code]
+        @data = error_details[:data]
+        super(error_details[:message])
+      end
+
+      # Returns a hash formatted for a JSON-RPC error response.
+      def as_json
+        hash = { code: code, message: message }
+        hash[:data] = data if data
+        hash
+      end
+
+      # Converts the error hash to a JSON string.
+      def to_json(*_args)
+        as_json.to_json
+      end
+    end
+  end
+end

data/lib/action_mcp/json_rpc/notification.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+  Notification = Data.define(:method, :params) do
+    def initialize(method:, params: nil)
+      super(method: method, params: params)
+    end
+
+    def to_h
+      hash = {
+        jsonrpc: "2.0",
+        method: method
+      }
+      hash[:params] = params if params
+      hash
+    end
+  end
+  end
+end

data/lib/action_mcp/json_rpc/request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+      Request = Data.define(:jsonrpc, :id, :method, :params) do
+        def initialize(id:, method:, params: nil)
+          validate_id(id)
+          super(id: id, method: method, params: params)
+        end
+
+        def to_h
+          hash = {
+            jsonrpc: "2.0",
+            id: id,
+            method: method
+          }
+          hash[:params] = params if params
+          hash
+        end
+      end
+  end
+end

data/lib/action_mcp/json_rpc/response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+  Response = Data.define(:id, :result, :error) do
+    def initialize(id:, result: nil, error: nil)
+      processed_error = process_error(error)
+      processed_result = error ? nil : result
+      validate_result_error!(processed_result, processed_error)
+      super(id: id, result: processed_result, error: processed_error)
+    end
+
+    def to_h
+      hash = {
+        jsonrpc: "2.0",
+        id: id
+      }
+      if error
+        hash[:error] = {
+          code: error[:code],
+          message: error[:message]
+        }
+        hash[:error][:data] = error[:data] if error[:data]
+      else
+        hash[:result] = result
+      end
+      hash
+    end
+
+    private
+
+    def process_error(error)
+      case error
+      when Symbol
+        ErrorCodes[error]
+      when Hash
+        validate_error!(error)
+        error
+      end
+    end
+
+    def validate_error!(error)
+      raise Error, "Error code must be an integer" unless error[:code].is_a?(Integer)
+      raise Error, "Error message is required" unless error[:message].is_a?(String)
+    end
+
+    def validate_result_error!(result, error)
+      raise Error, "Either result or error must be set" unless result || error
+      raise Error, "Cannot set both result and error" if result && error
+    end
+  end
+  end
+end

data/lib/action_mcp/json_rpc.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  module JsonRpc
+    extend ActiveSupport::Autoload
+
+    autoload :Base
+    autoload :JsonRpcError
+    autoload :Notification
+    autoload :Request
+    autoload :Response
+  end
+end

data/lib/action_mcp/prompt.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # Abstract base class for Prompts
+  # Defines: name, description, arguments, plus auto-registration.
+  class Prompt
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    class_attribute :_prompt_name, instance_accessor: false
+    class_attribute :_description, instance_accessor: false, default: ""
+    class_attribute :_argument_definitions, instance_accessor: false, default: []
+    class_attribute :abstract_prompt, instance_accessor: false, default: false
+
+    def self.inherited(subclass)
+      super
+      return if subclass == Prompt
+      return if "ApplicationPrompt" == subclass.name
+      subclass.abstract_prompt = false
+
+      # Automatically register the subclass with the PromptsRegistry
+      PromptsRegistry.register(subclass.prompt_name, subclass)
+    end
+
+    def self.abstract!
+      self.abstract_prompt = true
+      # If already registered, you might want to unregister it here.
+    end
+
+    def self.abstract?
+      self.abstract_prompt
+    end
+
+    # ---------------------------------------------------
+    # Prompt Name
+    # ---------------------------------------------------
+    def self.prompt_name(name = nil)
+      if name
+        self._prompt_name = name
+      else
+        _prompt_name || default_prompt_name
+      end
+    end
+
+    def self.default_prompt_name
+      name.demodulize.underscore.dasherize.sub(/-prompt$/, "")
+    end
+
+    # ---------------------------------------------------
+    # Description
+    # ---------------------------------------------------
+    def self.description(text = nil)
+      if text
+        self._description = text
+      else
+        _description
+      end
+    end
+
+    # ---------------------------------------------------
+    # Argument DSL
+    # ---------------------------------------------------
+    def self.argument(arg_name, description: "", required: false, default: nil)
+      arg_def = {
+        name: arg_name.to_s,
+        description: description,
+        required: required,
+        default: default
+      }
+      self._argument_definitions += [ arg_def ]
+
+      # Register the attribute so it's recognized by ActiveModel
+      attribute arg_name, :string, default: default
+    end
+
+    def self.arguments
+      _argument_definitions
+    end
+
+    # ---------------------------------------------------
+    # Convert prompt definition to Hash
+    # ---------------------------------------------------
+    def self.to_h
+      {
+        name: prompt_name,
+        description: description.presence,
+        arguments: arguments.map { |arg| arg.slice(:name, :description, :required) }
+      }.compact
+    end
+
+    # ---------------------------------------------------
+    # Class-level call method
+    # ---------------------------------------------------
+    # Receives a Hash of params, initializes a prompt instance,
+    # validates it, and if valid, calls the instance call method.
+    # If invalid, raises a JsonRpcError with code :invalid_params.
+    #
+    # Usage:
+    #   result = MyPromptClass.call(params)
+    #
+    # Raises:
+    #   ActionMCP::JsonRpc::JsonRpcError(:invalid_params) if validation fails.
+    #
+    def self.call(params)
+      prompt = new(params)  # Initialize an instance with provided params
+      unless prompt.valid?
+        # Collect all validation errors into a single string or array
+        errors_str = prompt.errors.full_messages.join(", ")
+
+        raise ActionMCP::JsonRpc::JsonRpcError.new(
+          :invalid_params,
+          message: "Prompt validation failed: #{errors_str}",
+          data: { errors: prompt.errors }
+        )
+      end
+
+      # If we reach here, the prompt is valid
+      prompt.call
+    end
+
+    # ---------------------------------------------------
+    # Instance call method
+    # ---------------------------------------------------
+    # By default, does nothing. Override in your subclasses to
+    # perform custom prompt processing. (Return a payload if needed)
+    #
+    # Usage: Called internally after validation in self.call
+    #
+    def call
+      raise NotImplementedError, "Subclasses must implement the call method"
+      # Default implementation (no-op)
+      # In a real subclass, you might do:
+      #   def call
+      #     # Perform logic, e.g. analyze code, etc.
+      #     # Return something meaningful.
+      #   end
+    end
+  end
+end

data/lib/action_mcp/prompts_registry.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  class PromptsRegistry < RegistryBase
+    class << self
+      alias_method :prompts, :items
+      alias_method :available_prompts, :enabled
+    end
+  end
+end

data/lib/action_mcp/railtie.rb

@@ -0,0 +1,14 @@
+require "rails"
+require "active_model/railtie"
+
+module ActionMCP
+  class Railtie < Rails::Railtie # :nodoc:
+    # TODO: fix this to be a proper railtie if you going to to opensource it
+    initializer "action_mcp.clear_registry" do |app|
+      app.config.to_prepare do
+        ActionMCP::ToolsRegistry.clear!
+        ActionMCP::PromptsRegistry.clear!
+      end
+    end
+  end
+end

data/lib/action_mcp/registry_base.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  class RegistryBase
+    class << self
+      def items
+        @items ||= {}
+      end
+
+      # Register an item by unique name
+      def register(name, item_class)
+        raise ArgumentError, "Name can't be blank" if name.blank?
+        raise ArgumentError, "Name '#{name}' is already registered." if items.key?(name)
+
+        items[name] = { class: item_class, enabled: true }
+      end
+
+      # Fetch an item’s metadata
+      # Returns { class: <Class>, enabled: <Boolean> } or nil
+      def fetch(name)
+        items[name]
+      end
+
+      # Number of registered items, ignoring abstract ones.
+      def size
+        items.values.reject { |item| abstract_item?(item) }.size
+      end
+
+      def unregister(name)
+        items.delete(name)
+      end
+
+      def clear!
+        items.clear
+      end
+
+      # List of currently available items, excluding abstract ones.
+      def enabled
+        items
+          .reject { |_name, item| item[:class].abstract? }
+          .select { |_name, item| item[:enabled] }
+      end
+
+      def fetch_available_tool(name)
+        enabled[name]&.fetch(:class)
+      end
+
+      # Enable an item by name
+      def enable(name)
+        raise ArgumentError, "Name '#{name}' not found." unless items.key?(name)
+
+        items[name][:enabled] = true
+      end
+
+      # Disable an item by name
+      def disable(name)
+        raise ArgumentError, "Name '#{name}' not found." unless items.key?(name)
+
+        items[name][:enabled] = false
+      end
+
+      private
+
+      # Helper to determine if an item is abstract.
+      def abstract_item?(item)
+        klass = item[:class]
+        klass.respond_to?(:abstract?) && klass.abstract?
+      end
+    end
+  end
+end

data/lib/action_mcp/resource.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  Resource = Data.define(:uri, :name, :description, :mime_type, :size) do
+    # Convert the resource to a hash with the keys expected by MCP.
+    # Note: The key for mime_type is converted to 'mimeType' as specified.
+    def to_h
+      hash = { uri: uri, name: name }
+      hash[:description] = description if description
+      hash[:mimeType]   = mime_type if mime_type
+      hash[:size]       = size if size
+      hash
+    end
+
+    # Convert the resource to a JSON string.
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+end