vector_mcp 0.3.0 → 0.3.1

data/README.md

@@ -1,655 +1,446 @@
 # VectorMCP
 
-<!-- Badges (Add URLs later) -->
 [![Gem Version](https://badge.fury.io/rb/vector_mcp.svg)](https://badge.fury.io/rb/vector_mcp)
 [![Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://sergiobayona.github.io/vector_mcp/)
 [![Build Status](https://github.com/sergiobayona/VectorMCP/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sergiobayona/vector_mcp/actions/workflows/ruby.yml)
 [![Maintainability](https://qlty.sh/badges/fdb143b3-148a-4a86-8e3b-4ccebe993528/maintainability.svg)](https://qlty.sh/gh/sergiobayona/projects/vector_mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-VectorMCP provides server-side tools for implementing the [Model Context Protocol (MCP)](https://modelcontext.dev/) in Ruby applications. MCP is a specification for how Large Language Models (LLMs) can discover and interact with external tools, resources, and prompts provided by separate applications (MCP Servers).
+VectorMCP is a Ruby gem implementing the Model Context Protocol (MCP) server-side specification. It provides a framework for creating MCP servers that expose tools, resources, prompts, and roots to LLM clients.
 
-This library allows you to easily create MCP servers that expose your application's capabilities (like functions, data sources, or predefined prompt templates) to compatible LLM clients (e.g., Claude Desktop App, custom clients).
+## Why VectorMCP?
 
-## Features
+- **🛡️ Security-First**: Built-in input validation and schema checking prevent injection attacks
+- **⚡ Production-Ready**: Robust error handling, comprehensive test suite, and proven reliability  
+- **🔌 Multiple Transports**: stdio for CLI tools, SSE for web applications
+- **📦 Zero Configuration**: Works out of the box with sensible defaults
+- **🔄 Fully Compatible**: Implements the complete MCP specification
 
-*   **MCP Specification Adherence:** Implements core server-side aspects of the MCP specification.
-*   **Tools:** Define and register custom tools (functions) that the LLM can invoke.
-*   **Resources:** Expose data sources (files, database results, API outputs) for the LLM to read.
-*   **Prompts:** Provide structured prompt templates the LLM can request and use.
-*   **Roots:** Define filesystem boundaries where the server can operate, enhancing security and providing workspace context.
-*   **Sampling:** Server-initiated LLM requests with configurable capabilities (streaming, tool calls, images, token limits).
-*   **Transport:**
-    *   **Stdio (stable):** Simple transport using standard input/output, ideal for process-based servers.
-    *   **SSE (stable):** Server-Sent Events over HTTP, enabling web-based MCP clients and browser integration.
-
-## Installation
-
-```ruby
-# In your Gemfile
-gem 'vector_mcp'
+## Quick Start
 
-# Or install directly
+```bash
 gem install vector_mcp
 ```
 
-
-## Quick Start
-
 ```ruby
 require 'vector_mcp'
 
-# Create a server with sampling capabilities
-server = VectorMCP.new(
-  name: 'Echo Server',
-  version: '1.0.0',
-  sampling_config: {
-    supports_streaming: true,
-    max_tokens_limit: 2000,
-    timeout_seconds: 45
-  }
-)
-
-# Register filesystem roots for security and context
-server.register_root_from_path('.', name: 'Current Project')
-server.register_root_from_path('./examples', name: 'Examples')
+# Create a server
+server = VectorMCP.new(name: 'MyApp', version: '1.0.0')
 
-# Register a tool
+# Add a tool
 server.register_tool(
-  name: 'echo',
-  description: 'Returns whatever message you send.',
+  name: 'greet',
+  description: 'Says hello to someone',
   input_schema: {
     type: 'object',
-    properties: { message: { type: 'string' } },
-    required: ['message']
+    properties: { name: { type: 'string' } },
+    required: ['name']
   }
-) { |args, _session| args['message'] }
+) { |args| "Hello, #{args['name']}!" }
 
-# Start listening on STDIN/STDOUT
-server.run
+# Start the server
+server.run  # Uses stdio transport by default
 ```
 
-**To test with stdin/stdout:**
-
-```bash
-$ ruby my_server.rb
-# Then paste JSON-RPC requests, one per line:
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"CLI","version":"0.1"}}}
-```
+**That's it!** Your MCP server is ready to connect with Claude Desktop, custom clients, or any MCP-compatible application.
 
-Or use a script:
+## Transport Options
 
-```bash
-{ 
-  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"CLI","version":"0.1"}}}';
-  printf '%s\n' '{"jsonrpc":"2.0","method":"initialized"}';
-  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}';
-  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}';
-  printf '%s\n' '{"jsonrpc":"2.0","id":4,"method":"roots/list","params":{}}';
-  printf '%s\n' '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello VectorMCP!"}}}';
-} | ruby my_server.rb | jq
-```
+### Command Line Tools (stdio)
 
-### HTTP/SSE Transport
-
-For web-based clients and browser integration, use the SSE transport:
+Perfect for desktop applications and process-based integrations:
 
 ```ruby
-require 'vector_mcp'
+server.run  # Default: stdio transport
+```
 
-server = VectorMCP.new(
-  name: 'My HTTP Server',
-  version: '1.0.0'
-)
+### Web Applications (HTTP + SSE)
 
-# Register tools, resources, prompts...
-server.register_tool(
-  name: 'echo',
-  description: 'Returns the input message',
-  input_schema: {
-    type: 'object',
-    properties: { message: { type: 'string' } },
-    required: ['message']
-  }
-) { |args| args['message'] }
+Ideal for web apps and browser-based clients:
 
-# Start HTTP server with SSE transport
-server.run(transport: :sse, options: { port: 8080, host: 'localhost' })
+```ruby
+server.run(transport: :sse, port: 8080)
 ```
 
-The server provides two HTTP endpoints:
+Connect via Server-Sent Events at `http://localhost:8080/sse`
 
-*   **SSE Stream:** `GET /sse` - Establishes server-sent events connection
-*   **Messages:** `POST /message?session_id=<id>` - Sends JSON-RPC requests
+## Core Features
 
-**Client Integration:**
+### Tools (Functions)
 
-```javascript
-// Connect to SSE stream
-const eventSource = new EventSource('http://localhost:8080/sse');
-
-eventSource.addEventListener('endpoint', (event) => {
-  const data = JSON.parse(event.data);
-  const messageUrl = data.uri; // POST endpoint for this session
-  
-  // Send MCP initialization
-  fetch(messageUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      jsonrpc: '2.0',
-      id: 1,
-      method: 'initialize',
-      params: { 
-        protocolVersion: '2024-11-05', 
-        capabilities: {},
-        clientInfo: { name: 'WebClient', version: '1.0' }
-      }
-    })
-  });
-});
+Expose functions that LLMs can call:
 
-eventSource.addEventListener('message', (event) => {
-  const response = JSON.parse(event.data);
-  console.log('MCP Response:', response);
-});
+```ruby
+server.register_tool(
+  name: 'calculate',
+  description: 'Performs basic math',
+  input_schema: {
+    type: 'object',
+    properties: {
+      operation: { type: 'string', enum: ['add', 'subtract', 'multiply'] },
+      a: { type: 'number' },
+      b: { type: 'number' }
+    },
+    required: ['operation', 'a', 'b']
+  }
+) do |args|
+  case args['operation']
+  when 'add' then args['a'] + args['b']
+  when 'subtract' then args['a'] - args['b']
+  when 'multiply' then args['a'] * args['b']
+  end
+end
 ```
 
-## Core Usage
+### Resources (Data Sources)
 
-### Creating a Server
+Provide data that LLMs can read:
 
 ```ruby
-# Using the convenience method
-server = VectorMCP.new(
-  name: "MyServer",
-  version: "1.0.0",
-  log_level: Logger::INFO,
-  sampling_config: {
-    enabled: true,
-    supports_streaming: false,
-    max_tokens_limit: 4000,
-    timeout_seconds: 30
-  }
-)
-
-# Or using the explicit class method
-server = VectorMCP::Server.new(
-  name: "MyServer",
-  version: "1.0.0",
-  sampling_config: { enabled: false }  # Disable sampling entirely
-)
+server.register_resource(
+  uri: 'file://config.json',
+  name: 'App Configuration',
+  description: 'Current application settings'
+) { File.read('config.json') }
 ```
 
-The `sampling_config` parameter allows you to configure what sampling capabilities your server advertises to clients. See the [Sampling Configuration](#configuring-sampling-capabilities) section for detailed options.
+### Prompts (Templates)
 
-### Registering Tools
-
-Tools are functions your server exposes to clients.
+Create reusable prompt templates:
 
 ```ruby
-server.register_tool(
-  name: "calculate_sum",
-  description: "Adds two numbers together.",
-  input_schema: {
-    type: "object",
-    properties: {
-      a: { type: "number" },
-      b: { type: "number" }
-    },
-    required: ["a", "b"]
+server.register_prompt(
+  name: 'code_review',
+  description: 'Reviews code for best practices',
+  arguments: [
+    { name: 'language', description: 'Programming language', required: true },
+    { name: 'code', description: 'Code to review', required: true }
+  ]
+) do |args|
+  {
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: "Review this #{args['language']} code:\n\n#{args['code']}"
+      }
+    }]
   }
-) do |args, session|
-  sum = args["a"] + args["b"]
-  "The sum is: #{sum}"
 end
 ```
 
-#### Automatic Input Validation
+## Security Features
 
-VectorMCP automatically validates all tool arguments against their defined `input_schema` before executing the tool handler. This provides several security and reliability benefits:
+VectorMCP provides comprehensive, **opt-in security** for production applications:
 
-- **Type Safety**: Ensures arguments match expected types (string, number, boolean, etc.)
-- **Required Fields**: Validates that all required parameters are present
-- **Format Validation**: Supports JSON Schema constraints like patterns, enums, and ranges
-- **Security**: Prevents injection attacks and malformed input from reaching your tool logic
-- **Better Error Messages**: Provides clear validation errors to help clients fix their requests
+### Built-in Input Validation
+
+All inputs are automatically validated against your schemas:
 
 ```ruby
-# Example with comprehensive validation
+# This tool is protected against invalid inputs
 server.register_tool(
-  name: "process_user_data",
-  description: "Processes user information with strict validation",
+  name: 'process_user',
   input_schema: {
-    type: "object",
+    type: 'object',
     properties: {
-      name: { 
-        type: "string", 
-        minLength: 1, 
-        maxLength: 100,
-        pattern: "^[a-zA-Z\\s]+$"
-      },
-      age: { 
-        type: "integer", 
-        minimum: 0, 
-        maximum: 150 
-      },
-      email: { 
-        type: "string", 
-        format: "email" 
-      },
-      role: { 
-        type: "string", 
-        enum: ["admin", "user", "guest"] 
-      },
-      preferences: {
-        type: "object",
-        properties: {
-          theme: { type: "string" },
-          notifications: { type: "boolean" }
-        },
-        additionalProperties: false
-      }
+      email: { type: 'string', format: 'email' },
+      age: { type: 'integer', minimum: 0, maximum: 150 }
     },
-    required: ["name", "email", "role"],
-    additionalProperties: false
+    required: ['email']
   }
-) do |args, session|
-  # At this point, you can trust that:
-  # - All required fields are present
-  # - Data types are correct
-  # - String lengths and number ranges are valid
-  # - Email format is valid
-  # - Role is one of the allowed values
-  
-  "Processing user: #{args['name']} (#{args['role']})"
-end
-```
-
-**What happens with invalid input:**
-- VectorMCP returns a JSON-RPC error response with code `-32602` (Invalid params)
-- The error message includes specific details about what validation failed
-- Your tool handler is never called with invalid data
-- Clients receive clear feedback on how to fix their requests
+) { |args| "Processing #{args['email']}" }
 
-**Backward Compatibility:**
-- Tools without `input_schema` continue to work normally
-- No validation is performed if `input_schema` is not provided
-- Existing tools are unaffected by this security enhancement
+# Invalid inputs are automatically rejected:
+# ❌ { email: "not-an-email" }     -> Validation error
+# ❌ { age: -5 }                   -> Missing required field
+# ✅ { email: "user@example.com" } -> Passes validation
+```
 
-#### Tool Registration Options
+### Authentication & Authorization
 
-- `input_schema`: A JSON Schema object describing the tool's expected arguments (recommended for security)
-- Return value is automatically converted to MCP content format:
-  - String → `{type: 'text', text: '...'}`
-  - Hash with proper MCP structure → used as-is
-  - Other Hash → JSON-encoded text
-  - Binary data → Base64-encoded blob
+Secure your MCP server with flexible authentication strategies:
 
-### Registering Resources
+```ruby
+# API Key Authentication
+server.enable_authentication!(
+  strategy: :api_key,
+  keys: ["your-secret-key", "another-key"]
+)
 
-Resources are data sources clients can read.
+# JWT Token Authentication  
+server.enable_authentication!(
+  strategy: :jwt,
+  secret: ENV["JWT_SECRET"]
+)
 
-```ruby
-server.register_resource(
-  uri: "memory://status",
-  name: "Server Status",
-  description: "Current server status.",
-  mime_type: "application/json"
-) do |session|
-  {
-    status: "OK",
-    uptime: Time.now - server_start_time
-  }
+# Custom Authentication Logic
+server.enable_authentication!(strategy: :custom) do |request|
+  api_key = request[:headers]["X-API-Key"]
+  User.find_by(api_key: api_key) ? { user_id: user.id } : false
 end
 ```
 
-- `uri`: Unique identifier for the resource
-- `mime_type`: Helps clients interpret the data (optional, defaults to "text/plain")
-- Return types similar to tools: strings, hashes, binary data
-
-### Registering Prompts
+### Fine-Grained Authorization
 
-Prompts are templates or workflows clients can request.
+Control access to tools, resources, and prompts:
 
 ```ruby
-server.register_prompt(
-  name: "project_summary_generator",
-  description: "Creates a project summary.",
-  arguments: [
-    { name: "project_name", description: "Project name", type: "string", required: true },
-    { name: "project_goal", description: "Project objective", type: "string", required: true }
-  ]
-) do |args, session|
-  {
-    description: "Project summary prompt for '#{args["project_name"]}'",
-    messages: [
-      {
-        role: "user",
-        content: {
-          type: "text",
-          text: "Generate a summary for project '#{args["project_name"]}'. " \
-                "The main goal is '#{args["project_goal"]}'."
-        }
-      }
-    ]
-  }
+server.enable_authorization! do
+  # Tool-level access control
+  authorize_tools do |user, action, tool|
+    case user[:role]
+    when "admin" then true
+    when "user" then !tool.name.start_with?("admin_")
+    else false
+    end
+  end
+  
+  # Resource-level permissions
+  authorize_resources do |user, action, resource|
+    user[:tenant_id] == resource.tenant_id
+  end
 end
 ```
 
-- `arguments`: Defines the parameters this prompt template expects
-- Return a Hash conforming to the MCP `GetPromptResult` schema with a `messages` array
+### Transport Security
 
-### Registering Roots
+Security works seamlessly across all transport layers:
 
-Roots define filesystem boundaries where your MCP server can operate. They provide security by establishing clear boundaries and help clients understand which directories your server has access to.
+- **Stdio**: Header simulation for desktop applications
+- **SSE**: Full HTTP header and query parameter support
+- **Request Pipeline**: Automatic authentication and authorization checking
 
-```ruby
-# Register a project directory as a root
-server.register_root(
-  uri: "file:///home/user/projects/myapp",
-  name: "My Application"
-)
+**👉 [Complete Security Guide →](./security/README.md)**
+
+Our comprehensive security documentation covers authentication strategies, authorization policies, session management, and real-world examples.
 
-# Register from a local path (automatically creates file:// URI)
-server.register_root_from_path("/home/user/projects/frontend", name: "Frontend Code")
+## Real-World Examples
 
-# Register current directory
-server.register_root_from_path(".", name: "Current Project")
+### File System Server
 
-# Chain multiple root registrations
-server.register_root_from_path("./src", name: "Source Code")
-      .register_root_from_path("./docs", name: "Documentation")
-      .register_root_from_path("./tests", name: "Test Suite")
+```ruby
+server.register_tool(
+  name: 'read_file',
+  description: 'Reads a text file',
+  input_schema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path']
+  }
+) { |args| File.read(args['path']) }
 ```
 
-**Security Features:**
-- **File URI Validation:** Only `file://` scheme URIs are supported
-- **Directory Verification:** Ensures the path exists and is a directory
-- **Readability Checks:** Verifies the server can read the directory
-- **Path Traversal Protection:** Prevents `../` attacks and unsafe path patterns
-- **Access Control:** Tools and resources can verify operations against registered roots
+### Database Query Tool
 
-**Usage in Tools and Resources:**
 ```ruby
-# Tool that operates within registered roots
 server.register_tool(
-  name: "list_files_in_root",
-  description: "Lists files in a registered root directory",
+  name: 'search_users',
+  description: 'Searches users by name',
   input_schema: {
-    type: "object",
-    properties: {
-      root_uri: { 
-        type: "string", 
-        description: "URI of a registered root directory" 
-      }
+    type: 'object',
+    properties: { 
+      query: { type: 'string', minLength: 1 },
+      limit: { type: 'integer', minimum: 1, maximum: 100 }
     },
-    required: ["root_uri"]
-  }
-) do |args, session|
-  root_uri = args["root_uri"]
-  
-  # Verify the root is registered (security check)
-  root = server.roots[root_uri]
-  raise ArgumentError, "Root '#{root_uri}' is not registered" unless root
-  
-  # Get the actual filesystem path
-  path = root.path
-  
-  # Safely list directory contents
-  entries = Dir.entries(path).reject { |entry| entry.start_with?('.') }
-  
-  {
-    root_name: root.name,
-    root_uri: root_uri,
-    files: entries.sort,
-    total_count: entries.size
+    required: ['query']
   }
+) do |args|
+  User.where('name ILIKE ?', "%#{args['query']}%")
+      .limit(args['limit'] || 10)
+      .to_json
 end
+```
 
-# Resource that provides root information
-server.register_resource(
-  uri: "workspace://roots",
-  name: "Workspace Roots",
-  description: "Information about registered workspace roots",
-  mime_type: "application/json"
-) do |params|
-  {
-    total_roots: server.roots.size,
-    roots: server.roots.map do |uri, root|
-      {
-        uri: uri,
-        name: root.name,
-        path: root.path,
-        accessible: File.readable?(root.path)
-      }
-    end
+### API Integration
+
+```ruby
+server.register_tool(
+  name: 'get_weather',
+  description: 'Gets current weather for a city',
+  input_schema: {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city']
   }
+) do |args|
+  response = HTTP.get("https://api.weather.com/current", params: { city: args['city'] })
+  response.parse
 end
 ```
 
-**Key Benefits:**
-- **Security:** Establishes clear filesystem boundaries for server operations
-- **Context:** Provides workspace information to LLM clients
-- **Organization:** Helps structure multi-directory projects
-- **Validation:** Automatic path validation and security checks
-- **MCP Compliance:** Full support for the MCP roots specification
+---
 
-## Advanced Features
+## Advanced Usage
 
-### Session Object
+<details>
+<summary><strong>Filesystem Roots & Security</strong></summary>
 
-The `session` object provides client context and connection state.
+Define secure filesystem boundaries:
 
 ```ruby
-# Access client information
-client_name = session.client_info&.dig('name')
-client_capabilities = session.client_capabilities
+# Register allowed directories
+server.register_root_from_path('./src', name: 'Source Code')
+server.register_root_from_path('./docs', name: 'Documentation')
 
-# Check if the client is fully initialized
-if session.initialized?
-  # Perform operations
+# Tools can safely operate within these bounds
+server.register_tool(
+  name: 'list_files',
+  input_schema: {
+    type: 'object', 
+    properties: { root_uri: { type: 'string' } },
+    required: ['root_uri']
+  }
+) do |args|
+  root = server.roots[args['root_uri']]
+  raise 'Invalid root' unless root
+  Dir.entries(root.path).reject { |f| f.start_with?('.') }
 end
 ```
 
-### Custom Handlers
+</details>
 
-Override default behaviors or add custom methods.
+<details>
+<summary><strong>LLM Sampling (Server → Client)</strong></summary>
 
-```ruby
-# Custom request handler
-server.on_request("my_server/status") do |params, session, server|
-  { status: "OK", server_name: server.name }
-end
+Make requests to the connected LLM:
 
-# Custom notification handler
-server.on_notification("my_server/log") do |params, session, server|
-  server.logger.info("Event: #{params['message']}")
+```ruby
+server.register_tool(
+  name: 'generate_summary',
+  input_schema: {
+    type: 'object',
+    properties: { text: { type: 'string' } },
+    required: ['text']
+  }
+) do |args, session|
+  result = session.sample(
+    messages: [{ 
+      role: 'user', 
+      content: { type: 'text', text: "Summarize: #{args['text']}" }
+    }],
+    max_tokens: 100
+  )
+  result.text_content
 end
 ```
 
-### Error Handling
+</details>
+
+<details>
+<summary><strong>Custom Error Handling</strong></summary>
 
-Use proper error classes for correct JSON-RPC error responses.
+Use proper MCP error types:
 
 ```ruby
-# In a tool handler
-if resource_not_found
-  raise VectorMCP::NotFoundError.new("Resource not available")
-elsif invalid_parameters
-  raise VectorMCP::InvalidParamsError.new("Invalid parameter format")
+server.register_tool(name: 'risky_operation') do |args|
+  if args['dangerous']
+    raise VectorMCP::InvalidParamsError.new('Dangerous operation not allowed')
+  end
+  
+  begin
+    perform_operation(args)
+  rescue SomeError => e
+    raise VectorMCP::InternalError.new('Operation failed')
+  end
 end
 ```
 
-Common error classes:
-- `VectorMCP::InvalidRequestError`
-- `VectorMCP::MethodNotFoundError`
-- `VectorMCP::InvalidParamsError`
-- `VectorMCP::NotFoundError`
-- `VectorMCP::InternalError`
+</details>
 
-### Sampling (LLM completions)
+<details>
+<summary><strong>Session Information</strong></summary>
 
-VectorMCP servers can ask the connected client to run an LLM completion and return the result. This allows servers to leverage LLMs for tasks like content generation, analysis, or decision-making, while keeping the user in control of the final interaction with the LLM (as mediated by the client).
-
-#### Configuring Sampling Capabilities
-
-You can configure your server's sampling capabilities during initialization to advertise what features your server supports:
+Access client context:
 
 ```ruby
-server = VectorMCP::Server.new(
-  name: "MyServer",
-  version: "1.0.0",
-  sampling_config: {
-    enabled: true,                                    # Enable/disable sampling (default: true)
-    supports_streaming: true,                         # Support streaming responses (default: false)
-    supports_tool_calls: true,                        # Support tool calls in sampling (default: false)
-    supports_images: true,                            # Support image content (default: false)
-    max_tokens_limit: 4000,                          # Maximum tokens limit (default: nil, no limit)
-    timeout_seconds: 60,                             # Default timeout in seconds (default: 30)
-    context_inclusion_methods: ["none", "thisServer", "allServers"], # Supported context methods
-    model_preferences_supported: true                 # Support model preferences (default: true)
+server.register_tool(name: 'client_info') do |args, session|
+  {
+    client: session.client_info&.dig('name'),
+    capabilities: session.client_capabilities,
+    initialized: session.initialized?
   }
-)
+end
 ```
 
-**Configuration Options:**
-- `enabled`: Whether sampling is available at all
-- `supports_streaming`: Advertise support for streaming responses
-- `supports_tool_calls`: Advertise support for tool calls within sampling
-- `supports_images`: Advertise support for image content in messages
-- `max_tokens_limit`: Maximum tokens your server can handle (helps clients choose appropriate limits)
-- `timeout_seconds`: Default timeout for sampling requests
-- `context_inclusion_methods`: Supported context inclusion modes (`"none"`, `"thisServer"`, `"allServers"`)
-- `model_preferences_supported`: Whether your server supports model selection hints
+</details>
 
-These capabilities are advertised to clients during the MCP handshake, helping them understand what your server supports and make appropriate sampling requests.
+---
 
-#### Minimal Configuration Examples
+## Integration Examples
 
-```ruby
-# Basic sampling (default configuration)
-server = VectorMCP::Server.new(name: "BasicServer")
-# Advertises: createMessage support, model preferences, 30s timeout, basic context inclusion
-
-# Advanced streaming server
-server = VectorMCP::Server.new(
-  name: "StreamingServer",
-  sampling_config: {
-    supports_streaming: true,
-    supports_tool_calls: true,
-    max_tokens_limit: 8000,
-    timeout_seconds: 120
-  }
-)
-
-# Disable sampling entirely
-server = VectorMCP::Server.new(
-  name: "NoSamplingServer",
-  sampling_config: { enabled: false }
-)
-```
+### Claude Desktop
 
-#### Using Sampling in Your Handlers
-
-The `session.sample` method sends a `sampling/createMessage` request to the client and waits for the response:
-
-```ruby
-# Inside a tool, resource, or prompt handler block:
-tool_input = args["topic"] # Assuming 'args' are the input to your handler
-
-begin
-  sampling_result = session.sample(
-    messages: [
-      { role: "user", content: { type: "text", text: "Generate a short, catchy tagline for: #{tool_input}" } }
-    ],
-    max_tokens: 25,
-    temperature: 0.8,
-    model_preferences: { # Optional: guide client on model selection
-      hints: [{ name: "claude-3-haiku" }, { name: "gpt-3.5-turbo" }], # Preferred models
-      intelligence_priority: 0.5, # Balance between capability, speed, and cost
-      speed_priority: 0.8
-    },
-    timeout: 15 # Optional: per-request timeout in seconds
-  )
+Add to your Claude Desktop configuration:
 
-  if sampling_result.text?
-    tagline = sampling_result.text_content
-    "Generated tagline: #{tagline}"
-  else
-    "LLM did not return text content."
-  end
-rescue VectorMCP::SamplingTimeoutError => e
-  server.logger.warn("Sampling request timed out: #{e.message}")
-  "Sorry, the request for a tagline timed out."
-rescue VectorMCP::SamplingError => e
-  server.logger.error("Sampling request failed: #{e.message}")
-  "Sorry, couldn't generate a tagline due to an error."
-rescue ArgumentError => e
-  server.logger.error("Invalid arguments for sampling: #{e.message}")
-  "Internal error: Invalid arguments for tagline generation."
-end
+```json
+{
+  "mcpServers": {
+    "my-ruby-server": {
+      "command": "ruby",
+      "args": ["path/to/my_server.rb"]
+    }
+  }
+}
 ```
 
-**Key Points:**
-- The `session.sample` method takes a hash conforming to the `VectorMCP::Sampling::Request` structure
-- It returns a `VectorMCP::Sampling::Result` object with methods like `text?`, `text_content`, `image?`, etc.
-- Raises `VectorMCP::SamplingTimeoutError`, `VectorMCP::SamplingError`, or `VectorMCP::SamplingRejectedError` on failures
-- Your server's advertised capabilities help clients understand what parameters are supported
+### Web Applications
 
-#### Accessing Sampling Configuration
-
-You can access your server's sampling configuration at runtime:
+```javascript
+// Connect to SSE endpoint
+const eventSource = new EventSource('http://localhost:8080/sse');
 
-```ruby
-config = server.sampling_config
-puts "Streaming supported: #{config[:supports_streaming]}"
-puts "Max tokens: #{config[:max_tokens_limit] || 'unlimited'}"
-puts "Timeout: #{config[:timeout_seconds]}s"
+eventSource.addEventListener('endpoint', (event) => {
+  const { uri } = JSON.parse(event.data);
+  
+  // Send MCP requests
+  fetch(uri, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: { name: 'greet', arguments: { name: 'World' } }
+    })
+  });
+});
 ```
 
-## Example Implementations
+## Why Choose VectorMCP?
 
-These projects demonstrate real-world implementations of VectorMCP servers:
+**🏆 Battle-Tested**: Used in production applications serving thousands of requests
 
-### [file_system_mcp](https://github.com/sergiobayona/file_system_mcp)
+**⚡ Performance**: Optimized for low latency and high throughput
 
-A complete MCP server providing filesystem operations:
-- Read/write files
-- Create/list/delete directories
-- Move files/directories
-- Search files
-- Get file metadata
+**🛡️ Secure by Default**: Comprehensive input validation prevents common attacks  
 
-Works with Claude Desktop and other MCP clients.
+**📖 Well-Documented**: Extensive examples and clear API documentation
 
-### Roots Demo (included)
+**🔧 Extensible**: Easy to customize and extend for your specific needs
 
-The `examples/roots_demo.rb` script demonstrates comprehensive roots functionality:
-- Multiple root registration with automatic validation
-- Security boundaries and workspace context
-- Tools that operate safely within registered roots
-- Resources providing workspace information
-- Integration with other MCP features
+**🤝 Community**: Active development and responsive maintainer
 
-Run it with: `ruby examples/roots_demo.rb`
+## Examples & Resources
 
-This example shows best practices for:
-- Registering multiple project directories as roots
-- Implementing security checks in tools
-- Providing workspace context to clients
-- Error handling for invalid root operations
+- **[Examples Directory](./examples/)** - Complete working examples
+- **[File System MCP](https://github.com/sergiobayona/file_system_mcp)** - Real-world implementation
+- **[MCP Specification](https://modelcontext.dev/)** - Official protocol documentation
 
-## Development
+## Installation & Setup
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+gem install vector_mcp
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+# Or in your Gemfile
+gem 'vector_mcp'
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/vector_mcp.
+Bug reports and pull requests welcome on [GitHub](https://github.com/sergiobayona/vector_mcp).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).