micro_mcp 0.1.0 → 0.1.4

data/lib/micro_mcp/runtime_helpers.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "validation_helpers"
+
+module MicroMcp
+  module RuntimeHelpers
+    # Helper method to make create_message calls more ergonomic
+    # Automatically extracts the text content from the response
+    def ask_assistant(question, system_prompt: "You are a helpful assistant.", max_tokens: 100, model_hints: ["o4-mini"])
+      params = {
+        "messages" => [
+          {
+            "role" => "user",
+            "content" => {"type" => "text", "text" => question}
+          }
+        ],
+        "modelPreferences" => {
+          "hints" => model_hints.map { |name| {"name" => name} },
+          "intelligencePriority" => 0.8,
+          "speedPriority" => 0.5
+        },
+        "systemPrompt" => system_prompt,
+        "maxTokens" => max_tokens
+      }
+
+      # Validate before sending
+      errors = ValidationHelpers.validate_create_message_params(params)
+      if errors.any?
+        raise ArgumentError, "Invalid create_message parameters: #{errors.join(", ")}"
+      end
+
+      result = create_message(params)
+
+      # Automatically extract the text content with error handling
+      # Response format: { "role": "assistant", "content": { "type": "text", "text": "..." }, "model": "...", "stopReason": "..." }
+      if result.is_a?(Hash) && result.dig("content", "text")
+        result["content"]["text"]
+      else
+        raise "Unexpected response format from create_message: #{result.inspect}"
+      end
+    end
+
+    # More advanced helper that handles different message types
+    def chat_with_assistant(messages, system_prompt: "You are a helpful assistant.", max_tokens: 100, model_hints: ["o4-mini"])
+      # Normalize messages to the expected format
+      normalized_messages = messages.map do |msg|
+        case msg
+        when String
+          {"role" => "user", "content" => {"type" => "text", "text" => msg}}
+        when Hash
+          # Ensure string keys and validate structure
+          normalized = ValidationHelpers.stringify_keys(msg)
+          unless normalized.key?("role") && normalized.key?("content")
+            raise ArgumentError, "Message hash must have 'role' and 'content' keys: #{msg.inspect}"
+          end
+          normalized
+        else
+          raise ArgumentError, "Messages must be strings or hashes, got: #{msg.class}"
+        end
+      end
+
+      params = {
+        "messages" => normalized_messages,
+        "modelPreferences" => {
+          "hints" => model_hints.map { |name| {"name" => name} },
+          "intelligencePriority" => 0.8,
+          "speedPriority" => 0.5
+        },
+        "systemPrompt" => system_prompt,
+        "maxTokens" => max_tokens
+      }
+
+      # Validate before sending
+      errors = ValidationHelpers.validate_create_message_params(params)
+      if errors.any?
+        raise ArgumentError, "Invalid create_message parameters: #{errors.join(", ")}"
+      end
+
+      result = create_message(params)
+
+      # Automatically extract the text content with error handling
+      # Response format: { "role": "assistant", "content": { "type": "text", "text": "..." }, "model": "...", "stopReason": "..." }
+      if result.is_a?(Hash) && result.dig("content", "text")
+        result["content"]["text"]
+      else
+        raise "Unexpected response format from create_message: #{result.inspect}"
+      end
+    end
+
+    # Safe wrapper around create_message with validation
+    def safe_create_message(params)
+      # Ensure all keys are strings
+      safe_params = ValidationHelpers.stringify_keys(params)
+
+      # Validate
+      errors = ValidationHelpers.validate_create_message_params(safe_params)
+      if errors.any?
+        raise ArgumentError, "Invalid create_message parameters: #{errors.join(", ")}"
+      end
+
+      create_message(safe_params)
+    end
+  end
+end

data/lib/micro_mcp/schema.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module MicroMcp
+  module Schema
+    # Schema builder class for chaining
+    class SchemaBuilder
+      def initialize(schema)
+        @schema = schema
+      end
+
+      def required
+        @schema.merge(required: true)
+      end
+
+      def optional
+        @schema
+      end
+
+      def method_missing(method, *args)
+        if @schema.respond_to?(method)
+          @schema.send(method, *args)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @schema.respond_to?(method) || super
+      end
+    end
+
+    # Alternative builder for required-first syntax
+    class RequiredBuilder
+      def integer(description = nil)
+        schema = {type: "integer"}
+        schema[:description] = description if description
+        schema.merge(required: true)
+      end
+
+      def string(description = nil)
+        schema = {type: "string"}
+        schema[:description] = description if description
+        schema.merge(required: true)
+      end
+
+      def number(description = nil)
+        schema = {type: "number"}
+        schema[:description] = description if description
+        schema.merge(required: true)
+      end
+
+      def boolean(description = nil)
+        schema = {type: "boolean"}
+        schema[:description] = description if description
+        schema.merge(required: true)
+      end
+
+      def array(items_type = nil, description = nil)
+        schema = {type: "array"}
+        schema[:items] = items_type if items_type
+        schema[:description] = description if description
+        schema.merge(required: true)
+      end
+    end
+
+    # Helper methods for common schema patterns with builder support
+    def self.integer(description = nil)
+      schema = {type: "integer"}
+      schema[:description] = description if description
+      SchemaBuilder.new(schema)
+    end
+
+    def self.string(description = nil)
+      schema = {type: "string"}
+      schema[:description] = description if description
+      SchemaBuilder.new(schema)
+    end
+
+    def self.number(description = nil)
+      schema = {type: "number"}
+      schema[:description] = description if description
+      SchemaBuilder.new(schema)
+    end
+
+    def self.boolean(description = nil)
+      schema = {type: "boolean"}
+      schema[:description] = description if description
+      SchemaBuilder.new(schema)
+    end
+
+    def self.array(items_type = nil, description = nil)
+      schema = {type: "array"}
+      schema[:items] = items_type if items_type
+      schema[:description] = description if description
+      SchemaBuilder.new(schema)
+    end
+
+    # Create object schema with properties and required fields
+    def self.object(**properties)
+      required_fields = []
+      schema_properties = {}
+
+      properties.each do |key, value|
+        if value.is_a?(Hash) && value[:required] == true
+          required_fields << key.to_s
+          value = value.dup
+          value.delete(:required)
+        end
+        schema_properties[key] = value
+      end
+
+      schema = {
+        type: "object",
+        properties: schema_properties
+      }
+      schema[:required] = required_fields unless required_fields.empty?
+      schema
+    end
+
+    # Entry point for required-first syntax
+    def self.required
+      RequiredBuilder.new
+    end
+  end
+end

data/lib/micro_mcp/server.rb

@@ -13,11 +13,11 @@ module MicroMcp
         thread.join
       rescue Interrupt
         puts "\nShutting down server..."
-        thread.kill
+        MicroMcpNative.shutdown_server
+        thread.join
       end
 
       puts "Server stopped."
-      Process.kill("KILL", Process.pid)
     end
   end
 end

data/lib/micro_mcp/tool_registry.rb

@@ -1,11 +1,74 @@
 # frozen_string_literal: true
 
+require_relative "runtime_helpers"
+
 module MicroMcp
   module ToolRegistry
-    def self.register_tool(name:, description: nil, &block)
+    def self.register_tool(name:, description: nil, arguments: nil, &block)
+      raise ArgumentError, "block required" unless block
+
+      # Wrap the block with error handling for all tools
+      wrapped_block = proc do |args, runtime|
+        block.call(args, runtime)
+      rescue => e
+        # For test tools that are designed to fail, re-raise the error
+        # so tests can verify the error behavior
+        if name.to_s.include?("error") ||
+            name.to_s.include?("fail") ||
+            name.to_s.include?("use_captured_runtime") ||
+            e.message.include?("McpServer reference")
+          raise e
+        end
+
+        # Better error reporting for unexpected failures
+        error_msg = "Tool '#{name}' failed: #{e.message}"
+        puts "ERROR: #{error_msg}"
+        puts "Backtrace: #{e.backtrace.first(3).join("\n")}" if ENV["MCP_DEBUG"]
+        error_msg
+      end
+
+      MicroMcpNative.register_tool(name, description, arguments, wrapped_block)
+    end
+
+    # Enhanced registration with better error handling and validation
+    def self.register_assistant_tool(name:, description:, question_param: "question", &block)
       raise ArgumentError, "block required" unless block
 
-      MicroMcpNative.register_tool(name, description, block)
+      arguments = Schema.object(
+        question_param.to_sym => Schema.string("Question for the assistant").required
+      )
+
+      register_tool(name: name, description: description, arguments: arguments) do |args, runtime|
+        # Extend runtime with helper methods
+        runtime.extend(RuntimeHelpers)
+
+        result = block.call(args, runtime)
+
+        # Auto-handle common return value patterns
+        case result
+        when Hash
+          # If it looks like a create_message result, extract the text
+          # Response format: { "role": "assistant", "content": { "type": "text", "text": "..." }, ... }
+          if result.dig("content", "text")
+            result["content"]["text"]
+          else
+            result
+          end
+        else
+          result
+        end
+      end
+    end
+
+    # Specialized method for simple question-answering tools
+    def self.register_qa_tool(name:, description:, system_prompt: "You are a helpful assistant.", max_tokens: 100)
+      register_assistant_tool(name: name, description: description) do |args, runtime|
+        runtime.ask_assistant(
+          args["question"],
+          system_prompt: system_prompt,
+          max_tokens: max_tokens
+        )
+      end
     end
   end
 end

data/lib/micro_mcp/validation_helpers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module MicroMcp
+  module ValidationHelpers
+    # Validate create_message parameters before sending
+    def self.validate_create_message_params(params)
+      errors = []
+
+      # Check required fields
+      errors << "Missing 'messages' field" unless params.key?("messages")
+      errors << "Missing 'maxTokens' field" unless params.key?("maxTokens")
+
+      if params["messages"]
+        # Validate messages structure
+        if params["messages"].is_a?(Array)
+          params["messages"].each_with_index do |msg, i|
+            unless msg.is_a?(Hash)
+              errors << "Message #{i} must be a hash"
+              next
+            end
+
+            unless msg.key?("role")
+              errors << "Message #{i} missing 'role' field"
+            end
+
+            unless msg.key?("content")
+              errors << "Message #{i} missing 'content' field"
+            end
+
+            if msg["content"] && !msg["content"].is_a?(Hash)
+              errors << "Message #{i} 'content' must be a hash"
+            end
+          end
+        else
+          errors << "'messages' must be an array"
+        end
+      end
+
+      # Check for common mistakes
+      if params.any? { |k, v| k.is_a?(Symbol) }
+        errors << "Hash keys must be strings, not symbols. Use string keys throughout."
+      end
+
+      errors
+    end
+
+    # Helper to convert symbol keys to string keys recursively
+    def self.stringify_keys(obj)
+      case obj
+      when Hash
+        obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+      when Array
+        obj.map { |v| stringify_keys(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/micro_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MicroMcp
-  VERSION = "0.1.0"
+  VERSION = "0.1.4"
 end

data/lib/micro_mcp.rb

@@ -1,9 +1,21 @@
 # frozen_string_literal: true
 
 require_relative "micro_mcp/version"
-require_relative "micro_mcp/micro_mcp"
+ruby_version = "#{RUBY_VERSION[/\d+\.\d+/]}"
+begin
+  require_relative "micro_mcp/micro_mcp"
+rescue LoadError
+  begin
+    require_relative "micro_mcp/#{ruby_version}/micro_mcp"
+  rescue LoadError
+    raise LoadError, "No native extension found for Ruby #{ruby_version}"
+  end
+end
+require_relative "micro_mcp/schema"
 require_relative "micro_mcp/tool_registry"
 require_relative "micro_mcp/server"
+require_relative "micro_mcp/runtime_helpers"
+require_relative "micro_mcp/validation_helpers"
 
 module MicroMcp
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: micro_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.4
 platform: ruby
 authors:
 - Erwin Kroon
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.91
+        version: 0.9.116
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.91
+        version: 0.9.116
 description: ''
 email:
 - 123574+ekroon@users.noreply.github.com
@@ -33,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".devcontainer/devcontainer.json"
 - ".standard.yml"
+- ".tool-versions"
 - ".vscode/mcp.json"
 - AGENTS.md
 - CHANGELOG.md
@@ -41,16 +42,20 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/changes/ERGONOMIC_IMPROVEMENTS.md
+- ext/micro_mcp/AGENTS.md
 - ext/micro_mcp/Cargo.toml
 - ext/micro_mcp/extconf.rb
 - ext/micro_mcp/src/lib.rs
 - ext/micro_mcp/src/server.rs
 - ext/micro_mcp/src/utils.rs
 - lib/micro_mcp.rb
+- lib/micro_mcp/runtime_helpers.rb
+- lib/micro_mcp/schema.rb
 - lib/micro_mcp/server.rb
 - lib/micro_mcp/tool_registry.rb
+- lib/micro_mcp/validation_helpers.rb
 - lib/micro_mcp/version.rb
-- sig/micro_mcp.rbs
 homepage: https://github.com/ekroon/micro_mcp
 licenses:
 - MIT

data/sig/micro_mcp.rbs

@@ -1,4 +0,0 @@
-module MicroMcp
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end