tsikol 0.1.0

data/docs/examples/complete-server.md

@@ -0,0 +1,726 @@
+# Complete MCP Server Example
+
+This example demonstrates all Tsikol features in a production-ready MCP server.
+
+## Full Implementation
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'tsikol'
+
+# Complete MCP server with all features
+Tsikol.start(name: "complete-mcp-server") do
+  # Load components from files
+  require_relative 'app/tools/code_analyzer'
+  require_relative 'app/tools/file_manager'
+  require_relative 'app/tools/ai_assistant'
+  require_relative 'app/resources/project_info'
+  require_relative 'app/resources/system_status'
+  require_relative 'app/prompts/development_chat'
+  
+  # Register components
+  tool CodeAnalyzer
+  tool FileManager
+  tool AiAssistant
+  resource ProjectInfo
+  resource SystemStatus
+  prompt DevelopmentChat
+  
+  # Enable all capabilities
+  logging true
+  completion true
+  
+  # Configure sampling for AI features
+  on_sampling do |request|
+    # In production, the MCP client handles this
+    # This is for testing/development
+    {
+      role: "assistant",
+      content: {
+        type: "text",
+        text: "AI response for: #{request[:messages].last[:content][:text]}"
+      }
+    }
+  end
+  
+  # Add middleware stack
+  use Tsikol::ValidationMiddleware
+  use Tsikol::LoggingMiddleware
+  use Tsikol::RateLimitMiddleware, max_requests: 100, window: 60
+  use AuthenticationMiddleware
+  use MetricsMiddleware
+  
+  # Lifecycle hooks
+  before_start do
+    log :info, "Initializing complete MCP server..."
+    @start_time = Time.now
+    load_configuration
+    initialize_connections
+  end
+  
+  after_start do
+    log :info, "Server ready!", data: {
+      tools: @tool_instances.keys,
+      resources: @resource_instances.keys,
+      capabilities: @server_capabilities.keys
+    }
+  end
+  
+  before_stop do
+    log :info, "Shutting down gracefully..."
+    save_state
+    close_connections
+  end
+  
+  after_stop do
+    uptime = Time.now - @start_time
+    log :info, "Server stopped", data: { uptime: uptime }
+  end
+  
+  # Tool-specific hooks
+  before_tool do |tool_name, params|
+    log :debug, "Executing tool: #{tool_name}", data: { params: params }
+    @metrics.increment("tools.#{tool_name}.calls")
+  end
+  
+  after_tool do |tool_name, params, result|
+    log :debug, "Tool completed: #{tool_name}"
+    track_tool_usage(tool_name, result)
+  end
+  
+  # Error handling for specific tools
+  before_tool "ai_assistant" do |params|
+    validate_ai_request(params)
+  end
+  
+  # Inline tools for simple operations
+  tool "ping" do
+    "pong"
+  end
+  
+  tool "echo" do |message:|
+    message
+  end
+  
+  # Inline resources
+  resource "health" do
+    {
+      status: "healthy",
+      uptime: Time.now - @start_time,
+      version: Tsikol::VERSION
+    }.to_json
+  end
+  
+  # Helper methods
+  private
+  
+  def load_configuration
+    # Load config from file or environment
+    @config = {
+      max_file_size: ENV.fetch('MAX_FILE_SIZE', 1024 * 1024).to_i,
+      allowed_extensions: %w[rb py js ts go rs java c cpp md txt json yaml],
+      ai_model: ENV.fetch('AI_MODEL', 'claude-3-sonnet')
+    }
+  end
+  
+  def initialize_connections
+    # Initialize any external connections
+    @cache = {}
+    @metrics = Tsikol::Metrics.new
+  end
+  
+  def save_state
+    # Save any persistent state
+    File.write('server_state.json', {
+      last_shutdown: Time.now,
+      total_requests: @metrics.get(:requests_total)
+    }.to_json)
+  end
+  
+  def close_connections
+    # Clean up connections
+    @cache.clear
+  end
+  
+  def track_tool_usage(tool_name, result)
+    # Track metrics
+    @metrics.increment("tools.#{tool_name}.success") if result
+  end
+  
+  def validate_ai_request(params)
+    # Validate AI requests
+    raise "Message too long" if params[:message]&.length > 10000
+  end
+end
+
+# Custom middleware
+class AuthenticationMiddleware < Tsikol::Middleware
+  def before_request(message)
+    # Skip auth for certain methods
+    return message if %w[initialize ping health tools/list].include?(message["method"])
+    
+    # Check authentication
+    token = message.dig("metadata", "auth_token")
+    unless valid_token?(token)
+      raise Tsikol::AuthenticationError, "Invalid authentication token"
+    end
+    
+    message
+  end
+  
+  private
+  
+  def valid_token?(token)
+    # In production, validate against real auth system
+    token == ENV['MCP_AUTH_TOKEN']
+  end
+end
+
+class MetricsMiddleware < Tsikol::Middleware
+  def initialize(app)
+    super
+    @metrics = {}
+  end
+  
+  def before_request(message)
+    message["_start_time"] = Time.now
+    message
+  end
+  
+  def after_response(response, original_message)
+    duration = Time.now - original_message["_start_time"]
+    track_metric(original_message["method"], duration)
+    response
+  end
+  
+  private
+  
+  def track_metric(method, duration)
+    @metrics[method] ||= []
+    @metrics[method] << duration
+    
+    # Log slow requests
+    if duration > 1.0
+      log :warning, "Slow request", data: {
+        method: method,
+        duration: duration
+      }
+    end
+  end
+end
+```
+
+## Component Files
+
+### app/tools/code_analyzer.rb
+
+```ruby
+# frozen_string_literal: true
+
+class CodeAnalyzer < Tsikol::Tool
+  description "Analyze code quality and complexity"
+  
+  parameter :file_path do
+    type :string
+    required
+    description "Path to file to analyze"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*").select { |f| 
+        f.match?(/\.(rb|py|js|ts|go)$/) 
+      }
+    end
+  end
+  
+  parameter :analysis_type do
+    type :string
+    optional
+    default "all"
+    enum ["complexity", "style", "security", "performance", "all"]
+    
+    complete do |partial|
+      ["complexity", "style", "security", "performance", "all"]
+        .select { |t| t.start_with?(partial) }
+    end
+  end
+  
+  def execute(file_path:, analysis_type: "all")
+    unless File.exist?(file_path)
+      raise Tsikol::ValidationError, "File not found: #{file_path}"
+    end
+    
+    log :info, "Analyzing #{file_path}", data: { type: analysis_type }
+    
+    code = File.read(file_path)
+    results = {}
+    
+    if analysis_type == "all" || analysis_type == "complexity"
+      results[:complexity] = analyze_complexity(code)
+    end
+    
+    if analysis_type == "all" || analysis_type == "style"
+      results[:style] = analyze_style(code)
+    end
+    
+    if analysis_type == "all" || analysis_type == "security"
+      results[:security] = analyze_security(code)
+    end
+    
+    if analysis_type == "all" || analysis_type == "performance"
+      results[:performance] = analyze_performance(code)
+    end
+    
+    format_results(results)
+  end
+  
+  private
+  
+  def analyze_complexity(code)
+    lines = code.lines.count
+    methods = code.scan(/def\s+\w+/).count
+    classes = code.scan(/class\s+\w+/).count
+    
+    {
+      lines_of_code: lines,
+      methods: methods,
+      classes: classes,
+      complexity_score: calculate_complexity_score(code)
+    }
+  end
+  
+  def analyze_style(code)
+    issues = []
+    
+    # Check line length
+    code.lines.each_with_index do |line, index|
+      if line.chomp.length > 100
+        issues << "Line #{index + 1}: Too long (#{line.chomp.length} chars)"
+      end
+    end
+    
+    # Check indentation
+    if code.match?(/\t/)
+      issues << "Uses tabs instead of spaces"
+    end
+    
+    {
+      style_issues: issues,
+      passed: issues.empty?
+    }
+  end
+  
+  def analyze_security(code)
+    vulnerabilities = []
+    
+    # Check for common security issues
+    if code.match?(/eval\s*\(/)
+      vulnerabilities << "Uses eval() - potential security risk"
+    end
+    
+    if code.match?(/system\s*\(|`.*`/)
+      vulnerabilities << "Executes system commands - verify input sanitization"
+    end
+    
+    {
+      vulnerabilities: vulnerabilities,
+      secure: vulnerabilities.empty?
+    }
+  end
+  
+  def analyze_performance(code)
+    suggestions = []
+    
+    # Look for performance anti-patterns
+    if code.match?(/\.select.*\.first/)
+      suggestions << "Use .find instead of .select.first"
+    end
+    
+    if code.match?(/\+\s*=.*loop/)
+      suggestions << "String concatenation in loop - consider using array.join"
+    end
+    
+    {
+      suggestions: suggestions,
+      optimized: suggestions.empty?
+    }
+  end
+  
+  def calculate_complexity_score(code)
+    # Simple cyclomatic complexity estimate
+    score = 1
+    score += code.scan(/\bif\b|\belsif\b|\bcase\b|\bwhen\b/).count
+    score += code.scan(/\bwhile\b|\bfor\b|\buntil\b/).count
+    score += code.scan(/\brescue\b/).count
+    score
+  end
+  
+  def format_results(results)
+    output = ["Code Analysis Results", "=" * 50]
+    
+    results.each do |type, data|
+      output << "\n#{type.to_s.capitalize} Analysis:"
+      output << JSON.pretty_generate(data)
+    end
+    
+    output.join("\n")
+  end
+  
+  def set_server(server)
+    @server = server
+    define_singleton_method(:log) do |level, message, data: nil|
+      @server.log(level, message, data: data)
+    end
+  end
+end
+```
+
+### app/tools/file_manager.rb
+
+```ruby
+# frozen_string_literal: true
+
+class FileManager < Tsikol::Tool
+  description "Manage project files"
+  
+  parameter :action do
+    type :string
+    required
+    enum ["list", "read", "create", "update", "delete", "search"]
+    
+    complete do |partial|
+      ["list", "read", "create", "update", "delete", "search"]
+        .select { |a| a.start_with?(partial) }
+    end
+  end
+  
+  parameter :path do
+    type :string
+    required
+    description "File or directory path"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*")
+    end
+  end
+  
+  parameter :content do
+    type :string
+    optional
+    description "Content for create/update operations"
+  end
+  
+  parameter :pattern do
+    type :string
+    optional
+    description "Search pattern for search operation"
+  end
+  
+  def execute(action:, path:, content: nil, pattern: nil)
+    case action
+    when "list"
+      list_directory(path)
+    when "read"
+      read_file(path)
+    when "create"
+      create_file(path, content)
+    when "update"
+      update_file(path, content)
+    when "delete"
+      delete_file(path)
+    when "search"
+      search_files(path, pattern)
+    else
+      raise Tsikol::ValidationError, "Unknown action: #{action}"
+    end
+  end
+  
+  private
+  
+  def list_directory(path)
+    unless File.directory?(path)
+      raise Tsikol::ValidationError, "Not a directory: #{path}"
+    end
+    
+    entries = Dir.entries(path).reject { |e| e.start_with?('.') }
+    
+    entries.map do |entry|
+      full_path = File.join(path, entry)
+      {
+        name: entry,
+        type: File.directory?(full_path) ? "directory" : "file",
+        size: File.size(full_path),
+        modified: File.mtime(full_path).iso8601
+      }
+    end.to_json
+  end
+  
+  def read_file(path)
+    unless File.exist?(path)
+      raise Tsikol::ValidationError, "File not found: #{path}"
+    end
+    
+    File.read(path)
+  end
+  
+  def create_file(path, content)
+    if File.exist?(path)
+      raise Tsikol::ValidationError, "File already exists: #{path}"
+    end
+    
+    File.write(path, content || "")
+    "File created: #{path}"
+  end
+  
+  def update_file(path, content)
+    unless File.exist?(path)
+      raise Tsikol::ValidationError, "File not found: #{path}"
+    end
+    
+    File.write(path, content)
+    "File updated: #{path}"
+  end
+  
+  def delete_file(path)
+    unless File.exist?(path)
+      raise Tsikol::ValidationError, "File not found: #{path}"
+    end
+    
+    File.delete(path)
+    "File deleted: #{path}"
+  end
+  
+  def search_files(path, pattern)
+    unless pattern
+      raise Tsikol::ValidationError, "Pattern required for search"
+    end
+    
+    matches = []
+    
+    Dir.glob("#{path}/**/*").each do |file|
+      next if File.directory?(file)
+      
+      begin
+        content = File.read(file)
+        if content.match?(Regexp.new(pattern, Regexp::IGNORECASE))
+          matches << {
+            file: file,
+            matches: content.lines.select { |line| 
+              line.match?(Regexp.new(pattern, Regexp::IGNORECASE)) 
+            }.first(3)
+          }
+        end
+      rescue => e
+        log :warning, "Error reading #{file}", data: { error: e.message }
+      end
+    end
+    
+    matches.to_json
+  end
+  
+  def set_server(server)
+    @server = server
+    define_singleton_method(:log) do |level, message, data: nil|
+      @server.log(level, message, data: data)
+    end
+  end
+end
+```
+
+### app/resources/system_status.rb
+
+```ruby
+# frozen_string_literal: true
+
+class SystemStatus < Tsikol::Resource
+  uri "system/status"
+  description "Current system status and metrics"
+  
+  def read
+    {
+      server: {
+        name: "complete-mcp-server",
+        version: Tsikol::VERSION,
+        protocol_version: Tsikol::PROTOCOL_VERSION,
+        uptime: calculate_uptime
+      },
+      system: {
+        ruby_version: RUBY_VERSION,
+        platform: RUBY_PLATFORM,
+        pid: Process.pid,
+        memory_usage: get_memory_usage
+      },
+      metrics: {
+        total_requests: @server.metrics.get(:requests_total),
+        active_requests: @server.metrics.get(:active_requests),
+        error_rate: calculate_error_rate,
+        average_response_time: @server.metrics.average(:response_time)
+      },
+      capabilities: @server.instance_variable_get(:@server_capabilities).keys,
+      health: determine_health_status
+    }.to_json
+  end
+  
+  private
+  
+  def calculate_uptime
+    start_time = @server.instance_variable_get(:@start_time)
+    return 0 unless start_time
+    Time.now - start_time
+  end
+  
+  def get_memory_usage
+    # Simple memory usage estimate
+    "#{(GC.stat[:heap_live_slots] * 40.0 / 1024 / 1024).round(2)}MB"
+  end
+  
+  def calculate_error_rate
+    total = @server.metrics.get(:requests_total)
+    errors = @server.metrics.get(:errors_total)
+    
+    return 0.0 if total == 0
+    (errors.to_f / total * 100).round(2)
+  end
+  
+  def determine_health_status
+    error_rate = calculate_error_rate
+    
+    if error_rate > 50
+      "critical"
+    elsif error_rate > 10
+      "degraded"
+    else
+      "healthy"
+    end
+  end
+  
+  def set_server(server)
+    @server = server
+  end
+end
+```
+
+## Testing the Server
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class CompleteServerTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    # Load the server
+    require_relative '../server'
+    @server = $tsikol_server # Set by server.rb
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    
+    # Initialize connection
+    @client.initialize_connection
+  end
+  
+  def test_ping
+    response = @client.request("ping")
+    assert_successful_response(response)
+    assert_equal({}, response[:result])
+  end
+  
+  def test_echo_tool
+    response = @client.call_tool("echo", { "message" => "Hello MCP!" })
+    assert_successful_response(response)
+    assert_equal "Hello MCP!", response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_code_analyzer
+    # Create test file
+    File.write("test.rb", "def hello\n  puts 'Hi'\nend")
+    
+    response = @client.call_tool("code_analyzer", {
+      "file_path" => "test.rb",
+      "analysis_type" => "complexity"
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_includes result, "Complexity Analysis"
+  ensure
+    File.delete("test.rb") if File.exist?("test.rb")
+  end
+  
+  def test_system_status_resource
+    response = @client.read_resource("system/status")
+    assert_successful_response(response)
+    
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    assert_equal "complete-mcp-server", data["server"]["name"]
+    assert_includes ["healthy", "degraded", "critical"], data["health"]
+  end
+  
+  def test_health_check
+    response = @client.read_resource("health")
+    assert_successful_response(response)
+    
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    assert_equal "healthy", data["status"]
+  end
+  
+  def test_completion
+    # Test tool parameter completion
+    response = @client.complete(
+      { type: "ref/tool", name: "code_analyzer" },
+      { name: "analysis_type", value: "sec" }
+    )
+    
+    assert_successful_response(response)
+    values = response.dig(:result, :completion, :values)
+    assert_includes values, "security"
+  end
+  
+  def test_rate_limiting
+    # Make many requests quickly
+    100.times do
+      @client.call_tool("echo", { "message" => "test" })
+    end
+    
+    # Next request should fail with rate limit
+    response = @client.call_tool("echo", { "message" => "test" })
+    assert response[:error]
+    assert_includes response[:error][:message], "Rate limit"
+  end
+end
+```
+
+## Running the Server
+
+1. Save all files in the appropriate directories
+2. Run the server:
+   ```bash
+   ./server.rb
+   ```
+3. Connect with MCP Inspector or any MCP client
+4. The server supports:
+   - All MCP protocol methods including ping
+   - Tools with completion
+   - Resources with real-time data
+   - Prompts for AI interactions
+   - Sampling for AI assistance
+   - Full logging and metrics
+   - Authentication and rate limiting
+   - Health monitoring
+
+## Key Features Demonstrated
+
+1. **All Protocol Methods**: Including ping, tools, resources, prompts, completion, sampling
+2. **Middleware Stack**: Authentication, rate limiting, metrics, logging
+3. **Lifecycle Hooks**: Server and tool-level hooks
+4. **Error Handling**: With custom error types and recovery
+5. **Completions**: Smart autocomplete for parameters
+6. **Health Monitoring**: Built-in health checks and metrics
+7. **Testing**: Comprehensive test coverage
+8. **Production Ready**: Authentication, rate limiting, error handling