s3db.js 10.0.7 → 10.0.8

package/mcp/README.md

@@ -1,1728 +0,0 @@
-# 🗃️ S3DB MCP Server
-
-<p align="center">
-  <img width="200" src="https://img.icons8.com/fluency/200/database.png" alt="S3DB MCP Server">
-</p>
-
-<p align="center">
-  <strong>Model Context Protocol (MCP) server for S3DB</strong><br>
-  <em>Transform AWS S3 into a powerful document database accessible by AI agents</em>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/s3db-mcp-server"><img src="https://img.shields.io/npm/v/s3db-mcp-server.svg?style=flat&color=brightgreen" alt="npm version"></a>
-  &nbsp;
-  <a href="https://github.com/forattini-dev/s3db.js"><img src="https://img.shields.io/github/stars/forattini-dev/s3db.js?style=flat&color=yellow" alt="GitHub stars"></a>
-  &nbsp;
-  <a href="https://github.com/forattini-dev/s3db.js/blob/main/UNLICENSE"><img src="https://img.shields.io/badge/license-Unlicense-blue.svg?style=flat" alt="License"></a>
-</p>
-
----
-
-## 🚀 Quick Start with Claude Desktop
-
-### Prerequisites
-Before starting, ensure you have:
-1. **Claude Desktop** installed (version 0.7.0 or later)
-2. **Node.js** installed (version 18+ recommended)
-3. **S3 Bucket** or S3-compatible storage (MinIO, etc.)
-4. **Credentials** for your S3 service
-
-### Step 1: Locate Claude Desktop Configuration
-
-The configuration file location depends on your operating system:
-
-```bash
-# macOS
-~/Library/Application Support/Claude/claude_desktop_config.json
-
-# Windows
-%APPDATA%\Claude\claude_desktop_config.json
-
-# Linux
-~/.config/Claude/claude_desktop_config.json
-```
-
-### Step 2: Configure Claude Desktop
-
-Open the configuration file and add the S3DB MCP server:
-
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://ACCESS_KEY:SECRET_KEY@bucket/databases/myapp",
-        "S3DB_CACHE_ENABLED": "true",
-        "S3DB_CACHE_DRIVER": "memory",
-        "S3DB_CACHE_MAX_SIZE": "1000",
-        "S3DB_CACHE_TTL": "300000",
-        "MCP_SERVER_PORT": "17500"
-      }
-    }
-  }
-}
-```
-
-### Step 3: Restart Claude Desktop
-
-After saving the configuration:
-1. Completely quit Claude Desktop (not just close the window)
-2. Restart Claude Desktop
-3. The MCP server should start automatically
-
-### Step 4: Test Your Setup
-
-In Claude Desktop, test with these commands:
-
-```javascript
-// 1. Test connection
-"Can you connect to the S3DB database and show me the status?"
-
-// 2. Create a resource
-"Please create a new resource called 'users' with these fields:
-- name (string, required)
-- email (string, required, unique)
-- age (number)
-- active (boolean, default true)"
-
-// 3. Insert data
-"Insert a new user with name 'John Doe', email 'john@example.com', age 30"
-
-// 4. Query data
-"Show me all users in the database"
-
-// 5. Check statistics
-"Can you show me the database statistics including cache hits and S3 costs?"
-```
-
----
-
-## 📋 Table of Contents
-
-- [🚀 Quick Start with Claude Desktop](#-quick-start-with-claude-desktop)
-- [💾 Alternative Installation Methods](#-alternative-installation-methods)
-- [⚙️ Configuration Examples](#️-configuration-examples)
-- [🛠️ Available Tools](#️-available-tools)
-- [📖 Command Line Examples](#-command-line-examples)
-- [🗂️ Partitions & Performance](#️-partitions--performance)
-- [🐳 Docker Deployment](#-docker-deployment)
-- [🔧 Advanced Configuration](#-advanced-configuration)
-- [🔒 Security](#-security)
-- [🚨 Troubleshooting](#-troubleshooting)
-
----
-
-## 💾 Alternative Installation Methods
-
-### Option 1: NPX (Recommended)
-```bash
-# SSE transport (web clients) - Default port: 17500
-npx s3db-mcp-server --transport=sse
-
-# STDIO transport (desktop clients)
-npx s3db-mcp-server --transport=stdio
-```
-
-### Option 2: Global Installation
-```bash
-npm install -g s3db-mcp-server
-s3db-mcp --transport=sse
-```
-
-### Option 3: Docker
-```bash
-docker run -p 17500:8000 -e S3DB_CONNECTION_STRING="s3://key:secret@bucket/db" s3db-mcp-server
-```
-
-### Option 4: Standalone Server
-```bash
-# Start the server (it will run in the foreground)
-npx s3db-mcp-server --transport=sse
-
-# With environment variables
-cat > s3db-mcp.env << EOF
-S3DB_CONNECTION_STRING=s3://ACCESS_KEY:SECRET_KEY@bucket-name/databases/myapp
-S3DB_CACHE_ENABLED=true
-S3DB_CACHE_DRIVER=memory
-S3DB_CACHE_MAX_SIZE=1000
-EOF
-
-env $(cat s3db-mcp.env | xargs) npx s3db-mcp-server --transport=sse
-```
-
-### Option 5: Background Process
-```bash
-# Using nohup (Linux/macOS)
-nohup npx s3db-mcp-server --transport=sse > s3db-mcp.log 2>&1 &
-echo $! > s3db-mcp.pid
-
-# To stop later
-kill $(cat s3db-mcp.pid)
-```
-
-### Option 6: Using PM2 Process Manager
-```bash
-# Install PM2 globally
-npm install -g pm2
-
-# Start with PM2
-pm2 start npx --name "s3db-mcp" -- s3db-mcp-server --transport=sse
-
-# View logs
-pm2 logs s3db-mcp
-
-# Stop/restart
-pm2 stop s3db-mcp
-pm2 restart s3db-mcp
-```
-
----
-
-## ⚙️ Configuration Examples
-
-### 🏠 Local Development with MinIO
-
-```json
-{
-  "mcpServers": {
-    "s3db-local": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://minioadmin:minioadmin123@localhost:9000/dev-bucket?forcePathStyle=true",
-        "S3DB_VERBOSE": "true",
-        "S3DB_CACHE_ENABLED": "true",
-        "S3DB_COSTS_ENABLED": "false",
-        "NODE_ENV": "development"
-      }
-    }
-  }
-}
-```
-
-### ☁️ Production with AWS S3
-
-```json
-{
-  "mcpServers": {
-    "s3db-prod": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://prod-data-bucket/databases/main",
-        "AWS_REGION": "us-east-1",
-        "AWS_ACCESS_KEY_ID": "AKIA...",
-        "AWS_SECRET_ACCESS_KEY": "wJal...",
-        "S3DB_CACHE_DRIVER": "filesystem",
-        "S3DB_CACHE_DIRECTORY": "/var/cache/s3db",
-        "S3DB_CACHE_TTL": "1800000",
-        "S3DB_PASSPHRASE": "your-strong-passphrase-here",
-        "S3DB_VERSIONING_ENABLED": "true",
-        "NODE_ENV": "production"
-      }
-    }
-  }
-}
-```
-
-### 🌊 DigitalOcean Spaces
-
-```json
-{
-  "mcpServers": {
-    "s3db-do": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://DO_ACCESS_KEY:DO_SECRET_KEY@nyc3.digitaloceanspaces.com/space-name/databases/app",
-        "S3_ENDPOINT": "https://nyc3.digitaloceanspaces.com",
-        "S3DB_CACHE_ENABLED": "true"
-      }
-    }
-  }
-}
-```
-
-### 🔧 Multiple Environments
-
-```json
-{
-  "mcpServers": {
-    "s3db-dev": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse", "--port=17500"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://minioadmin:minioadmin123@localhost:9000/dev-bucket?forcePathStyle=true"
-      }
-    },
-    "s3db-staging": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse", "--port=17501"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://staging-bucket/databases/staging",
-        "AWS_REGION": "us-east-1"
-      }
-    },
-    "s3db-prod": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse", "--port=17502"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://prod-bucket/databases/production",
-        "AWS_REGION": "us-east-1",
-        "S3DB_CACHE_DRIVER": "filesystem"
-      }
-    }
-  }
-}
-```
-
-## ⚙️ Configuration Reference
-
-### 📝 Configuration Overview
-
-The S3DB MCP Server can be configured through multiple methods (in order of precedence):
-1. **Command-line arguments** (highest priority)
-2. **Environment variables** 
-3. **`.env` file**
-4. **Default values** (lowest priority)
-
-### 🌐 Server Configuration
-
-#### **Core Server Settings**
-
-| Variable | Default | Description | Example | Notes |
-|----------|---------|-------------|---------|-------|
-| `NODE_ENV` | `development` | Environment mode | `production`, `development`, `test` | Affects logging verbosity and error details |
-| `MCP_SERVER_HOST` | `0.0.0.0` | Server bind address | `localhost`, `127.0.0.1`, `0.0.0.0` | Use `0.0.0.0` to accept connections from any interface |
-| `MCP_SERVER_PORT` | `17500` | Server port | Any port 1024-65535 | Changed from 8000 to avoid conflicts |
-| `MCP_TRANSPORT` | `sse` | Transport method | `sse`, `stdio` | SSE for web clients, stdio for CLI tools |
-
-#### **Transport Modes Explained**
-
-- **SSE (Server-Sent Events)**: 
-  - Best for: Web-based AI clients, Claude Desktop, Cursor IDE
-  - Protocol: HTTP/HTTPS
-  - URL format: `http://localhost:17500/sse`
-  
-- **STDIO (Standard Input/Output)**:
-  - Best for: CLI tools, shell scripts, pipe-based communication
-  - Protocol: JSON-RPC over stdin/stdout
-  - No network port required
-
-### 🗄️ S3DB Core Configuration
-
-#### **Essential Database Settings**
-
-| Variable | Default | Required | Description | Example Values |
-|----------|---------|----------|-------------|----------------|
-| `S3DB_CONNECTION_STRING` | - | ✅ Yes | Complete S3 connection URL | See [Connection String Formats](#connection-string-formats) below |
-| `S3DB_VERBOSE` | `false` | No | Enable detailed operation logs | `true` for debugging, `false` for production |
-| `S3DB_PARALLELISM` | `10` | No | Max concurrent S3 operations | `5` (conservative), `20` (aggressive), `50` (high-performance) |
-| `S3DB_PASSPHRASE` | `secret` | No | Encryption key for sensitive fields | Any strong passphrase (min 12 chars recommended) |
-| `S3DB_VERSIONING_ENABLED` | `false` | No | Track resource schema versions | `true` for production, `false` for development |
-
-#### **Performance Tuning Guidelines**
-
-```bash
-# Development (fast iteration, verbose logging)
-S3DB_VERBOSE=true
-S3DB_PARALLELISM=5
-S3DB_VERSIONING_ENABLED=false
-
-# Staging (balanced performance)
-S3DB_VERBOSE=false
-S3DB_PARALLELISM=10
-S3DB_VERSIONING_ENABLED=true
-
-# Production (optimized for scale)
-S3DB_VERBOSE=false
-S3DB_PARALLELISM=20
-S3DB_VERSIONING_ENABLED=true
-```
-
-### 🔌 Plugin Configuration
-
-#### **Cache Plugin Settings**
-
-| Variable | Default | Description | When to Change | Impact |
-|----------|---------|-------------|----------------|--------|
-| `S3DB_CACHE_ENABLED` | `true` | Master cache toggle | Set `false` only for debugging | 70-90% performance improvement when enabled |
-| `S3DB_CACHE_DRIVER` | `memory` | Cache storage backend | Use `filesystem` for persistent cache | Memory: faster, Filesystem: survives restarts |
-| `S3DB_CACHE_MAX_SIZE` | `1000` | Max cached items (memory only) | Increase for read-heavy workloads | Each item ~1-10KB RAM |
-| `S3DB_CACHE_TTL` | `300000` | Cache lifetime (ms) | Decrease for frequently changing data | 5 min default, 0 = no expiry |
-| `S3DB_CACHE_DIRECTORY` | `./cache` | Filesystem cache location | Use SSD path for best performance | Only for filesystem driver |
-| `S3DB_CACHE_PREFIX` | `s3db` | Cache file prefix | Change for multiple instances | Prevents cache conflicts |
-
-#### **Cache Strategy Examples**
-
-```bash
-# High-traffic read-heavy API
-S3DB_CACHE_DRIVER=memory
-S3DB_CACHE_MAX_SIZE=5000
-S3DB_CACHE_TTL=600000  # 10 minutes
-
-# Data analytics workload
-S3DB_CACHE_DRIVER=filesystem
-S3DB_CACHE_DIRECTORY=/mnt/ssd/cache
-S3DB_CACHE_TTL=3600000  # 1 hour
-
-# Real-time application
-S3DB_CACHE_DRIVER=memory
-S3DB_CACHE_MAX_SIZE=500
-S3DB_CACHE_TTL=30000  # 30 seconds
-```
-
-#### **Cost Tracking Plugin**
-
-| Variable | Default | Description | Use Case |
-|----------|---------|-------------|----------|
-| `S3DB_COSTS_ENABLED` | `true` | Track S3 API costs | Disable for local MinIO/testing |
-
-Cost tracking provides:
-- Per-operation cost breakdown
-- Daily/monthly projections
-- Request type statistics
-- Data transfer metrics
-
-### 🔐 AWS & S3-Compatible Configuration
-
-#### **AWS Credentials**
-
-| Variable | Default | Description | Priority Order |
-|----------|---------|-------------|----------------|
-| `AWS_ACCESS_KEY_ID` | - | AWS access key | 1. Env var, 2. IAM role, 3. Connection string |
-| `AWS_SECRET_ACCESS_KEY` | - | AWS secret key | Required if using access key |
-| `AWS_SESSION_TOKEN` | - | Temporary credentials | For STS/assumed roles |
-| `AWS_REGION` | `us-east-1` | AWS region | Must match bucket region |
-
-#### **S3-Compatible Services**
-
-| Variable | Default | Description | Services |
-|----------|---------|-------------|----------|
-| `S3_ENDPOINT` | - | Custom S3 API endpoint | MinIO, DigitalOcean, Backblaze, Wasabi |
-| `S3_FORCE_PATH_STYLE` | `false` | URL style | Required for MinIO, LocalStack |
-
-### 🔗 Connection String Formats
-
-#### **Anatomy of a Connection String**
-
-```
-s3://[ACCESS_KEY:SECRET_KEY@]BUCKET[/PATH][?PARAMS]
-```
-
-Components:
-- `ACCESS_KEY:SECRET_KEY` - Optional inline credentials
-- `BUCKET` - S3 bucket name
-- `PATH` - Optional path prefix for organization
-- `PARAMS` - Query parameters for advanced config
-
-#### **Real-World Examples**
-
-```bash
-# AWS S3 - Production with IAM role (recommended)
-S3DB_CONNECTION_STRING="s3://my-prod-bucket/databases/main"
-
-# AWS S3 - Development with credentials
-S3DB_CONNECTION_STRING="s3://AKIA...:wJal...@my-dev-bucket/databases/dev"
-
-# MinIO - Local development
-S3DB_CONNECTION_STRING="s3://minioadmin:minioadmin123@localhost:17998/s3db?forcePathStyle=true"
-
-# DigitalOcean Spaces
-S3DB_CONNECTION_STRING="s3://DO_KEY:DO_SECRET@nyc3.digitaloceanspaces.com/space-name/databases/prod"
-
-# Backblaze B2
-S3DB_CONNECTION_STRING="s3://KEY_ID:APP_KEY@s3.us-west-002.backblazeb2.com/bucket-name/db"
-
-# Wasabi
-S3DB_CONNECTION_STRING="s3://ACCESS_KEY:SECRET_KEY@s3.wasabisys.com/bucket-name/databases/app"
-
-# LocalStack (testing)
-S3DB_CONNECTION_STRING="s3://test:test@localhost:4566/test-bucket/db?forcePathStyle=true"
-```
-
-### 📁 Complete Configuration Examples
-
-#### **Development Setup (.env)**
-
-```bash
-# Server
-NODE_ENV=development
-MCP_SERVER_PORT=17500
-MCP_TRANSPORT=sse
-
-# S3DB
-S3DB_CONNECTION_STRING=s3://minioadmin:minioadmin123@localhost:9000/dev-bucket/db
-S3DB_VERBOSE=true
-S3DB_PARALLELISM=5
-
-# Cache
-S3DB_CACHE_ENABLED=true
-S3DB_CACHE_DRIVER=memory
-S3DB_CACHE_MAX_SIZE=100
-S3DB_CACHE_TTL=60000
-
-# Costs
-S3DB_COSTS_ENABLED=false
-```
-
-#### **Production Setup (.env)**
-
-```bash
-# Server
-NODE_ENV=production
-MCP_SERVER_PORT=17500
-MCP_TRANSPORT=sse
-
-# S3DB (using IAM role)
-S3DB_CONNECTION_STRING=s3://prod-data-bucket/databases/main
-S3DB_VERBOSE=false
-S3DB_PARALLELISM=20
-S3DB_PASSPHRASE=${SECRET_PASSPHRASE}
-S3DB_VERSIONING_ENABLED=true
-
-# Cache
-S3DB_CACHE_ENABLED=true
-S3DB_CACHE_DRIVER=filesystem
-S3DB_CACHE_DIRECTORY=/var/cache/s3db
-S3DB_CACHE_TTL=1800000
-S3DB_CACHE_PREFIX=prod
-
-# Costs
-S3DB_COSTS_ENABLED=true
-
-# AWS
-AWS_REGION=us-east-1
-```
-
-### 🚀 Command Line Options
-
-```bash
-# Basic usage
-npx s3db-mcp-server [OPTIONS]
-
-# Transport selection
-npx s3db-mcp-server --transport=sse      # Web clients (default)
-npx s3db-mcp-server --transport=stdio    # CLI/pipe communication
-
-# Network configuration
-npx s3db-mcp-server --host=0.0.0.0 --port=17500
-
-# Override environment variables
-npx s3db-mcp-server --transport=sse \
-  --host=127.0.0.1 \
-  --port=18000
-
-# Combined with environment variables
-S3DB_CONNECTION_STRING="s3://..." \
-S3DB_CACHE_DRIVER=filesystem \
-npx s3db-mcp-server --transport=sse
-
-# Debug mode with verbose output
-S3DB_VERBOSE=true \
-NODE_ENV=development \
-npx s3db-mcp-server --transport=stdio
-```
-
-### 🔍 Configuration Validation
-
-The server validates configuration on startup and will:
-1. Check for required `S3DB_CONNECTION_STRING`
-2. Test S3 connectivity
-3. Verify bucket permissions
-4. Initialize cache directory (if using filesystem)
-5. Report configuration summary
-
-Example startup log:
-```
-S3DB MCP Server v1.0.0 started
-Transport: sse
-Port: 17500
-Cache: memory (1000 items, 5 min TTL)
-Costs tracking: enabled
-Connected to: s3://my-bucket/databases/main
-Ready for connections...
-```
-
----
-
-## 🛠️ Available Tools
-
-### Database Management
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `dbConnect` | Connect to S3DB database with costs & cache | `connectionString`, `verbose?`, `parallelism?`, `passphrase?`, `versioningEnabled?`, `enableCache?`, `enableCosts?`, `cacheDriver?`, `cacheMaxSize?`, `cacheTtl?`, `cacheDirectory?`, `cachePrefix?` |
-| `dbDisconnect` | Disconnect from database | - |
-| `dbStatus` | Get connection status | - |
-| `dbCreateResource` | Create resource/collection | `name`, `attributes`, `behavior?`, `timestamps?`, `partitions?`, `paranoid?` |
-| `dbListResources` | List all resources | - |
-| `dbGetStats` | Get database statistics (costs, cache, resources) | - |
-| `dbClearCache` | Clear cache data | `resourceName?` (optional - clears all if not provided) |
-
-### Document Operations
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `resourceInsert` | Insert single document | `resourceName`, `data` |
-| `resourceInsertMany` | Insert multiple documents | `resourceName`, `data[]` |
-| `resourceGet` | Get document by ID | `resourceName`, `id` |
-| `resourceGetMany` | Get multiple documents | `resourceName`, `ids[]` |
-| `resourceUpdate` | Update document | `resourceName`, `id`, `data` |
-| `resourceUpsert` | Insert or update | `resourceName`, `data` |
-| `resourceDelete` | Delete document | `resourceName`, `id` |
-| `resourceDeleteMany` | Delete multiple documents | `resourceName`, `ids[]` |
-
-### Query Operations
-
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `resourceExists` | Check if document exists | `resourceName`, `id` |
-| `resourceList` | List with pagination | `resourceName`, `limit?`, `offset?`, `partition?`, `partitionValues?` |
-| `resourceListIds` | List document IDs only | `resourceName`, `limit?`, `offset?` |
-| `resourceCount` | Count documents | `resourceName`, `partition?`, `partitionValues?` |
-| `resourceGetAll` | Get all documents | `resourceName` |
-| `resourceDeleteAll` | Delete all documents | `resourceName`, `confirm: true` |
-
----
-
-## 📖 Command Line Examples
-
-### 📝 Basic CRUD Operations
-
-```bash
-# Connect to database
-"Please connect to the S3DB database using the connection string: s3://my-bucket/databases/app"
-
-# Create a blog posts resource
-"Create a resource named 'posts' with fields: title (string, required), content (string), author (string), published (boolean), tags (array of strings)"
-
-# Insert a blog post
-"Insert a new post with title 'Getting Started with S3DB', content 'S3DB is amazing...', author 'john-doe', published true, and tags ['tutorial', 's3db']"
-
-# Query posts
-"List all published posts"
-"Find posts by author 'john-doe'"
-"Count how many posts have the tag 'tutorial'"
-
-# Update a post
-"Update the post with ID 'post-123' to set published to false"
-
-# Delete a post
-"Delete the post with ID 'post-456'"
-```
-
-### 🔍 Advanced Queries with Partitions
-
-```bash
-# Create partitioned resource
-"Create an 'orders' resource with:
-- orderId (string, required, unique)
-- customerId (string, required)
-- amount (number, required)
-- status (string: pending, processing, shipped, delivered)
-- region (string)
-- orderDate (date)
-And create partitions by status and region"
-
-# Query specific partition
-"Show me all orders with status 'pending' in the 'north' region"
-
-# Count by partition
-"Count orders by status"
-
-# List with pagination
-"List the first 10 orders, then get the next 10"
-```
-
-### 🛠️ Database Management
-
-```bash
-# Check connection status
-"Show me the current database connection status"
-
-# List all resources
-"What resources/collections exist in the database?"
-
-# Get statistics
-"Show database statistics including cache performance and S3 costs"
-
-# Clear cache
-"Clear the cache for the 'users' resource"
-"Clear all cached data"
-
-# Bulk operations
-"Insert 100 test users with random data"
-"Delete all users where active is false"
-```
-
-### 📊 Reporting and Analytics
-
-```bash
-# Cost analysis
-"How much are we spending on S3 operations today?"
-"Show me a breakdown of S3 costs by operation type"
-
-# Performance metrics
-"What's the cache hit ratio?"
-"Which queries are slowest?"
-
-# Data overview
-"Give me a summary of all resources: total records, size, last modified"
-"Which partitions have the most data?"
-```
-
-## 📖 API Usage Examples
-
-### Basic CRUD Operations
-
-```javascript
-// 1. Connect to database with automatic cache and costs tracking
-await agent.callTool('dbConnect', {
-  connectionString: 's3://ACCESS_KEY:SECRET_KEY@bucket/databases/blog',
-  verbose: false,
-  parallelism: 10,
-  enableCache: true,        // Cache enabled by default
-  enableCosts: true,        // Costs tracking enabled by default
-  cacheDriver: 'memory',    // 'memory' or 'filesystem'
-  cacheMaxSize: 1000,       // Cache up to 1000 items (memory only)
-  cacheTtl: 300000,         // 5 minute cache TTL
-  cacheDirectory: './cache', // Directory for filesystem cache
-  cachePrefix: 's3db'       // Prefix for cache files
-});
-
-// 2. Create a resource with schema validation
-await agent.callTool('dbCreateResource', {
-  name: 'posts',
-  attributes: {
-    title: 'string|required|min:3|max:200',
-    content: 'string|required',
-    author: 'string|required',
-    tags: 'array|items:string',
-    published: 'boolean',
-    publishDate: 'date',
-    metadata: {
-      views: 'number|positive',
-      likes: 'number|positive'
-    }
-  },
-  behavior: 'user-managed',
-  timestamps: true,  // Adds createdAt/updatedAt automatically
-  paranoid: true     // Soft deletes
-});
-
-// 3. Insert a blog post
-const post = await agent.callTool('resourceInsert', {
-  resourceName: 'posts',
-  data: {
-    title: 'Getting Started with S3DB MCP',
-    content: 'S3DB transforms AWS S3 into a powerful document database...',
-    author: 'john-doe',
-    tags: ['tutorial', 's3db', 'mcp', 'ai'],
-    published: true,
-    publishDate: '2024-01-15',
-    metadata: {
-      views: 0,
-      likes: 0
-    }
-  }
-});
-
-// 4. Update the post
-await agent.callTool('resourceUpdate', {
-  resourceName: 'posts',
-  id: post.data.id,
-  data: {
-    metadata: {
-      views: 150,
-      likes: 12
-    }
-  }
-});
-
-// 5. Query posts with pagination
-const posts = await agent.callTool('resourceList', {
-  resourceName: 'posts',
-  limit: 10,
-  offset: 0
-});
-
-// 6. Check if post exists
-const exists = await agent.callTool('resourceExists', {
-  resourceName: 'posts',
-  id: post.data.id
- });
-
-// 7. Check performance statistics
-const stats = await agent.callTool('dbGetStats');
-console.log('Cache hits:', stats.stats.cache.size);
-console.log('S3 costs:', stats.stats.costs.estimatedCostUSD);
-console.log('Total requests:', stats.stats.costs.totalRequests);
-
-// 8. Clear cache if needed
-await agent.callTool('dbClearCache', {
-  resourceName: 'posts'  // Clear cache for specific resource
-});
-```
-
-### Performance & Costs Monitoring
-
-```javascript
-// Monitor database performance and costs
-const stats = await agent.callTool('dbGetStats');
-
-console.log('Database Stats:', {
-  resources: stats.stats.database.resources,
-  totalCosts: `$${stats.stats.costs.estimatedCostUSD.toFixed(6)}`,
-  cacheHitRate: `${stats.stats.cache.keyCount}/${stats.stats.cache.maxSize}`,
-  s3Operations: stats.stats.costs.requestsByType
-});
-
-// Cache performance
-if (stats.stats.cache.enabled) {
-  console.log('Cache Performance:', {
-    driver: stats.stats.cache.driver,
-    itemsCached: stats.stats.cache.size,
-    maxCapacity: stats.stats.cache.maxSize,
-    ttl: `${stats.stats.cache.ttl / 1000}s`,
-    sampleKeys: stats.stats.cache.sampleKeys
-  });
-}
-
-// S3 costs breakdown
-if (stats.stats.costs) {
-  console.log('S3 Costs Breakdown:', {
-    totalRequests: stats.stats.costs.totalRequests,
-    getRequests: stats.stats.costs.requestsByType.get,
-    putRequests: stats.stats.costs.requestsByType.put,
-    listRequests: stats.stats.costs.requestsByType.list,
-    estimatedCost: `$${stats.stats.costs.estimatedCostUSD.toFixed(6)}`
-  });
-}
-
-// Clear cache for performance reset
-await agent.callTool('dbClearCache');  // Clear all cache
-// or
-await agent.callTool('dbClearCache', { resourceName: 'posts' });  // Clear specific resource
-```
-
-### Batch Operations
-
-```javascript
-// Insert multiple documents at once
-await agent.callTool('resourceInsertMany', {
-  resourceName: 'posts',
-  data: [
-    {
-      title: 'AI and Databases',
-      content: 'Exploring the intersection...',
-      author: 'jane-smith',
-      published: true
-    },
-    {
-      title: 'S3DB Performance Tips',
-      content: 'Best practices for...',
-      author: 'bob-wilson',
-      published: false
-    }
-  ]
-});
-
-// Get multiple documents by ID
-const multiplePosts = await agent.callTool('resourceGetMany', {
-  resourceName: 'posts',
-  ids: ['post_123', 'post_456', 'post_789']
-});
-
-// Delete multiple documents
-await agent.callTool('resourceDeleteMany', {
-  resourceName: 'posts',
-  ids: ['post_old1', 'post_old2']
-});
-```
-
-### E-commerce Example with Complex Schema
-
-```javascript
-// Create products resource
-await agent.callTool('dbCreateResource', {
-  name: 'products',
-  attributes: {
-    sku: 'string|required|unique',
-    name: 'string|required|min:2|max:200',
-    description: 'string|required',
-    price: 'number|positive|required',
-    category: 'string|required',
-    subcategory: 'string|optional',
-    inStock: 'boolean',
-    inventory: {
-      quantity: 'number|integer|min:0',
-      reserved: 'number|integer|min:0',
-      warehouse: 'string|required'
-    },
-    specifications: {
-      weight: 'number|positive|optional',
-      dimensions: {
-        length: 'number|positive',
-        width: 'number|positive', 
-        height: 'number|positive'
-      },
-      color: 'string|optional',
-      material: 'string|optional'
-    },
-    pricing: {
-      cost: 'number|positive',
-      markup: 'number|positive',
-      discountPercent: 'number|min:0|max:100'
-    },
-    tags: 'array|items:string',
-    images: 'array|items:url'
-  },
-  partitions: {
-    byCategory: {
-      fields: { category: 'string' },
-      description: 'Partition products by main category'
-    },
-    byCategoryAndSubcategory: {
-      fields: { 
-        category: 'string',
-        subcategory: 'string'
-      },
-      description: 'Fine-grained category partitioning'
-    }
-  },
-  timestamps: true
-});
-
-// Insert a complex product
-await agent.callTool('resourceInsert', {
-  resourceName: 'products',
-  data: {
-    sku: 'LAP-GAMING-001',
-    name: 'Gaming Laptop Pro 15"',
-    description: 'High-performance gaming laptop with RTX graphics',
-    price: 1299.99,
-    category: 'electronics',
-    subcategory: 'laptops',
-    inStock: true,
-    inventory: {
-      quantity: 25,
-      reserved: 3,
-      warehouse: 'US-WEST-1'
-    },
-    specifications: {
-      weight: 2.3,
-      dimensions: {
-        length: 35.5,
-        width: 25.0,
-        height: 2.2
-      },
-      color: 'black',
-      material: 'aluminum'
-    },
-    pricing: {
-      cost: 850.00,
-      markup: 0.53,
-      discountPercent: 0
-    },
-    tags: ['gaming', 'laptop', 'rtx', 'high-performance'],
-    images: [
-      'https://example.com/laptop-1.jpg',
-      'https://example.com/laptop-2.jpg'
-    ]
-  }
-});
-```
-
----
-
-## 🗂️ Partitions & Performance
-
-Partitions organize data for better performance and logical separation.
-
-### Creating Partitioned Resources
-
-```javascript
-await agent.callTool('dbCreateResource', {
-  name: 'orders',
-  attributes: {
-    orderId: 'string|required|unique',
-    customerId: 'string|required',
-    amount: 'number|positive|required',
-    status: 'string|enum:pending,paid,shipped,delivered,cancelled',
-    region: 'string|required',
-    orderDate: 'date|required',
-    items: 'array|items:object'
-  },
-  partitions: {
-    // Single field partitions
-    byRegion: {
-      fields: { region: 'string' },
-      description: 'Geographic distribution'
-    },
-    byStatus: {
-      fields: { status: 'string' },
-      description: 'Order status tracking'
-    },
-    byMonth: {
-      fields: { orderDate: 'date|maxlength:7' }, // YYYY-MM format
-      description: 'Monthly order archives'
-    },
-    
-    // Multi-field partitions
-    byRegionAndStatus: {
-      fields: { 
-        region: 'string',
-        status: 'string'
-      },
-      description: 'Regional status tracking'
-    },
-    byRegionAndMonth: {
-      fields: {
-        region: 'string',
-        orderDate: 'date|maxlength:7'
-      },
-      description: 'Regional monthly reports'
-    }
-  },
-  timestamps: true
-});
-```
-
-### Querying with Partitions
-
-```javascript
-// Query specific partition - much faster than full scan
-const northernOrders = await agent.callTool('resourceList', {
-  resourceName: 'orders',
-  partition: 'byRegion',
-  partitionValues: { region: 'north' },
-  limit: 100
-});
-
-// Multi-field partition query
-const northPendingOrders = await agent.callTool('resourceList', {
-  resourceName: 'orders', 
-  partition: 'byRegionAndStatus',
-  partitionValues: {
-    region: 'north',
-    status: 'pending'
-  }
-});
-
-// Time-based partition query
-const januaryOrders = await agent.callTool('resourceList', {
-  resourceName: 'orders',
-  partition: 'byMonth', 
-  partitionValues: { orderDate: '2024-01' }
-});
-
-// Count documents in partition
-const pendingCount = await agent.callTool('resourceCount', {
-  resourceName: 'orders',
-  partition: 'byStatus',
-  partitionValues: { status: 'pending' }
-});
-```
-
-### Automatic Partition Migration (v9.2.2+)
-
-**🎯 NEW FEATURE**: Records automatically move between partitions when you update partition fields!
-
-```javascript
-// 1. Insert order with status 'pending' - goes to 'pending' partition
-const order = await agent.callTool('resourceInsert', {
-  resourceName: 'orders',
-  data: {
-    orderId: 'ORD-001',
-    customerId: 'CUST-123',
-    amount: 299.99,
-    status: 'pending',  // Goes to 'pending' partition
-    region: 'north'
-  }
-});
-
-// 2. Update status to 'shipped' - AUTOMATICALLY moves to 'shipped' partition!
-await agent.callTool('resourceUpdate', {
-  resourceName: 'orders',
-  id: order.id,
-  data: {
-    ...order,
-    status: 'shipped'  // Automatically moved from 'pending' to 'shipped' partition
-  }
-});
-
-// The record is now:
-// ✅ In the 'shipped' partition
-// ❌ NOT in the 'pending' partition anymore (automatically cleaned up!)
-```
-
-### Partition Best Practices
-
-**Common Partition Patterns:**
-- **By Date**: `{ orderDate: 'date|maxlength:10' }` (YYYY-MM-DD)
-- **By Month**: `{ orderDate: 'date|maxlength:7' }` (YYYY-MM)
-- **By Category**: `{ category: 'string' }`
-- **By User**: `{ userId: 'string' }`
-- **By Status**: `{ status: 'string' }`
-- **By Geographic Region**: `{ region: 'string', country: 'string' }`
-
-**Performance Benefits:**
-- ⚡ **Faster queries** - scans only relevant partition
-- 💰 **Lower S3 costs** - fewer requests and data transfer
-- 📊 **Better analytics** - efficient aggregations
-- 🔄 **Easier maintenance** - targeted operations
-
----
-
-## 🐳 Docker Deployment
-
-### Quick Start with Docker Compose
-
-```bash
-# 1. Create project directory
-mkdir s3db-mcp && cd s3db-mcp
-
-# 2. Create docker-compose.yml
-curl -o docker-compose.yml https://raw.githubusercontent.com/forattini-dev/s3db.js/main/mcp-server/docker-compose.yml
-
-# 3. Create .env file
-curl -o .env.example https://raw.githubusercontent.com/forattini-dev/s3db.js/main/mcp-server/.env.example
-cp .env.example .env
-
-# 4. Edit .env with your configuration
-# 5. Start services
-docker compose up
-```
-
-### Production Docker Setup
-
-```yaml
-services:
-  s3db-mcp-server:
-    image: s3db-mcp-server:latest
-    restart: unless-stopped
-    environment:
-      - NODE_ENV=production
-      - S3DB_CONNECTION_STRING=s3://bucket/databases/prod
-      - MCP_TRANSPORT=sse
-      - MCP_SERVER_PORT=17500
-    ports:
-      - "17500:8000"
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "10m"
-        max-file: "3"
-```
-
-### Local Development with MinIO
-
-```bash
-# Start with MinIO for local S3 testing
-docker compose --profile local-testing up
-
-# Access:
-# - MCP Server: http://localhost:17500/sse  
-# - MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
-# - Health Check: http://localhost:8001/health
-```
-
-### Docker Environment Variables
-
-All the configuration variables mentioned above can be used in Docker:
-
-```bash
-docker run -p 17500:8000 \
-  -e S3DB_CONNECTION_STRING="s3://key:secret@bucket/db" \
-  -e S3DB_VERBOSE=true \
-  -e S3DB_PARALLELISM=20 \
-  -e MCP_TRANSPORT=sse \
-  s3db-mcp-server
-```
-
----
-
-## 🤖 AI Agent Integration
-
-### Claude Desktop Integration
-
-1. **Locate config file:**
-   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-2. **Add S3DB MCP server:**
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "transport": "sse",
-      "url": "http://localhost:17500/sse"
-    }
-  }
-}
-```
-
-3. **For STDIO transport:**
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "transport": "stdio",
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=stdio"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://bucket/databases/myapp"
-      }
-    }
-  }
-}
-```
-
-### Cursor IDE Integration
-
-Add to your MCP settings:
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "url": "http://localhost:17500/sse"
-    }
-  }
-}
-```
-
-### AI Agent Usage Rules
-
-**Before any task:**
-1. Always use `dbConnect` first to establish connection (cache and costs tracking are enabled by default)
-2. Use `dbStatus` to verify connection and see resources
-3. Use `dbListResources` to see available collections
-
-**For data operations:**
-1. Use `resourceExists` to check if documents exist before operations
-2. Prefer batch operations (`resourceInsertMany`, `resourceGetMany`) for efficiency
-3. Use partitions for performance when querying large datasets
-4. Always use pagination (`resourceList` with `limit`/`offset`) for large results
-
-**Schema design:**
-- Define validation rules: `"email": "email|required|unique"`
-- Use nested objects for complex data structures
-- Enable timestamps for audit trails
-- Consider partitioning strategy upfront
-
-**Performance monitoring:**
-- Use `dbGetStats` to monitor S3 costs and cache performance
-- Cache is automatically enabled for read operations (get, list, count)
-- Use `dbClearCache` to reset cache when needed
-- Monitor costs to optimize S3 usage patterns
-
-**Error handling:**
-- Check connection status before operations
-- Validate data structure matches schema
-- Handle resource not found errors gracefully
-- Use appropriate error messages for users
-
----
-
-## 🔧 Advanced Usage
-
-### 🔄 Auto-restart on Failure
-
-Using systemd (Linux):
-```ini
-# /etc/systemd/system/s3db-mcp.service
-[Unit]
-Description=S3DB MCP Server
-After=network.target
-
-[Service]
-Type=simple
-User=youruser
-WorkingDirectory=/home/youruser
-ExecStart=/usr/bin/npx s3db-mcp-server --transport=sse
-Restart=always
-RestartSec=10
-Environment="S3DB_CONNECTION_STRING=s3://..."
-
-[Install]
-WantedBy=multi-user.target
-```
-
-```bash
-sudo systemctl enable s3db-mcp
-sudo systemctl start s3db-mcp
-sudo systemctl status s3db-mcp
-```
-
-### 🔐 Secure Credential Management
-
-Instead of hardcoding credentials:
-
-**Option 1: Use AWS Credentials File**
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://bucket/databases/app",
-        "AWS_PROFILE": "production"
-      }
-    }
-  }
-}
-```
-
-**Option 2: Use Environment Variables**
-```bash
-# Set in your shell profile
-export S3DB_CONNECTION_STRING="s3://..."
-export AWS_ACCESS_KEY_ID="..."
-export AWS_SECRET_ACCESS_KEY="..."
-```
-
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"]
-      // No env section - uses system environment
-    }
-  }
-}
-```
-
-### 🎯 Performance Optimization
-
-For production workloads:
-```json
-{
-  "mcpServers": {
-    "s3db-optimized": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_PARALLELISM": "20",
-        "S3DB_CACHE_DRIVER": "filesystem",
-        "S3DB_CACHE_DIRECTORY": "/mnt/ssd/s3db-cache",
-        "S3DB_CACHE_MAX_SIZE": "10000",
-        "S3DB_CACHE_TTL": "3600000",
-        "NODE_ENV": "production"
-      }
-    }
-  }
-}
-```
-
----
-
-## 🔒 Security
-
-### AWS IAM Policy
-
-Minimal S3 permissions required:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:GetObject",
-        "s3:PutObject",
-        "s3:DeleteObject",
-        "s3:ListBucket",
-        "s3:HeadObject"
-      ],
-      "Resource": [
-        "arn:aws:s3:::your-s3db-bucket",
-        "arn:aws:s3:::your-s3db-bucket/*"
-      ]
-    }
-  ]
-}
-```
-
-### Security Best Practices
-
-1. **Use IAM roles** when possible instead of access keys
-2. **Rotate credentials** regularly  
-3. **Use environment variables** never hardcode credentials
-4. **Enable S3 bucket encryption** and versioning
-5. **Monitor access logs** and set up CloudTrail
-6. **Use strong passphrases** for S3DB encryption
-7. **Restrict network access** with security groups
-8. **Enable HTTPS** for all connections
-
-### Field-Level Encryption
-
-```javascript
-await agent.callTool('dbCreateResource', {
-  name: 'sensitive_data',
-  attributes: {
-    publicInfo: 'string',
-    privateData: 'secret',  // Automatically encrypted
-    ssn: 'secret',          // Encrypted with passphrase
-    creditCard: 'secret'    // Encrypted
-  }
-});
-```
-
----
-
-## 🚨 Troubleshooting
-
-### ❌ Common Issues and Solutions
-
-#### 1. MCP Server Not Starting
-
-**Issue**: Claude Desktop can't connect to MCP server
-
-**Solution**:
-```bash
-# Check if port is already in use
-lsof -i :17500  # macOS/Linux
-netstat -an | findstr :17500  # Windows
-
-# Use a different port
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse", "--port=18000"],
-      "env": {
-        "MCP_SERVER_PORT": "18000"
-      }
-    }
-  }
-}
-```
-
-#### 2. Connection String Issues
-
-**Issue**: "Invalid connection string" error
-
-**Solution**:
-```bash
-# Test connection string directly
-export S3DB_CONNECTION_STRING="s3://..."
-npx s3db-mcp-server --transport=sse
-
-# Common fixes:
-# 1. URL-encode special characters in credentials
-# 2. Add forcePathStyle=true for MinIO
-# 3. Ensure bucket exists
-```
-
-#### 3. Permission Errors
-
-**Issue**: "Access Denied" when accessing S3
-
-**Solution**:
-```json
-{
-  "env": {
-    // Ensure credentials are correct
-    "AWS_ACCESS_KEY_ID": "your-key",
-    "AWS_SECRET_ACCESS_KEY": "your-secret",
-    "AWS_REGION": "correct-region"
-  }
-}
-```
-
-#### 4. Cache Not Working
-
-**Issue**: Slow performance, no cache hits
-
-**Solution**:
-```json
-{
-  "env": {
-    "S3DB_CACHE_ENABLED": "true",  // Must be string "true"
-    "S3DB_CACHE_DRIVER": "memory",
-    "S3DB_CACHE_MAX_SIZE": "5000",  // Increase size
-    "S3DB_CACHE_TTL": "600000"      // 10 minutes
-  }
-}
-```
-
-### 🔍 Debugging
-
-Enable verbose logging:
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_VERBOSE": "true",
-        "NODE_ENV": "development",
-        "DEBUG": "true"
-      }
-    }
-  }
-}
-```
-
-View MCP logs in Claude Desktop:
-1. Open Developer Tools: `Cmd+Option+I` (Mac) or `Ctrl+Shift+I` (Windows)
-2. Go to Console tab
-3. Filter for "mcp" messages
-
-### S3 Access Issues
-
-```bash
-# Test S3 connection
-aws s3 ls s3://your-bucket
-
-# Check credentials
-aws sts get-caller-identity
-
-# Test with MinIO
-mc alias set local http://localhost:9000 minioadmin minioadmin
-mc ls local
-```
-
-**Performance Issues:**
-- Increase `S3DB_PARALLELISM` for better throughput
-- Use partitions to reduce query scope
-- Implement proper pagination 
-- Monitor S3 request patterns
-
-**Memory Issues:**
-- Avoid `resourceGetAll` on large datasets
-- Use `resourceList` with pagination instead
-- Increase Docker memory limits if needed
-
-### Error Messages
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Database not connected" | No `dbConnect` called | Call `dbConnect` tool first |
-| "Resource not found" | Invalid resource name | Check with `dbListResources` |
-| "Validation failed" | Data doesn't match schema | Review attribute definitions |
-| "Connection string invalid" | Malformed connection string | Check format: `s3://key:secret@bucket/path` |
-| "Health check failed" | Server not responding | Check if process is running on correct port |
-
-### Debug Mode
-
-Enable verbose logging:
-```bash
-# Environment variable
-export S3DB_VERBOSE=true
-
-# Command line
-s3db-mcp --transport=sse
-
-# Docker
-docker run -e S3DB_VERBOSE=true s3db-mcp-server
-```
-
-### Health Monitoring
-
-```bash
-# Check server health
-curl http://localhost:8001/health
-
-# Response includes:
-{
-  "status": "healthy",
-  "database": {
-    "connected": true,
-    "bucket": "my-bucket", 
-    "resourceCount": 5
-  },
-  "memory": { "rss": 45000000 },
-  "uptime": 3600
-}
-```
-
-### 🎉 Success Indicators
-
-You know your setup is working when:
-1. ✅ Claude Desktop shows "Connected to s3db" in the MCP status
-2. ✅ You can run database commands without errors
-3. ✅ Cache statistics show hits after repeated queries
-4. ✅ Cost tracking shows S3 operation counts
-
-### 💡 Pro Tips
-
-1. **Start simple**: Test with MinIO locally before using AWS S3
-2. **Monitor costs**: Use `dbGetStats` regularly to track S3 expenses
-3. **Optimize partitions**: Design partitions based on query patterns
-4. **Cache wisely**: Filesystem cache survives restarts, memory cache is faster
-5. **Use batch operations**: `insertMany` is much faster than multiple `insert` calls
-
----
-
-## 🔌 Built-in Performance Features
-
-The S3DB MCP Server includes **automatic performance optimizations**:
-
-### **🏎️ Configurable Cache (Enabled by Default)**
-- **Two cache drivers**: Memory (fast, temporary) and Filesystem (persistent)
-- **Automatic caching** of read operations (get, list, count, exists)
-- **Partition-aware** caching for optimized queries
-- **Configurable TTL** and size limits
-- **Cache invalidation** on write operations
-- **Performance monitoring** via `dbGetStats`
-
-#### **Memory Cache**
-- ⚡ **Fastest performance** for frequently accessed data
-- 🔄 **Lost on restart** - ideal for temporary caching
-- 📊 **Size-limited** by number of items
-
-#### **Filesystem Cache**  
-- 💾 **Persistent across restarts** - cache survives server restarts
-- 🗜️ **Automatic compression** to save disk space
-- 🧹 **Automatic cleanup** of expired files
-- 📁 **Configurable directory** and file naming
-
-### **💰 Costs Tracking (Enabled by Default)**
-- **Real-time S3 costs** calculation
-- **Request counting** by operation type
-- **Cost estimation** in USD
-- **Performance analytics** for optimization
-
-### **Configuration Options**
-```javascript
-// Connect with memory cache (fast, temporary)
-await agent.callTool('dbConnect', {
-  connectionString: 's3://...',
-  enableCache: true,        // Default: true
-  enableCosts: true,        // Default: true  
-  cacheDriver: 'memory',    // Fast but lost on restart
-  cacheMaxSize: 2000,       // Default: 1000
-  cacheTtl: 600000          // Default: 300000 (5 min)
-});
-
-// Connect with filesystem cache (persistent)
-await agent.callTool('dbConnect', {
-  connectionString: 's3://...',
-  enableCache: true,
-  cacheDriver: 'filesystem', // Survives restarts
-  cacheDirectory: './data/cache',
-  cachePrefix: 'myapp',
-  cacheTtl: 1800000          // 30 minutes
-});
-
-// Monitor performance
-const stats = await agent.callTool('dbGetStats');
-console.log('Cache size:', stats.stats.cache.size);
-console.log('Cache driver:', stats.stats.cache.driver);
-console.log('S3 costs:', stats.stats.costs.estimatedCostUSD);
-
-// Clear cache when needed
-await agent.callTool('dbClearCache', { resourceName: 'users' });
-```
-
-### **Environment Variables**
-```bash
-S3DB_CACHE_ENABLED=true           # Enable/disable cache
-S3DB_CACHE_DRIVER=memory          # Cache driver: 'memory' or 'filesystem'
-S3DB_CACHE_MAX_SIZE=1000          # Cache capacity (memory driver)
-S3DB_CACHE_TTL=300000             # 5 minute TTL
-S3DB_CACHE_DIRECTORY=./cache      # Filesystem cache directory
-S3DB_CACHE_PREFIX=s3db            # Filesystem cache file prefix
-S3DB_COSTS_ENABLED=true           # Enable/disable costs tracking
-```
-
----
-
-## 🚀 **Cache Strategy Guide**
-
-Choose the right cache driver for your use case:
-
-### **When to Use Memory Cache**
-- ⚡ **Development & Testing** - fastest performance, no setup required
-- 🔄 **Short-lived processes** - containers that restart frequently  
-- 📊 **High-frequency reads** - when you need maximum speed
-- 💰 **Cost optimization** - minimize S3 requests for hot data
-- ⚠️ **Limitation**: Cache is lost on restart
-
-### **When to Use Filesystem Cache**
-- 💾 **Production environments** - cache survives server restarts
-- 🔄 **Long-running processes** - persistent data across deployments
-- 📦 **Containerized deployments** - mount cache volume for persistence
-- 🔧 **Development consistency** - maintain cache between code changes
-- 🗂️ **Large datasets** - no memory size limitations
-
-### **Configuration Examples**
-
-```javascript
-// High-performance temporary cache
-await agent.callTool('dbConnect', {
-  cacheDriver: 'memory',
-  cacheMaxSize: 5000,
-  cacheTtl: 600000  // 10 minutes
-});
-
-// Production persistent cache
-await agent.callTool('dbConnect', {
-  cacheDriver: 'filesystem',
-  cacheDirectory: './data/cache',
-  cachePrefix: 'prod',
-  cacheTtl: 3600000  // 1 hour
-});
-```
-
-### **Docker Volume Setup**
-```yaml
-# docker-compose.yml
-volumes:
-  - ./cache-data:/app/cache  # Persistent filesystem cache
-environment:
-  - S3DB_CACHE_DRIVER=filesystem
-  - S3DB_CACHE_DIRECTORY=/app/cache
-```
-
----
-
-## 📊 Performance Tips
-
-1. **Choose appropriate cache** - memory for speed, filesystem for persistence
-2. **Leverage built-in cache** - read operations are automatically cached
-3. **Use partitions** for large datasets to improve cache efficiency
-4. **Monitor costs** with `dbGetStats` to optimize S3 usage
-5. **Batch operations** when possible to reduce S3 requests
-6. **Proper pagination** - don't load everything at once
-7. **Connection reuse** - keep connections alive
-8. **Appropriate parallelism** - tune `S3DB_PARALLELISM`
-
----
-
-## 📚 Additional Resources
-
-- [S3DB Documentation](https://github.com/forattini-dev/s3db.js)
-- [MCP Protocol Specification](https://modelcontextprotocol.io)
-- [Claude Desktop Downloads](https://claude.ai/download)
-- [GitHub Issues](https://github.com/forattini-dev/s3db.js/issues)
-- [NPM Package](https://www.npmjs.com/package/s3db-mcp-server)
-
-Need help? Check the [Troubleshooting](#troubleshooting) section or file an issue on [GitHub](https://github.com/forattini-dev/s3db.js/issues).
-
----
-
-## 📄 License
-
-This project is licensed under the same license as the parent S3DB project.
-
----
-
-<p align="center">
-  <strong>🎉 Ready to supercharge your AI agents with persistent data storage!</strong><br>
-  <em>Start building with S3DB MCP Server today</em>
-</p>