tsikol 0.1.0

data/docs/guides/tools.md

@@ -0,0 +1,627 @@
+# Tools Guide
+
+Tools are functions that MCP clients can call to perform actions. This guide covers everything you need to know about creating and using tools in Tsikol.
+
+## Table of Contents
+
+1. [What are Tools?](#what-are-tools)
+2. [Creating Tools](#creating-tools)
+3. [Parameters](#parameters)
+4. [Parameter Types](#parameter-types)
+5. [Completions](#completions)
+6. [Error Handling](#error-handling)
+7. [Logging](#logging)
+8. [Advanced Patterns](#advanced-patterns)
+9. [Testing Tools](#testing-tools)
+
+## What are Tools?
+
+Tools are the primary way MCP clients interact with your server. They:
+- Accept parameters
+- Perform actions
+- Return results
+- Can have side effects
+
+Think of tools as API endpoints that AI can call.
+
+## Creating Tools
+
+### Inline Tools
+
+Quick tools defined directly in server.rb:
+
+```ruby
+Tsikol.server "my-server" do
+  tool "greet" do |name:|
+    "Hello, #{name}!"
+  end
+  
+  tool "calculate" do |a:, b:, operation: "add"|
+    case operation
+    when "add" then a + b
+    when "subtract" then a - b
+    when "multiply" then a * b
+    when "divide" then b.zero? ? "Error: Division by zero" : a.to_f / b
+    end
+  end
+end
+```
+
+### Class-Based Tools
+
+For complex tools, use classes:
+
+```ruby
+# app/tools/file_processor.rb
+class FileProcessor < Tsikol::Tool
+  description "Process files with various operations"
+  
+  parameter :file_path do
+    type :string
+    required
+    description "Path to the file to process"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*")
+    end
+  end
+  
+  parameter :operation do
+    type :string
+    required
+    enum ["read", "analyze", "compress", "convert"]
+    description "Operation to perform"
+  end
+  
+  parameter :options do
+    type :object
+    optional
+    description "Additional options for the operation"
+  end
+  
+  def execute(file_path:, operation:, options: {})
+    unless File.exist?(file_path)
+      raise Tsikol::ValidationError, "File not found: #{file_path}"
+    end
+    
+    case operation
+    when "read"
+      read_file(file_path, options)
+    when "analyze"
+      analyze_file(file_path, options)
+    when "compress"
+      compress_file(file_path, options)
+    when "convert"
+      convert_file(file_path, options)
+    end
+  end
+  
+  private
+  
+  def read_file(path, options)
+    encoding = options["encoding"] || "UTF-8"
+    File.read(path, encoding: encoding)
+  end
+  
+  def analyze_file(path, options)
+    content = File.read(path)
+    {
+      size: File.size(path),
+      lines: content.lines.count,
+      words: content.split.count,
+      type: File.extname(path)
+    }.to_json
+  end
+  
+  def compress_file(path, options)
+    # Implementation
+    "Compressed #{path}"
+  end
+  
+  def convert_file(path, options)
+    # Implementation
+    "Converted #{path}"
+  end
+end
+```
+
+## Parameters
+
+### Basic Parameters
+
+```ruby
+parameter :name do
+  type :string
+  required
+  description "User's name"
+end
+
+parameter :age do
+  type :integer
+  optional
+  default 18
+  description "User's age"
+end
+```
+
+### Parameter Options
+
+All available parameter options:
+
+```ruby
+parameter :example do
+  type :string              # :string, :number, :integer, :boolean, :array, :object
+  required                  # or optional
+  default "value"          # Default value if optional
+  description "Purpose"    # What this parameter does
+  enum ["opt1", "opt2"]   # Allowed values
+  
+  complete do |partial|    # Autocomplete suggestions
+    # Return array of suggestions
+  end
+end
+```
+
+## Parameter Types
+
+### String Parameters
+
+```ruby
+parameter :message do
+  type :string
+  required
+  description "Message to process"
+end
+
+parameter :format do
+  type :string
+  optional
+  default "plain"
+  enum ["plain", "markdown", "html"]
+end
+```
+
+### Number Parameters
+
+```ruby
+parameter :amount do
+  type :number
+  required
+  description "Amount in dollars"
+end
+
+parameter :percentage do
+  type :number
+  optional
+  default 0.0
+  description "Percentage (0-100)"
+end
+```
+
+### Boolean Parameters
+
+```ruby
+parameter :verbose do
+  type :boolean
+  optional
+  default false
+  description "Enable verbose output"
+end
+```
+
+### Array Parameters
+
+```ruby
+parameter :tags do
+  type :array
+  optional
+  default []
+  description "List of tags"
+end
+
+def execute(tags: [])
+  # tags is an array
+  tags.join(", ")
+end
+```
+
+### Object Parameters
+
+```ruby
+parameter :config do
+  type :object
+  optional
+  description "Configuration object"
+end
+
+def execute(config: {})
+  # config is a hash
+  timeout = config["timeout"] || 30
+  retries = config["retries"] || 3
+end
+```
+
+## Completions
+
+Add intelligent autocomplete to parameters:
+
+### Static Completions
+
+```ruby
+parameter :language do
+  type :string
+  required
+  
+  complete do |partial|
+    languages = ["ruby", "python", "javascript", "go", "rust"]
+    languages.select { |lang| lang.start_with?(partial.downcase) }
+  end
+end
+```
+
+### Dynamic Completions
+
+```ruby
+parameter :file do
+  type :string
+  required
+  
+  complete do |partial|
+    # File system completion
+    Dir.glob("#{partial}*").map do |path|
+      File.directory?(path) ? "#{path}/" : path
+    end
+  end
+end
+```
+
+### Context-Aware Completions
+
+```ruby
+parameter :branch do
+  type :string
+  required
+  
+  complete do |partial, context|
+    # Access other parameters via context
+    repo = context[:repository]
+    
+    branches = fetch_branches_for_repo(repo)
+    branches.select { |b| b.include?(partial) }
+  end
+end
+```
+
+## Error Handling
+
+### Validation Errors
+
+```ruby
+def execute(file_path:)
+  unless File.exist?(file_path)
+    raise Tsikol::ValidationError, "File not found: #{file_path}"
+  end
+  
+  unless File.readable?(file_path)
+    raise Tsikol::ValidationError, "File not readable: #{file_path}"
+  end
+  
+  process_file(file_path)
+end
+```
+
+### Graceful Degradation
+
+```ruby
+def execute(url:)
+  begin
+    response = fetch_url(url)
+    process_response(response)
+  rescue Net::HTTPError => e
+    log :error, "HTTP error", data: { url: url, error: e.message }
+    "Unable to fetch URL: #{e.message}"
+  rescue => e
+    log :error, "Unexpected error", data: { error: e.class.name }
+    "An error occurred. Please try again."
+  end
+end
+```
+
+## Logging
+
+### Basic Logging
+
+```ruby
+def execute(task:)
+  log :info, "Starting task", data: { task: task }
+  
+  result = perform_task(task)
+  
+  log :info, "Task completed", data: { task: task, result: result }
+  
+  result
+end
+```
+
+### Log Levels
+
+```ruby
+log :debug, "Detailed information"
+log :info, "General information"
+log :warning, "Warning message"
+log :error, "Error occurred", data: { error: error.message }
+```
+
+### Enabling Logging
+
+```ruby
+def set_server(server)
+  @server = server
+  
+  define_singleton_method(:log) do |level, message, data: nil|
+    @server.log(level, message, data: data)
+  end
+end
+```
+
+## Advanced Patterns
+
+### Async Operations
+
+```ruby
+class AsyncProcessor < Tsikol::Tool
+  description "Process data asynchronously"
+  
+  parameter :data do
+    type :string
+    required
+  end
+  
+  parameter :callback_url do
+    type :string
+    optional
+    description "URL to call when complete"
+  end
+  
+  def execute(data:, callback_url: nil)
+    job_id = SecureRandom.uuid
+    
+    # Start async job
+    Thread.new do
+      result = process_data(data)
+      
+      if callback_url
+        notify_completion(callback_url, job_id, result)
+      end
+    end
+    
+    {
+      job_id: job_id,
+      status: "processing",
+      message: "Job started. Use job_id to check status."
+    }.to_json
+  end
+end
+```
+
+### Batch Operations
+
+```ruby
+class BatchProcessor < Tsikol::Tool
+  description "Process multiple items"
+  
+  parameter :items do
+    type :array
+    required
+    description "Items to process"
+  end
+  
+  parameter :parallel do
+    type :boolean
+    optional
+    default false
+    description "Process in parallel"
+  end
+  
+  def execute(items:, parallel: false)
+    if parallel
+      process_parallel(items)
+    else
+      process_sequential(items)
+    end
+  end
+  
+  private
+  
+  def process_parallel(items)
+    threads = items.map do |item|
+      Thread.new { process_item(item) }
+    end
+    
+    results = threads.map(&:value)
+    format_results(results)
+  end
+  
+  def process_sequential(items)
+    results = items.map { |item| process_item(item) }
+    format_results(results)
+  end
+end
+```
+
+### Tool Composition
+
+```ruby
+class CompositeTool < Tsikol::Tool
+  description "Combines multiple operations"
+  
+  def execute(input:)
+    # Step 1: Validate
+    validated = ValidationTool.new.execute(data: input)
+    
+    # Step 2: Process
+    processed = ProcessingTool.new.execute(data: validated)
+    
+    # Step 3: Format
+    FormattingTool.new.execute(data: processed)
+  end
+end
+```
+
+### Caching Results
+
+```ruby
+class CachedTool < Tsikol::Tool
+  def initialize
+    super
+    @cache = {}
+  end
+  
+  def execute(query:)
+    cache_key = generate_cache_key(query)
+    
+    if cached = @cache[cache_key]
+      log :debug, "Cache hit", data: { key: cache_key }
+      return cached[:result]
+    end
+    
+    result = expensive_operation(query)
+    
+    @cache[cache_key] = {
+      result: result,
+      timestamp: Time.now
+    }
+    
+    # Clean old entries
+    clean_cache if @cache.size > 100
+    
+    result
+  end
+  
+  private
+  
+  def generate_cache_key(query)
+    Digest::SHA256.hexdigest(query)
+  end
+  
+  def clean_cache
+    cutoff = Time.now - 3600 # 1 hour
+    @cache.delete_if { |_, v| v[:timestamp] < cutoff }
+  end
+end
+```
+
+## Testing Tools
+
+### Basic Tool Test
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class FileProcessorTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.register_tool_instance(FileProcessor.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_read_file
+    # Create test file
+    File.write("test.txt", "Hello, World!")
+    
+    response = @client.call_tool("file_processor", {
+      "file_path" => "test.txt",
+      "operation" => "read"
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_equal "Hello, World!", result
+  ensure
+    File.delete("test.txt") if File.exist?("test.txt")
+  end
+  
+  def test_file_not_found
+    response = @client.call_tool("file_processor", {
+      "file_path" => "nonexistent.txt",
+      "operation" => "read"
+    })
+    
+    assert_error_response(response, -32603)
+    assert_match /File not found/, response[:error][:message]
+  end
+end
+```
+
+### Testing Completions
+
+```ruby
+def test_language_completion
+  response = @client.complete(
+    { type: "ref/tool", name: "code_analyzer" },
+    { name: "language", value: "ru" }
+  )
+  
+  assert_successful_response(response)
+  values = response.dig(:result, :completion, :values)
+  assert_includes values, "ruby"
+  assert_includes values, "rust"
+end
+```
+
+### Mocking External Dependencies
+
+```ruby
+class ExternalApiToolTest < Minitest::Test
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @tool = ExternalApiTool.new
+    
+    # Mock external API
+    @tool.define_singleton_method(:fetch_from_api) do |endpoint|
+      case endpoint
+      when "/users"
+        [{ id: 1, name: "Test User" }]
+      when "/error"
+        raise "API Error"
+      else
+        []
+      end
+    end
+    
+    @server.register_tool_instance(@tool)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def test_successful_api_call
+    response = @client.call_tool("external_api", {
+      "endpoint" => "/users"
+    })
+    
+    assert_successful_response(response)
+    result = JSON.parse(response.dig(:result, :content, 0, :text))
+    assert_equal 1, result.first["id"]
+  end
+end
+```
+
+## Best Practices
+
+1. **Clear Descriptions**: Help users understand what your tool does
+2. **Validate Input**: Check parameters before processing
+3. **Handle Errors**: Provide helpful error messages
+4. **Add Completions**: Make tools easier to use
+5. **Log Important Events**: Aid debugging and monitoring
+6. **Keep It Focused**: Each tool should do one thing well
+7. **Test Thoroughly**: Cover success and error cases
+
+## Next Steps
+
+- Learn about [Resources](resources.md)
+- Explore [Prompts](prompts.md)
+- Add [Completions](completion.md)
+- Set up [Testing](testing.md)

data/examples/README.md

@@ -0,0 +1,92 @@
+# Tsikol Examples
+
+This directory contains example MCP servers built with Tsikol, demonstrating various features and patterns.
+
+## Examples Overview
+
+### 1. [basic.rb](basic.rb)
+A simple inline server showing the original DSL-style API. Great for quick prototypes.
+
+```bash
+ruby examples/basic.rb
+```
+
+### 2. [basic-migrated/](basic-migrated/)
+Shows how to migrate from inline DSL to the Rails-like structure with separate files.
+
+```bash
+cd examples/basic-migrated
+./server.rb
+```
+
+### 3. [weather-service/](weather-service/)
+Full-featured example with namespaced modules and proper project structure.
+
+```bash
+cd examples/weather-service
+./server.rb
+```
+
+### 4. [middleware_example.rb](middleware_example.rb)
+Demonstrates the middleware system with authentication, rate limiting, and custom middleware.
+
+```bash
+ruby examples/middleware_example.rb
+```
+
+### 5. [sampling_example.rb](sampling_example.rb)
+Shows how to use sampling for AI-assisted features.
+
+```bash
+ruby examples/sampling_example.rb
+```
+
+### 6. [advanced_features.rb](advanced_features.rb)
+Demonstrates lifecycle hooks, error handling, and health monitoring.
+
+```bash
+ruby examples/advanced_features.rb
+```
+
+### 7. [full_featured.rb](full_featured.rb)
+Complete example showing all Tsikol features working together.
+
+```bash
+ruby examples/full_featured.rb
+```
+
+## Running Examples
+
+All examples can be run directly:
+
+```bash
+# From the gem root
+ruby examples/basic.rb
+
+# Or make them executable
+chmod +x examples/basic.rb
+./examples/basic.rb
+```
+
+For structured examples with directories:
+
+```bash
+cd examples/weather-service
+bundle install  # If needed
+./server.rb
+```
+
+## Testing Examples
+
+Connect with MCP Inspector or any MCP client to test the servers.
+
+## Creating Your Own
+
+Use the Tsikol CLI to create your own project:
+
+```bash
+tsikol new my-project
+cd my-project
+bundle install
+./server.rb
+```