anima-core 0.2.1 → 1.0.0

data/skills/mcp-server/examples/rails_integration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Rails MCP Integration
+# Demonstrates: server_context with auth, configuration in initializer, permission checks
+#
+# See: ../references/server.md, ../references/transport.md, ../references/tools.md
+#
+# Add these files to your Rails application
+
+# config/routes.rb
+Rails.application.routes.draw do
+  post "/mcp", to: "mcp#handle"
+end
+
+# app/controllers/mcp_controller.rb
+class McpController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def handle
+    server = build_server
+    response = server.handle_json(request.body.read)
+    render json: response
+  end
+
+  private
+
+  def build_server
+    MCP::Server.new(
+      name: "rails_mcp",
+      version: Rails.application.config.version,
+      tools: [
+        UserSearchTool,
+        CreateRecordTool,
+        DatabaseQueryTool
+      ],
+      server_context: {
+        user_id: current_user&.id,
+        request_id: request.uuid,
+        permissions: current_user&.permissions || []
+      },
+      configuration: Rails.application.config.mcp_configuration
+    )
+  end
+end
+
+# config/initializers/mcp.rb
+Rails.application.config.mcp_configuration = MCP::Configuration.new(
+  protocol_version: "2025-11-25",
+  exception_reporter: ->(e, ctx) {
+    Rails.logger.error("MCP Error: #{e.message}")
+    Bugsnag.notify(e) { |r| r.add_metadata(:mcp, ctx) }
+  },
+  instrumentation_callback: ->(data) {
+    ActiveSupport::Notifications.instrument("mcp.request", data)
+  }
+)
+
+# app/tools/user_search_tool.rb
+class UserSearchTool < MCP::Tool
+  description "Searches for users by name or email"
+  input_schema(
+    properties: {
+      query: { type: "string", minLength: 2 },
+      limit: { type: "integer", minimum: 1, maximum: 100 }
+    },
+    required: ["query"]
+  )
+
+  class << self
+    def call(query:, limit: 10, server_context:)
+      unless server_context[:permissions].include?("users:read")
+        return MCP::Tool::Response.new(
+          [{ type: "text", text: "Permission denied" }],
+          error: true
+        )
+      end
+
+      users = User.where("name ILIKE ? OR email ILIKE ?", "%#{query}%", "%#{query}%")
+                  .limit(limit)
+                  .select(:id, :name, :email)
+
+      MCP::Tool::Response.new(
+        [{ type: "text", text: users.to_json }],
+        structured_content: users.as_json
+      )
+    end
+  end
+end

data/skills/mcp-server/examples/stdio_server.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Complete STDIO MCP Server
+# Demonstrates: Class-based tools, prompts, resources, dynamic tool definition
+#
+# See: ../references/tools.md, ../references/prompts.md, ../references/transport.md
+#
+# Run: ruby stdio_server.rb
+# Then type JSON-RPC requests:
+#   {"jsonrpc":"2.0","id":1,"method":"ping"}
+#   {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+#   {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":5,"b":3}}}
+
+require "mcp"
+
+class AddTool < MCP::Tool
+  description "Adds two numbers together"
+  input_schema(
+    properties: {
+      a: { type: "number" },
+      b: { type: "number" }
+    },
+    required: %w[a b]
+  )
+
+  class << self
+    def call(a:, b:, server_context: nil)
+      MCP::Tool::Response.new([{
+        type: "text",
+        text: "#{a} + #{b} = #{a + b}"
+      }])
+    end
+  end
+end
+
+class CodeReviewPrompt < MCP::Prompt
+  description "Generates a code review prompt"
+  arguments [
+    MCP::Prompt::Argument.new(
+      name: "code",
+      description: "The code to review",
+      required: true
+    ),
+    MCP::Prompt::Argument.new(
+      name: "language",
+      description: "Programming language",
+      required: false
+    )
+  ]
+
+  class << self
+    def template(args, server_context:)
+      lang = args[:language] || "unknown"
+      MCP::Prompt::Result.new(
+        description: "Code review request",
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new(
+              "Review this #{lang} code:\n\n```#{lang}\n#{args[:code]}\n```"
+            )
+          )
+        ]
+      )
+    end
+  end
+end
+
+config_resource = MCP::Resource.new(
+  uri: "config://app",
+  name: "app-config",
+  description: "Application configuration",
+  mime_type: "application/json"
+)
+
+server = MCP::Server.new(
+  name: "example_server",
+  version: "1.0.0",
+  tools: [AddTool],
+  prompts: [CodeReviewPrompt],
+  resources: [config_resource]
+)
+
+# Dynamic tool example
+server.define_tool(
+  name: "echo",
+  description: "Echoes input back",
+  input_schema: {
+    properties: { message: { type: "string" } },
+    required: ["message"]
+  }
+) do |message:|
+  MCP::Tool::Response.new([{ type: "text", text: message }])
+end
+
+# Resource handler
+server.resources_read_handler do |params|
+  case params[:uri]
+  when "config://app"
+    { uri: params[:uri], mimeType: "application/json", text: '{"env":"prod"}' }
+  else
+    { uri: params[:uri], mimeType: "text/plain", text: "Unknown resource" }
+  end
+end
+
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open

data/skills/mcp-server/examples/streaming_client.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SSE Streaming Client
+# Demonstrates: SSE connections, session management, real-time notifications
+#
+# See: ../references/transport.md, ../references/gotchas.md
+
+require "net/http"
+require "json"
+
+class MCPStreamingClient
+  def initialize(base_url)
+    @base_url = base_url
+    @session_id = nil
+  end
+
+  def connect
+    response = post_request("initialize", {})
+    @session_id = response["Mcp-Session-Id"]
+
+    @sse_thread = Thread.new { listen_sse }
+    sleep(0.5)
+  end
+
+  def call_tool(name, arguments)
+    post_request("tools/call", { name:, arguments: })
+  end
+
+  def disconnect
+    @sse_thread&.kill
+    delete_request if @session_id
+    @session_id = nil
+  end
+
+  private
+
+  def post_request(method, params)
+    uri = URI(@base_url)
+    http = Net::HTTP.new(uri.host, uri.port)
+
+    request = Net::HTTP::Post.new(uri.path.empty? ? "/" : uri.path)
+    request["Content-Type"] = "application/json"
+    request["Mcp-Session-Id"] = @session_id if @session_id
+
+    request.body = {
+      jsonrpc: "2.0",
+      method:,
+      params:,
+      id: rand(10000)
+    }.to_json
+
+    response = http.request(request)
+    @session_id ||= response["Mcp-Session-Id"]
+
+    JSON.parse(response.body)
+  end
+
+  def listen_sse
+    uri = URI(@base_url)
+    Net::HTTP.start(uri.host, uri.port) do |http|
+      request = Net::HTTP::Get.new(uri)
+      request["Mcp-Session-Id"] = @session_id
+      request["Accept"] = "text/event-stream"
+
+      http.request(request) do |response|
+        response.read_body do |chunk|
+          chunk.split("\n").each do |line|
+            next unless line.start_with?("data: ")
+
+            data = JSON.parse(line[6..])
+            puts "SSE Event: #{data['method']}"
+          end
+        end
+      end
+    end
+  rescue StandardError => e
+    puts "SSE Error: #{e.message}"
+  end
+
+  def delete_request
+    uri = URI(@base_url)
+    http = Net::HTTP.new(uri.host, uri.port)
+    request = Net::HTTP::Delete.new(uri.path.empty? ? "/" : uri.path)
+    request["Mcp-Session-Id"] = @session_id
+    http.request(request)
+  end
+end
+
+# Usage
+client = MCPStreamingClient.new("http://localhost:9292")
+client.connect
+result = client.call_tool("echo", { message: "Hello!" })
+puts result
+client.disconnect

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

@@ -0,0 +1,183 @@
+# MCP Ruby SDK - Gotchas and Error Handling
+
+## Tricky Behaviors
+
+### Schema Transformation
+
+**Symbol keys become string keys:**
+```ruby
+input_schema({ required: [:message] })
+# Stored as: { required: ["message"] }
+```
+
+### JSON-RPC ID Validation
+
+**IDs are validated against alphanumeric pattern:**
+```ruby
+id: "<script>alert('xss')</script>"  # REJECTED
+id: "request-123_ABC"  # OK
+id: "550e8400-e29b-41d4-a716-446655440000"  # OK (UUID)
+```
+
+**Invalid IDs in error responses become nil:**
+```ruby
+error_response(id: "<invalid>")
+# Returns: { ..., id: nil, ... }
+```
+
+### Batch Requests
+
+**Single-item batch responses are unwrapped:**
+```ruby
+# Request: [{ ... }] (array with one item)
+# Response: { ... } (single object, NOT array)
+
+# Request: [{ ... }, { ... }] (two items)
+# Response: [{ ... }, { ... }] (array)
+```
+
+### Server Context Detection
+
+**Framework inspects method signature:**
+```ruby
+# These receive server_context:
+def call(message:, server_context: nil)  # Detected
+def call(message:, server_context:)      # Detected
+def call(**kwargs)                        # Detected (keyrest)
+
+# This doesn't:
+def call(message:)  # NOT detected
+```
+
+### Tool Name Derivation
+
+**Class names auto-convert to snake_case:**
+```ruby
+class MyCustomTool < MCP::Tool; end
+# Name: "my_custom_tool"
+
+class HTMLParser < MCP::Tool; end
+# Name: "html_parser"
+```
+
+### Notifications
+
+**No response for notifications (requests without id):**
+```ruby
+server.handle({ jsonrpc: "2.0", method: "ping" })  # => nil
+```
+
+**Silent no-op if no transport:**
+```ruby
+server.notify_tools_list_changed  # Does nothing if transport not set
+```
+
+### StreamableHTTP Transport
+
+**GET only works in stateful mode:**
+```ruby
+# Stateless: GET returns 405
+# Stateful: GET sets up SSE stream
+```
+
+**Session cleanup on stream errors:**
+```ruby
+# IOError/EPIPE automatically cleans up session
+```
+
+### Configuration Merging
+
+**Non-nil values from other config take precedence:**
+```ruby
+config1 = Configuration.new(protocol_version: "2025-03-26")
+config2 = Configuration.new  # Uses default
+
+merged = config1.merge(config2)
+# Uses config1's version (config2 didn't set explicitly)
+```
+
+### Validation Flow
+
+**Two-step validation:**
+```ruby
+# Step 1: Check required fields (always)
+# Step 2: JSON Schema validation (if validate_tool_call_arguments = true)
+```
+
+---
+
+## Error Handling
+
+### Error Classes
+
+```ruby
+MCP::Server::RequestHandlerError      # General request errors
+  # error_type: :internal_error, :tool_not_found, :prompt_not_found,
+  #             :missing_required_arguments, :invalid_schema
+
+MCP::Server::MethodAlreadyDefinedError  # Duplicate custom method
+MCP::Server::ToolNotUnique              # Duplicate tool names
+MCP::Tool::InputSchema::ValidationError  # Schema validation failed
+MCP::Methods::MissingRequiredCapabilityError  # Capability not supported
+```
+
+### JSON-RPC Error Codes
+
+```ruby
+PARSE_ERROR = -32700       # Invalid JSON
+INVALID_REQUEST = -32600   # Malformed request
+METHOD_NOT_FOUND = -32601  # Method doesn't exist
+INVALID_PARAMS = -32602    # Invalid parameters
+INTERNAL_ERROR = -32603    # Server error
+```
+
+### Tool Errors vs JSON-RPC Errors
+
+```ruby
+# Tool errors (business logic) - return response with isError: true
+{ content: [...], isError: true }
+
+# JSON-RPC errors (protocol) - return error object
+{ jsonrpc: "2.0", id: 1, error: { code: -32600, ... } }
+```
+
+### Client Error Handling
+
+```ruby
+client.call_tool(tool:, arguments:)
+rescue MCP::Client::RequestHandlerError => e
+  case e.error_type
+  when :bad_request          # 400
+  when :unauthorized         # 401
+  when :forbidden            # 403
+  when :not_found            # 404
+  when :unprocessable_entity # 422
+  when :internal_error       # Other
+  end
+end
+```
+
+### Transport Error Handling
+
+**StdioTransport catches Interrupt:**
+```ruby
+# Ctrl-C exits with status 130 (SIGINT)
+```
+
+**StreamableHTTP handles stream errors:**
+```ruby
+# IOError/EPIPE caught, session cleaned up, returns false
+```
+
+---
+
+## See Also
+
+### Related References
+- **[Tools](tools.md)** - Schema definition and validation
+- **[Server](server.md)** - Configuration and notifications
+- **[Transport](transport.md)** - Transport-specific behaviors
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - Basic patterns avoiding common pitfalls
+- **[`../examples/http_server.rb`](../examples/http_server.rb)** - HTTP error handling

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

@@ -0,0 +1,98 @@
+# MCP Prompts Reference
+
+## Prompt Definition
+
+### Class-Based
+
+```ruby
+class MyPrompt < MCP::Prompt
+  prompt_name "custom_name"  # Optional
+  title "Prompt Title"
+  description "What this prompt does"
+
+  arguments [
+    MCP::Prompt::Argument.new(
+      name: "message",
+      title: "Message Title",
+      description: "The input message",
+      required: true
+    ),
+    MCP::Prompt::Argument.new(
+      name: "context",
+      description: "Optional context",
+      required: false
+    )
+  ]
+
+  meta(version: "1.0", category: "general")
+
+  class << self
+    def template(args, server_context:)
+      MCP::Prompt::Result.new(
+        description: "Result description",
+        messages: [
+          MCP::Prompt::Message.new(
+            role: "user",
+            content: MCP::Content::Text.new(args[:message])
+          ),
+          MCP::Prompt::Message.new(
+            role: "assistant",
+            content: MCP::Content::Text.new("Response")
+          )
+        ]
+      )
+    end
+  end
+end
+```
+
+### Block-Based
+
+```ruby
+prompt = MCP::Prompt.define(
+  name: "prompt_name",
+  title: "Title",
+  description: "Description",
+  arguments: [
+    MCP::Prompt::Argument.new(name: "arg", required: true)
+  ],
+  meta: { version: "1.0" }
+) do |args, server_context:|
+  MCP::Prompt::Result.new(
+    messages: [
+      MCP::Prompt::Message.new(
+        role: "user",
+        content: MCP::Content::Text.new(args[:arg])
+      )
+    ]
+  )
+end
+```
+
+## Content Types
+
+```ruby
+# Text content
+MCP::Content::Text.new(
+  "Text content",
+  annotations: { key: "value" }  # Optional
+)
+
+# Image content
+MCP::Content::Image.new(
+  "base64_encoded_data",
+  "image/png",
+  annotations: { source: "camera" }
+)
+```
+
+---
+
+## See Also
+
+### Related References
+- **[Server](server.md)** - Prompt registration and handler overrides
+- **[Transport](transport.md)** - Protocol methods (`prompts/list`, `prompts/get`)
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - Class-based prompt definition (`CodeReviewPrompt`)

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

@@ -0,0 +1,53 @@
+# MCP Resources Reference
+
+## Resource Definition
+
+```ruby
+# Static resource
+MCP::Resource.new(
+  uri: "file:///path/to/file",
+  name: "resource-name",
+  title: "Resource Title",      # Optional
+  description: "Description",   # Optional
+  mime_type: "text/plain"       # Optional
+)
+
+# Resource template (dynamic URIs)
+MCP::ResourceTemplate.new(
+  uri_template: "file:///{path}",  # RFC 6570
+  name: "template-name",
+  title: "Template Title",
+  description: "Description",
+  mime_type: "text/plain"
+)
+```
+
+## Resource Contents
+
+```ruby
+# Text content
+MCP::Resource::TextContents.new(
+  text: "File content",
+  uri: "file:///path",
+  mime_type: "text/plain"
+)
+
+# Binary content
+MCP::Resource::BlobContents.new(
+  data: "base64_encoded",
+  uri: "file:///image.png",
+  mime_type: "image/png"
+)
+```
+
+---
+
+## See Also
+
+### Related References
+- **[Server](server.md)** - Resource registration and `resources_read_handler`
+- **[Transport](transport.md)** - Protocol methods (`resources/list`, `resources/read`, `resources/templates/list`)
+
+### Related Examples
+- **[`../examples/stdio_server.rb`](../examples/stdio_server.rb)** - Static resource with read handler
+- **[`../examples/file_manager_tool.rb`](../examples/file_manager_tool.rb)** - File-based resources with security