actionmcp 0.103.0 → 0.104.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b98e5c438f85bfe710dbe07d1b9cc2a12d7347b4fc200c66a0492f380615599
-  data.tar.gz: 921adb81f040f14533248ce6c52b142a85d8445299e19a83501171b344601c11
+  metadata.gz: 3f008e25bbf68f4c85a29052acb37e59324d302fe5b53c209f7370e80c62e21e
+  data.tar.gz: 8d436c6029b33e6e46b43689ea9ab063b7e8474146263d72bbbfc888fffb4b56
 SHA512:
-  metadata.gz: 9aee10304fc9e926a34805c760545adb565b5a19dd7fe59e445ed938d82b2e92e9e7d8e5762db2a5dfc12a844fdbbfb9b84ed7a15f2879703fe7c83b6eb29ec2
-  data.tar.gz: 4b35888139f56c100415e64f495e61efcd43eac2652bf99b1dfbf1ae269fb317d19fad9f0a1ee99b8a19d1e2a36dd3d1818d4ff76a67456f7e9c7edc21457fb7
+  metadata.gz: 2f3bf909be5df38c2ca0377ac0773d6b61bfd776f25b2148aae0d218241ee80879ab43fd49dbc6b206985cf9e96a6ffe421ff0158dec48f9d9368690342b6419
+  data.tar.gz: 75ad95eb4c7bd7b309e2db5ae7f47722c620e1d585aed0c30f186eaec55bfa4637b99865fe7613e01b7eb217e7e6d28555b8b8ef4695c14c21a97fbbd8e94c52

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

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

@@ -2,7 +2,7 @@
 
 require_relative "gem_version"
 module ActionMCP
-  VERSION = "0.103.0"
+  VERSION = "0.104.0"
 
   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.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -302,7 +302,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.1
 specification_version: 4
 summary: Lightweight Model Context Protocol (MCP) server toolkit for Ruby/Rails
 test_files: []