actionmcp 0.2.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e01fe9b15e57ab4450f9712dd2a38dbf355cbdc50d196a8026cbb205d3d8a07
-  data.tar.gz: 8ce8ffd799f5b9487c0bb3b78c7d7242cff31742e8cc1a79a76116e50f6cb896
+  metadata.gz: 51df9fa26245d233eebbbf193729618ee8c0f8cc7aa6c680d1a2daac97b9a19e
+  data.tar.gz: b3b898d71781a538ee1826c64294018494e4824a0971768adadcb516be2dd2df
 SHA512:
-  metadata.gz: b044250b38fc6680fc5afa90f33dfc1082cb4ca7ec5916339e8e2a1f0b5ff64a32229968c24eeec19ec706a4341c413cc0d3546f7edee8dd9dd4ffd807427056
-  data.tar.gz: 8b98f315be3dd31d80f77d85eeddd66ab434af8077d04358928c7be3793e7ad0565d37c9042666a93810694688a45e7147b9a540ae0505b061b34b77a58cf991
+  metadata.gz: a5304f933ec4c0b4e97ca263c2c6833a380dd99ae3beca60e00709c71dbe921024e9572bf1a2ba38e69729d8c8d7728c6d1ab2d3e854cdbfc720c8c494fb59fc
+  data.tar.gz: c79eac91747d34080ae55326d41005e0a71e2ab940abbb858f35e6601797e6ea923f0e4a21bf718456a0a3a6688a05c833ec41e5717d03bd6fcf4eaff2aa554b

data/README.md

@@ -1,6 +1,6 @@
 # ActionMCP
 
-**ActionMCP** is a Ruby gem that provides essential tooling for building Model Context Protocol (MCP) capable servers. 
+**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. 
 
@@ -12,7 +12,7 @@ With ActionMCP, you can focus on your app's logic while it handles the boilerpla
 
 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)). 
+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.
 
@@ -30,63 +30,82 @@ In short, ActionMCP helps you build an MCP server (the component that exposes ca
 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:
-  ```
+
+  ```bash
   $ 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:
+
+Note that ActionMCP requires a Rails application; it is not meant for standalone Ruby apps.
 
 ### Configuration
-ActionMCP is configured via config.action_mcp in your Rails application. 
-By default, the name is set to your application's name and the version defaults to "0.0.1". 
-You can override these settings in your configuration (e.g., in config/application.rb):
+
+ActionMCP is configured via `config.action_mcp` in your Rails application. 
+
+By default, the name is set to your application's name and the version defaults to "0.0.1" unless your app has a version file.
+
+You can override these settings in your configuration (e.g., in `config/application.rb`):
+
 ```ruby
 module Tron
   class Application < Rails::Application
     config.action_mcp.name = "Friendly MCP (Master Control Program)"  # defaults to Rails.application.name
-    config.action_mcp.version = "1.2.3"                 # defaults to "0.0.1"
-    config.action_mcp.logging_enabled = true            # defaults to true
+    config.action_mcp.version = "1.2.3"                               # defaults to "0.0.1"
+    config.action_mcp.logging_enabled = true                          # defaults to true
+    config.action_mcp.logging_level = :info                           # defaults to :info, can be :debug, :info, :warn, :error, :fatal
   end
 end
 ```
-For dynamic versioning, consider adding the rails_app_version gem.
 
-## Generators
+For dynamic versioning, consider adding the `rails_app_version` gem.
+
+### Engine
+
+ActionMCP is implemented as a Rails engine, which means it can be mounted in your application's routes.
+The engine provides no authentication or authorization by default, so you'll need to handle that in your application for now.
+
+To mount the ActionMCP engine in your routes, add the following line to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount ActionMCP::Engine => "/action_mcp"
+end
+```
+
+### Generators
 
-ActionMCP includes Rails generators to help you quickly set up your MCP server components. You can generate the base classes for your MCP Prompt and Tool using the following commands.
+ActionMCP includes Rails generators to help you quickly set up your MCP server components. 
 
-To generate both the ApplicationPrompt and ApplicationTool files in your application, run:
+You can generate the base classes for your MCP Prompt and Tool using the following command:
 
 ```bash
 bin/rails generate action_mcp:install 
 ```
 
 This command will create:
-•	app/prompts/application_prompt.rb
-•	app/tools/application_tool.rb
+- `app/prompts/application_prompt.rb`
+- `app/tools/application_tool.rb`
 
-### Generate a New Prompt
+#### Generate a New Prompt
 
 Run the following command to generate a new prompt class:
 
 ```bash
 bin/rails generate action_mcp:prompt AnalyzeCode
 ```
-This command will create a file at app/prompts/analyze_code_prompt.rb with content similar to:
+
+This command will create a file at `app/prompts/analyze_code_prompt.rb` with content similar to:
 
 ```ruby
 class AnalyzeCodePrompt < ApplicationPrompt
-  # Override the prompt_name (otherwise we'd get "analyze-code")
+  # Override the prompt_name (otherwise we'd get "analyze_code")
   prompt_name "analyze-code"
 
   # Provide a user-facing description for your prompt.
@@ -96,38 +115,122 @@ class AnalyzeCodePrompt < ApplicationPrompt
   argument :language, description: "Programming language", default: "Ruby"
   argument :code, description: "Code to explain", required: true
 
-  # Add validations (note: "Ruby" is not allowed per the validation)
-  validates :language, inclusion: { in: %w[C Cobol FORTRAN] }
+  # Add validations
+  validates :language, inclusion: { in: %w[Ruby C Cobol FORTRAN] }
+  
+  def call
+    # Implement your prompt logic here
+    render_text("Analyzing #{language} code: #{code}")
+  end
 end
 ```
 
-## Generate a New Tool
+#### Generate a New Tool
+
 Similarly, run the following command to generate a new tool class:
 
 ```bash
 bin/rails generate action_mcp:tool CalculateSum
 ```
 
-This command will create a file at app/tools/calculate_sum_tool.rb with content similar to:
+This command will create a file at `app/tools/calculate_sum_tool.rb` with content similar to:
 
 ```ruby
 class CalculateSumTool < ApplicationTool
-  tool_name "calculate-sum"
+  tool_name "calculate_sum"
   description "Calculate the sum of two numbers"
 
   property :a, type: "number", description: "First number", required: true
   property :b, type: "number", description: "Second number", required: true
+  
+  def call
+    render_text(a + b)
+  end
 end
 ```
 
 ### ActionMCP::Prompt
 
-Make Rails Say Sexy stuff 
+A **Prompt** defines a question or request that an LLM can make to your application. It encapsulates the input parameters required for the request and any validations that need to be performed. For example, you might define a prompt called "analyze-code" that takes a code snippet as input and returns an analysis of the code.
 
 ### ActionMCP::Tool
 
-Make Rails Do Sexy stuff and serve beer to Clients.
+A **Tool** defines an action that your application can perform on behalf of an LLM. It encapsulates the input parameters required for the action and any logic that needs to be executed. For example, you might define a tool called "execute-command" that takes a shell command as input and executes it on the server, returning the output. This could be used to retrieve system information, run scripts, or perform other administrative tasks.
 
 ### ActionMCP::Resource
 
-I dont need this for now
+*I don't need this for now.*
+
+## Usage Example
+
+Both Tool and Prompt classes are based on ActiveModel, which means they share the same initialization and validation behavior. You can instantiate them with initial values, update their attributes later if necessary, and then call the `call` method to execute the logic defined in your class.
+
+### Example for a Prompt
+
+```ruby
+# Instantiate the prompt with initial values
+analyze_prompt = AnalyzeCodePrompt.new(language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
+
+# Optionally update attributes later:
+analyze_prompt.code = "def goodbye; puts 'Goodbye!'; end"
+
+# Validate the prompt before calling it
+if analyze_prompt.valid?
+  result = analyze_prompt.call # => #<ActionMCP::Content::Text:0x00000001239398c8 @text="The code you provided is written in Ruby and looks great!", @type="text">
+  puts result.to_h  # => {type: "text", text: "The code you provided is written in Ruby and looks great!"}
+else
+  puts analyze_prompt.errors.full_messages
+end
+```
+
+### Example for a Tool
+
+```ruby
+# Instantiate the tool with initial values
+sum_tool = CalculateSumTool.new(a: 5, b: 10)
+
+# Optionally update attributes later:
+sum_tool.a = 15
+sum_tool.b = 20
+
+# Validate the tool before calling it
+if sum_tool.valid?
+  result = sum_tool.call # => #<ActionMCP::Content::Text:0x0000000124cfaba0 @text="35.0", @type="text">
+  puts result.to_h  # => {type: "text", text: "35.0"}
+else
+  puts sum_tool.errors.full_messages
+end
+```
+
+These examples show that both prompts and tools follow a consistent pattern for initialization, validation, and execution, making it easy to integrate them into your application logic.
+
+## Examples & Important Notes
+
+- **Running the Dummy App:**
+  After creating the database with `bin/rails db:prepare`, you can run the dummy application using:
+  ```bash
+  bin/rails s
+  ```
+  This allows you to test and interact with the MCP server from the dummy environment. 
+- **Inspecting the App:**
+  You can use the mcp inspector to test your app ```npx @modelcontextprotocol/inspector```
+  the path by default will be http://localhost:3000/action_mcp
+  
+
+- **Postgres on macOS:**
+  If you are using Postgres on macOS, you may encounter issues due to a bug in Puma and the `pg` gem. To work around this, set the following environment variables:
+  ```bash
+  export PGGSSENCMODE=disable
+  export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
+  ```
+  More details can be found in [Rails Issue #38560](https://github.com/rails/rails/issues/38560).
+
+- **Notifiers:**
+  ActionMCP works with the ActiveCable Postgres notifier by default, but its architecture is flexible enough to support other notifier implementations.
+
+- **API Stability:**
+  The ActionMCP API is stable, though it is acceptable for improvements and changes to be introduced as we move forward. This approach ensures the gem stays modern and adaptable to evolving requirements.
+
+## Conclusion
+
+ActionMCP empowers developers to build MCP-compliant servers efficiently by handling the standardization and boilerplate associated with integrating with LLMs. With built-in generators, clear configuration options, robust usage examples, and important deployment considerations, it is designed to accelerate development and integration work while remaining flexible for future enhancements.

data/Rakefile

@@ -4,6 +4,4 @@ require 'bundler/setup'
 
 APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
 
-load 'rails/tasks/statistics.rake'
-
 require 'bundler/gem_tasks'

data/exe/actionmcp_cli

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup' # Ensure correct gem dependencies
+require 'optparse'
+require 'multi_json'
+require 'actionmcp'
+require 'action_mcp/client'
+require 'securerandom'
+require 'logger'
+
+# Default options
+options = {
+  logging_level: "INFO",
+  auto_initialize: true
+}
+
+# Set up logger
+logger = Logger.new(STDOUT)
+logger.formatter = proc do |severity, _, _, msg|
+  "#{severity}: #{msg}\n"
+end
+
+# Parse command-line arguments
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: mcp_client ENDPOINT [options]"
+  opts.on("-l", "--log-level LEVEL", "Set log level (DEBUG, INFO, WARN, ERROR)") do |l|
+    options[:logging_level] = l.upcase
+    logger.level = Logger.const_get(l.upcase) rescue Logger::INFO
+  end
+  opts.on("--no-auto-init", "Don't automatically initialize the connection") do
+    options[:auto_initialize] = false
+  end
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    exit
+  end
+end
+
+# Extract first argument as endpoint
+endpoint = ARGV.shift
+
+# Parse remaining options
+parser.parse!(ARGV)
+
+if endpoint.nil?
+  puts "Error: You must provide an MCP endpoint."
+  puts parser
+  exit 1
+end
+
+# Function to generate a unique request ID
+def generate_request_id
+  SecureRandom.uuid
+end
+
+# Function to parse command shortcuts and return a Request object
+def parse_command(input)
+  parts = input.strip.split(/\s+/)
+  command = parts.shift
+
+  case command
+  when "call_tool"
+    tool_name = parts.shift
+    return nil unless tool_name
+
+    arguments = {}
+    parts.each do |arg|
+      key, value = arg.split(":", 2)
+      next unless value
+
+      # Try to convert the value to appropriate type
+      parsed_value = case value
+      when /^\d+$/
+                       value.to_i
+      when /^\d+\.\d+$/
+                       value.to_f
+      when "true"
+                       true
+      when "false"
+                       false
+      when "null"
+                       nil
+      else
+                       value
+      end
+
+      arguments[key] = parsed_value
+    end
+
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "tools/get",
+      params: {
+        "name" => tool_name,
+        "arguments" => arguments
+      }
+    )
+  when "list_tools"
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "tools/list"
+    )
+  when "list_prompts"
+    ActionMCP::JsonRpc::Request.new(
+      id: generate_request_id,
+      method: "prompts/list"
+    )
+  else
+    nil
+  end
+end
+
+# Help message for shortcuts
+def print_help
+  puts "Available shortcuts:"
+  puts "  list_tools"
+  puts "    - Get a list of available tools"
+  puts "  call_tool TOOL_NAME PARAM1:VALUE1 PARAM2:VALUE2 ..."
+  puts "    - Sends a tools/get request with the specified tool and parameters"
+  puts "  list_prompts"
+  puts "    - Get a list of available prompts"
+  puts "  get_prompt PROMPT_NAME PARAM1:VALUE1 PARAM2:VALUE2 ..."
+  puts "    - Sends a prompts/get request with the specified prompt and arguments"
+  puts "  help - Show this help message"
+  puts "  exit - Quit the client"
+  puts "Otherwise, enter a raw JSON-RPC request to send directly"
+end
+
+# Initialize and start the client
+client = ActionMCP.create_client(endpoint, logger: logger)
+
+# Start the transport
+unless client.connect
+  error_msg = client.connection_error || "Unknown connection error"
+  puts "\nERROR: Failed to connect to MCP server at #{endpoint}"
+  puts "Reason: #{error_msg}"
+  puts "\nPlease check that:"
+  puts "  1. The server is running"
+  puts "  2. The endpoint URL/address is correct"
+  puts "  3. Any required firewall ports are open"
+
+  if endpoint =~ /\Ahttps?:\/\//
+    puts "  4. The URL includes the correct protocol, host, and port"
+    puts "     For example: http://localhost:3000/action_mcp"
+  end
+
+  exit 1
+end
+
+Signal.trap("INT") do
+  puts "\nReceived Ctrl+C. Disconnecting..."
+  client.disconnect
+  puts "MCP Client stopped."
+  exit 0
+end
+
+# Main REPL loop
+loop do
+  print "mcp> "
+  input = gets&.chomp
+  break unless input # Handle EOF
+  next if input.empty?
+
+  case input.downcase
+  when "exit"
+    break
+  when "help"
+    print_help
+    next
+  else
+    begin
+      # Check if input is a command shortcut
+      if input.start_with?("call_tool")
+        request = parse_command(input)
+        logger.debug("Parsed shortcut to: #{request.to_h}") if request
+      elsif input.start_with?("connect") || input.start_with?("initialize")
+        request = parse_command(input)
+        logger.debug("Initializing connection with: #{request.to_h}") if request
+      elsif input.start_with?("list_tools") || input.start_with?("list_prompts")
+        request = parse_command(input)
+        logger.debug("Requesting tool list: #{request.to_h}") if request
+      else
+        # Try parsing as JSON and creating a Request object
+        begin
+          json = MultiJson.load(input)
+          # Validate that the parsed JSON has the required fields
+          if json["method"]
+            request = ActionMCP::JsonRpc::Request.new(
+              id: json["id"] || generate_request_id,
+              method: json["method"],
+              params: json["params"]
+            )
+          else
+            puts "Invalid JSON-RPC request: missing 'method' field"
+            next
+          end
+        rescue MultiJson::ParseError => e
+          puts "Invalid input: not a valid command or JSON. #{e.message}"
+          next
+        rescue ActionMCP::JsonRpc::JsonRpcError => e
+          puts "Invalid JSON-RPC request: #{e.message}"
+          next
+        end
+      end
+
+      if request
+        client.send_request(request.to_h)
+      else
+        puts "Invalid command format. Type 'help' for available commands."
+      end
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      puts e.backtrace.first(5) if logger.level == Logger::DEBUG
+    end
+  end
+end
+
+puts "Disconnecting..."
+client.disconnect
+puts "MCP Client stopped."

data/lib/action_mcp/capability.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "renderable"
+
+module ActionMCP
+  class Capability
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include Renderable
+
+    class_attribute :_capability_name, instance_accessor: false
+    class_attribute :_description, instance_accessor: false, default: ""
+    class_attribute :abstract_tool, instance_accessor: false, default: false
+
+    # use _capability_name or default_capability_name
+    def self.capability_name
+      _capability_name || default_capability_name
+    end
+
+    def self.abstract_capability
+      @abstract_tool ||= false # Default to false, unique to each class
+    end
+
+    def self.abstract_capability=(value)
+      @abstract_tool = value
+    end
+
+    # Marks this tool as abstract so that it won’t be available for use.
+    # If the tool is registered in ToolsRegistry, it is unregistered.
+    #
+    # @return [void]
+    def self.abstract!
+      self.abstract_capability = true
+    end
+
+    # Returns whether this tool is abstract.
+    #
+    # @return [Boolean] true if abstract, false otherwise.
+    def self.abstract?
+      abstract_capability
+    end
+
+
+    def self.description(text = nil)
+      if text
+        self._description = text
+      else
+        _description
+      end
+    end
+  end
+end