tsikol 0.1.0

data/docs/guides/project-structure.md

@@ -0,0 +1,434 @@
+# Project Structure Guide
+
+Understanding how Tsikol projects are organized helps you build maintainable MCP servers.
+
+## Table of Contents
+
+1. [Directory Layout](#directory-layout)
+2. [File Organization](#file-organization)
+3. [Naming Conventions](#naming-conventions)
+4. [Component Structure](#component-structure)
+5. [Configuration](#configuration)
+6. [Best Practices](#best-practices)
+
+## Directory Layout
+
+A typical Tsikol project follows this structure:
+
+```
+my-mcp-server/
+├── server.rb           # Main server file and entry point
+├── Gemfile            # Ruby dependencies
+├── README.md          # Project documentation
+├── .gitignore         # Git ignore rules
+├── app/               # Application components
+│   ├── tools/         # Tool implementations
+│   ├── resources/     # Resource implementations
+│   └── prompts/       # Prompt implementations
+├── config/            # Configuration files (optional)
+├── lib/               # Additional libraries (optional)
+├── test/              # Test files
+└── tmp/               # Temporary files (logs, etc.)
+```
+
+## File Organization
+
+### Tools Directory (`app/tools/`)
+
+Tools are organized by functionality:
+
+```
+app/tools/
+├── file_manager.rb         # Single tool
+├── database_query.rb       # Single tool
+└── analytics/              # Grouped tools
+    ├── report_generator.rb
+    ├── data_processor.rb
+    └── metrics_calculator.rb
+```
+
+### Resources Directory (`app/resources/`)
+
+Resources follow URI-based organization:
+
+```
+app/resources/
+├── system_status.rb        # URI: system/status
+├── health_check.rb         # URI: health/check
+└── api/                    # Grouped resources
+    ├── endpoints.rb        # URI: api/endpoints
+    └── documentation.rb    # URI: api/documentation
+```
+
+### Prompts Directory (`app/prompts/`)
+
+Prompts are organized by purpose:
+
+```
+app/prompts/
+├── code_assistant.rb       # Single prompt
+├── writer.rb              # Single prompt
+└── development/           # Grouped prompts
+    ├── debugger.rb
+    ├── refactorer.rb
+    └── reviewer.rb
+```
+
+## Naming Conventions
+
+### File Names
+
+- Use snake_case: `file_manager.rb`, `system_status.rb`
+- Match the class name: `FileManager` → `file_manager.rb`
+- For namespaced classes: `Analytics::ReportGenerator` → `analytics/report_generator.rb`
+
+### Class Names
+
+- Use PascalCase: `FileManager`, `SystemStatus`
+- Inherit from appropriate base: `< Tsikol::Tool`, `< Tsikol::Resource`, `< Tsikol::Prompt`
+- Use modules for namespacing: `module Analytics; class ReportGenerator < Tsikol::Tool`
+
+### URIs and Names
+
+- Resources: URI matches file structure
+  - File: `app/resources/weather/alerts.rb`
+  - URI: `weather/alerts`
+- Tools: Name is class name in snake_case
+  - Class: `FileManager`
+  - Name: `file_manager`
+- Prompts: Explicit name in class
+  - Class: `CodeAssistant`
+  - Name: `code_assistant` (set with `name "code_assistant"`)
+
+## Component Structure
+
+### Tool Structure
+
+```ruby
+# app/tools/example_tool.rb
+class ExampleTool < Tsikol::Tool
+  description "Brief description of what this tool does"
+  
+  parameter :required_param do
+    type :string
+    required
+    description "What this parameter is for"
+  end
+  
+  parameter :optional_param do
+    type :integer
+    optional
+    default 10
+    description "Optional parameter with default"
+  end
+  
+  def execute(required_param:, optional_param: 10)
+    # Implementation
+  end
+  
+  private
+  
+  def helper_method
+    # Private helpers
+  end
+  
+  def set_server(server)
+    @server = server
+    # Setup logging
+  end
+end
+```
+
+### Resource Structure
+
+```ruby
+# app/resources/example_resource.rb
+class ExampleResource < Tsikol::Resource
+  uri "example/resource"
+  description "What this resource provides"
+  
+  def read
+    # Return data as string (JSON, text, etc.)
+    {
+      data: fetch_data,
+      timestamp: Time.now.iso8601
+    }.to_json
+  end
+  
+  private
+  
+  def fetch_data
+    # Implementation
+  end
+  
+  def set_server(server)
+    @server = server
+  end
+end
+```
+
+### Prompt Structure
+
+```ruby
+# app/prompts/example_prompt.rb
+class ExamplePrompt < Tsikol::Prompt
+  name "example_prompt"
+  description "What this prompt helps with"
+  
+  argument :topic do
+    type :string
+    required
+    description "The topic to discuss"
+  end
+  
+  def get_messages(topic:)
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a helpful assistant."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Help me with: #{topic}"
+        }
+      }
+    ]
+  end
+  
+  def set_server(server)
+    @server = server
+  end
+end
+```
+
+## Configuration
+
+### Server Configuration
+
+The main `server.rb` file configures your MCP server:
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'tsikol'
+
+# Require all components
+Dir.glob('app/**/*.rb').each { |file| require_relative file }
+
+Tsikol.start(name: "my-mcp-server") do
+  # Register components
+  tool FileManager
+  tool DatabaseQuery
+  resource SystemStatus
+  prompt CodeAssistant
+  
+  # Enable capabilities
+  logging true
+  completion true
+  sampling true
+  
+  # Add middleware
+  use Tsikol::LoggingMiddleware
+  use Tsikol::RateLimitMiddleware, max_requests: 100
+  
+  # Lifecycle hooks
+  before_start do
+    # Initialize
+  end
+  
+  after_start do
+    # Ready
+  end
+end
+```
+
+### Environment Configuration
+
+Use environment variables for configuration:
+
+```ruby
+# config/environment.rb
+module Config
+  DATABASE_URL = ENV.fetch('DATABASE_URL', 'sqlite://db/development.db')
+  API_KEY = ENV.fetch('API_KEY', nil)
+  LOG_LEVEL = ENV.fetch('LOG_LEVEL', 'info')
+  MAX_REQUEST_SIZE = ENV.fetch('MAX_REQUEST_SIZE', '1048576').to_i
+end
+
+# In server.rb
+require_relative 'config/environment'
+```
+
+## Best Practices
+
+### 1. Single Responsibility
+
+Each component should have one clear purpose:
+
+```ruby
+# Good: Focused tool
+class FileReader < Tsikol::Tool
+  description "Read file contents"
+  # Just reads files
+end
+
+# Bad: Doing too much
+class FileManager < Tsikol::Tool
+  description "Read, write, delete, compress, upload files"
+  # Too many responsibilities
+end
+```
+
+### 2. Consistent Naming
+
+Follow conventions throughout:
+
+```ruby
+# File: app/tools/code_analyzer.rb
+class CodeAnalyzer < Tsikol::Tool
+  # Matches file name
+end
+
+# File: app/resources/system/metrics.rb
+module System
+  class Metrics < Tsikol::Resource
+    uri "system/metrics"  # Matches file path
+  end
+end
+```
+
+### 3. Modular Organization
+
+Group related components:
+
+```
+app/tools/git/
+├── commit.rb
+├── branch.rb
+├── merge.rb
+└── push.rb
+```
+
+### 4. Shared Code
+
+Put shared code in lib:
+
+```ruby
+# lib/database.rb
+module Database
+  def self.connection
+    @connection ||= establish_connection
+  end
+end
+
+# In tools
+require_relative '../../lib/database'
+
+class QueryTool < Tsikol::Tool
+  def execute(query:)
+    Database.connection.execute(query)
+  end
+end
+```
+
+### 5. Testing Structure
+
+Mirror your app structure:
+
+```
+test/
+├── tools/
+│   ├── file_manager_test.rb
+│   └── analytics/
+│       └── report_generator_test.rb
+├── resources/
+│   └── system_status_test.rb
+└── test_helper.rb
+```
+
+## Advanced Patterns
+
+### Namespaced Components
+
+For larger projects:
+
+```ruby
+# app/tools/analytics/sales_report.rb
+module Analytics
+  class SalesReport < Tsikol::Tool
+    description "Generate sales reports"
+    
+    def execute(period:)
+      # Implementation
+    end
+  end
+end
+
+# In server.rb
+tool Analytics::SalesReport
+```
+
+### Shared Base Classes
+
+Create base classes for common functionality:
+
+```ruby
+# app/tools/base_tool.rb
+class BaseTool < Tsikol::Tool
+  def set_server(server)
+    @server = server
+    setup_logging
+    setup_metrics
+  end
+  
+  private
+  
+  def setup_logging
+    define_singleton_method(:log) do |level, message, data: nil|
+      @server.log(level, message, data: data)
+    end
+  end
+  
+  def setup_metrics
+    @metrics = @server.metrics
+  end
+end
+
+# app/tools/specific_tool.rb
+class SpecificTool < BaseTool
+  # Inherits common setup
+end
+```
+
+### Plugin System
+
+For extensible servers:
+
+```ruby
+# lib/plugin_loader.rb
+module PluginLoader
+  def self.load_plugins(server)
+    Dir.glob('plugins/*/init.rb').each do |plugin|
+      require_relative plugin
+    end
+  end
+end
+
+# plugins/custom_tools/init.rb
+require_relative 'tools/custom_tool'
+Tsikol.current_server.tool CustomTool
+```
+
+## Next Steps
+
+- Learn about [Tools](tools.md) in detail
+- Understand [Resources](resources.md)
+- Explore [Prompts](prompts.md)
+- Set up [Testing](testing.md)