anima-core 0.2.1 → 1.0.0

data/skills/mcp-server/references/server.md

@@ -0,0 +1,140 @@
+# MCP Server Reference
+
+## Server Initialization
+
+```ruby
+MCP::Server.new(
+  # Required
+  name: "server_name",
+
+  # Metadata
+  version: "1.0.0",                    # Default: "0.1.0"
+  description: "Server description",   # Protocol 2025-11-25+
+  title: "Human-Readable Name",        # Protocol 2025-06-18+
+  website_url: "https://example.com",  # Protocol 2025-06-18+
+  instructions: "Usage instructions",  # Protocol 2025-03-26+
+
+  # Components
+  tools: [ToolClass1, ToolClass2],
+  prompts: [PromptClass1],
+  resources: [resource_instance],
+  resource_templates: [template_instance],
+
+  # Runtime
+  server_context: { key: "value" },
+  transport: transport_instance,
+
+  # Configuration
+  configuration: MCP::Configuration.new(...),
+  capabilities: {                      # Override auto-detected
+    tools: { listChanged: true },
+    prompts: { listChanged: true },
+    resources: { listChanged: true }
+  }
+)
+```
+
+## Configuration
+
+```ruby
+MCP::Configuration.new(
+  protocol_version: "2025-11-25",      # Or: "2025-06-18", "2025-03-26", "2024-11-05"
+  exception_reporter: ->(exception, server_context) { ... },
+  instrumentation_callback: ->(data) { ... },
+  validate_tool_call_arguments: true   # Default: true
+)
+
+# Global configuration
+MCP.configure do |config|
+  config.protocol_version = "2025-11-25"
+  config.exception_reporter = ->(e, ctx) { ErrorTracker.report(e, ctx) }
+  config.instrumentation_callback = ->(data) { StatsD.increment(data[:method]) }
+end
+```
+
+### Instrumentation Data Keys
+
+```ruby
+{
+  method: "tools/call",      # JSON-RPC method
+  tool_name: "my_tool",      # For tools/call
+  prompt_name: "my_prompt",  # For prompts/get
+  resource_uri: "file://x",  # For resources/read
+  error: :tool_not_found,    # Error symbol if failed
+  duration: 0.123            # Seconds (auto-added)
+}
+```
+
+## Handler Overrides
+
+```ruby
+# Replace default handlers
+server.tools_list_handler do |params|
+  [{ name: "custom", description: "Custom tool" }]
+end
+
+server.tools_call_handler do |params|
+  MCP::Tool::Response.new([{ type: "text", text: "OK" }]).to_h
+end
+
+server.prompts_list_handler do |params|
+  [{ name: "custom", description: "Custom prompt" }]
+end
+
+server.prompts_get_handler do |params|
+  MCP::Prompt::Result.new(messages: [...]).to_h
+end
+
+server.resources_list_handler do |params|
+  [{ uri: "file:///x", name: "x" }]
+end
+
+server.resources_read_handler do |params|
+  { uri: params[:uri], mimeType: "text/plain", text: "Content" }
+end
+
+server.resources_templates_list_handler do |params|
+  [{ uriTemplate: "file:///{id}", name: "template" }]
+end
+```
+
+## Custom Methods
+
+```ruby
+# Define custom JSON-RPC method
+server.define_custom_method(method_name: "custom/method") do |params|
+  { result: params[:value] * 2 }  # Return value becomes result
+end
+
+# Notification method (return nil)
+server.define_custom_method(method_name: "custom/notify") do |params|
+  process_notification(params)
+  nil  # No response sent
+end
+```
+
+## Notifications
+
+```ruby
+# Requires: server.transport = transport
+server.notify_tools_list_changed
+server.notify_prompts_list_changed
+server.notify_resources_list_changed
+```
+
+---
+
+## See Also
+
+### Related References
+- **[Tools](tools.md)** - Tool definition DSL and response types
+- **[Prompts](prompts.md)** - Prompt definition and content types
+- **[Resources](resources.md)** - Resource and template definitions
+- **[Transport](transport.md)** - STDIO and HTTP transport configuration
+- **[Gotchas](gotchas.md)** - Configuration merging, notification quirks
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - Complete server with all components
+- **[`../examples/http_server.rb`](../examples/http_server.rb)** - HTTP server with Rack
+- **[`../examples/rails_integration.rb`](../examples/rails_integration.rb)** - Rails controller and routes
+- **[`../examples/dynamic_tools.rb`](../examples/dynamic_tools.rb)** - Runtime registration with notifications

data/skills/mcp-server/references/tools.md

@@ -0,0 +1,146 @@
+# MCP Tools Reference
+
+## Tool Definition
+
+Three patterns for defining tools:
+
+### Class-Based (recommended)
+
+```ruby
+class MyTool < MCP::Tool
+  # Name (optional - defaults to snake_case of class name)
+  tool_name "custom_name"
+
+  # Metadata
+  title "Human Title"
+  description "What this tool does"
+
+  # Input validation (JSON Schema)
+  input_schema(
+    type: "object",          # Default if omitted
+    properties: {
+      message: { type: "string", minLength: 1 },
+      count: { type: "integer", minimum: 0, maximum: 100 },
+      options: {
+        type: "object",
+        properties: { verbose: { type: "boolean" } }
+      },
+      tags: {
+        type: "array",
+        items: { type: "string" }
+      }
+    },
+    required: ["message"],
+    additionalProperties: false  # Strict mode
+  )
+
+  # Output documentation (optional)
+  output_schema(
+    properties: {
+      result: { type: "string" },
+      success: { type: "boolean" }
+    },
+    required: ["result", "success"]
+  )
+
+  # Behavior hints (protocol 2025-03-26+)
+  annotations(
+    read_only_hint: false,     # Default: false
+    destructive_hint: true,    # Default: true
+    idempotent_hint: false,    # Default: false
+    open_world_hint: true,     # Default: true
+    title: "Tool Title"
+  )
+
+  # Custom metadata
+  meta(version: "1.0", author: "Team")
+
+  # Implementation
+  class << self
+    def call(message:, count: 1, options: {}, server_context: nil)
+      MCP::Tool::Response.new([
+        { type: "text", text: "Result" }
+      ])
+    end
+  end
+end
+```
+
+### Block-Based (Tool.define)
+
+```ruby
+tool = MCP::Tool.define(
+  name: "tool_name",
+  title: "Tool Title",
+  description: "Description",
+  input_schema: { properties: { x: { type: "string" } } },
+  output_schema: { properties: { y: { type: "string" } } },
+  annotations: { read_only_hint: true },
+  meta: { version: "1.0" }
+) do |x:, server_context: nil|
+  MCP::Tool::Response.new([{ type: "text", text: x }])
+end
+```
+
+### Dynamic (server.define_tool)
+
+```ruby
+server.define_tool(
+  name: "dynamic_tool",
+  description: "Added at runtime",
+  input_schema: { properties: { arg: { type: "string" } } }
+) do |arg:, server_context:|
+  MCP::Tool::Response.new([{ type: "text", text: arg }])
+end
+```
+
+## Tool Response
+
+```ruby
+MCP::Tool::Response.new(
+  content,                    # Array of content items
+  error: false,              # Mark as error without exception
+  structured_content: nil    # Machine-readable data
+)
+
+# Content item types
+{ type: "text", text: "..." }
+{ type: "image", data: "base64...", mimeType: "image/png" }
+{ type: "resource", resource: { uri: "...", ... } }
+```
+
+## Schema Objects
+
+```ruby
+# As Hash (auto-converted)
+input_schema({ properties: { x: { type: "string" } } })
+
+# As InputSchema object
+input_schema MCP::Tool::InputSchema.new(
+  properties: { x: { type: "string" } },
+  required: ["x"]
+)
+
+# Schema methods
+schema.to_h
+schema.missing_required_arguments({ x: "value" })  # => []
+schema.validate_arguments({ x: 123 })  # Raises ValidationError
+```
+
+**Constraints:**
+- `$ref` is NOT allowed (raises ArgumentError)
+- Type defaults to "object" if not specified
+- Required fields auto-convert symbols to strings
+
+---
+
+## See Also
+
+### Related References
+- **[Server](server.md)** - Dynamic tool registration with `server.define_tool`
+- **[Gotchas](gotchas.md)** - Schema quirks, tool name derivation, validation flow
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - Class-based and dynamic tool definitions
+- **[`../examples/file_manager_tool.rb`](../examples/file_manager_tool.rb)** - Complex tool with security patterns
+- **[`../examples/dynamic_tools.rb`](../examples/dynamic_tools.rb)** - Runtime tool registration

data/skills/mcp-server/references/transport.md

@@ -0,0 +1,104 @@
+# MCP Transport Reference
+
+## Transport Configuration
+
+### StdioTransport
+
+```ruby
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open   # Blocking loop
+transport.close  # Signal stop
+transport.send_response({ jsonrpc: "2.0", result: {} })
+transport.send_notification("method", { key: "value" })
+```
+
+### StreamableHTTPTransport
+
+```ruby
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(
+  server,
+  stateless: false  # Default: false (session-based)
+)
+
+# Link to server for notifications
+server.transport = transport
+
+# Handle Rack requests
+response = transport.handle_request(rack_request)
+# Returns: [status, headers, body]
+
+# Send notifications
+transport.send_notification("method", params, session_id: id)  # Specific session
+transport.send_notification("method", params)  # Broadcast to all
+```
+
+## Request Handling
+
+```ruby
+# Handle Hash request
+response = server.handle({
+  jsonrpc: "2.0",
+  method: "tools/call",
+  params: { name: "my_tool", arguments: { x: 1 } },
+  id: 1
+})
+
+# Handle JSON string
+json_response = server.handle_json('{"jsonrpc":"2.0",...}')
+```
+
+## Protocol Methods
+
+```ruby
+# Core methods
+"initialize"
+"ping"
+"tools/list"
+"tools/call"
+"prompts/list"
+"prompts/get"
+"resources/list"
+"resources/read"
+"resources/templates/list"
+
+# Notifications (no response)
+"notifications/initialized"
+"notifications/tools/list_changed"
+"notifications/prompts/list_changed"
+"notifications/resources/list_changed"
+```
+
+## Error Classes
+
+```ruby
+MCP::Server::RequestHandlerError      # General request errors
+MCP::Server::MethodAlreadyDefinedError  # Duplicate custom method
+MCP::Server::ToolNotUnique            # Duplicate tool names
+MCP::Tool::InputSchema::ValidationError  # Schema validation failed
+MCP::Tool::OutputSchema::ValidationError  # Output validation failed
+MCP::Methods::MissingRequiredCapabilityError  # Capability not supported
+```
+
+## Protocol Versions
+
+| Version | Features Added |
+|---------|----------------|
+| 2024-11-05 | Base protocol |
+| 2025-03-26 | `instructions`, `annotations`, `title` (server) |
+| 2025-06-18 | `title`, `website_url` |
+| 2025-11-25 | `description` (latest stable) |
+
+---
+
+## See Also
+
+### Related References
+- **[Server](server.md)** - Server initialization and `server.transport` linking
+- **[Gotchas](gotchas.md)** - StreamableHTTP quirks, notification behavior, error handling
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - STDIO transport usage
+- **[`../examples/http_server.rb`](../examples/http_server.rb)** - Streamable HTTP with Rack
+- **[`../examples/rails_integration.rb`](../examples/rails_integration.rb)** - HTTP transport in Rails
+- **[`../examples/http_client.rb`](../examples/http_client.rb)** - Client connecting to HTTP server
+- **[`../examples/streaming_client.rb`](../examples/streaming_client.rb)** - SSE streaming client

data/skills/ratatui-ruby/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: ratatui-ruby
+description: "RatatuiRuby terminal UI development — widgets, layouts, events, Tea MVU. Activate when building TUI apps, working with RatatuiRuby, terminal rendering, or editing TUI application files."
+---
+
+# RatatuiRuby
+
+This skill provides guidance for building terminal user interfaces with RatatuiRuby, a Ruby gem wrapping Rust's Ratatui library. Use for TUI development, terminal widgets, layout systems, event handling, and testing terminal applications.
+
+## Quick Reference
+
+### Minimal Application
+
+```ruby
+require "ratatui_ruby"
+
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      widget = tui.paragraph(text: "Hello, TUI!", block: tui.block(title: "App"))
+      frame.render_widget(widget, frame.area)
+    end
+
+    case tui.poll_event
+    in {type: :key, code: "q"}
+      break
+    in {type: :key, code: "c", modifiers: ["ctrl"]}
+      break
+    else
+      # Continue
+    end
+  end
+end
+```
+
+### Key Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| `RatatuiRuby.run` | Managed loop handling terminal setup/teardown |
+| `tui.draw` | Render widgets each frame |
+| `tui.poll_event` | Capture keyboard/mouse input |
+| `frame.area` | Available rendering area (Rect) |
+| `frame.render_widget` | Render stateless widgets |
+| `frame.render_stateful_widget` | Render widgets with state (List, Table) |
+
+### Two Operating Modes
+
+| Mode | Use Case | Setup |
+|------|----------|-------|
+| **Full-Screen** | Complete TUI applications | `RatatuiRuby.run { }` (default) |
+| **Inline Viewport** | Rich CLI moments (spinners, progress) | `RatatuiRuby.run(viewport: :inline, height: 5) { }` |
+
+**Full-Screen**: Takes over terminal, alternate screen, restored on exit.
+
+**Inline Viewport**: Preserves scrollback, fixed-height widget area, output remains visible after exit.
+
+## Core Pattern
+
+The managed loop pattern handles terminal lifecycle:
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    # 1. Draw UI
+    tui.draw do |frame|
+      # Render widgets
+    end
+
+    # 2. Handle events
+    case tui.poll_event
+    in {type: :key, code: "q"}
+      break
+    end
+  end
+end
+```
+
+## Common Widgets
+
+| Widget | Factory | Purpose |
+|--------|---------|---------|
+| Paragraph | `tui.paragraph(text:)` | Text display |
+| Block | `tui.block(title:, borders:)` | Borders, titles, padding |
+| List | `tui.list(items:)` | Selectable item list |
+| Table | `tui.table(rows:, widths:)` | Tabular data |
+| Gauge | `tui.gauge(ratio:)` | Progress indication |
+| Tabs | `tui.tabs(titles:)` | Tab navigation |
+| Chart | `tui.chart(datasets:)` | Data visualization |
+| Canvas | `tui.canvas { }` | Custom drawing |
+| Scrollbar | `tui.scrollbar` | Scroll indication |
+
+### Stateless vs Stateful Widgets
+
+**Stateless** (Paragraph, Block, Gauge):
+
+```ruby
+widget = tui.paragraph(text: "Hello")
+frame.render_widget(widget, frame.area)
+```
+
+**Stateful** (List, Table):
+
+```ruby
+# Create state once (outside draw loop)
+list_state = tui.list_state(0)
+
+# In draw block
+list = tui.list(items: ["Item A", "Item B", "Item C"])
+frame.render_stateful_widget(list, frame.area, list_state)
+
+# Update state on input
+list_state.select_next if event_down?
+```
+
+### Block Composition
+
+Wrap widgets with Block for borders and titles:
+
+```ruby
+block = tui.block(
+  title: "Main",
+  titles: [
+    {content: "Help: q", position: :bottom, alignment: :right}
+  ],
+  borders: [:all],
+  border_style: {fg: "cyan"}
+)
+
+paragraph = tui.paragraph(text: "Content", block:)
+```
+
+## Layout
+
+Split areas using constraints:
+
+```ruby
+layout = tui.layout(
+  direction: :vertical,
+  constraints: [
+    tui.constraint(:percentage, 20),  # Header: 20%
+    tui.constraint(:min, 0),           # Body: remaining
+    tui.constraint(:length, 3)         # Footer: 3 rows
+  ]
+)
+
+chunks = layout.split(frame.area)
+# chunks[0] -> header area
+# chunks[1] -> body area
+# chunks[2] -> footer area
+```
+
+### Constraint Types
+
+| Type | Syntax | Behavior |
+|------|--------|----------|
+| Length | `tui.constraint(:length, 5)` | Fixed 5 rows/cols |
+| Percentage | `tui.constraint(:percentage, 50)` | 50% of parent |
+| Min | `tui.constraint(:min, 10)` | At least 10 |
+| Max | `tui.constraint(:max, 20)` | At most 20 |
+| Ratio | `tui.constraint(:ratio, 1, 3)` | 1/3 of space |
+| Fill | `tui.constraint(:fill)` | Expand into excess |
+
+## Event Handling
+
+### Pattern Matching
+
+```ruby
+case tui.poll_event
+in {type: :key, code: "q"}
+  break
+in {type: :key, code: "j"} | {type: :key, code: "down"}
+  list_state.select_next
+in {type: :key, code: "k"} | {type: :key, code: "up"}
+  list_state.select_previous
+in {type: :key, code: "c", modifiers: ["ctrl"]}
+  break
+in {type: :mouse, kind: "down", button: "left", x:, y:}
+  handle_click(x, y)
+in {type: :resize}
+  # Terminal resized, next draw adapts
+end
+```
+
+### Event Helper Methods
+
+```ruby
+event = tui.poll_event
+break if event.ctrl_c?
+list_state.select_next if event.down? || event.j?
+```
+
+## Styling
+
+Hash-based syntax for colors and modifiers:
+
+```ruby
+tui.paragraph(
+  text: "Styled text",
+  style: {fg: "green", bold: true},
+  block: tui.block(border_style: {fg: "cyan"})
+)
+```
+
+### Text Composition
+
+```ruby
+line = tui.line([
+  tui.span("Normal "),
+  tui.span("Bold", style: {bold: true}),
+  tui.span(" Red", style: {fg: "red"})
+])
+
+tui.paragraph(text: line)
+```
+
+### Color Options
+
+- Named: `"red"`, `"green"`, `"cyan"`, `"white"`
+- Hex: `"#FF5733"`
+- Indexed: 0-255 palette
+
+## Testing
+
+```ruby
+require "ratatui_ruby/test_helper"
+
+class MyAppTest < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def test_renders_greeting
+    with_test_terminal(80, 24) do
+      RatatuiRuby.draw do |frame|
+        widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
+        frame.render_widget(widget, frame.area)
+      end
+
+      assert_snapshots("greeting")  # Creates/compares snapshots/greeting.txt
+    end
+  end
+
+  def test_keyboard_navigation
+    with_test_terminal do
+      inject_keys("j", "j", "k")  # Down, down, up
+      # Assert state changes
+    end
+  end
+end
+```
+
+## Frameworks
+
+### Tea (MVU Architecture)
+
+Functional, Elm-style architecture for predictable state:
+
+```ruby
+require "ratatui_ruby/tea"
+
+class Counter
+  include RatatuiRuby::Tea::App
+
+  def init
+    [Model.new(count: 0), nil]
+  end
+
+  def view(model, tui)
+    tui.paragraph(text: "Count: #{model.count}")
+  end
+
+  def update(message, model)
+    case message
+    in {type: :key, code: "q"}
+      [model, RatatuiRuby::Tea::Command.exit]
+    in {type: :key, code: "j"}
+      [model.with(count: model.count + 1), nil]
+    else
+      [model, nil]
+    end
+  end
+end
+
+Counter.new.run
+```
+
+## Best Practices
+
+### Do
+
+- Use `RatatuiRuby.run` for managed terminal lifecycle
+- Create state objects outside the draw loop
+- Use pattern matching for event handling
+- Use inline viewports for CLI "rich moments"
+- Test with `RatatuiRuby::TestHelper`
+
+### Don't
+
+- Handle Ctrl+C manually (use `event.ctrl_c?` helper)
+- Forget to break the loop (leads to CPU spin)
+- Render widgets before poll_event (blocks input)
+- Use full-screen for simple progress indicators
+
+## Additional Resources
+
+### Reference Files
+
+For detailed API documentation and patterns:
+
+- **`references/core-concepts.md`** - Managed loop, terminal lifecycle, inline vs full-screen
+- **`references/widgets.md`** - Complete widget catalog, composition patterns
+- **`references/layout.md`** - Constraints, directions, nested layouts
+- **`references/events.md`** - Keyboard, mouse, event handling patterns
+- **`references/styling.md`** - Colors, modifiers, text composition
+- **`references/testing.md`** - TestHelper, snapshots, event injection
+- **`references/frameworks.md`** - Tea MVU, Kit components