tsikol 0.1.0

data/docs/api/server.md

@@ -0,0 +1,509 @@
+# Server API Reference
+
+The `Tsikol::Server` class is the core of your MCP server, handling protocol communication, component registration, and request routing.
+
+## Class: Tsikol::Server
+
+### Constructor
+
+```ruby
+server = Tsikol::Server.new(name: "my-server", version: "1.0.0")
+```
+
+#### Parameters
+
+- `name` (String, required): The server name
+- `version` (String, optional): Server version (default: "1.0.0")
+- `options` (Hash, optional): Additional configuration options
+
+### Configuration Methods
+
+#### `#use(middleware, options = {})`
+
+Add middleware to the processing chain.
+
+```ruby
+server.use Tsikol::LoggingMiddleware, level: :debug
+server.use AuthenticationMiddleware, secret_key: ENV['SECRET']
+```
+
+#### `#logging(enabled)`
+
+Enable or disable logging capability.
+
+```ruby
+server.logging true
+```
+
+#### `#completion(enabled)`
+
+Enable or disable completion support.
+
+```ruby
+server.completion true
+```
+
+#### `#sampling(enabled)`
+
+Enable or disable sampling capability.
+
+```ruby
+server.sampling true
+```
+
+### Component Registration
+
+#### `#register_tool(name, &block)`
+
+Register an inline tool.
+
+```ruby
+server.register_tool("echo") do |message:|
+  message
+end
+```
+
+#### `#register_tool_class(klass)`
+
+Register a tool class.
+
+```ruby
+server.register_tool_class(FileManager)
+# or
+server.tool FileManager
+```
+
+#### `#register_tool_instance(instance)`
+
+Register a tool instance.
+
+```ruby
+tool = FileManager.new(config: config)
+server.register_tool_instance(tool)
+```
+
+#### `#register_resource(uri, &block)`
+
+Register an inline resource.
+
+```ruby
+server.register_resource("version") do
+  "1.0.0"
+end
+```
+
+#### `#register_resource_class(klass)`
+
+Register a resource class.
+
+```ruby
+server.register_resource_class(SystemStatus)
+# or
+server.resource SystemStatus
+```
+
+#### `#register_prompt_class(klass)`
+
+Register a prompt class.
+
+```ruby
+server.register_prompt_class(CodeAssistant)
+# or
+server.prompt CodeAssistant
+```
+
+### Lifecycle Hooks
+
+#### `#before_start(&block)`
+
+Execute code before the server starts.
+
+```ruby
+server.before_start do
+  puts "Initializing server..."
+  load_configuration
+end
+```
+
+#### `#after_start(&block)`
+
+Execute code after the server starts.
+
+```ruby
+server.after_start do
+  puts "Server ready!"
+  notify_monitoring_service
+end
+```
+
+#### `#before_stop(&block)`
+
+Execute code before the server stops.
+
+```ruby
+server.before_stop do
+  save_state
+  close_connections
+end
+```
+
+#### `#after_stop(&block)`
+
+Execute code after the server stops.
+
+```ruby
+server.after_stop do
+  puts "Server stopped"
+  cleanup_resources
+end
+```
+
+### Request Handling
+
+#### `#handle_request(request)`
+
+Process a JSON-RPC request.
+
+```ruby
+request = {
+  "jsonrpc" => "2.0",
+  "id" => 1,
+  "method" => "tools/call",
+  "params" => { "name" => "echo", "arguments" => { "message" => "Hello" } }
+}
+
+response = server.handle_request(request)
+```
+
+#### `#start`
+
+Start the server and listen for requests on stdin/stdout.
+
+```ruby
+server.start  # Blocks until interrupted
+```
+
+### Capability Methods
+
+#### `#capabilities`
+
+Get server capabilities.
+
+```ruby
+caps = server.capabilities
+# => {
+#   tools: { supported: true },
+#   resources: { supported: true },
+#   prompts: { supported: true },
+#   completion: { supported: true },
+#   sampling: { supported: true }
+# }
+```
+
+#### `#logging_enabled?`
+
+Check if logging is enabled.
+
+```ruby
+if server.logging_enabled?
+  # Logging is available
+end
+```
+
+#### `#completion_enabled?`
+
+Check if completion is enabled.
+
+```ruby
+if server.completion_enabled?
+  # Completion is available
+end
+```
+
+#### `#sampling_enabled?`
+
+Check if sampling is enabled.
+
+```ruby
+if server.sampling_enabled?
+  # Sampling is available
+end
+```
+
+### Logging Methods
+
+#### `#log(level, message, data: nil)`
+
+Log a message (only if logging is enabled).
+
+```ruby
+server.log(:info, "Processing request", data: { method: "tools/call" })
+server.log(:error, "Request failed", data: { error: e.message })
+```
+
+Log levels:
+- `:debug`
+- `:info`
+- `:warning`
+- `:error`
+
+### Sampling Methods
+
+#### `#sample_text(messages:, temperature: 0.7, max_tokens: nil, stop_sequences: nil, model_hint: nil)`
+
+Request text generation from the client (only if sampling is enabled).
+
+```ruby
+response = server.sample_text(
+  messages: [
+    { role: "system", content: { type: "text", text: "You are helpful." } },
+    { role: "user", content: { type: "text", text: "Hello!" } }
+  ],
+  temperature: 0.5,
+  max_tokens: 100
+)
+
+if response[:error]
+  # Handle error
+else
+  generated_text = response[:text]
+end
+```
+
+### Utility Methods
+
+#### `#name`
+
+Get the server name.
+
+```ruby
+server.name  # => "my-server"
+```
+
+#### `#version`
+
+Get the server version.
+
+```ruby
+server.version  # => "1.0.0"
+```
+
+#### `#tools`
+
+Get registered tools.
+
+```ruby
+server.tools  # => { "echo" => #<Proc>, "file_manager" => FileManager }
+```
+
+#### `#resources`
+
+Get registered resources.
+
+```ruby
+server.resources  # => { "version" => #<Proc>, "system/status" => SystemStatus }
+```
+
+#### `#prompts`
+
+Get registered prompts.
+
+```ruby
+server.prompts  # => { "code_assistant" => CodeAssistant }
+```
+
+## DSL Methods
+
+The server provides a DSL for configuration:
+
+```ruby
+Tsikol.server "my-server" do
+  # Enable capabilities
+  logging true
+  completion true
+  sampling true
+  
+  # Add middleware
+  use Tsikol::LoggingMiddleware
+  use Tsikol::RateLimitMiddleware, max_requests: 100
+  
+  # Register components
+  tool FileManager
+  resource SystemStatus
+  prompt CodeAssistant
+  
+  # Inline tool
+  tool "echo" do |message:|
+    message
+  end
+  
+  # Inline resource
+  resource "version" do
+    "1.0.0"
+  end
+  
+  # Lifecycle hooks
+  before_start do
+    puts "Starting..."
+  end
+  
+  after_start do
+    puts "Ready!"
+  end
+end
+```
+
+## Starting the Server
+
+### Method 1: Direct Start
+
+```ruby
+server = Tsikol::Server.new(name: "my-server")
+# Configure server...
+server.start
+```
+
+### Method 2: Using Tsikol.start
+
+```ruby
+Tsikol.start(name: "my-server") do
+  # Configuration block
+  tool MyTool
+  resource MyResource
+end
+```
+
+### Method 3: Using Tsikol.server
+
+```ruby
+server = Tsikol.server "my-server" do
+  # Configuration block
+end
+
+# Later...
+server.start
+```
+
+## Error Handling
+
+The server handles various error conditions:
+
+```ruby
+# Invalid request format
+{
+  jsonrpc: "2.0",
+  id: 1,
+  error: {
+    code: -32600,
+    message: "Invalid Request"
+  }
+}
+
+# Method not found
+{
+  jsonrpc: "2.0",
+  id: 1,
+  error: {
+    code: -32601,
+    message: "Method not found"
+  }
+}
+
+# Invalid parameters
+{
+  jsonrpc: "2.0",
+  id: 1,
+  error: {
+    code: -32602,
+    message: "Invalid params"
+  }
+}
+
+# Internal error
+{
+  jsonrpc: "2.0",
+  id: 1,
+  error: {
+    code: -32603,
+    message: "Internal error",
+    data: { details: "..." }
+  }
+}
+```
+
+## Thread Safety
+
+The server is designed to be thread-safe:
+
+- Component registration should happen before starting
+- Request handling is thread-safe
+- Logging methods are thread-safe
+- Sampling requests are thread-safe
+
+## Examples
+
+### Basic Server
+
+```ruby
+require 'tsikol'
+
+server = Tsikol::Server.new(name: "basic-server")
+
+server.register_tool("greet") do |name:|
+  "Hello, #{name}!"
+end
+
+server.register_resource("time") do
+  Time.now.iso8601
+end
+
+server.start
+```
+
+### Advanced Server
+
+```ruby
+require 'tsikol'
+
+class MyServer < Tsikol::Server
+  def initialize
+    super(name: "advanced-server", version: "2.0.0")
+    
+    configure_middleware
+    register_components
+    setup_hooks
+  end
+  
+  private
+  
+  def configure_middleware
+    use Tsikol::LoggingMiddleware, level: :info
+    use Tsikol::ErrorHandlingMiddleware
+    use Tsikol::RateLimitMiddleware, max_requests: 1000
+  end
+  
+  def register_components
+    tool FileManager
+    tool DatabaseQuery
+    resource SystemMetrics
+    prompt AiAssistant
+  end
+  
+  def setup_hooks
+    before_start { initialize_database }
+    after_start { notify_monitoring }
+    before_stop { save_state }
+    after_stop { cleanup }
+  end
+end
+
+server = MyServer.new
+server.start
+```
+
+## See Also
+
+- [Getting Started Guide](../guides/getting-started.md)
+- [Tool API](tool.md)
+- [Resource API](resource.md)
+- [Middleware API](middleware.md)