tsikol 0.1.0

data/docs/guides/getting-started.md

@@ -0,0 +1,462 @@
+# Getting Started with Tsikol
+
+Welcome to Tsikol! This guide will help you create your first MCP (Model Context Protocol) server in Ruby.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Understanding MCP](#understanding-mcp)
+4. [CLI Usage](#cli-usage)
+5. [Basic Concepts](#basic-concepts)
+6. [Your First Server](#your-first-server)
+7. [Testing Your Server](#testing-your-server)
+8. [Next Steps](#next-steps)
+
+## Installation
+
+### Prerequisites
+
+- Ruby 3.0 or higher
+- Bundler gem
+
+### Install Tsikol
+
+```bash
+gem install tsikol
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'tsikol'
+```
+
+## Quick Start
+
+Create a new MCP server in under a minute:
+
+```bash
+# Create a new project
+tsikol new my-mcp-server
+cd my-mcp-server
+
+# Install dependencies
+bundle install
+
+# Run the server
+ruby server.rb
+```
+
+## Understanding MCP
+
+### What is MCP?
+
+The Model Context Protocol (MCP) is a standard for communication between AI assistants and external tools. It enables:
+
+- **Tools**: Functions the AI can call
+- **Resources**: Data the AI can access
+- **Prompts**: Reusable AI configurations
+- **Completion**: Intelligent autocomplete
+- **Sampling**: AI text generation capabilities
+
+### How It Works
+
+```
+┌─────────────┐     MCP Protocol      ┌─────────────┐
+│ AI Client   │ ◄──────────────────► │ MCP Server  │
+│ (Claude,    │                       │ (Your Ruby  │
+│  ChatGPT)   │                       │  Server)    │
+└─────────────┘                       └─────────────┘
+```
+
+## CLI Usage
+
+### Create a New Project
+
+```bash
+tsikol new PROJECT_NAME [OPTIONS]
+
+# Examples
+tsikol new weather-server
+tsikol new code-assistant --git
+tsikol new file-manager --test minitest
+```
+
+Options:
+- `--git` / `--no-git` - Initialize git repository (default: true)
+- `--test [framework]` - Testing framework: minitest, rspec, none (default: minitest)
+
+### Generate Components
+
+```bash
+# Generate a new tool
+tsikol generate tool process_file path:string operation:string
+
+# Generate a resource
+tsikol generate resource system_status
+
+# Generate a prompt
+tsikol generate prompt code_review language:string code:string
+
+# Short alias
+tsikol g tool my_tool param1:type param2:type
+```
+
+The generators automatically:
+- Create the component file
+- Add proper requires to server.rb
+- Register the component with the server
+
+## Basic Concepts
+
+### Tools
+
+Tools are functions that AI can call:
+
+```ruby
+tool "greet" do |name:|
+  "Hello, #{name}!"
+end
+```
+
+### Resources
+
+Resources provide read-only data:
+
+```ruby
+resource "version" do
+  "1.0.0"
+end
+```
+
+### Prompts
+
+Prompts configure AI behavior:
+
+```ruby
+prompt "translator" do |text:, language:|
+  [
+    {
+      role: "system",
+      content: { type: "text", text: "Translate to #{language}" }
+    },
+    {
+      role: "user",
+      content: { type: "text", text: text }
+    }
+  ]
+end
+```
+
+## Your First Server
+
+Let's build a simple MCP server step by step.
+
+### 1. Create the Project
+
+```bash
+tsikol new hello-mcp
+cd hello-mcp
+```
+
+### 2. Define a Tool
+
+```bash
+tsikol generate tool greeting name:string style:string
+```
+
+Edit `app/tools/greeting.rb`:
+
+```ruby
+class Greeting < Tsikol::Tool
+  description "Generate personalized greetings"
+  
+  parameter :name do
+    type :string
+    required
+    description "Person's name"
+  end
+  
+  parameter :style do
+    type :string
+    optional
+    default "friendly"
+    enum ["friendly", "formal", "casual"]
+    description "Greeting style"
+  end
+  
+  def execute(name:, style: "friendly")
+    case style
+    when "friendly"
+      "Hey #{name}! How's it going?"
+    when "formal"
+      "Good day, #{name}. I hope you are well."
+    when "casual"
+      "Yo #{name}, what's up?"
+    end
+  end
+end
+```
+
+### 3. Add a Resource
+
+```bash
+tsikol generate resource server_info
+```
+
+Edit `app/resources/server_info.rb`:
+
+```ruby
+class ServerInfo < Tsikol::Resource
+  uri "server/info"
+  description "Information about this server"
+  
+  def read
+    {
+      name: "Hello MCP Server",
+      version: "1.0.0",
+      author: "Your Name",
+      capabilities: ["greetings", "server info"]
+    }.to_json
+  end
+end
+```
+
+### 4. Create a Prompt
+
+```bash
+tsikol generate prompt friendly_assistant topic:string
+```
+
+Edit `app/prompts/friendly_assistant.rb`:
+
+```ruby
+class FriendlyAssistant < Tsikol::Prompt
+  name "friendly_assistant"
+  description "A helpful and friendly AI assistant"
+  
+  argument :topic do
+    type :string
+    required
+    description "What to help with"
+  end
+  
+  def get_messages(topic:)
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a friendly and helpful assistant. Be concise but warm."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "I need help with: #{topic}"
+        }
+      }
+    ]
+  end
+end
+```
+
+### 5. Configure the Server
+
+The generated `server.rb` already includes your components:
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'tsikol'
+
+# Require all components
+Dir.glob('app/**/*.rb').each { |file| require_relative file }
+
+Tsikol.start(name: "hello-mcp") do
+  # Components are auto-registered by the generator
+  tool Greeting
+  resource ServerInfo
+  prompt FriendlyAssistant
+  
+  # Enable features
+  completion true
+  sampling true
+  
+  # Add middleware
+  use Tsikol::LoggingMiddleware, level: :info
+end
+```
+
+## Testing Your Server
+
+### 1. Manual Testing
+
+Run your server:
+
+```bash
+ruby server.rb
+```
+
+The server listens on stdin/stdout for MCP protocol messages.
+
+### 2. Using MCP Inspector
+
+Install the MCP Inspector:
+
+```bash
+npm install -g @modelcontextprotocol/inspector
+```
+
+Run the inspector:
+
+```bash
+mcp-inspector ruby server.rb
+```
+
+Visit http://localhost:5173 to interact with your server.
+
+### 3. Writing Tests
+
+Create `test/tools/greeting_test.rb`:
+
+```ruby
+require_relative '../test_helper'
+
+class GreetingTest < TsikolTest
+  def setup
+    super
+    @server.register_tool_instance(Greeting.new)
+    @client.initialize_connection
+  end
+  
+  def test_friendly_greeting
+    response = @client.call_tool("greeting", {
+      "name" => "Alice",
+      "style" => "friendly"
+    })
+    
+    assert_successful_response(response)
+    assert_match /Hey Alice/, response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_formal_greeting
+    response = @client.call_tool("greeting", {
+      "name" => "Dr. Smith",
+      "style" => "formal"
+    })
+    
+    assert_successful_response(response)
+    assert_match /Good day, Dr. Smith/, response.dig(:result, :content, 0, :text)
+  end
+end
+```
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+## Connecting to AI Clients
+
+### Claude Desktop
+
+Add to Claude's configuration:
+
+```json
+{
+  "mcpServers": {
+    "hello-mcp": {
+      "command": "ruby",
+      "args": ["/path/to/hello-mcp/server.rb"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Other Clients
+
+Most MCP clients support similar configuration. Provide:
+- Command: `ruby`
+- Arguments: `["/full/path/to/server.rb"]`
+- Any required environment variables
+
+## Common Patterns
+
+### Environment Variables
+
+```ruby
+# In server.rb
+Tsikol.start(name: "my-server") do
+  # Use environment variables for configuration
+  if api_key = ENV['API_KEY']
+    metadata api_key: api_key[0..5] + "..."
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+class SafeTool < Tsikol::Tool
+  def execute(input:)
+    validate_input!(input)
+    process(input)
+  rescue ValidationError => e
+    "Validation failed: #{e.message}"
+  rescue => e
+    log :error, "Unexpected error", error: e.message
+    "An error occurred. Please try again."
+  end
+end
+```
+
+### Logging
+
+```ruby
+class VerboseTool < Tsikol::Tool
+  def execute(data:)
+    log :info, "Processing started", size: data.size
+    
+    result = process_data(data)
+    
+    log :info, "Processing complete", result_size: result.size
+    
+    result
+  end
+end
+```
+
+## Next Steps
+
+Now that you have a working MCP server:
+
+1. **Learn More**:
+   - [Tools Guide](tools.md) - Deep dive into tools
+   - [Resources Guide](resources.md) - Managing data
+   - [Prompts Guide](prompts.md) - AI configurations
+   - [Middleware Guide](middleware.md) - Cross-cutting concerns
+
+2. **Explore Examples**:
+   - [Echo Server](../examples/echo-server.md) - Simple example
+   - [Weather Service](../examples/weather-service.md) - API integration
+   - [Code Assistant](../examples/code-assistant.md) - Complex tools
+
+3. **Advanced Topics**:
+   - [Testing Guide](testing.md) - Comprehensive testing
+   - [Error Handling](../cookbook/error-handling.md) - Robust servers
+   - [Authentication](../cookbook/authentication.md) - Secure servers
+
+## Getting Help
+
+- **Documentation**: Read through the guides in this folder
+- **Examples**: Check the [examples](../examples/) directory
+- **Issues**: Report bugs on [GitHub](https://github.com/your-username/tsikol)
+- **Community**: Join our Discord/Slack (if applicable)
+
+Happy building with Tsikol! 🚀