actionmcp 0.103.0 → 0.104.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b98e5c438f85bfe710dbe07d1b9cc2a12d7347b4fc200c66a0492f380615599
-  data.tar.gz: 921adb81f040f14533248ce6c52b142a85d8445299e19a83501171b344601c11
+  metadata.gz: 6cfb5ce2385d840e5a70a47707ff2a684b2b1129ab19e55869832cff57286619
+  data.tar.gz: aedeccd60db4263d29eee4da2d051d5910978c50951765dc7ec6b83cb1c2c6c9
 SHA512:
-  metadata.gz: 9aee10304fc9e926a34805c760545adb565b5a19dd7fe59e445ed938d82b2e92e9e7d8e5762db2a5dfc12a844fdbbfb9b84ed7a15f2879703fe7c83b6eb29ec2
-  data.tar.gz: 4b35888139f56c100415e64f495e61efcd43eac2652bf99b1dfbf1ae269fb317d19fad9f0a1ee99b8a19d1e2a36dd3d1818d4ff76a67456f7e9c7edc21457fb7
+  metadata.gz: c6fe8f1b667633f25e566df67f6c8da36d652ef993eb568b8c73b23fd46bb85c3c096560b91c62056bc00325fd1daa23aba789d960697007b5d28881ce02d292
+  data.tar.gz: dc9a41f5f340b09e11c551d64857239501341602731136686f508e3f8fa22558e9f10392941887c20f2ae6cbd7f1174d87fa4b371142e90bcbd3e0bfe8b90353

data/README.md

@@ -470,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
 ```
@@ -521,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:

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

@@ -49,7 +49,9 @@ module ActionMCP
                   :tasks_list_enabled,
                   :tasks_cancel_enabled,
                   # --- Schema Validation Options ---
-                  :validate_structured_content
+                  :validate_structured_content,
+                  # --- Allowed identity keys for gateway ---
+                  :allowed_identity_keys
 
     def initialize
       @logging_enabled = false
@@ -74,6 +76,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
 
@@ -81,6 +86,11 @@ module ActionMCP
       @session_store_type = Rails.env.production? ? :active_record : :volatile
       @client_session_store_type = nil # defaults to session_store_type
       @server_session_store_type = nil # defaults to session_store_type
+
+      # Whitelist of allowed identity attribute names to prevent method shadowing
+      # and unauthorized attribute assignment. Extend this list if you use custom
+      # identifier names in your GatewayIdentifier implementations.
+      @allowed_identity_keys = %w[user api_key jwt bearer token account session].freeze
     end
 
     def name
@@ -91,6 +101,34 @@ 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 allowed_identity_keys=(value)
+      @allowed_identity_keys = Array(value).map(&:to_s).freeze
+    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 +381,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 +407,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/gateway.rb

@@ -4,11 +4,6 @@ module ActionMCP
   class UnauthorizedError < StandardError; end
 
   class Gateway
-    # Whitelist of allowed identity attribute names to prevent method shadowing
-    # and unauthorized attribute assignment. Extend this list if you use custom
-    # identifier names in your GatewayIdentifier implementations.
-    ALLOWED_IDENTITY_KEYS = %w[user api_key jwt bearer token account session].freeze
-
     class << self
       # pluck in one or many GatewayIdentifier classes
       def identified_by(*klasses)
@@ -78,9 +73,9 @@ module ActionMCP
         name_str = name.to_s
 
         # Validate identity key against whitelist to prevent method shadowing
-        unless ALLOWED_IDENTITY_KEYS.include?(name_str)
+        unless allowed_identity_keys.include?(name_str)
           raise ArgumentError, "Invalid identity key: '#{name_str}'. " \
-                               "Allowed keys: #{ALLOWED_IDENTITY_KEYS.join(', ')}"
+                               "Allowed keys: #{allowed_identity_keys.join(', ')}"
         end
 
         # define accessor on the fly
@@ -114,5 +109,9 @@ module ActionMCP
     def apply_profile_from_authentication(identities)
       # Default: do nothing. Override in subclass if you want profile switching.
     end
+
+    def allowed_identity_keys
+      ActionMCP.configuration.allowed_identity_keys
+    end
   end
 end

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/version.rb

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

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.103.0
+  version: 0.104.1
 platform: ruby
 authors:
 - Abdelkader Boudih