actionmcp 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a853f65451f67bb2da8d67e317ed0554d832ecb0660b8adbe9d002c949792d43
-  data.tar.gz: 23212ca96b1538d71ed309a2e1f6b3e5143917ff117827b46306d4384ca0b0f0
+  metadata.gz: 6794bfeea02de8502aa4b084548a93269149b9376117663d602ecfae54af8014
+  data.tar.gz: 49bca81dc1f59d27fc8d27c1b8978a8def6d3414822f261ce1aee2a4ebfc45b0
 SHA512:
-  metadata.gz: e4701665f0d8912fe33213d17e0e3d69ff01cc3adac1d69d9d461963c366fca879d09b9be06a2bdfb6579e8bdbcb842eb349bcde45f53316162a58be382f62cb
-  data.tar.gz: 59dfe42ba51f7bae693bbcee84833961eb3f1ea1312e046d105760328a2459842968d85e67289a411c57ddbc9d0bad54aef59ea54e37053fa5bb26360b3c4384
+  metadata.gz: 3f94f11e49df2549d1e43c4499f7fedfc9f7000279f6b08d2eb3ffb9e32add617a14277869fa3b34a31bde7aa2e6e66674f2e7b49cd57f5606daebbd060097f7
+  data.tar.gz: 9ce4b731e107c76a1e057ea4ce33a90998d1d5700946f8e056eea3763535e12ca941ba875324914c910d375bbac04c12f4c0da25255d2d7cf5e746b9bd1fa19c

data/README.md

@@ -1,27 +1,27 @@
 # 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 in Ruby on Rails applications.
 
-It offers base classes and helpers for creating MCP applications, making it easier to integrate your Ruby/Rails application with the MCP standard. 
+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)). 
+**Model Context Protocol (MCP)** is an open protocol that standardizes how applications provide context to large language models (LLMs).
 
-Think of it as a universal interface for connecting AI assistants to external data sources and tools. 
+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.
 
 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. 
+**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. 
+Instead of implementing MCP support from scratch, you can subclass and configure the provided **Prompt**, **Tool**, and **ResourceTemplate** 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. 
+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.
 
@@ -39,193 +39,202 @@ This will load the ActionMCP library so you can start defining MCP prompts, tool
 
 ## Core Components
 
-ActionMCP provides three core abstractions to streamline MCP server development: **Prompt**, **Tool**, and **Resource**. 
+ActionMCP provides three core abstractions to streamline MCP server development:
 
-These correspond to key MCP concepts and let you define what context or capabilities your server exposes to LLMs. 
+### ActionMCP::Prompt
 
-Note that ActionMCP requires a Rails application; it is not meant for standalone Ruby apps.
+`ActionMCP::Prompt` enables you to create reusable prompt templates that can be discovered and used by LLMs. Each prompt is defined as a Ruby class that inherits from `ApplicationMCPPrompt`.
 
-### Configuration
+Key features:
+- Define expected arguments with descriptions and validation rules
+- Build multi-step conversations with mixed content types
+- Support for text, images, audio, and resource attachments
+- Add messages with different roles (user/assistant)
 
-ActionMCP is configured via `config.action_mcp` in your Rails application. 
+**Example:**
 
-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.
+```ruby
+class AnalyzeCodePrompt < ApplicationMCPPrompt
+  prompt_name "analyze_code"
+  description "Analyze code for potential improvements"
 
-You can override these settings in your configuration (e.g., in `config/application.rb`):
+  argument :language, description: "Programming language", default: "Ruby"
+  argument :code, description: "Code to explain", required: true
 
-```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.logging_level = :info                           # defaults to :info, can be :debug, :info, :warn, :error, :fatal
+  validates :language, inclusion: { in: %w[Ruby Python JavaScript] }
+
+  def perform
+    render(text: "Please analyze this #{language} code for improvements:")
+    render(text: code)
+    
+    # You can add assistant messages too
+    render(text: "Here are some things to focus on in your analysis:", role: :assistant)
+    
+    # Even add resources if needed
+    render(resource: "file://documentation/#{language.downcase}_style_guide.pdf", 
+           mime_type: "application/pdf", 
+           blob: get_style_guide_pdf(language))
+  end
+  
+  private
+  
+  def get_style_guide_pdf(language)
+    # Implementation to retrieve style guide as base64
   end
 end
 ```
 
-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`:
+Prompts can be executed by instantiating them and calling the `call` method:
 
 ```ruby
-Rails.application.routes.draw do
-  mount ActionMCP::Engine => "/action_mcp"
-end
+analyze_prompt = AnalyzeCodePrompt.new(language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
+result = analyze_prompt.call
 ```
 
-### Generators
+### ActionMCP::Tool
 
-ActionMCP includes Rails generators to help you quickly set up your MCP server components. 
+`ActionMCP::Tool` allows you to create interactive functions that LLMs can call with arguments to perform specific tasks. Each tool is a Ruby class that inherits from `ApplicationMCPTool`.
 
-You can generate the base classes for your MCP Prompt and Tool using the following command:
+Key features:
+- Define input properties with types, descriptions, and validation
+- Return multiple response types (text, images, errors)
+- Progressive responses with multiple render calls
+- Automatic input validation based on property definitions
 
-```bash
-bin/rails action_mcp:install:migrations  # to copy the migrations
-bin/rails generate action_mcp:install 
-```
+**Example:**
 
-This command will create:
-- `app/mcp/prompts/application_prompt.rb`
-- `app/mcp/tools/application_tool.rb`
+```ruby
+class CalculateSumTool < ApplicationMCPTool
+  tool_name "calculate_sum"
+  description "Calculate the sum of two numbers"
 
-#### Generate a New Prompt
+  property :a, type: "number", description: "First number", required: true
+  property :b, type: "number", description: "Second number", required: true
+  
+  def perform
+    sum = a + b
+    render(text: "Calculating #{a} + #{b}...")
+    render(text: "The sum is #{sum}")
+    
+    # You can render errors if needed
+    if sum > 1000
+      render(error: ["Warning: Sum exceeds recommended limit"])
+    end
+    
+    # Or even images
+    render(image: generate_visualization(a, b), mime_type: "image/png")
+  end
+  
+  private
+  
+  def generate_visualization(a, b)
+    # Implementation to create a visualization as base64
+  end
+end
+```
 
-Run the following command to generate a new prompt class:
+Tools can be executed by instantiating them and calling the `call` method:
 
-```bash
-bin/rails generate action_mcp:prompt AnalyzeCode
+```ruby
+sum_tool = CalculateSumTool.new(a: 5, b: 10)
+result = sum_tool.call
 ```
 
-This command will create a file at `app/mcp/prompts/analyze_code_prompt.rb` with content similar to:
+### ActionMCP::ResourceTemplate
 
-```ruby
+`ActionMCP::ResourceTemplate` facilitates the creation of URI templates for dynamic resources that LLMs can access. 
+This allows models to request specific data using parameterized URIs.
 
-class AnalyzeCodePrompt < ApplicationMCPPrompt
-  # Override the prompt_name (otherwise we'd get "analyze_code")
-  prompt_name "analyze-code"
+**Example:**
 
-  # Provide a user-facing description for your prompt.
-  description "Analyze code for potential improvements"
+```ruby
 
-  # Configure arguments via the new DSL
-  argument :language, description: "Programming language", default: "Ruby"
-  argument :code, description: "Code to explain", required: true
+class ProductResourceTemplate < ApplicationMCPResTemplate
+  uri_template "product/{id}"
+  description "Access product information by ID"
 
-  # Add validations
-  validates :language, inclusion: { in: %w[Ruby C Cobol FORTRAN] }
+  parameter :id, description: "Product identifier", required: true
 
-  def perform
-    # Implement your prompt logic here
-    render(text: "Analyzing #{language} code: #{code}")
+  validates :id, format: { with: /\A\d+\z/, message: "must be numeric" }
+
+  def resolve
+    product = Product.find_by(id: id)
+    return unless product
+    ActionMCP::Resource.new(
+      uri: "ecommerce://products/#{product_id}",
+      name: "Product #{product_id}",
+      description: "Product information for product #{product_id}",
+      mime_type: "application/json",
+      size: product.to_json.length
+    )
   end
 end
 ```
 
-#### Generate a New Tool
+Resource templates are automatically registered and used when LLMs request resources matching their patterns.
 
-Similarly, run the following command to generate a new tool class:
+## Configuration
 
-```bash
-bin/rails generate action_mcp:tool CalculateSum
-```
+ActionMCP is configured via `config.action_mcp` in your Rails application.
 
-This command will create a file at `app/mcp/tools/calculate_sum_tool.rb` with content similar to:
+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.
 
-```ruby
-class CalculateSumTool < ApplicationMCPTool
-  tool_name "calculate_sum"
-  description "Calculate the sum of two numbers"
+You can override these settings in your configuration (e.g., in `config/application.rb`):
 
-  property :a, type: "number", description: "First number", required: true
-  property :b, type: "number", description: "Second number", required: true
-  
-  def perform
-    render(text: a + b)
+```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.logging_level = :info                           # defaults to :info, can be :debug, :info, :warn, :error, :fatal
   end
 end
 ```
 
-### ActionMCP::Prompt
-
-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
-
-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 don't need this for now.*
+For dynamic versioning, consider adding the `rails_app_version` gem.
 
-## Usage Example
+## Engine and Mounting
 
-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.
+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.
 
-### Example for a Prompt
+To mount the ActionMCP engine in your routes, add the following line to your `config/routes.rb`:
 
 ```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"
-
-result = analyze_prompt.call #=> #<ActionMCP::PromptResponse messages: [{role: "user", content: {type: "text", text: "The code you provided is written in Ruby and looks great!"}}]>
-puts result.to_h #=> {messages: [{role: "user", content: {type: "text", text: "The code you provided is written in Ruby and looks great!"}}]}
+Rails.application.routes.draw do
+  mount ActionMCP::Engine => "/action_mcp"
+end
 ```
 
-### Example for a Tool
+## Generators
 
-```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
+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 command:
 
-# Validate the tool before calling it
-result = sum_tool.call # => #<ActionMCP::ToolResponse content: [#<ActionMCP::Content::Text:0x000000012bb50f78 @type="text", @text="35.0">], isError: false>
-puts result.to_h  # => {content: [{type: "text", text: "35.0"}]}
+```bash
+bin/rails action_mcp:install:migrations  # to copy the migrations
+bin/rails generate action_mcp:install 
 ```
 
-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.
+This will create the base application classes in your app directory.
 
-## Examples & Important Notes
+### Generate a New Prompt
 
-- **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).
+```bash
+bin/rails generate action_mcp:prompt AnalyzeCode
+```
 
-- **Notifiers:**
-  ActionMCP works with the ActiveCable Postgres notifier by default, but its architecture is flexible enough to support other notifier implementations.
+### Generate a New Tool
 
-- **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.
+```bash
+bin/rails generate action_mcp:tool CalculateSum
+```
 
-## Testing with the TestHelper
+## Testing with TestHelper
 
-ActionMCP provides a `TestHelper` module to simplify testing of tools and prompts. To use the `TestHelper`, include it in your test class:
+ActionMCP provides a `TestHelper` module to simplify testing of tools and prompts:
 
 ```ruby
 require "test_helper"
@@ -248,21 +257,16 @@ class ToolTest < ActiveSupport::TestCase
 end
 ```
 
-The `TestHelper` module provides the following methods:
+## Inspecting Your MCP Server
 
-*   `assert_tool_findable(tool_name)`: Asserts that a tool is findable in the `ToolsRegistry`.
-*   `assert_prompt_findable(prompt_name)`: Asserts that a prompt is findable in the `PromptsRegistry`.
-*   `execute_tool(tool_name, args = {})`: Executes a tool with the given name and arguments.
-*   `execute_prompt(prompt_name, args = {})`: Executes a prompt with the given name and arguments.
-*   `assert_tool_output(expected_output, result)`: Asserts that the output of a tool is equal to the expected output.
-*   `assert_prompt_output(expected_output, result)`: Asserts that the output of a prompt is equal to the expected output.
+You can use the MCP Inspector to test your server implementation:
 
-To use the `TestHelper`, you need to require it in your `test_helper.rb` file:
-
-```ruby
-require "action_mcp/test_helper"
+```bash
+npx @modelcontextprotocol/inspector
 ```
 
+The default path will be http://localhost:3000/action_mcp
+
 ## 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, important deployment considerations, and a helpful testing module, it is designed to accelerate development and integration work while remaining flexible for future enhancements.
+ActionMCP empowers developers to build MCP-compliant servers efficiently by handling the standardization and boilerplate associated with integrating with LLMs. With its intuitive abstractions for tools, prompts, and resource templates, you can quickly expose your application's capabilities to AI models while maintaining full control over how they interact with your system.

data/Rakefile

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

data/app/controllers/action_mcp/{application_controller.rb → mcp_controller.rb}

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module ActionMCP
-  class ApplicationController < ActionController::Metal
+  class MCPController < ActionController::Metal
     abstract!
     ActionController::API.without_modules(:StrongParameters, :ParamsWrapper).each do |left|
       include left

data/app/controllers/action_mcp/messages_controller.rb

@@ -1,10 +1,14 @@
+# frozen_string_literal: true
+
 module ActionMCP
-  class MessagesController < ApplicationController
+  class MessagesController < MCPController
+    include Instrumentation::ControllerRuntime
+
     # @route POST / (sse_in)
     def create
       begin
         handle_post_message(clean_params, response)
-      rescue => e
+      rescue StandardError
         head :internal_server_error
       end
       head response.status
@@ -21,9 +25,7 @@ module ActionMCP
     end
 
     def handle_post_message(params, response)
-      if params[:method] == "initialize"
-        mcp_session.initialize!
-      end
+      mcp_session.initialize! if params[:method] == "initialize"
       json_rpc_handler.call(params)
 
       response.status = :accepted

data/app/controllers/action_mcp/sse_controller.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module ActionMCP
-  class SSEController < ApplicationController
+  class SSEController < MCPController
     HEARTBEAT_INTERVAL = 30 # TODO: The frequency of pings SHOULD be configurable
     include ActionController::Live
 
@@ -26,14 +28,17 @@ module ActionMCP
           sse.write(message)
           message_received = true
         end
-        sleep 1
-        # Heartbeat loop
-        unless message_received
-          Rails.logger.warn "No message received within 1 second, closing connection for session: #{session_id}"
-          error = JsonRpc::Response.new(id: SecureRandom.uuid_v7, error: JsonRpc::JsonRpcError.new(:server_error, message: "No message received within 1 second").to_h).to_h
-          sse.write(error)
-          return
-        end
+          sleep 1
+          # Heartbeat loop
+          unless message_received
+            Rails.logger.warn "No message received within 1 second, closing connection for session: #{session_id}"
+            error = JsonRpc::Response.new(id: SecureRandom.uuid_v7,
+                                          error: JsonRpc::JsonRpcError.new(
+                                            :server_error, message: "No message received within 1 second"
+                                          ).to_h).to_h
+            sse.write(error)
+            return
+          end
 
           until response.stream.closed?
             sleep HEARTBEAT_INTERVAL
@@ -45,7 +50,7 @@ module ActionMCP
         end
       rescue ActionController::Live::ClientDisconnected, IOError => e
         Rails.logger.debug "SSE: Expected disconnection: #{e.message}"
-      rescue => e
+      rescue StandardError => e
         Rails.logger.error "SSE: Unexpected error: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
       ensure
         response.stream.close
@@ -82,6 +87,7 @@ module ActionMCP
 
   class SSEListener
     attr_reader :session_key, :adapter
+
     delegate :session_key, :adapter, to: :@session
 
     # @param session [ActionMCP::Session]
@@ -94,19 +100,19 @@ module ActionMCP
     def start(&callback)
       Rails.logger.debug "Starting listener for channel: #{session_key}"
 
-      success_callback = -> {
+      success_callback = lambda {
         puts "Successfully subscribed to channel: #{session_key}"
         @subscription_active = true
       }
 
       # Set up message callback
-      message_callback = ->(raw_message) {
+      message_callback = lambda { |raw_message|
         begin
           # Try to parse the message if it's JSON
           message = MultiJson.load(raw_message)
           # Send the message to the callback
           callback.call(message) if callback && !@stopped
-        rescue => e
+        rescue StandardError
           # Still try to send the raw message as a fallback
           callback.call(raw_message) if callback && !@stopped
         end