tool_forge 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f747b53bc12b00107b180fd1fe950d7146f2937a3c5a5cf9b31638ee8d4a31
-  data.tar.gz: cca823e5fa54ffdc144497b63e37e6f977f2d5cc6ccb70bf38982d62d1db135d
+  metadata.gz: 7b224a5666b3a1f3129f0f6c433d0da618be11d7e96401cdf632b268bb4667b3
+  data.tar.gz: e9e1b5d02fcbb000c8ef15b6e7c1707ac214b5b35d9346c711ab150507ee8209
 SHA512:
-  metadata.gz: 76b3684d98cf72f531ce523f00fc56c3d885fe0b9f2d1f64ee2a7f3597fb8b4f13204846fbbdbf40a66e3083f095bd2f964aa7a9d3b1c22a3d23b4285d2a9d6e
-  data.tar.gz: 6d2b16c9539435fdfa11060d60606da6b5b3213f8dac86df08be35f2e42bb186cec5f80133f784696df497fc0e245adb1e396f6cc060031b8c43a95216912127
+  metadata.gz: d50f61a50e87a6a3c5754b4d0f71910363651386cc47bb3634f5bc888f35214737449c10c411085fb95888f41ba9e0c96af7168be31a7f165ecb104a904627bc
+  data.tar.gz: 4d02123db7d4b56c83bdf53913f238c5e408f250edfdcbd2e963abcfd0049e2736762b2e4798ff7d9b6440b2242e1be39fcb5e9c3b640d29b66153e7bc3b0591

data/README.md

@@ -1,28 +1,336 @@
 # ToolForge
 
-TODO: Delete this and the text below, and describe your gem
+ToolForge is a Ruby gem that provides a unified DSL for defining tools that can be converted to both [RubyLLM](https://github.com/ruby-llm/ruby-llm) and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) formats. Write your tool once, use it anywhere.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/tool_forge`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Features
 
-## Installation
+- 🎯 **Unified DSL**: Define tools once, convert to multiple formats
+- 🔧 **Helper Methods**: Support for both instance and class helper methods
+- 📊 **Type Safety**: Parameter validation and type conversion
+- 🚀 **Framework Agnostic**: Works with RubyLLM and MCP frameworks
+- 📝 **Clean API**: Intuitive, Ruby-like syntax
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add tool_forge
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install tool_forge
+```
+
+## Quick Start
+
+```ruby
+require 'tool_forge'
+
+# Define a tool
+tool = ToolForge.define(:greet_user) do
+  description 'Greets a user with a personalized message'
+
+  param :name, type: :string, description: 'User name'
+  param :greeting, type: :string, description: 'Greeting style',
+        required: false, default: 'Hello'
+
+  execute do |name:, greeting:|
+    "#{greeting}, #{name}! Welcome to ToolForge!"
+  end
+end
+
+# Convert to RubyLLM format
+ruby_llm_tool = tool.to_ruby_llm_tool
+instance = ruby_llm_tool.new
+result = instance.execute(name: 'Alice')
+#=> "Hello, Alice! Welcome to ToolForge!"
+
+# Convert to MCP format
+mcp_tool = tool.to_mcp_tool
+result = mcp_tool.call(server_context: nil, name: 'Bob')
+#=> Returns MCP::Tool::Response object
+```
+
+## Detailed Usage
+
+### Basic Tool Definition
+
+```ruby
+tool = ToolForge.define(:file_reader) do
+  description 'Reads and processes files'
+
+  # Define parameters with types and validation
+  param :filename, type: :string, description: 'Path to file'
+  param :encoding, type: :string, required: false, default: 'utf-8'
+  param :max_lines, type: :integer, required: false
+
+  # Define execution logic
+  execute do |filename:, encoding:, max_lines:|
+    content = File.read(filename, encoding: encoding)
+    lines = content.lines
+
+    if max_lines
+      lines.first(max_lines).join
+    else
+      content
+    end
+  end
+end
 ```
 
-## Usage
+### Helper Methods
+
+ToolForge supports two types of helper methods:
+
+#### Instance Helper Methods
+
+Use `helper` for methods that operate on instance data:
+
+```ruby
+tool = ToolForge.define(:text_processor) do
+  description 'Processes text with formatting'
+
+  param :text, type: :string
+  param :format, type: :string, default: 'uppercase'
+
+  # Instance helper method
+  helper(:format_text) do |text, format|
+    case format
+    when 'uppercase' then text.upcase
+    when 'lowercase' then text.downcase
+    when 'title' then text.split.map(&:capitalize).join(' ')
+    else text
+    end
+  end
+
+  helper(:add_prefix) do |text|
+    "PROCESSED: #{text}"
+  end
+
+  execute do |text:, format:|
+    formatted = format_text(text, format)
+    add_prefix(formatted)
+  end
+end
+```
+
+#### Class Helper Methods
+
+Use `class_helper` for utility methods that don't depend on instance state:
+
+```ruby
+tool = ToolForge.define(:docker_copy) do
+  description 'Copies files to Docker containers'
+
+  param :container_id, type: :string
+  param :source_path, type: :string
+  param :dest_path, type: :string
+
+  # Class helper method - useful for utilities
+  class_helper(:add_to_tar) do |file_path, tar_path|
+    # Implementation for tar operations
+    "Added #{file_path} to tar archive as #{tar_path}"
+  end
+
+  class_helper(:validate_container) do |container_id|
+    # Validation logic
+    container_id.match?(/^[a-f0-9]{12}$/)
+  end
+
+  execute do |container_id:, source_path:, dest_path:|
+    return "Invalid container ID" unless self.class.validate_container(container_id)
+
+    tar_result = self.class.add_to_tar(source_path, dest_path)
+    "Copied #{source_path} to #{container_id}:#{dest_path} - #{tar_result}"
+  end
+end
+```
+
+### Parameter Types
+
+ToolForge supports various parameter types:
+
+```ruby
+tool = ToolForge.define(:complex_tool) do
+  param :name, type: :string              # String parameter
+  param :count, type: :integer             # Integer parameter
+  param :active, type: :boolean            # Boolean parameter
+  param :rate, type: :number               # Numeric parameter
+  param :tags, type: :array                # Array parameter
+  param :metadata, type: :object           # Object/Hash parameter
+  param :config, type: :string, required: false, default: 'default.json'
+
+  execute do |**params|
+    # Access all parameters
+    params.inspect
+  end
+end
+```
+
+### Framework Integration
+
+#### RubyLLM Integration
+
+```ruby
+require 'ruby_llm'
+require 'tool_forge'
+
+tool = ToolForge.define(:my_tool) do
+  # ... tool definition
+end
+
+# Convert to RubyLLM format
+ruby_llm_class = tool.to_ruby_llm_tool
+
+# Use with RubyLLM
+llm = RubyLLM::Client.new
+llm.add_tool(ruby_llm_class)
+```
+
+#### MCP Integration
+
+```ruby
+require 'mcp'
+require 'tool_forge'
+
+tool = ToolForge.define(:my_tool) do
+  # ... tool definition
+end
+
+# Convert to MCP format
+mcp_class = tool.to_mcp_tool
+
+# Use with MCP server
+server = MCP::Server.new
+server.add_tool(mcp_class)
+```
+
+## Advanced Features
+
+### Complex Data Processing
+
+```ruby
+tool = ToolForge.define(:data_analyzer) do
+  description 'Analyzes data files and generates reports'
+
+  param :files, type: :array, description: 'List of file paths'
+  param :output_format, type: :string, default: 'json'
+
+  helper(:read_file_data) do |file_path|
+    return { error: "File not found: #{file_path}" } unless File.exist?(file_path)
+
+    {
+      path: file_path,
+      size: File.size(file_path),
+      lines: File.readlines(file_path).count,
+      modified: File.mtime(file_path)
+    }
+  end
+
+  helper(:format_output) do |data, format|
+    case format
+    when 'json' then JSON.pretty_generate(data)
+    when 'yaml' then data.to_yaml
+    when 'csv' then data.map { |row| row.values.join(',') }.join("\n")
+    else data.inspect
+    end
+  end
+
+  execute do |files:, output_format:|
+    results = files.map { |file| read_file_data(file) }
+
+    summary = {
+      total_files: results.count,
+      total_size: results.sum { |r| r[:size] || 0 },
+      files: results
+    }
+
+    format_output(summary, output_format)
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+tool = ToolForge.define(:safe_processor) do
+  description 'Processes data with comprehensive error handling'
+
+  param :input, type: :string
+  param :operation, type: :string
+
+  helper(:validate_input) do |input|
+    raise ArgumentError, "Input cannot be empty" if input.nil? || input.empty?
+    raise ArgumentError, "Input too long" if input.length > 1000
+    true
+  end
+
+  execute do |input:, operation:|
+    begin
+      validate_input(input)
+
+      case operation
+      when 'reverse' then input.reverse
+      when 'upcase' then input.upcase
+      when 'analyze' then { length: input.length, words: input.split.count }
+      else
+        { error: "Unknown operation: #{operation}" }
+      end
+    rescue => e
+      { error: e.message }
+    end
+  end
+end
+```
+
+## API Reference
+
+### ToolForge.define(name, &block)
+
+Creates a new tool definition.
+
+- `name` (Symbol): The tool name
+- `block`: Configuration block using the DSL
+
+### DSL Methods
+
+#### `description(text)`
+Sets the tool description.
+
+#### `param(name, options = {})`
+Defines a parameter with options:
+- `type`: Parameter type (`:string`, `:integer`, `:boolean`, `:number`, `:array`, `:object`)
+- `description`: Parameter description
+- `required`: Whether required (default: `true`)
+- `default`: Default value for optional parameters
+
+#### `helper(name, &block)`
+Defines an instance helper method.
+
+#### `class_helper(name, &block)`
+Defines a class helper method.
+
+#### `execute(&block)`
+Defines the tool execution logic.
+
+### Conversion Methods
+
+#### `#to_ruby_llm_tool`
+Converts to a RubyLLM::Tool class.
+
+#### `#to_mcp_tool`
+Converts to an MCP::Tool class.
+
+## Examples
 
-TODO: Write usage instructions here
+See the [examples directory](examples/) for more comprehensive examples including:
+- File processing tools
+- API integration tools
+- Data transformation tools
+- Docker management tools
 
 ## Development
 
@@ -32,7 +340,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/tool_forge.
+Bug reports and pull requests are welcome on GitHub at https://github.com/afstanton/tool_forge.
 
 ## License
 

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/examples/README.md

@@ -0,0 +1,95 @@
+# ToolForge Examples
+
+This directory contains practical examples of ToolForge usage, demonstrating various features and patterns.
+
+## Examples
+
+### 1. Docker Copy Tool (`docker_copy_tool.rb`)
+Demonstrates:
+- **Class helper methods** for utility functions (`add_to_tar`, `validate_container_id`)
+- **Instance helper methods** for result formatting
+- **Parameter validation** and error handling
+- **Complex return values** with structured data
+
+**Key Features:**
+- Container ID validation
+- Tar archive operations simulation
+- File existence checking
+- Comprehensive error handling
+
+### 2. File Processor Tool (`file_processor_tool.rb`)
+Demonstrates:
+- **Multiple instance helper methods** for different concerns
+- **Array parameters** for multiple operations
+- **Complex text processing** with various transformations
+- **Multiple output formats** (JSON, YAML, text)
+- **Preserve original data** option
+
+**Key Features:**
+- Text analysis (word count, line count, etc.)
+- Text transformations (case changes, reversals, etc.)
+- Flexible output formatting
+- Operation chaining
+
+## Running Examples
+
+To run these examples:
+
+```bash
+# From the project root
+ruby examples/docker_copy_tool.rb
+ruby examples/file_processor_tool.rb
+```
+
+## Creating Your Own Tools
+
+Use these examples as templates for your own tools:
+
+1. **Start with a clear purpose** - what does your tool do?
+2. **Define parameters** - what inputs does it need?
+3. **Break down complex logic** into helper methods
+4. **Choose the right helper type**:
+   - Use `helper` for instance methods that work with tool data
+   - Use `class_helper` for utility functions and static operations
+5. **Handle errors gracefully** - return structured error information
+6. **Consider output format** - how will users consume the results?
+
+## Integration Examples
+
+### With RubyLLM
+
+```ruby
+require 'ruby_llm'
+require_relative 'docker_copy_tool'
+
+# Convert to RubyLLM format
+ruby_llm_tool = docker_copy_tool.to_ruby_llm_tool
+
+# Use with RubyLLM framework
+llm = RubyLLM::Client.new
+llm.add_tool(ruby_llm_tool)
+```
+
+### With MCP
+
+```ruby
+require 'mcp'
+require_relative 'file_processor_tool'
+
+# Convert to MCP format
+mcp_tool = file_processor_tool.to_mcp_tool
+
+# Use with MCP server
+server = MCP::Server.new
+server.add_tool(mcp_tool)
+```
+
+## Best Practices Demonstrated
+
+1. **Clear parameter documentation** - each parameter has a description
+2. **Sensible defaults** - optional parameters have reasonable defaults
+3. **Input validation** - check inputs before processing
+4. **Error handling** - graceful failure with informative messages
+5. **Structured outputs** - consistent, parseable return values
+6. **Helper method organization** - logical separation of concerns
+7. **Type safety** - appropriate parameter types for inputs

data/examples/docker_copy_tool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Example: Docker Copy Tool
+# Demonstrates class helper methods for utility functions
+
+require 'tool_forge'
+
+docker_copy_tool = ToolForge.define(:docker_copy) do
+  description 'Copies files to Docker containers with tar archive support'
+
+  param :container_id, type: :string, description: 'Docker container ID'
+  param :source_path, type: :string, description: 'Local file path to copy'
+  param :dest_path, type: :string, description: 'Destination path in container'
+  param :create_archive, type: :boolean, required: false, default: true
+
+  # Class helper method for tar operations
+  class_helper(:add_to_tar) do |file_path, tar_path|
+    # In a real implementation, this would create a tar archive
+    {
+      operation: 'tar_add',
+      source: file_path,
+      target: tar_path,
+      timestamp: Time.now.iso8601,
+      success: true
+    }
+  end
+
+  # Class helper method for container validation
+  class_helper(:validate_container_id) do |container_id|
+    # Simple validation - real implementation would check with Docker
+    container_id.match?(/^[a-f0-9]{12,64}$/)
+  end
+
+  # Instance helper method for formatting results
+  helper(:format_result) do |operation_result, container_id, dest_path|
+    if operation_result[:success]
+      "✅ Successfully copied to #{container_id}:#{dest_path} at #{operation_result[:timestamp]}"
+    else
+      "❌ Failed to copy: #{operation_result[:error]}"
+    end
+  end
+
+  execute do |container_id:, source_path:, dest_path:, create_archive:|
+    # Validate container ID using class helper
+    unless self.class.validate_container_id(container_id)
+      return { error: "Invalid container ID format: #{container_id}" }
+    end
+
+    # Check if source file exists
+    return { error: "Source file not found: #{source_path}" } unless File.exist?(source_path)
+
+    begin
+      if create_archive
+        # Use class helper for tar operations
+        tar_result = self.class.add_to_tar(source_path, dest_path)
+
+        # Use instance helper for formatting
+        format_result(tar_result, container_id, dest_path)
+      else
+        # Direct copy simulation
+        {
+          message: "Direct copy to #{container_id}:#{dest_path}",
+          source: source_path,
+          destination: dest_path,
+          method: 'direct_copy',
+          timestamp: Time.now.iso8601
+        }
+      end
+    rescue StandardError => e
+      { error: "Copy operation failed: #{e.message}" }
+    end
+  end
+end
+
+# Example usage:
+if __FILE__ == $PROGRAM_NAME
+  # This would normally require the actual RubyLLM or MCP frameworks
+  puts 'Docker Copy Tool Definition Created'
+  puts "Description: #{docker_copy_tool.description}"
+  puts "Parameters: #{docker_copy_tool.params.map { |p| p[:name] }.join(', ')}"
+  puts "Helper methods: #{docker_copy_tool.helper_methods.map { |type, methods| "#{type}: #{methods.keys}" }}"
+end

data/examples/file_processor_tool.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Example: File Processor Tool
+# Demonstrates instance helper methods and complex data processing
+
+require 'tool_forge'
+
+file_processor_tool = ToolForge.define(:file_processor) do
+  description 'Processes text files with various transformations and analysis'
+
+  param :file_path, type: :string, description: 'Path to the file to process'
+  param :operations, type: :array, description: 'List of operations to perform'
+  param :output_format, type: :string, required: false, default: 'json'
+  param :preserve_original, type: :boolean, required: false, default: true
+
+  # Instance helper methods for text processing
+  helper(:read_file_content) do |path|
+    return { error: "File not found: #{path}" } unless File.exist?(path)
+
+    {
+      content: File.read(path),
+      size: File.size(path),
+      lines: File.readlines(path).count,
+      encoding: File.read(path).encoding.name
+    }
+  end
+
+  helper(:analyze_text) do |content|
+    lines = content.lines
+    words = content.split(/\s+/)
+
+    {
+      character_count: content.length,
+      word_count: words.length,
+      line_count: lines.length,
+      average_line_length: lines.empty? ? 0 : (content.length.to_f / lines.length).round(2),
+      longest_word: words.max_by(&:length) || '',
+      unique_words: words.map(&:downcase).uniq.length
+    }
+  end
+
+  helper(:transform_text) do |content, operation|
+    case operation.downcase
+    when 'uppercase'
+      content.upcase
+    when 'lowercase'
+      content.downcase
+    when 'title_case'
+      content.split.map(&:capitalize).join(' ')
+    when 'reverse_lines'
+      content.lines.reverse.join
+    when 'reverse_words'
+      content.split.reverse.join(' ')
+    when 'remove_blank_lines'
+      content.lines.reject { |line| line.strip.empty? }.join
+    when 'number_lines'
+      content.lines.map.with_index(1) { |line, i| "#{i}. #{line}" }.join
+    else
+      content
+    end
+  end
+
+  helper(:format_output) do |data, format|
+    case format.downcase
+    when 'json'
+      JSON.pretty_generate(data)
+    when 'yaml'
+      begin
+        require 'yaml'
+        data.to_yaml
+      rescue LoadError
+        "YAML not available, falling back to JSON:\n#{JSON.pretty_generate(data)}"
+      end
+    when 'text'
+      if data.is_a?(Hash)
+        data.map { |k, v| "#{k}: #{v}" }.join("\n")
+      else
+        data.to_s
+      end
+    else
+      data.inspect
+    end
+  end
+
+  execute do |file_path:, operations:, output_format:, preserve_original:|
+    # Read the file
+    file_data = read_file_content(file_path)
+    return file_data if file_data[:error]
+
+    content = file_data[:content]
+    original_content = preserve_original ? content.dup : nil
+
+    # Process each operation
+    processed_content = content
+    operation_results = []
+
+    operations.each do |operation|
+      case operation.downcase
+      when 'analyze'
+        analysis = analyze_text(processed_content)
+        operation_results << { operation: operation, result: analysis }
+      else
+        # Text transformation
+        old_content = processed_content
+        processed_content = transform_text(processed_content, operation)
+        operation_results << {
+          operation: operation,
+          applied: old_content != processed_content,
+          preview: processed_content[0..100] + (processed_content.length > 100 ? '...' : '')
+        }
+      end
+    end
+
+    # Prepare final result
+    result = {
+      file_info: file_data.except(:content),
+      operations_applied: operation_results,
+      final_content: processed_content,
+      processing_summary: {
+        operations_count: operations.length,
+        content_changed: preserve_original ? (original_content != processed_content) : nil,
+        final_size: processed_content.length
+      }
+    }
+
+    result[:original_content] = original_content if preserve_original
+
+    # Format output according to preference
+    format_output(result, output_format)
+  rescue StandardError => e
+    format_output({ error: e.message, backtrace: e.backtrace.first(3) }, output_format)
+  end
+end
+
+# Example usage:
+if __FILE__ == $PROGRAM_NAME
+  puts 'File Processor Tool Definition Created'
+  puts "Description: #{file_processor_tool.description}"
+  puts "Parameters: #{file_processor_tool.params.map { |p| "#{p[:name]} (#{p[:type]})" }.join(', ')}"
+
+  # Example of what the tool can do:
+  puts "\nSupported operations:"
+  puts '- analyze: Provides text statistics'
+  puts '- uppercase, lowercase, title_case: Text case transformations'
+  puts '- reverse_lines, reverse_words: Content reversal'
+  puts '- remove_blank_lines: Cleanup operations'
+  puts '- number_lines: Add line numbers'
+end

data/lib/tool_forge/tool_definition.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module ToolForge
+  # ToolDefinition is the core class for defining tools that can be converted
+  # to both RubyLLM and MCP tool formats. It provides a clean DSL for defining
+  # tool metadata, parameters, helper methods, and execution logic.
+  #
+  # @example Basic tool definition
+  #   tool = ToolForge::ToolDefinition.new(:greet_user) do
+  #     description 'Greets a user by name'
+  #     param :name, type: :string, description: 'User name'
+  #     execute { |name:| "Hello, #{name}!" }
+  #   end
+  #
+  # @example Tool with helper methods
+  #   tool = ToolForge::ToolDefinition.new(:file_processor) do
+  #     description 'Processes files with helper methods'
+  #     param :file_path, type: :string
+  #
+  #     # Instance helper method
+  #     helper(:format_data) { |data| "FORMATTED: #{data}" }
+  #
+  #     # Class helper method (useful for utilities like tar operations)
+  #     class_helper(:add_to_tar) { |file, path| "Added #{file} to #{path}" }
+  #
+  #     execute do |file_path:|
+  #       data = File.read(file_path)
+  #       formatted = format_data(data)
+  #       tar_result = self.class.add_to_tar(file_path, '/archive')
+  #       "#{formatted} - #{tar_result}"
+  #     end
+  #   end
+  class ToolDefinition
+    # @return [Symbol] the name of the tool
+    # @return [Array<Hash>] the parameters defined for the tool
+    # @return [Proc] the execution block for the tool
+    # @return [Hash] the helper methods organized by type (:instance and :class)
+    attr_reader :name, :params, :execute_block, :helper_methods
+
+    # Creates a new tool definition with the given name.
+    #
+    # @param name [Symbol] the name of the tool
+    # @yield [] optional block for configuring the tool using the DSL
+    #
+    # @example
+    #   tool = ToolDefinition.new(:my_tool) do
+    #     description 'A sample tool'
+    #     param :input, type: :string
+    #     execute { |input:| "Processed: #{input}" }
+    #   end
+    def initialize(name, &)
+      @name = name
+      @description = nil
+      @params = []
+      @execute_block = nil
+      @helper_methods = { instance: {}, class: {} }
+
+      instance_eval(&) if block_given?
+    end
+
+    # Sets or returns the tool description.
+    #
+    # @param text [String, nil] the description text to set, or nil to return current description
+    # @return [String, nil] the current description when called without arguments
+    #
+    # @example Setting description
+    #   description 'This tool processes files'
+    #
+    # @example Getting description
+    #   tool.description #=> 'This tool processes files'
+    def description(text = nil)
+      if text
+        @description = text
+      else
+        @description
+      end
+    end
+
+    # Defines a parameter for the tool.
+    #
+    # @param name [Symbol] the parameter name
+    # @param type [Symbol] the parameter type (:string, :integer, :boolean, etc.)
+    # @param description [String, nil] optional description of the parameter
+    # @param required [Boolean] whether the parameter is required (default: true)
+    # @param default [Object, nil] default value for optional parameters
+    #
+    # @example Required string parameter
+    #   param :filename, type: :string, description: 'File to process'
+    #
+    # @example Optional parameter with default
+    #   param :format, type: :string, description: 'Output format', required: false, default: 'json'
+    def param(name, type: :string, description: nil, required: true, default: nil)
+      @params << {
+        name: name,
+        type: type,
+        description: description,
+        required: required,
+        default: default
+      }
+    end
+
+    # Defines the execution logic for the tool.
+    #
+    # @yield [**args] block that receives tool parameters as keyword arguments
+    # @return [void]
+    #
+    # @example
+    #   execute do |filename:, format:|
+    #     data = File.read(filename)
+    #     format == 'json' ? JSON.parse(data) : data
+    #   end
+    def execute(&block)
+      @execute_block = block
+    end
+
+    # Defines an instance helper method that can be called within the execute block.
+    # Instance helper methods are available as regular method calls in the execution context.
+    #
+    # @param method_name [Symbol] the name of the helper method
+    # @yield [*args] block that defines the helper method logic
+    # @return [void]
+    #
+    # @example
+    #   helper(:format_output) do |data|
+    #     "FORMATTED: #{data.upcase}"
+    #   end
+    #
+    #   execute do |input:|
+    #     format_output(input) # Called as instance method
+    #   end
+    def helper(method_name, &block)
+      @helper_methods[:instance][method_name] = block
+    end
+
+    # Defines a class helper method that can be called within the execute block.
+    # Class helper methods are useful for utility functions that don't depend on instance state.
+    # They are accessed via self.class.method_name in the execution context.
+    #
+    # @param method_name [Symbol] the name of the class helper method
+    # @yield [*args] block that defines the helper method logic
+    # @return [void]
+    #
+    # @example
+    #   class_helper(:add_to_tar) do |file_path, tar_path|
+    #     # Implementation for adding files to tar archive
+    #     "Added #{file_path} to tar as #{tar_path}"
+    #   end
+    #
+    #   execute do |file:|
+    #     self.class.add_to_tar(file, '/archive/file.tar') # Called as class method
+    #   end
+    def class_helper(method_name, &block)
+      @helper_methods[:class][method_name] = block
+    end
+
+    # Converts this tool definition to a RubyLLM::Tool class.
+    # The resulting class can be instantiated and used with the RubyLLM framework.
+    #
+    # Instance helper methods become instance methods on the generated class.
+    # Class helper methods become singleton methods on the generated class.
+    #
+    # @return [Class] a class that inherits from RubyLLM::Tool
+    # @raise [LoadError] if RubyLLM is not loaded
+    #
+    # @example
+    #   tool_class = tool_definition.to_ruby_llm_tool
+    #   instance = tool_class.new
+    #   result = instance.execute(filename: 'data.txt')
+    def to_ruby_llm_tool
+      raise LoadError, 'RubyLLM is not loaded. Please require "ruby_llm" first.' unless defined?(RubyLLM::Tool)
+      raise LoadError, 'RubyLLM is not loaded. Please require "ruby_llm" first.' if RubyLLM::Tool.nil?
+
+      definition = self
+
+      Class.new(RubyLLM::Tool) do
+        description definition.description
+
+        definition.params.each do |param_def|
+          param param_def[:name], type: param_def[:type], desc: param_def[:description]
+        end
+
+        # Add instance helper methods
+        definition.helper_methods[:instance].each do |method_name, method_block|
+          define_method(method_name, &method_block)
+        end
+
+        # Add class helper methods
+        definition.helper_methods[:class].each do |method_name, method_block|
+          define_singleton_method(method_name, &method_block)
+        end
+
+        define_method(:execute) do |**args|
+          # Execute the block in the context of this instance so helper methods are available
+          instance_exec(**args, &definition.execute_block)
+        end
+      end
+    end
+
+    # Converts this tool definition to an MCP::Tool class.
+    # The resulting class can be used with the Model Context Protocol framework.
+    #
+    # Both instance and class helper methods are available in the execution context.
+    # Class helper methods are accessed via self.class.method_name.
+    #
+    # @return [Class] a class that inherits from MCP::Tool
+    # @raise [LoadError] if MCP SDK is not loaded
+    #
+    # @example
+    #   tool_class = tool_definition.to_mcp_tool
+    #   result = tool_class.call(server_context: nil, filename: 'data.txt')
+    def to_mcp_tool
+      raise LoadError, 'MCP SDK is not loaded. Please require "mcp" first.' unless defined?(MCP::Tool)
+      raise LoadError, 'MCP SDK is not loaded. Please require "mcp" first.' if MCP::Tool.nil?
+
+      definition = self
+
+      Class.new(MCP::Tool) do
+        description definition.description
+
+        # Build properties hash for input schema
+        properties = {}
+        required_params = []
+
+        definition.params.each do |param_def|
+          prop = {
+            type: param_def[:type].to_s
+          }
+          prop[:description] = param_def[:description] if param_def[:description]
+
+          properties[param_def[:name].to_s] = prop
+          required_params << param_def[:name].to_s if param_def[:required]
+        end
+
+        input_schema(
+          properties: properties,
+          required: required_params
+        )
+
+        # Create a helper object that contains all the helper methods
+        helper_class = Class.new do
+          definition.helper_methods[:instance].each do |method_name, method_block|
+            define_method(method_name, &method_block)
+          end
+
+          # Class methods are defined as singleton methods on the class itself
+          definition.helper_methods[:class].each do |method_name, method_block|
+            define_singleton_method(method_name, &method_block)
+          end
+        end
+
+        define_singleton_method(:call) do |server_context:, **args|
+          # Create an instance of the helper class to provide context for helper methods
+          helper_instance = helper_class.new
+
+          # Execute the block in the context of the helper instance so helper methods are available
+          # For class methods, they'll be available on the helper_class itself
+          result = helper_instance.instance_exec(**args, &definition.execute_block)
+
+          # Smart formatting for different return types
+          result_text = case result
+                        when String
+                          result
+                        when Hash, Array
+                          JSON.pretty_generate(result)
+                        else
+                          result.to_s
+                        end
+
+          MCP::Tool::Response.new([{ type: 'text', text: result_text }])
+        end
+      end
+    end
+  end
+end

data/lib/tool_forge/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module ToolForge
-  VERSION = "0.0.1"
+  # The current version of the ToolForge gem
+  VERSION = '0.2.0'
 end

data/lib/tool_forge.rb

@@ -1,8 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "tool_forge/version"
+require 'json'
+require 'zeitwerk'
 
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.setup # ready!
+
+require_relative 'tool_forge/version'
+
+# ToolForge provides a unified DSL for defining tools that can be converted
+# to both RubyLLM and Model Context Protocol (MCP) formats.
+#
+# @example Basic usage
+#   tool = ToolForge.define(:greet_user) do
+#     description 'Greets a user by name'
+#     param :name, type: :string, description: 'User name'
+#     execute { |name:| "Hello, #{name}!" }
+#   end
+#
+#   # Convert to RubyLLM format
+#   ruby_llm_tool = tool.to_ruby_llm_tool
+#
+#   # Convert to MCP format
+#   mcp_tool = tool.to_mcp_tool
 module ToolForge
+  # Base error class for ToolForge-specific errors
   class Error < StandardError; end
-  # Your code goes here...
+
+  # Creates a new tool definition with the given name and configuration block.
+  #
+  # @param name [Symbol] the name of the tool
+  # @yield [] block for configuring the tool using the DSL
+  # @return [ToolDefinition] a new tool definition instance
+  #
+  # @example Define a simple tool
+  #   tool = ToolForge.define(:calculator) do
+  #     description 'Performs basic arithmetic'
+  #     param :operation, type: :string, description: 'Operation to perform'
+  #     param :a, type: :number, description: 'First number'
+  #     param :b, type: :number, description: 'Second number'
+  #
+  #     execute do |operation:, a:, b:|
+  #       case operation
+  #       when 'add' then a + b
+  #       when 'subtract' then a - b
+  #       when 'multiply' then a * b
+  #       when 'divide' then b != 0 ? a / b : 'Cannot divide by zero'
+  #       else 'Unknown operation'
+  #       end
+  #     end
+  #   end
+  def self.define(name, &)
+    ToolDefinition.new(name, &)
+  end
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: tool_forge
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron F Stanton
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Ruby gem for building AI tools for large language models using a simple
   domain-specific language.
 email:
@@ -20,7 +34,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/README.md
+- examples/docker_copy_tool.rb
+- examples/file_processor_tool.rb
 - lib/tool_forge.rb
+- lib/tool_forge/tool_definition.rb
 - lib/tool_forge/version.rb
 - sig/tool_forge.rbs
 homepage: https://github.com/afstanton/tool_forge
@@ -30,6 +48,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/afstanton/tool_forge
   source_code_uri: https://github.com/afstanton/tool_forge
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib