tsikol 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 486f6d3cabbbf5b62f65a7135c592c1f1e23bf8d8f0ca5f7cdd72a3519230ec2
+  data.tar.gz: 4ad29f7c0cd2235bb954472cddae5adbe2e9664fc1094581ec1bfa18506d609f
+SHA512:
+  metadata.gz: 226b841f33b0c3f7cbec1a42f0b706fa262a0b86fe512f60d0e063dcbd98eaa38801eac80dd204c86314d50bd4a08c4ab3eb2089e38e9a9f62d6e5119626c528
+  data.tar.gz: 77e614efd0dc4a7211da3b9602a52bed1f26b6e1b7fffa5c38b75eaa7a3091dc13aef95317a2a04ffea7104ae52d3dbaed897c692cebf0d857d915c220794568

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-01-29
+
+### Added
+- Initial release of Tsikol MCP Framework
+- Full MCP protocol support (Tools, Resources, Prompts)
+- Logging, Completion, and Sampling capabilities
+- Middleware system for cross-cutting concerns
+- Error handling with circuit breakers
+- Lifecycle hooks (server and tool-level)
+- Built-in health monitoring and metrics
+- Testing utilities and mock client
+- CLI tool with generators
+- Rails-like project structure
+- Auto-discovery of components
+- Comprehensive documentation and examples

data/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing to Tsikol
+
+We love your input! We want to make contributing to Tsikol as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## We Develop with Github
+
+We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html)
+
+Pull requests are the best way to propose changes to the codebase:
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## Any contributions you make will be under the MIT Software License
+
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using Github's [issues](https://github.com/arturodz/tsikol/issues)
+
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/arturodz/tsikol/issues/new); it's that easy!
+
+## Write bug reports with detail, background, and sample code
+
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+## Development Setup
+
+1. Fork and clone the repository
+2. Run `bundle install`
+3. Run tests with `bundle exec rake test`
+4. Make your changes
+5. Add tests for your changes
+6. Run tests again to ensure they pass
+7. Submit a pull request
+
+## Testing
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+ruby -Ilib:test test/example_test.rb
+```
+
+## Code Style
+
+- Follow Ruby community style guidelines
+- Use RuboCop for linting: `bundle exec rubocop`
+- Keep methods small and focused
+- Write descriptive commit messages
+
+## Adding New Features
+
+When adding new features:
+
+1. Update the appropriate documentation
+2. Add examples if applicable
+3. Update the CHANGELOG.md
+4. Add tests covering the new functionality
+
+## License
+
+By contributing, you agree that your contributions will be licensed under its MIT License.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tsikol Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,579 @@
+# Tsikol - Ruby MCP Framework
+
+A elegant and easy to use framework for building Model Context Protocol (MCP) servers in Ruby.
+
+## Features
+
+- 🚀 **Rails-like Structure** - Familiar project organization with `app/tools`, `app/resources`, `app/prompts`
+- 🔧 **Flexible DSL** - Define components inline or in separate files
+- 🔄 **Full MCP Protocol Support** - Tools, Resources, Prompts, Logging, Completion, Sampling
+- 🛡️ **Middleware System** - Add cross-cutting concerns like auth, rate limiting, logging
+- 📊 **Built-in Monitoring** - Health checks, metrics, error tracking
+- 🧪 **Testing Utilities** - Comprehensive test helpers and mock client
+- ⚡ **Hot Reload** - Auto-discovery of components
+- 🔍 **Advanced Error Handling** - Circuit breakers, error recovery, detailed logging
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'tsikol'
+```
+
+Or install directly:
+
+```bash
+gem install tsikol
+```
+
+## CLI Usage
+
+Tsikol includes a powerful CLI tool for scaffolding projects and generating components.
+
+### Create a New Project
+
+```bash
+tsikol new my-mcp-server
+cd my-mcp-server
+bundle install
+```
+
+This creates a complete project structure with:
+- `server.rb` - Main server file
+- `Gemfile` - Dependencies
+- `app/` directory structure for components
+- README and .gitignore
+
+### Generate Components
+
+The CLI can generate tools, resources, and prompts with automatic server.rb updates:
+
+#### Generate a Tool
+
+```bash
+# Basic tool
+tsikol generate tool calculate
+
+# Tool with parameters (name:type format)
+tsikol generate tool calculate a:number b:number operation:string
+
+# Optional parameters use ? suffix
+tsikol generate tool weather_forecast location:string days?:integer units?:string
+
+# Short alias
+tsikol g tool my_tool param1:string param2:boolean
+```
+
+#### Generate a Resource
+
+```bash
+# Basic resource
+tsikol generate resource system_status
+
+# Resource with custom URI (auto-converts underscores to slashes)
+tsikol generate resource user_profile  # Creates URI: user/profile
+
+# Short alias
+tsikol g resource my_data
+```
+
+#### Generate a Prompt
+
+```bash
+# Basic prompt
+tsikol generate prompt code_review
+
+# Prompt with arguments
+tsikol generate prompt code_review language:string code:string style?:string
+
+# Short alias
+tsikol g prompt chat_assistant topic:string context?:string
+```
+
+### How the CLI Works
+
+1. **Generates the component file** in the appropriate directory:
+   - Tools → `app/tools/`
+   - Resources → `app/resources/`
+   - Prompts → `app/prompts/`
+
+2. **Updates server.rb automatically**:
+   - Adds the require statement
+   - Registers the component in the routes
+
+3. **Smart insertion** - Components are grouped by type in server.rb
+
+### Example Workflow
+
+```bash
+# Create a new weather service
+tsikol new weather-service
+cd weather-service
+
+# Generate tools
+tsikol g tool get_current_weather location:string units?:string
+tsikol g tool get_forecast location:string days:integer
+
+# Generate resources
+tsikol g resource weather_alerts
+tsikol g resource service_status
+
+# Generate prompts
+tsikol g prompt weather_chat city:string topic:string
+
+# Your server.rb is automatically updated with all components!
+./server.rb
+```
+
+## Quick Start
+
+### Simple Server
+
+```ruby
+#!/usr/bin/env ruby
+require 'tsikol'
+
+Tsikol.server "my-server" do
+  tool "greet" do |name:|
+    "Hello, #{name}!"
+  end
+  
+  resource "status" do
+    "Server is running"
+  end
+  
+  prompt "chat" do |topic:|
+    "Let's discuss #{topic}"
+  end
+end
+```
+
+### Rails-like Structure
+
+```ruby
+# server.rb
+require 'tsikol'
+
+Tsikol.start(name: "weather-service") do
+  # Direct class references
+  tool GetCurrentWeather
+  tool GetForecast
+  resource WeatherAlerts
+  prompt WeatherChat
+end
+```
+
+```ruby
+# app/tools/get_current_weather.rb
+class GetCurrentWeather < Tsikol::Tool
+  description "Get current weather for a location"
+  
+  parameter :location do
+    type :string
+    required
+    description "City name"
+    
+    complete do |partial|
+      ["New York", "London", "Tokyo"].select { |c| c.start_with?(partial) }
+    end
+  end
+  
+  def execute(location:)
+    "Currently 72°F in #{location}"
+  end
+end
+```
+
+## Core Concepts
+
+### Tools
+
+Tools are functions that can be called by the MCP client:
+
+```ruby
+# Inline definition
+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
+
+# Class-based definition
+class Calculate < Tsikol::Tool
+  description "Perform calculations"
+  
+  parameter :a do
+    type :number
+    required
+    description "First number"
+  end
+  
+  parameter :b do
+    type :number
+    required
+    description "Second number"
+  end
+  
+  parameter :operation do
+    type :string
+    optional
+    default "add"
+    enum ["add", "subtract", "multiply", "divide"]
+  end
+  
+  def execute(a:, b:, operation: "add")
+    # Implementation
+  end
+end
+```
+
+### Resources
+
+Resources provide data that can be read by the client:
+
+```ruby
+# Inline definition
+resource "config/database" do
+  {
+    host: ENV['DB_HOST'],
+    port: ENV['DB_PORT'],
+    name: ENV['DB_NAME']
+  }.to_json
+end
+
+# Class-based definition
+class DatabaseConfig < Tsikol::Resource
+  uri "config/database"
+  description "Database configuration"
+  
+  def read
+    # Return content
+  end
+end
+```
+
+### Prompts
+
+Prompts generate messages for AI interactions:
+
+```ruby
+# Inline definition
+prompt "code_review" do |language:, code:|
+  "Review this #{language} code:\n```#{language}\n#{code}\n```"
+end
+
+# Class-based definition
+class CodeReview < Tsikol::Prompt
+  name "code_review"
+  description "Generate code review prompt"
+  
+  argument :language do
+    type :string
+    required
+    complete do |partial|
+      ["ruby", "python", "javascript"].select { |l| l.start_with?(partial) }
+    end
+  end
+  
+  def get_messages(language:, code:)
+    [{
+      role: "user",
+      content: {
+        type: "text",
+        text: "Review this #{language} code:\n```#{language}\n#{code}\n```"
+      }
+    }]
+  end
+end
+```
+
+### Completion (Autocomplete)
+
+Provide intelligent autocomplete suggestions for tool parameters and prompt arguments:
+
+```ruby
+# Tool with parameter completion
+class SearchFiles < Tsikol::Tool
+  description "Search for files in the project"
+  
+  parameter :file_type do
+    type :string
+    required
+    description "Type of file to search for"
+    
+    complete do |partial|
+      # Return suggestions based on partial input
+      extensions = ["rb", "js", "py", "md", "yml", "json", "xml"]
+      extensions.select { |ext| ext.start_with?(partial) }
+    end
+  end
+  
+  parameter :directory do
+    type :string
+    optional
+    description "Directory to search in"
+    
+    complete do |partial|
+      # Dynamic completion based on filesystem
+      Dir.glob("#{partial}*").select { |f| File.directory?(f) }
+    end
+  end
+  
+  def execute(file_type:, directory: ".")
+    Dir.glob("#{directory}/**/*.#{file_type}")
+  end
+end
+
+# Inline completion for tools
+tool "database_query" do |table:, operation:|
+  "Executing #{operation} on #{table}"
+end
+
+# Define completions separately
+completion_for "tool", "database_query", "table" do |partial|
+  # List available tables
+  ["users", "posts", "comments", "tags"].select { |t| t.start_with?(partial) }
+end
+
+completion_for "tool", "database_query", "operation" do |partial|
+  ["select", "insert", "update", "delete"].select { |op| op.start_with?(partial) }
+end
+```
+
+## Advanced Features
+
+### Middleware
+
+Add cross-cutting concerns with middleware:
+
+```ruby
+Tsikol.server "my-server" do
+  # Built-in middleware
+  use Tsikol::LoggingMiddleware
+  use Tsikol::RateLimitMiddleware, max_requests: 100, window: 60
+  use Tsikol::ValidationMiddleware
+  
+  # Custom middleware
+  use AuthMiddleware, api_keys: ["secret-key"]
+  
+  # Tools, resources, prompts...
+end
+```
+
+### Lifecycle Hooks
+
+```ruby
+Tsikol.server "my-server" do
+  before_start do
+    log :info, "Initializing connections..."
+    # Setup code
+  end
+  
+  after_start do
+    log :info, "Server ready!"
+  end
+  
+  before_stop do
+    log :info, "Cleaning up..."
+    # Cleanup code
+  end
+  
+  # Tool-specific hooks
+  before_tool "critical_operation" do |params|
+    log :warning, "About to run critical operation", data: params
+  end
+  
+  after_tool "critical_operation" do |params, result|
+    log :info, "Critical operation completed", data: { result: result }
+  end
+end
+```
+
+### Sampling (AI Assistance)
+
+Enable AI-assisted content generation where the MCP server can request help from the AI client:
+
+```ruby
+Tsikol.server "my-server" do
+  # Enable sampling and define handler
+  on_sampling do |request|
+    # The request contains:
+    # - messages: Array of conversation messages
+    # - model_preferences: Hints about which model to use
+    # - system_prompt: Optional system instructions
+    # - max_tokens: Maximum response length
+    
+    # In production, the MCP client (e.g., Claude) handles this
+    # For testing, you can simulate responses:
+    {
+      role: "assistant",
+      content: {
+        type: "text",
+        text: "AI-generated response based on: #{request[:messages].last}"
+      }
+    }
+  end
+  
+  # Tool that uses AI assistance
+  tool "write_documentation" do |code:, style: "technical"|
+    # In a real MCP client, this would trigger a sampling request
+    prompt = case style
+    when "technical"
+      "Write technical documentation for this code"
+    when "tutorial"
+      "Write a beginner-friendly tutorial for this code"
+    when "api"
+      "Write API reference documentation"
+    end
+    
+    # The actual AI response would come from the client
+    "#{prompt}:\n\n```ruby\n#{code}\n```"
+  end
+  
+  # Advanced example with context
+  tool "refactor_code" do |code:, goal:|
+    # Build conversation for AI
+    messages = [
+      {
+        role: "system",
+        content: "You are an expert Ruby developer focused on clean code."
+      },
+      {
+        role: "user",
+        content: "Refactor this code to #{goal}:\n\n```ruby\n#{code}\n```"
+      }
+    ]
+    
+    # In production, this would send a sampling request
+    # with the messages to the MCP client
+    "Refactored code would appear here"
+  end
+end
+
+# Class-based tool with sampling
+class CodeGenerator < Tsikol::Tool
+  description "Generate code using AI assistance"
+  
+  parameter :description do
+    type :string
+    required
+    description "What code to generate"
+  end
+  
+  parameter :language do
+    type :string
+    optional
+    default "ruby"
+    enum ["ruby", "python", "javascript", "go"]
+  end
+  
+  def execute(description:, language: "ruby")
+    # Build sampling request
+    sampling_request = {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: "Generate #{language} code that: #{description}"
+          }
+        }
+      ],
+      model_preferences: {
+        hints: [{ name: "claude-3-sonnet" }],
+        temperature: 0.7
+      },
+      max_tokens: 2000
+    }
+    
+    # This would be sent to the MCP client
+    # Response would contain AI-generated code
+    "Generated #{language} code for: #{description}"
+  end
+end
+```
+
+### Health Monitoring
+
+Built-in health endpoints are automatically added:
+
+- `resource "health"` - Basic health status
+- `resource "health/detailed"` - Detailed health with metrics
+- `resource "metrics"` - Raw metrics data
+
+### Error Handling
+
+Advanced error handling with circuit breakers:
+
+```ruby
+tool "external_api" do
+  # Automatically wrapped with circuit breaker
+  # After 5 failures, circuit opens for 60 seconds
+  call_external_service
+end
+```
+
+## Testing
+
+Tsikol includes comprehensive testing utilities:
+
+```ruby
+require 'tsikol/test_helpers'
+
+class MyServerTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = create_my_server
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def test_echo_tool
+    @client.initialize_connection
+    assert_tool_result(@client, "echo", { "msg" => "Hi" }, "Echo: Hi")
+  end
+  
+  def test_error_handling
+    response = @client.call_tool("failing_tool")
+    assert_error_response(response, -32603, /Internal error/)
+  end
+end
+```
+
+## Project Structure
+
+```
+my-mcp-server/
+├── server.rb           # Main entry point
+├── Gemfile
+├── app/
+│   ├── tools/         # Tool classes
+│   ├── resources/     # Resource classes
+│   └── prompts/       # Prompt classes
+├── config/
+│   └── tsikol.yml     # Configuration (optional)
+└── test/
+    └── server_test.rb # Tests
+```
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic.rb` - Simple inline server
+- `weather-service/` - Full Rails-like project
+- `middleware_example.rb` - Middleware demonstration
+- `sampling_example.rb` - AI assistance
+- `advanced_features.rb` - All features combined
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+Built for the Model Context Protocol (MCP) by Anthropic.