vector_mcp 0.2.0 → 0.3.1

data/README.md

@@ -1,517 +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 (work-in-progress):** Server-Sent Events support is under active development and currently unavailable.
-
-## Installation
-
-```ruby
-# In your Gemfile
-gem 'vector_mcp'
+## Quick Start
 
-# Or install directly
+```bash
 gem install vector_mcp
 ```
 
-> ⚠️  **Note:** SSE transport is not yet supported in the released gem.
-
-## 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
-  }
-)
+# Create a server
+server = VectorMCP.new(name: 'MyApp', version: '1.0.0')
 
-# Register filesystem roots for security and context
-server.register_root_from_path('.', name: 'Current Project')
-server.register_root_from_path('./examples', name: 'Examples')
-
-# 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:**
+**That's it!** Your MCP server is ready to connect with Claude Desktop, custom clients, or any MCP-compatible application.
 
-```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"}}}
-```
+## Transport Options
 
-Or use a script:
+### Command Line Tools (stdio)
 
-```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
+Perfect for desktop applications and process-based integrations:
+
+```ruby
+server.run  # Default: stdio transport
 ```
 
-## Core Usage
+### Web Applications (HTTP + SSE)
 
-### Creating a Server
+Ideal for web apps and browser-based clients:
 
 ```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.run(transport: :sse, port: 8080)
 ```
 
-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.
+Connect via Server-Sent Events at `http://localhost:8080/sse`
 
-### Registering Tools
+## Core Features
 
-Tools are functions your server exposes to clients.
+### Tools (Functions)
+
+Expose functions that LLMs can call:
 
 ```ruby
 server.register_tool(
-  name: "calculate_sum",
-  description: "Adds two numbers together.",
+  name: 'calculate',
+  description: 'Performs basic math',
   input_schema: {
-    type: "object",
+    type: 'object',
     properties: {
-      a: { type: "number" },
-      b: { type: "number" }
+      operation: { type: 'string', enum: ['add', 'subtract', 'multiply'] },
+      a: { type: 'number' },
+      b: { type: 'number' }
     },
-    required: ["a", "b"]
+    required: ['operation', 'a', 'b']
   }
-) do |args, session|
-  sum = args["a"] + args["b"]
-  "The sum is: #{sum}"
+) 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
 ```
 
-- `input_schema`: A JSON Schema object describing the tool's expected arguments
-- 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
+### Resources (Data Sources)
 
-### Registering Resources
-
-Resources are data sources clients can read.
+Provide data that LLMs can read:
 
 ```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
-  }
-end
+  uri: 'file://config.json',
+  name: 'App Configuration',
+  description: 'Current application settings'
+) { File.read('config.json') }
 ```
 
-- `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
+### Prompts (Templates)
 
-### Registering Prompts
-
-Prompts are templates or workflows clients can request.
+Create reusable prompt templates:
 
 ```ruby
 server.register_prompt(
-  name: "project_summary_generator",
-  description: "Creates a project summary.",
+  name: 'code_review',
+  description: 'Reviews code for best practices',
   arguments: [
-    { name: "project_name", description: "Project name", type: "string", required: true },
-    { name: "project_goal", description: "Project objective", type: "string", required: true }
+    { name: 'language', description: 'Programming language', required: true },
+    { name: 'code', description: 'Code to review', required: true }
   ]
-) do |args, session|
+) do |args|
   {
-    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"]}'."
-        }
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: "Review this #{args['language']} code:\n\n#{args['code']}"
       }
-    ]
+    }]
   }
 end
 ```
 
-- `arguments`: Defines the parameters this prompt template expects
-- Return a Hash conforming to the MCP `GetPromptResult` schema with a `messages` array
-
-### Registering Roots
-
-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.
+## Security Features
 
-```ruby
-# Register a project directory as a root
-server.register_root(
-  uri: "file:///home/user/projects/myapp",
-  name: "My Application"
-)
-
-# Register from a local path (automatically creates file:// URI)
-server.register_root_from_path("/home/user/projects/frontend", name: "Frontend Code")
+VectorMCP provides comprehensive, **opt-in security** for production applications:
 
-# Register current directory
-server.register_root_from_path(".", name: "Current Project")
-
-# 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")
-```
+### Built-in Input Validation
 
-**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
+All inputs are automatically validated against your schemas:
 
-**Usage in Tools and Resources:**
 ```ruby
-# Tool that operates within registered roots
+# This tool is protected against invalid inputs
 server.register_tool(
-  name: "list_files_in_root",
-  description: "Lists files in a registered root directory",
+  name: 'process_user',
   input_schema: {
-    type: "object",
+    type: 'object',
     properties: {
-      root_uri: { 
-        type: "string", 
-        description: "URI of a registered root directory" 
-      }
+      email: { type: 'string', format: 'email' },
+      age: { type: 'integer', minimum: 0, maximum: 150 }
     },
-    required: ["root_uri"]
+    required: ['email']
   }
-) 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
-  }
-end
+) { |args| "Processing #{args['email']}" }
 
-# 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
-  }
-end
+# Invalid inputs are automatically rejected:
+# ❌ { email: "not-an-email" }     -> Validation error
+# ❌ { age: -5 }                   -> Missing required field
+# ✅ { email: "user@example.com" } -> Passes validation
 ```
 
-**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
+### Authentication & Authorization
 
-## Advanced Features
-
-### Session Object
-
-The `session` object provides client context and connection state.
+Secure your MCP server with flexible authentication strategies:
 
 ```ruby
-# Access client information
-client_name = session.client_info&.dig('name')
-client_capabilities = session.client_capabilities
+# API Key Authentication
+server.enable_authentication!(
+  strategy: :api_key,
+  keys: ["your-secret-key", "another-key"]
+)
+
+# JWT Token Authentication  
+server.enable_authentication!(
+  strategy: :jwt,
+  secret: ENV["JWT_SECRET"]
+)
 
-# Check if the client is fully initialized
-if session.initialized?
-  # Perform operations
+# 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
 ```
 
-### Custom Handlers
+### Fine-Grained Authorization
 
-Override default behaviors or add custom methods.
+Control access to tools, resources, and prompts:
 
 ```ruby
-# Custom request handler
-server.on_request("my_server/status") do |params, session, server|
-  { status: "OK", server_name: server.name }
-end
-
-# Custom notification handler
-server.on_notification("my_server/log") do |params, session, server|
-  server.logger.info("Event: #{params['message']}")
+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
 ```
 
-### Error Handling
+### Transport Security
+
+Security works seamlessly across all transport layers:
 
-Use proper error classes for correct JSON-RPC error responses.
+- **Stdio**: Header simulation for desktop applications
+- **SSE**: Full HTTP header and query parameter support
+- **Request Pipeline**: Automatic authentication and authorization checking
+
+**👉 [Complete Security Guide →](./security/README.md)**
+
+Our comprehensive security documentation covers authentication strategies, authorization policies, session management, and real-world examples.
+
+## Real-World Examples
+
+### File System Server
 
 ```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: 'read_file',
+  description: 'Reads a text file',
+  input_schema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path']
+  }
+) { |args| File.read(args['path']) }
+```
+
+### Database Query Tool
+
+```ruby
+server.register_tool(
+  name: 'search_users',
+  description: 'Searches users by name',
+  input_schema: {
+    type: 'object',
+    properties: { 
+      query: { type: 'string', minLength: 1 },
+      limit: { type: 'integer', minimum: 1, maximum: 100 }
+    },
+    required: ['query']
+  }
+) do |args|
+  User.where('name ILIKE ?', "%#{args['query']}%")
+      .limit(args['limit'] || 10)
+      .to_json
 end
 ```
 
-Common error classes:
-- `VectorMCP::InvalidRequestError`
-- `VectorMCP::MethodNotFoundError`
-- `VectorMCP::InvalidParamsError`
-- `VectorMCP::NotFoundError`
-- `VectorMCP::InternalError`
+### API Integration
 
-### Sampling (LLM completions)
+```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
+```
+
+---
 
-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).
+## Advanced Usage
 
-#### Configuring Sampling Capabilities
+<details>
+<summary><strong>Filesystem Roots & Security</strong></summary>
 
-You can configure your server's sampling capabilities during initialization to advertise what features your server supports:
+Define secure filesystem boundaries:
 
 ```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)
+# Register allowed directories
+server.register_root_from_path('./src', name: 'Source Code')
+server.register_root_from_path('./docs', name: 'Documentation')
+
+# 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
 ```
 
-**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.
+<details>
+<summary><strong>LLM Sampling (Server → Client)</strong></summary>
 
-#### Minimal Configuration Examples
+Make requests to the connected LLM:
 
 ```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
+server.register_tool(
+  name: 'generate_summary',
+  input_schema: {
+    type: 'object',
+    properties: { text: { type: 'string' } },
+    required: ['text']
   }
-)
-
-# Disable sampling entirely
-server = VectorMCP::Server.new(
-  name: "NoSamplingServer",
-  sampling_config: { enabled: false }
-)
+) do |args, session|
+  result = session.sample(
+    messages: [{ 
+      role: 'user', 
+      content: { type: 'text', text: "Summarize: #{args['text']}" }
+    }],
+    max_tokens: 100
+  )
+  result.text_content
+end
 ```
 
-#### Using Sampling in Your Handlers
+</details>
 
-The `session.sample` method sends a `sampling/createMessage` request to the client and waits for the response:
+<details>
+<summary><strong>Custom Error Handling</strong></summary>
 
-```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
-  )
+Use proper MCP error types:
 
-  if sampling_result.text?
-    tagline = sampling_result.text_content
-    "Generated tagline: #{tagline}"
-  else
-    "LLM did not return text content."
+```ruby
+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
-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
 ```
 
-**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
+</details>
 
-#### Accessing Sampling Configuration
+<details>
+<summary><strong>Session Information</strong></summary>
 
-You can access your server's sampling configuration at runtime:
+Access client context:
 
 ```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"
+server.register_tool(name: 'client_info') do |args, session|
+  {
+    client: session.client_info&.dig('name'),
+    capabilities: session.client_capabilities,
+    initialized: session.initialized?
+  }
+end
+```
+
+</details>
+
+---
+
+## Integration Examples
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "my-ruby-server": {
+      "command": "ruby",
+      "args": ["path/to/my_server.rb"]
+    }
+  }
+}
+```
+
+### Web Applications
+
+```javascript
+// Connect to SSE endpoint
+const eventSource = new EventSource('http://localhost:8080/sse');
+
+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).