actionmcp 0.102.0 → 0.104.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01a1c6af1a49f9992d61bfe0e0bb6aa6ab8429dbdd21e977c27506fd21cb90e
-  data.tar.gz: 650eac8eb9711cafffee1b5e27d45873f8a28b3a9c07d27ca91d4bada3c72436
+  metadata.gz: 3f008e25bbf68f4c85a29052acb37e59324d302fe5b53c209f7370e80c62e21e
+  data.tar.gz: 8d436c6029b33e6e46b43689ea9ab063b7e8474146263d72bbbfc888fffb4b56
 SHA512:
-  metadata.gz: 750107898a375f73d7055cb1b346971e5f1bdfe5ca82d8839a280a67c03a396970e9e7919dac5146e456cc0a49ffbe6013bfac0ec8ded7da515bd3691147a18d
-  data.tar.gz: a1701f0a82a4320896731bc33f7db4968524133e5b6f407ac0174fed70165a36d36079e6f6f179d149305bbbbfb4977320f63d7e36afc78bc16d2f012911dac5
+  metadata.gz: 2f3bf909be5df38c2ca0377ac0773d6b61bfd776f25b2148aae0d218241ee80879ab43fd49dbc6b206985cf9e96a6ffe421ff0158dec48f9d9368690342b6419
+  data.tar.gz: 75ad95eb4c7bd7b309e2db5ae7f47722c620e1d585aed0c30f186eaec55bfa4637b99865fe7613e01b7eb217e7e6d28555b8b8ef4695c14c21a97fbbd8e94c52

data/README.md

@@ -46,6 +46,14 @@ In short, ActionMCP helps you build an MCP server (the component that exposes ca
 
 > **Client connections:** The client part of ActionMCP is meant to connect to remote MCP servers only. Connecting to local processes (such as via STDIO) is not supported.
 
+## Requirements
+
+- **Ruby**: 3.4.8+ or 4.0.0+
+- **Rails**: 8.1.1+
+- **Database**: PostgreSQL, MySQL, or SQLite3
+
+ActionMCP is tested against Ruby 3.4.8 and 4.0.0 with Rails 8.1.1+.
+
 ## Installation
 
 To start using ActionMCP, add it to your project:
@@ -179,7 +187,7 @@ For tools that perform sensitive operations (file system access, database modifi
 class FileSystemTool < ApplicationMCPTool
   tool_name "read_file"
   description "Read contents of a file"
-  
+
   # Require explicit consent before execution
   requires_consent!
 
@@ -392,7 +400,7 @@ ActionMCP provides comprehensive documentation across multiple specialized guide
 - **[Installation & Configuration](README.md#installation)** - Initial setup, database migrations, and basic configuration
 - **[Authentication with Gateway](README.md#authentication-with-gateway)** - User authentication and authorization patterns
 
-### Component Development  
+### Component Development
 - **[📋 TOOLS.MD](TOOLS.MD)** - Complete guide to developing MCP tools
   - Generator usage and best practices
   - Property definitions, validation, and consent management
@@ -462,6 +470,12 @@ module Tron
     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
+
+    # Server instructions - helps LLMs understand the server's purpose
+    config.action_mcp.server_instructions = [
+      "Use this server to access and control Tron system programs",
+      "Helpful for managing system processes and user data"
+    ]
   end
 end
 ```
@@ -513,6 +527,35 @@ production:
   max_queue: 500      # Maximum number of tasks that can be queued
 ```
 
+### Server Instructions
+
+Server instructions help LLMs understand **what your server is for** and **when to use it**. They describe the server's purpose and goal, not technical details like rate limits or authentication (tools are self-documented via their own descriptions).
+
+Instructions are returned at the top level of the MCP initialization response.
+
+You can configure server instructions in your `config/mcp.yml` file:
+
+```yaml
+shared:
+  # Describe the server's purpose - helps LLMs know when to use this server
+  server_instructions:
+    - "Use this server to manage Fizzy project tickets and workflows"
+    - "Helpful for tracking bugs, features, and sprint planning"
+
+development:
+  # Development-specific purpose description
+  server_instructions:
+    - "Development server for testing Fizzy integration"
+    - "Use for prototyping ticket management workflows"
+
+production:
+  # Production-specific purpose description
+  server_instructions:
+    - "Production Fizzy server for managing live project data"
+```
+
+Instructions are sent as a single string (joined by newlines) at the top level of the initialization response, helping LLMs understand your server's purpose.
+
 #### SolidMCP (Database-backed, Recommended)
 
 For SolidMCP, add it to your Gemfile:
@@ -1042,7 +1085,7 @@ class MyTool < ApplicationMCPTool
       report_error("Clear error message for the LLM")
       return
     end
-    
+
     # Normal processing
     render(text: "Success message")
   end

data/app/models/action_mcp/session.rb

@@ -140,11 +140,15 @@ module ActionMCP
     end
 
     def server_capabilities_payload
-      {
+      payload = {
         protocolVersion: protocol_version || ActionMCP::DEFAULT_PROTOCOL_VERSION,
         serverInfo: server_info,
         capabilities: server_capabilities
       }
+      # Add instructions at top level if configured
+      instructions = ActionMCP.configuration.instructions
+      payload[:instructions] = instructions if instructions
+      payload
     end
 
     def server_capabilities
@@ -359,10 +363,7 @@ module ActionMCP
 
     # This will keep the version and name of the server when this session was created
     def set_server_info
-      self.server_info = {
-        name: ActionMCP.configuration.name,
-        version: ActionMCP.configuration.version
-      }
+      self.server_info = ActionMCP.configuration.server_info
     end
 
     # This can be overridden by the application in future versions

data/lib/action_mcp/configuration.rb

@@ -44,12 +44,12 @@ module ActionMCP
                   :max_queue,
                   :polling_interval,
                   :connects_to,
-                  # --- Tasks Options (MCP 2025-11-25) ---
-                  :tasks_enabled,
-                  :tasks_list_enabled,
-                  :tasks_cancel_enabled,
-                  # --- Schema Validation Options ---
-                  :validate_structured_content
+                   # --- Tasks Options (MCP 2025-11-25) ---
+                   :tasks_enabled,
+                   :tasks_list_enabled,
+                   :tasks_cancel_enabled,
+                   # --- Schema Validation Options ---
+                   :validate_structured_content
 
     def initialize
       @logging_enabled = false
@@ -74,6 +74,9 @@ module ActionMCP
       # Schema validation - disabled by default for backward compatibility
       @validate_structured_content = false
 
+      # Server instructions - empty by default
+      @server_instructions = []
+
       # Gateway - resolved lazily to account for Zeitwerk autoloading
       @gateway_class_name = nil
 
@@ -91,6 +94,30 @@ module ActionMCP
       @version || (has_rails_version ? Rails.application.version.to_s : "0.0.1")
     end
 
+    # Server information (name and version only)
+    def server_info
+      {
+        name: name,
+        version: version
+      }
+    end
+
+    # Instructions for LLMs about the server's purpose (joined as string for MCP payload)
+    def instructions
+      return nil if server_instructions.nil? || server_instructions.empty?
+
+      server_instructions.join("\n")
+    end
+
+    # Custom getter/setter to ensure array elements are strings
+    def server_instructions
+      @server_instructions
+    end
+
+    def server_instructions=(value)
+      @server_instructions = parse_instructions(value)
+    end
+
     def gateway_class
       # Resolve gateway class lazily to account for Zeitwerk autoloading
       # This allows ApplicationGateway to be loaded from app/mcp even if the
@@ -343,9 +370,14 @@ module ActionMCP
         @client_session_store_type = config["client_session_store_type"].to_sym
       end
 
-      return unless config["server_session_store_type"]
+      if config["server_session_store_type"]
+        @server_session_store_type = config["server_session_store_type"].to_sym
+      end
 
-      @server_session_store_type = config["server_session_store_type"].to_sym
+      # Extract server instructions
+      if config["server_instructions"]
+        @server_instructions = parse_instructions(config["server_instructions"])
+      end
     end
 
     def should_include_all?(type)
@@ -364,6 +396,10 @@ module ActionMCP
       false
     end
 
+    def parse_instructions(instructions)
+      Array(instructions).map(&:to_s)
+    end
+
     def ensure_mcp_components_loaded
       # Only load if we haven't loaded yet - but in development, always reload
       return if @mcp_components_loaded && !Rails.env.development?

data/lib/action_mcp/server/base_session.rb

@@ -128,11 +128,15 @@ module ActionMCP
 
       # Capability methods
       def server_capabilities_payload
-        {
+        payload = {
           protocolVersion: ActionMCP::LATEST_VERSION,
           serverInfo: server_info,
           capabilities: server_capabilities
         }
+        # Add instructions at top level if configured
+        instructions = ActionMCP.configuration.instructions
+        payload[:instructions] = instructions if instructions
+        payload
       end
 
       def set_protocol_version(version)

data/lib/action_mcp/test_helper/session_store_assertions.rb

@@ -51,64 +51,6 @@ module ActionMCP
                      message || "Expected #{expected} session operations#{type_desc}, got #{actual}"
       end
 
-      # Client session store assertions
-      def assert_client_session_saved(session_id, message = nil)
-        assert client_session_store.session_saved?(session_id),
-               message || "Expected client session #{session_id} to have been saved"
-      end
-
-      def assert_client_session_not_saved(session_id, message = nil)
-        assert_not client_session_store.session_saved?(session_id),
-                   message || "Expected client session #{session_id} not to have been saved"
-      end
-
-      def assert_client_session_loaded(session_id, message = nil)
-        assert client_session_store.session_loaded?(session_id),
-               message || "Expected client session #{session_id} to have been loaded"
-      end
-
-      def assert_client_session_not_loaded(session_id, message = nil)
-        assert_not client_session_store.session_loaded?(session_id),
-                   message || "Expected client session #{session_id} not to have been loaded"
-      end
-
-      def assert_client_session_updated(session_id, message = nil)
-        assert client_session_store.session_updated?(session_id),
-               message || "Expected client session #{session_id} to have been updated"
-      end
-
-      def assert_client_session_not_updated(session_id, message = nil)
-        assert_not client_session_store.session_updated?(session_id),
-                   message || "Expected client session #{session_id} not to have been updated"
-      end
-
-      def assert_client_session_deleted(session_id, message = nil)
-        assert client_session_store.session_deleted?(session_id),
-               message || "Expected client session #{session_id} to have been deleted"
-      end
-
-      def assert_client_session_not_deleted(session_id, message = nil)
-        assert_not client_session_store.session_deleted?(session_id),
-                   message || "Expected client session #{session_id} not to have been deleted"
-      end
-
-      def assert_client_session_operation_count(expected, type = nil, message = nil)
-        actual = client_session_store.operation_count(type)
-        type_desc = type ? " of type #{type}" : ""
-        assert_equal expected, actual,
-                     message || "Expected #{expected} client session operations#{type_desc}, got #{actual}"
-      end
-
-      def assert_client_session_data_includes(session_id, expected_data, message = nil)
-        saved_data = client_session_store.last_saved_data(session_id)
-        assert saved_data, "No saved data found for session #{session_id}"
-
-        expected_data.each do |key, value|
-          assert_equal value, saved_data[key],
-                       message || "Expected session #{session_id} data to include #{key}: #{value}"
-        end
-      end
-
       private
 
       def server_session_store
@@ -117,18 +59,6 @@ module ActionMCP
 
         store
       end
-
-      def client_session_store
-        # This would need to be set by the test or could use a thread-local variable
-        # For now, we'll assume it's available as an instance variable
-        store = @client_session_store || Thread.current[:test_client_session_store]
-        unless store
-          raise "Client session store not set. Set @client_session_store or Thread.current[:test_client_session_store]"
-        end
-        raise "Client session store is not a TestSessionStore" unless store.is_a?(ActionMCP::Client::TestSessionStore)
-
-        store
-      end
     end
   end
 end

data/lib/action_mcp/version.rb

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.102.0"
+  VERSION = "0.104.0"
 
   class << self
     alias version gem_version

data/lib/action_mcp.rb

@@ -29,7 +29,6 @@ end.setup
 
 module ActionMCP
   require_relative "action_mcp/version"
-  require_relative "action_mcp/client"
 
   # Error raised when structured content doesn't match the declared output_schema
   class StructuredContentValidationError < StandardError; end

data/lib/generators/action_mcp/identifier/templates/identifier.rb.erb

@@ -22,14 +22,14 @@ class <%= class_name %> < ActionMCP::GatewayIdentifier
   private
 
   # Add any custom helper methods here
-  # 
+  #
   # Example helper methods:
-  # 
+  #
   # def extract_credentials_from_request
   #   # Custom extraction logic
   # end
-  # 
+  #
   # def validate_credentials(credentials)
   #   # Custom validation logic
   # end
-end
+end

data/lib/generators/action_mcp/install/templates/mcp.yml

@@ -16,6 +16,11 @@ shared:
   # Server-specific session store type (falls back to session_store_type if not specified)
   # server_session_store_type: active_record
 
+  # Server instructions - helps LLMs understand the server's purpose
+  # Describe what the server is for, not technical details (tools are self-documented)
+  # server_instructions:
+  #   - "Use this server to manage project tickets and workflows"
+  #   - "Helpful for tracking bugs, features, and sprint planning"
 
   # MCP capability profiles
   profiles:
@@ -46,6 +51,11 @@ development:
   # Use simple pub/sub adapter for development
   adapter: simple
 
+  # Development-specific purpose description
+  # server_instructions:
+  #   - "Development server for testing your MCP integration"
+  #   - "Use for prototyping and experimenting with tools"
+
   # Session store examples for development
   # Use volatile client sessions for faster development
   # client_session_store_type: volatile
@@ -106,4 +116,4 @@ production:
   # channel_prefix: my_mcp_app_production
   # min_threads: 10    # Minimum number of threads in the pool
   # max_threads: 20    # Maximum number of threads in the pool
-  # max_queue: 500     # Maximum number of tasks that can be queued
+  # max_queue: 500     # Maximum number of tasks that can be queued

data/lib/generators/action_mcp/tool/templates/tool.rb.erb

@@ -34,12 +34,12 @@ class <%= class_name %> < ApplicationMCPTool
 
   # Uncomment to allow additional properties beyond those defined above:
   # additional_properties true           # Allow any additional properties
-  # additional_properties false          # Explicitly disallow additional properties 
+  # additional_properties false          # Explicitly disallow additional properties
   # additional_properties({"type" => "string"})  # Allow additional properties but restrict to strings
 
   def perform
     render(text: "Processing <%= properties.map { |p| p[:name] }.join(', ') %>")
-    
+
     # If additional_properties is enabled, you can access extra parameters:
     # extra_params = additional_params
     # extra_params.each do |key, value|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: actionmcp
 version: !ruby/object:Gem::Version
-  version: 0.102.0
+  version: 0.104.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -173,31 +173,6 @@ files:
 - lib/action_mcp/base_response.rb
 - lib/action_mcp/callbacks.rb
 - lib/action_mcp/capability.rb
-- lib/action_mcp/client.rb
-- lib/action_mcp/client/active_record_session_store.rb
-- lib/action_mcp/client/base.rb
-- lib/action_mcp/client/blueprint.rb
-- lib/action_mcp/client/catalog.rb
-- lib/action_mcp/client/collection.rb
-- lib/action_mcp/client/elicitation.rb
-- lib/action_mcp/client/json_rpc_handler.rb
-- lib/action_mcp/client/logging.rb
-- lib/action_mcp/client/messaging.rb
-- lib/action_mcp/client/prompt_book.rb
-- lib/action_mcp/client/prompts.rb
-- lib/action_mcp/client/request_timeouts.rb
-- lib/action_mcp/client/resources.rb
-- lib/action_mcp/client/roots.rb
-- lib/action_mcp/client/server.rb
-- lib/action_mcp/client/session_store.rb
-- lib/action_mcp/client/session_store_factory.rb
-- lib/action_mcp/client/streamable_client.rb
-- lib/action_mcp/client/streamable_http_transport.rb
-- lib/action_mcp/client/test_session_store.rb
-- lib/action_mcp/client/toolbox.rb
-- lib/action_mcp/client/tools.rb
-- lib/action_mcp/client/transport.rb
-- lib/action_mcp/client/volatile_session_store.rb
 - lib/action_mcp/configuration.rb
 - lib/action_mcp/console_detector.rb
 - lib/action_mcp/content.rb

data/lib/action_mcp/client/active_record_session_store.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module ActionMCP
-  module Client
-    # ActiveRecord-backed session store for production
-    class ActiveRecordSessionStore
-      include SessionStore
-
-      def load_session(session_id)
-        session = ActionMCP::Session.find_by(id: session_id)
-        return nil unless session
-
-        {
-          id: session.id,
-          protocol_version: session.protocol_version,
-          client_info: session.client_info,
-          client_capabilities: session.client_capabilities,
-          server_info: session.server_info,
-          server_capabilities: session.server_capabilities,
-          created_at: session.created_at,
-          updated_at: session.updated_at
-        }
-      end
-
-      def save_session(session_id, session_data)
-        session = ActionMCP::Session.find_or_initialize_by(id: session_id)
-
-        # Only assign attributes that exist in the database
-        attributes = {}
-        attributes[:protocol_version] = session_data[:protocol_version] if session_data.key?(:protocol_version)
-        attributes[:client_info] = session_data[:client_info] if session_data.key?(:client_info)
-        attributes[:client_capabilities] = session_data[:client_capabilities] if session_data.key?(:client_capabilities)
-        attributes[:server_info] = session_data[:server_info] if session_data.key?(:server_info)
-        attributes[:server_capabilities] = session_data[:server_capabilities] if session_data.key?(:server_capabilities)
-
-        # Store any extra data in a jsonb column if available
-        # For now, we'll skip last_event_id and session_data as they don't exist in the DB
-
-        session.assign_attributes(attributes)
-        session.save!
-        session_data
-      end
-
-      def delete_session(session_id)
-        ActionMCP::Session.find_by(id: session_id)&.destroy
-      end
-
-      def session_exists?(session_id)
-        ActionMCP::Session.exists?(id: session_id)
-      end
-
-      def cleanup_expired_sessions(older_than: 24.hours.ago)
-        ActionMCP::Session.where("updated_at < ?", older_than).delete_all
-      end
-    end
-  end
-end