actionmcp 0.14.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a853f65451f67bb2da8d67e317ed0554d832ecb0660b8adbe9d002c949792d43
-  data.tar.gz: 23212ca96b1538d71ed309a2e1f6b3e5143917ff117827b46306d4384ca0b0f0
+  metadata.gz: e33a00e3a56b0dba226465afd8ce6695158400bb5a26876fa92f72cea65a5418
+  data.tar.gz: 9243f9316686638c66f716d333803db0b8ad0e32d052728b1ca1e1dc5eda21cb
 SHA512:
-  metadata.gz: e4701665f0d8912fe33213d17e0e3d69ff01cc3adac1d69d9d461963c366fca879d09b9be06a2bdfb6579e8bdbcb842eb349bcde45f53316162a58be382f62cb
-  data.tar.gz: 59dfe42ba51f7bae693bbcee84833961eb3f1ea1312e046d105760328a2459842968d85e67289a411c57ddbc9d0bad54aef59ea54e37053fa5bb26360b3c4384
+  metadata.gz: d0bdf008e20cbe4bc36d4a295201eb16570fd5e5dc83c24fef759daac1c622c6b58ce16f671db06d326714587e7ecca1b22234829d9c59ea40759b9c78b8e976
+  data.tar.gz: 948bf31356b50d4004093890ca8a336a1e3eb41a85ce95d46e01a41f1a1823f0a2ff20fd849ab2eccda1b7569db9573ab0c84911ea263c2db0b85f2f20c07cdc

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,228 @@ 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::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`.
 
-ActionMCP includes Rails generators to help you quickly set up your MCP server components. 
+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
 
-You can generate the base classes for your MCP Prompt and Tool using the following command:
+**Example:**
 
-```bash
-bin/rails action_mcp:install:migrations  # to copy the migrations
-bin/rails generate action_mcp:install 
+```ruby
+class CalculateSumTool < ApplicationMCPTool
+  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 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
 ```
 
-This command will create:
-- `app/mcp/prompts/application_prompt.rb`
-- `app/mcp/tools/application_tool.rb`
+Tools can be executed by instantiating them and calling the `call` method:
 
-#### Generate a New Prompt
+```ruby
+sum_tool = CalculateSumTool.new(a: 5, b: 10)
+result = sum_tool.call
+```
 
-Run the following command to generate a new prompt class:
+### ActionMCP::ResourceTemplate
 
-```bash
-bin/rails generate action_mcp:prompt AnalyzeCode
-```
+`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.
 
-This command will create a file at `app/mcp/prompts/analyze_code_prompt.rb` with content similar to:
+**Example:**
 
 ```ruby
 
-class AnalyzeCodePrompt < ApplicationMCPPrompt
-  # Override the prompt_name (otherwise we'd get "analyze_code")
-  prompt_name "analyze-code"
-
-  # Provide a user-facing description for your prompt.
-  description "Analyze code for potential improvements"
+class ProductResourceTemplate < ApplicationMCPResTemplate
+  uri_template "product/{id}"
+  description "Access product information by ID"
 
-  # Configure arguments via the new DSL
-  argument :language, description: "Programming language", default: "Ruby"
-  argument :code, description: "Code to explain", required: true
+  parameter :id, description: "Product identifier", required: true
 
-  # Add validations
-  validates :language, inclusion: { in: %w[Ruby C Cobol FORTRAN] }
+  validates :id, format: { with: /\A\d+\z/, message: "must be numeric" }
 
-  def perform
-    # Implement your prompt logic here
-    render(text: "Analyzing #{language} code: #{code}")
+  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
+# Example of callbacks:
 
-Similarly, run the following command to generate a new tool class:
+```ruby
+before_resolve do |template|
+  logger.tagged("ProductsTemplate") { logger.info("Starting to resolve product: #{template.product_id}") }
+end
 
-```bash
-bin/rails generate action_mcp:tool CalculateSum
-```
+after_resolve do |template|
+  logger.tagged("ProductsTemplate") { logger.info("Finished resolving product resource for product: #{template.product_id}") }
+end
 
-This command will create a file at `app/mcp/tools/calculate_sum_tool.rb` with content similar to:
+around_resolve do |template, block|
+  start_time = Time.current
+  logger.tagged("ProductsTemplate") { logger.info("Starting resolution for product: #{template.product_id}") }
 
-```ruby
-class CalculateSumTool < ApplicationMCPTool
-  tool_name "calculate_sum"
-  description "Calculate the sum of two numbers"
+  resource = block.call
 
-  property :a, type: "number", description: "First number", required: true
-  property :b, type: "number", description: "Second number", required: true
-  
-  def perform
-    render(text: a + b)
+  if resource
+    logger.tagged("ProductsTemplate") { logger.info("Product #{template.product_id} resolved successfully in #{Time.current - start_time}s") }
+  else
+    logger.tagged("ProductsTemplate") { logger.info("Product #{template.product_id} not found") }
   end
+
+  resource
 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.
+Resource templates are automatically registered and used when LLMs request resources matching their patterns.
 
-### ActionMCP::Tool
+## Configuration
 
-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 is configured via `config.action_mcp` in your Rails application.
 
-### ActionMCP::Resource
+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.
 
-*I don't need this for now.*
+You can override these settings in your configuration (e.g., in `config/application.rb`):
 
-## Usage Example
+```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
+```
 
-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.
+For dynamic versioning, consider adding the `rails_app_version` gem.
 
-### Example for a Prompt
+## Engine and Mounting
 
-```ruby
-# Instantiate the prompt with initial values
-analyze_prompt = AnalyzeCodePrompt.new(language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
+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.
 
-# Optionally update attributes later:
-analyze_prompt.code = "def goodbye; puts 'Goodbye!'; end"
+To mount the ActionMCP engine in your routes, add the following line to your `config/routes.rb`:
 
-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!"}}]}
+```ruby
+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.
 
-# 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"}]}
-```
+You can generate the base classes for your MCP Prompt and Tool using the following command:
 
-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.
+```bash
+bin/rails action_mcp:install:migrations  # to copy the migrations
+bin/rails generate action_mcp:install 
+```
 
-## Examples & Important Notes
+This will create the base application classes in your app directory.
 
-- **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
-  
+### Generate a New Prompt
 
-- **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 +283,16 @@ class ToolTest < ActiveSupport::TestCase
 end
 ```
 
-The `TestHelper` module provides the following methods:
-
-*   `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.
+## Inspecting Your MCP Server
 
-To use the `TestHelper`, you need to require it in your `test_helper.rb` file:
+You can use the MCP Inspector to test your server implementation:
 
-```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