actionmcp 0.2.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e01fe9b15e57ab4450f9712dd2a38dbf355cbdc50d196a8026cbb205d3d8a07
-  data.tar.gz: 8ce8ffd799f5b9487c0bb3b78c7d7242cff31742e8cc1a79a76116e50f6cb896
+  metadata.gz: 0a1cd6d70ca62ff8ecf4d25c00e29d9592bc9d80ca46db50330a2f818a66ce1f
+  data.tar.gz: 259e35b08f9627aa4165157b71436f4fdd4c0c9eaedc2ae41ddb6f0bb8c3fdde
 SHA512:
-  metadata.gz: b044250b38fc6680fc5afa90f33dfc1082cb4ca7ec5916339e8e2a1f0b5ff64a32229968c24eeec19ec706a4341c413cc0d3546f7edee8dd9dd4ffd807427056
-  data.tar.gz: 8b98f315be3dd31d80f77d85eeddd66ab434af8077d04358928c7be3793e7ad0565d37c9042666a93810694688a45e7147b9a540ae0505b061b34b77a58cf991
+  metadata.gz: c213f50edbec5dc96af78b3090f562dae9fe479a405a44d573927ef65c1c042d6a43ef174297bca3bc92280a372d5a3a74c61aec5a8dfc3e1381550c56b27397
+  data.tar.gz: 343bee907d44e4e7869372b5ffa250c6d628c8789ef51a4690b311c494d6b5b20199837dbbc5f39959e36b8a71d3ce2942b82685b4076897ddc393e59e73d8e3

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/app/controllers/action_mcp/application_controller.rb

@@ -0,0 +1,13 @@
+module ActionMCP
+  class ApplicationController < ActionController::Metal
+    abstract!
+    ActionController::API.without_modules(:StrongParameters, :ParamsWrapper).each do |left|
+      include left
+    end
+    include Engine.routes.url_helpers
+
+    def session_key
+      @session_key = "action_mcp-sessions-#{session_id}"
+    end
+  end
+end

data/app/controllers/action_mcp/messages_controller.rb

@@ -0,0 +1,51 @@
+module ActionMCP
+  class MessagesController < ApplicationController
+    # @route POST / (sse_in)
+    def create
+      begin
+        handle_post_message(params, response)
+      rescue => e
+        head :internal_server_error
+      end
+      head response.status
+    end
+
+    private
+
+    def transport
+      @transport ||= Transport.new(session_key)
+    end
+
+    def transport_handler
+      TransportHandler.new(transport)
+    end
+
+    def json_rpc_handler
+      @json_rpc_handler ||= ActionMCP::JsonRpcHandler.new(transport_handler)
+    end
+
+    def handle_post_message(params, response)
+      json_rpc_handler.call(params)
+
+      response.status = :accepted
+    rescue StandardError => e
+      response.status = :bad_request
+    end
+
+    def session_id
+      params[:session_id]
+    end
+
+    class Transport
+      attr_reader :session_key, :adapter
+      def initialize(session_key)
+        @session_key = session_key
+        @adapter = ActionMCP::Server.server.pubsub
+      end
+
+      def write(data)
+        adapter.broadcast(session_key, data.to_json)
+      end
+    end
+  end
+end

data/app/controllers/action_mcp/sse_controller.rb

@@ -0,0 +1,151 @@
+module ActionMCP
+  class SSEController < ApplicationController
+    HEARTBEAT_INTERVAL = 10
+    INITIALIZATION_TIMEOUT = 2
+    include ActionController::Live
+
+    # @route GET /sse (sse_out)
+    def events
+      # Set headers first
+      response.headers["X-Accel-Buffering"] = "no"
+      response.headers["Content-Type"] = "text/event-stream"
+      response.headers["Cache-Control"] = "no-cache"
+      response.headers["Connection"] = "keep-alive"
+
+      listener = nil
+      begin
+        # Now start streaming - send endpoint
+        send_endpoint_event(sse_in_url)
+
+        # Start listener and process messages via the transport
+        listener = SseListener.new(session_key)
+        if listener.start do |message|
+          begin
+            Rails.logger.debug "Processing message in controller: #{message.inspect} (#{message.class})"
+
+            # Send with proper SSE formatting
+            sse = SSE.new(response.stream)
+            sse.write(message)
+          rescue => e
+            Rails.logger.error "Error sending SSE message: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
+          end
+        end
+
+          # Heartbeat loop
+          until response.stream.closed?
+            sleep HEARTBEAT_INTERVAL
+            send_ping!
+          end
+        else
+          Rails.logger.error "Listener failed to activate for session: #{session_id}"
+          raise "Failed to establish subscription"
+        end
+      rescue ActionController::Live::ClientDisconnected, IOError => e
+        Rails.logger.debug "SSE: Expected disconnection: #{e.message}"
+      rescue => e
+        Rails.logger.error "SSE: Unexpected error: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
+      ensure
+        listener&.stop
+        response.stream.close
+        Rails.logger.debug "SSE: Connection closed for session: #{session_id}"
+      end
+    end
+
+    private
+
+    def send_endpoint_event(messages_url)
+      endpoint = "#{messages_url}?session_id=#{session_id}"
+      SSE.new(response.stream,
+              event: "endpoint")
+         .write(endpoint)
+    end
+
+    def send_ping!
+      SSE.new(response.stream,
+              event: "ping")
+         .write(Time.now.to_i)
+    end
+
+    def default_url_options
+      { host: request.host, port: request.port }
+    end
+
+    def session_id
+      @session_id ||= SecureRandom.hex(6)
+    end
+  end
+
+  class SseListener
+    attr_reader :session_key, :adapter
+
+    def initialize(session_key)
+      @session_key = session_key
+      @adapter = ActionMCP::Server.server.pubsub
+      @stopped = false
+      @subscription_active = false
+    end
+
+    # Start listening using ActionCable's PostgreSQL adapter
+    def start(&callback)
+      Rails.logger.debug "Starting listener for channel: #{session_key}"
+
+      # Set up success callback
+      success_callback = -> {
+        Rails.logger.debug "Successfully subscribed to channel: #{session_key}"
+        @subscription_active = true
+      }
+
+      # Set up message callback with detailed debugging
+      message_callback = ->(raw_message) {
+        Rails.logger.debug "Received raw message via adapter: #{raw_message.inspect} (#{raw_message.class})"
+
+        begin
+          # Try to parse the message if it's JSON
+          message = raw_message.is_a?(String) ? JSON.parse(raw_message) : raw_message
+          Rails.logger.debug "Processed message: #{message.inspect}"
+
+          # Send the message to the callback
+          callback.call(message) if callback && !@stopped
+        rescue => e
+          Rails.logger.error "Error processing message: #{e.class} - #{e.message}"
+          # Still try to send the raw message as a fallback
+          callback.call(raw_message) if callback && !@stopped
+        end
+      }
+
+      # Subscribe using the ActionCable adapter
+      adapter.subscribe(session_key, message_callback, success_callback)
+
+      # Give some time for the subscription to be established
+      sleep 1.5
+
+      # Check if subscription was successful
+      if @subscription_active
+        Rails.logger.debug "Subscription confirmed active for: #{session_key}"
+        true
+      else
+        Rails.logger.error "Failed to activate subscription for: #{session_key}"
+        false
+      end
+    end
+
+    def stop
+      Rails.logger.debug "Stopping listener for: #{session_key}"
+      @stopped = true
+
+      # Unsubscribe using the correct method signature
+      begin
+        # Create a dummy callback that matches the one we provided in start
+        dummy_callback = ->(_) { }
+        adapter.unsubscribe(session_key, dummy_callback)
+        Rails.logger.debug "Unsubscribed from: #{session_key}"
+      rescue => e
+        Rails.logger.error "Error unsubscribing from #{session_key}: #{e.message}"
+      end
+    end
+
+    def active?
+      @subscription_active
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+ActionMCP::Engine.routes.draw do
+  get "/", to: "sse#events", as: :sse_out
+  post "/", to: "messages#create", as: :sse_in
+end