tsikol 0.1.0

data/docs/examples/echo-server.md

@@ -0,0 +1,501 @@
+# Echo Server Example
+
+A simple MCP server that echoes back input with various transformations.
+
+## Overview
+
+This example demonstrates:
+- Basic tool implementation
+- Parameter validation
+- Multiple operations in a single tool
+- Error handling
+- Logging
+
+## Implementation
+
+### server.rb
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'tsikol'
+
+# Simple echo tool with transformations
+class EchoTool < Tsikol::Tool
+  name "echo"
+  description "Echoes text with optional transformations"
+  
+  parameter :text do
+    type :string
+    required
+    description "Text to echo"
+  end
+  
+  parameter :transform do
+    type :string
+    optional
+    default "none"
+    enum ["none", "uppercase", "lowercase", "reverse", "capitalize"]
+    description "Transformation to apply"
+  end
+  
+  parameter :repeat do
+    type :number
+    optional
+    default 1
+    description "Number of times to repeat"
+  end
+  
+  def execute(text:, transform: "none", repeat: 1)
+    # Validate repeat count
+    if repeat < 1 || repeat > 10
+      raise ArgumentError, "Repeat must be between 1 and 10"
+    end
+    
+    # Apply transformation
+    result = case transform
+    when "uppercase"
+      text.upcase
+    when "lowercase"
+      text.downcase
+    when "reverse"
+      text.reverse
+    when "capitalize"
+      text.split.map(&:capitalize).join(" ")
+    else
+      text
+    end
+    
+    # Repeat if requested
+    if repeat > 1
+      result = Array.new(repeat, result).join(" ")
+    end
+    
+    log :info, "Echoed text", 
+        original_length: text.length,
+        transform: transform,
+        repeat: repeat
+    
+    result
+  end
+end
+
+# ASCII art generator tool
+class AsciiArtTool < Tsikol::Tool
+  name "ascii_art"
+  description "Generate simple ASCII art"
+  
+  parameter :type do
+    type :string
+    required
+    enum ["box", "banner", "divider"]
+    description "Type of ASCII art to generate"
+  end
+  
+  parameter :text do
+    type :string
+    optional
+    description "Text to include in the art"
+  end
+  
+  parameter :width do
+    type :number
+    optional
+    default 40
+    description "Width of the art"
+  end
+  
+  def execute(type:, text: nil, width: 40)
+    case type
+    when "box"
+      create_box(text || "Hello", width)
+    when "banner"
+      create_banner(text || "BANNER", width)
+    when "divider"
+      create_divider(width)
+    end
+  end
+  
+  private
+  
+  def create_box(text, width)
+    # Ensure text fits
+    text = text[0...width-4] if text.length > width - 4
+    
+    border = "+" + "-" * (width - 2) + "+"
+    padding = (width - 4 - text.length) / 2
+    content = "| " + " " * padding + text + " " * (width - 4 - padding - text.length) + " |"
+    
+    [border, content, border].join("\n")
+  end
+  
+  def create_banner(text, width)
+    text = text.upcase[0...width]
+    "=" * width + "\n" + text.center(width) + "\n" + "=" * width
+  end
+  
+  def create_divider(width)
+    "-" * width
+  end
+end
+
+# Start the server
+Tsikol.start(
+  name: "echo-server",
+  version: "1.0.0",
+  description: "Simple echo server with text transformations"
+) do
+  # Enable logging
+  logging true
+  
+  # Use logging middleware
+  use Tsikol::LoggingMiddleware, level: :info
+  
+  # Register tools
+  tool EchoTool
+  tool AsciiArtTool
+  
+  # Add a simple resource
+  resource "status" do
+    description "Server status information"
+    
+    def read
+      {
+        status: "operational",
+        uptime: Time.now - @started_at,
+        tools_available: ["echo", "ascii_art"],
+        requests_served: @request_count || 0
+      }.to_json
+    end
+  end
+  
+  # Track server start time
+  before_start do
+    @started_at = Time.now
+    @request_count = 0
+  end
+  
+  # Count requests
+  after_request do |request, response|
+    @request_count += 1
+  end
+end
+```
+
+### Gemfile
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'tsikol', '~> 1.0'
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+bundle install
+ruby server.rb
+```
+
+### Example Requests
+
+#### Basic Echo
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "echo",
+    "arguments": {
+      "text": "Hello, World!"
+    }
+  }
+}
+```
+
+Response:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Hello, World!"
+      }
+    ]
+  }
+}
+```
+
+#### Echo with Transformation
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "echo",
+    "arguments": {
+      "text": "Hello, World!",
+      "transform": "uppercase",
+      "repeat": 3
+    }
+  }
+}
+```
+
+Response:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "HELLO, WORLD! HELLO, WORLD! HELLO, WORLD!"
+      }
+    ]
+  }
+}
+```
+
+#### ASCII Art Generation
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "ascii_art",
+    "arguments": {
+      "type": "box",
+      "text": "Welcome",
+      "width": 30
+    }
+  }
+}
+```
+
+Response:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "+----------------------------+\n|         Welcome           |\n+----------------------------+"
+      }
+    ]
+  }
+}
+```
+
+#### Server Status
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "resources/read",
+  "params": {
+    "uri": "status"
+  }
+}
+```
+
+## Testing
+
+### test_echo_server.rb
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+require_relative 'server'
+
+class EchoServerTest < Minitest::Test
+  include Tsikol::TestHelpers
+  
+  def setup
+    @server = create_test_server
+    @client = TestClient.new(@server)
+  end
+  
+  def test_basic_echo
+    response = @client.call_tool("echo", {
+      "text" => "Hello, Test!"
+    })
+    
+    assert_successful_response(response)
+    assert_equal "Hello, Test!", response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_echo_with_uppercase
+    response = @client.call_tool("echo", {
+      "text" => "hello",
+      "transform" => "uppercase"
+    })
+    
+    assert_successful_response(response)
+    assert_equal "HELLO", response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_echo_with_repeat
+    response = @client.call_tool("echo", {
+      "text" => "Hi",
+      "repeat" => 3
+    })
+    
+    assert_successful_response(response)
+    assert_equal "Hi Hi Hi", response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_invalid_repeat_count
+    response = @client.call_tool("echo", {
+      "text" => "Test",
+      "repeat" => 20
+    })
+    
+    assert_error_response(response)
+    assert_match /between 1 and 10/, response[:error][:message]
+  end
+  
+  def test_ascii_art_box
+    response = @client.call_tool("ascii_art", {
+      "type" => "box",
+      "text" => "Test",
+      "width" => 20
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /\+\-+\+/, result
+    assert_match /Test/, result
+  end
+  
+  def test_server_status
+    response = @client.read_resource("status")
+    
+    assert_successful_response(response)
+    
+    status = JSON.parse(response.dig(:result, :contents, 0, :text))
+    assert_equal "operational", status["status"]
+    assert_includes status["tools_available"], "echo"
+    assert_includes status["tools_available"], "ascii_art"
+  end
+  
+  private
+  
+  def create_test_server
+    Tsikol::Server.new(name: "test-echo-server") do
+      tool EchoTool
+      tool AsciiArtTool
+      
+      resource "status" do
+        def read
+          { status: "operational" }.to_json
+        end
+      end
+    end
+  end
+end
+```
+
+Run tests:
+```bash
+ruby test_echo_server.rb
+```
+
+## Extensions
+
+### Adding More Transformations
+
+```ruby
+parameter :transform do
+  type :string
+  optional
+  default "none"
+  enum ["none", "uppercase", "lowercase", "reverse", "capitalize", 
+        "rot13", "leetspeak", "titlecase", "snakecase", "camelcase"]
+  description "Transformation to apply"
+end
+
+def execute(text:, transform: "none", repeat: 1)
+  result = case transform
+  when "rot13"
+    text.tr('A-Za-z', 'N-ZA-Mn-za-m')
+  when "leetspeak"
+    text.gsub(/[aeioAEIO]/, 'a' => '4', 'e' => '3', 'i' => '1', 'o' => '0',
+                           'A' => '4', 'E' => '3', 'I' => '1', 'O' => '0')
+  when "titlecase"
+    text.split.map { |word| word[0].upcase + word[1..-1].downcase }.join(" ")
+  when "snakecase"
+    text.downcase.gsub(/\s+/, '_')
+  when "camelcase"
+    text.split.map.with_index { |word, i| 
+      i == 0 ? word.downcase : word.capitalize 
+    }.join
+  # ... existing cases
+  end
+  
+  # ... rest of method
+end
+```
+
+### Adding Word Statistics
+
+```ruby
+class WordStatsTool < Tsikol::Tool
+  name "word_stats"
+  description "Analyze text and provide statistics"
+  
+  parameter :text do
+    type :string
+    required
+    description "Text to analyze"
+  end
+  
+  def execute(text:)
+    words = text.split(/\s+/)
+    
+    {
+      character_count: text.length,
+      word_count: words.length,
+      line_count: text.lines.count,
+      average_word_length: words.map(&:length).sum.to_f / words.length,
+      longest_word: words.max_by(&:length),
+      most_common_word: words.group_by(&:itself)
+                             .max_by { |_, v| v.length }
+                             &.first
+    }.to_json
+  end
+end
+```
+
+## Best Practices Demonstrated
+
+1. **Parameter Validation** - Check bounds and provide clear errors
+2. **Comprehensive Logging** - Log operations for debugging
+3. **Error Handling** - Graceful handling of invalid inputs
+4. **Testing** - Full test coverage including edge cases
+5. **Documentation** - Clear examples and usage instructions
+6. **Extensibility** - Easy to add new transformations
+7. **Resource Monitoring** - Status endpoint for health checks
+
+## Next Steps
+
+- Add more text transformation options
+- Implement caching for repeated requests
+- Add rate limiting for production use
+- Create a web UI for interactive testing
+- Add persistent storage for echo history