Add automatic _meta parameter extraction support

[erickreutz]

Summary

This PR adds native support for the MCP protocol's _meta parameter, eliminating the need for manual extraction in controllers.

Background

The MCP specification defines a _meta field that allows clients to pass request-specific metadata. Previously, Ruby SDK users had to manually extract this field from request parameters.

Changes

• Automatic extraction: The server now automatically extracts _meta from request parameters in call_tool and get_prompt methods
• Nested structure: _meta is passed as a nested field within server_context (accessible via server_context[:_meta])
• Compatibility: This implementation matches the TypeScript and Python SDKs, which also nest _meta within the context
• Efficient context creation: Context is only created when there's either server_context or _meta present

Testing

• Added comprehensive tests for _meta extraction and nesting behavior
• All tests pass with the new implementation
• Provider-agnostic test examples (no vendor-specific references)

Documentation

• Updated README with _meta usage examples
• Added link to official MCP specification
• Included both access patterns and client request examples

Usage Example

class MyTool < MCP::Tool
  def self.call(message:, server_context: nil)
    # Access request-specific metadata
    session_id = server_context&.dig(:_meta, :session_id)
    
    # Access server's original context
    user_id = server_context&.dig(:user_id)
    
    MCP::Tool::Response.new([{
      type: "text",
      text: "Processing for user #{user_id} in session #{session_id}"
    }])
  end
end

Breaking Changes

None - this is backwards compatible. Tools that don't use server_context or don't access _meta will continue to work unchanged.

Notes

While implementing this feature, we discovered that the README incorrectly states that server_context is passed to exception and instrumentation callbacks, though the actual implementation only passes contextual error information to these callbacks.

[erickreutz]

@scutuatua-crypto lgtm?

[koic]

The code duplication caught my attention. Could it be updated as a change like the following overall?

index e9a4e50..862c3cd 100644
--- a/lib/mcp/server.rb
+++ b/lib/mcp/server.rb
@@ -419,7 +419,7 @@ module MCP
         end
       end
 
-      call_tool_with_args(tool, arguments)
+      call_tool_with_args(tool, arguments, server_context_with_meta(request))
     rescue RequestHandlerError
       raise
     rescue => e
@@ -445,7 +445,7 @@ module MCP
       prompt_args = request[:arguments]
       prompt.validate_arguments!(prompt_args)
 
-      call_prompt_template_with_args(prompt, prompt_args)
+      call_prompt_template_with_args(prompt, prompt_args, server_context_with_meta(request))
     end
 
     def list_resources(request)
@@ -488,7 +488,7 @@ module MCP
       parameters.any? { |type, name| type == :keyrest || name == :server_context }
     end
 
-    def call_tool_with_args(tool, arguments)
+    def call_tool_with_args(tool, arguments, server_context)
       args = arguments&.transform_keys(&:to_sym) || {}
 
       if accepts_server_context?(tool.method(:call))
@@ -498,12 +498,25 @@ module MCP
       end
     end
 
-    def call_prompt_template_with_args(prompt, args)
+    def call_prompt_template_with_args(prompt, args, server_context)
       if accepts_server_context?(prompt.method(:template))
         prompt.template(args, server_context: server_context).to_h
       else
         prompt.template(args).to_h
       end
     end
+
+    def server_context_with_meta(request)
+      meta = request[:_meta]
+      if @server_context && meta
+        context = @server_context.dup
+        context[:_meta] = meta
+        context
+      elsif meta
+        { _meta: meta }
+      elsif @server_context
+        @server_context
+      end
+    end
   end
 end

[koic]

This comment appears unnecessary since it is already explained in the test code.

[koic]

In this test, it appears that a server_context with _meta set is always passed.

Suggested change

	meta_info = server_context&.dig(:_meta, :provider, :metadata) || "no metadata"
	def call(message:, server_context:)
	meta_info = server_context.dig(:_meta, :provider, :metadata)

[koic]

Suggested change

	session_id = server_context&.dig(:_meta, :session_id) || "unknown"
	def call(message:, server_context:)
	user = server_context[:user]
	session_id = server_context.dig(:_meta, :session_id)

[koic]

Suggested change

	meta_priority = server_context&.dig(:_meta, :priority) || "none"
	def call(server_context:)
	priority = server_context[:priority]
	meta_priority = server_context.dig(:_meta, :priority)

[koic]

Suggested change

	meta_info = server_context&.dig(:_meta, :request_id) || "no request id"
	def template(args, server_context:)
	meta_info = server_context.dig(:_meta, :request_id)

[koic]

Suggested change

	def template(args, server_context: nil)
	user = server_context&.dig(:user) || "unknown"
	trace_id = server_context&.dig(:_meta, :trace_id) || "unknown"
	def template(args, server_context:)
	user = server_context[:user]
	trace_id = server_context.dig(:_meta, :trace_id)

[koic]

It seems that the example would be simpler if written as follows.

Suggested change

	def self.call(message:, server_context: nil)
	# Access provider-specific metadata
	session_id = server_context&.dig(:_meta, :session_id)
	request_id = server_context&.dig(:_meta, :request_id)
	# Access server's original context
	user_id = server_context&.dig(:user_id)
	def self.call(message:, server_context:)
	# Access provider-specific metadata
	session_id = server_context.dig(:_meta, :session_id)
	request_id = server_context.dig(:_meta, :request_id)
	# Access server's original context
	user_id = server_context.dig(:user_id)

[erickreutz]

@koic feedback addressed

[koic]

@erickreutz This looks good to me. Can you squash your commits into one?

[erickreutz]

@koic done

[koic]

Thanks!