s3db.js 11.2.6 → 11.3.1

package/README.md

@@ -110,6 +110,7 @@
 - [🎣 Advanced Hooks System](#-advanced-hooks-system)
 - [🧩 Resource Middlewares](#-resource-middlewares)
 - [🎧 Event Listeners Configuration](#-event-listeners-configuration)
+- [🤖 MCP Server](#-mcp-server)
 - [🔧 Troubleshooting](#-troubleshooting)
 - [📖 API Reference](#-api-reference)
 
@@ -1866,6 +1867,143 @@ await users.insert({ name: 'John' });
 
 ---
 
+## 🤖 MCP Server
+
+S3DB includes a powerful **Model Context Protocol (MCP) server** that enables AI assistants like Claude to interact with your S3DB databases. The MCP server provides **28 specialized tools** for database operations, debugging, monitoring, and data management.
+
+### ⚡ Quick Start with npx
+
+**For Claude CLI** (one command setup):
+```bash
+claude mcp add s3db \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+**For Claude Desktop** - Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "s3db": {
+      "command": "npx",
+      "args": ["-y", "s3db.js", "s3db-mcp", "--transport=sse"],
+      "env": {
+        "S3DB_CONNECTION_STRING": "s3://ACCESS_KEY:SECRET_KEY@bucket/databases/myapp",
+        "S3DB_CACHE_ENABLED": "true",
+        "S3DB_COSTS_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+**Standalone Server:**
+```bash
+# Start HTTP server
+npx s3db.js s3db-mcp --transport=sse
+```
+
+📖 **Complete setup guides:**
+- [NPX Setup Guide](./mcp/NPX_SETUP.md) - Use with `npx` (recommended)
+- [Claude CLI Setup](./mcp/CLAUDE_CLI_SETUP.md) - Detailed configuration
+
+### Available Tools
+
+The MCP server provides 28 tools organized into 7 categories:
+
+#### 🔌 **Connection Management** (3 tools)
+- `dbConnect` - Connect with cache and costs tracking
+- `dbDisconnect` - Graceful disconnection
+- `dbStatus` - Check connection status
+
+#### 🔍 **Debugging Tools** (5 tools)
+- `dbInspectResource` - Deep resource inspection
+- `dbGetMetadata` - View raw metadata.json
+- `resourceValidate` - Validate data against schema
+- `dbHealthCheck` - Comprehensive health check
+- `resourceGetRaw` - View raw S3 object data
+
+#### 📊 **Query & Filtering** (2 tools)
+- `resourceQuery` - Complex queries with filters
+- `resourceSearch` - Full-text search
+
+#### 🔧 **Partition Management** (4 tools)
+- `resourceListPartitions` - List all partitions
+- `resourceListPartitionValues` - Get partition values
+- `dbFindOrphanedPartitions` - Detect orphaned partitions
+- `dbRemoveOrphanedPartitions` - Clean up orphaned partitions
+
+#### 🚀 **Bulk Operations** (3 tools)
+- `resourceUpdateMany` - Update with filters
+- `resourceBulkUpsert` - Bulk upsert operations
+- `resourceDeleteAll` - Delete all documents
+
+#### 💾 **Export/Import** (3 tools)
+- `resourceExport` - Export to JSON/CSV/NDJSON
+- `resourceImport` - Import from JSON/NDJSON
+- `dbBackupMetadata` - Create metadata backups
+
+#### 📈 **Monitoring** (4 tools)
+- `dbGetStats` - Database statistics
+- `resourceGetStats` - Resource-specific stats
+- `cacheGetStats` - Cache performance metrics
+- `dbClearCache` - Clear cache
+
+Plus **standard CRUD operations**: insert, get, update, delete, list, count, and more.
+
+### Features
+
+- ✅ **Automatic Performance**: Cache and cost tracking enabled by default
+- ✅ **Multiple Transports**: SSE for web clients, stdio for CLI
+- ✅ **Partition-Aware**: Intelligent caching with partition support
+- ✅ **Debugging**: Comprehensive tools for troubleshooting
+- ✅ **Bulk Operations**: Efficient batch processing
+- ✅ **Export/Import**: Data migration and backup
+
+### Full Documentation
+
+**Complete MCP documentation**: [**docs/mcp.md**](./docs/mcp.md)
+
+Includes:
+- Tool reference with all 28 tools
+- Configuration examples (AWS, MinIO, DigitalOcean)
+- Docker deployment guides
+- Performance optimization
+- Troubleshooting
+- Security best practices
+
+### Example Usage
+
+```javascript
+// Connect to database
+await dbConnect({
+  connectionString: "s3://bucket/databases/app",
+  enableCache: true,
+  enableCosts: true
+})
+
+// Inspect resource
+await dbInspectResource({ resourceName: "users" })
+
+// Query with filters
+await resourceQuery({
+  resourceName: "users",
+  filters: { status: "active", age: { $gt: 18 } }
+})
+
+// Export data
+await resourceExport({
+  resourceName: "users",
+  format: "csv",
+  filters: { status: "active" }
+})
+
+// Check health
+await dbHealthCheck({ includeOrphanedPartitions: true })
+```
+
+---
+
 ## 📖 API Reference
 
 ### 📚 Core Classes Documentation

package/dist/s3db.cjs.js

@@ -15283,7 +15283,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.6" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.3.1" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -16087,7 +16087,7 @@ class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== void 0 ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
-      strictValidation: this.strictValidation,
+      strictValidation: config.strictValidation !== void 0 ? config.strictValidation : this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,

package/dist/s3db.es.js

@@ -15279,7 +15279,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.6" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.3.1" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -16083,7 +16083,7 @@ class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== void 0 ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
-      strictValidation: this.strictValidation,
+      strictValidation: config.strictValidation !== void 0 ? config.strictValidation : this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,

package/mcp/.env.example

@@ -0,0 +1,117 @@
+# ==============================================================================
+# S3DB MCP Server Configuration
+# ==============================================================================
+
+# Server Configuration
+NODE_ENV=development
+MCP_SERVER_HOST=0.0.0.0
+MCP_SERVER_PORT=8000
+MCP_TRANSPORT=sse
+
+# ==============================================================================
+# S3DB Database Configuration
+# ==============================================================================
+
+# Primary S3DB connection string
+# Format: s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/database/path
+# Example: s3://AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY@my-s3db-bucket/databases/production
+S3DB_CONNECTION_STRING=s3://YOUR_ACCESS_KEY:YOUR_SECRET_KEY@YOUR_BUCKET/databases/development
+
+# S3DB Options
+S3DB_VERBOSE=false
+S3DB_PARALLELISM=10
+S3DB_PASSPHRASE=your-encryption-passphrase
+S3DB_VERSIONING_ENABLED=false
+
+# Plugin Configuration
+S3DB_COSTS_ENABLED=true              # Enable automatic S3 costs tracking
+S3DB_CACHE_ENABLED=true              # Enable cache for performance
+S3DB_CACHE_DRIVER=memory             # Cache driver: 'memory' or 'filesystem'
+S3DB_CACHE_MAX_SIZE=1000             # Maximum items in memory cache (memory driver only)
+S3DB_CACHE_TTL=300000                # Cache TTL in milliseconds (5 minutes)
+S3DB_CACHE_DIRECTORY=./cache         # Directory for filesystem cache (filesystem driver only)
+S3DB_CACHE_PREFIX=s3db               # Prefix for cache files (filesystem driver only)
+
+# ==============================================================================
+# AWS Configuration
+# ==============================================================================
+
+# AWS Credentials (required unless using IAM roles)
+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+AWS_SESSION_TOKEN=
+AWS_REGION=us-east-1
+
+# ==============================================================================
+# S3-Compatible Services (MinIO, DigitalOcean Spaces, etc.)
+# ==============================================================================
+
+# Uncomment and configure for S3-compatible services
+# S3_ENDPOINT=http://localhost:9000
+# S3_FORCE_PATH_STYLE=true
+
+# MinIO specific (for local testing)
+# S3_ENDPOINT=http://minio:9000
+# MINIO_ROOT_USER=minioadmin
+# MINIO_ROOT_PASSWORD=minioadmin
+
+# DigitalOcean Spaces example
+# S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
+# S3_FORCE_PATH_STYLE=false
+
+# ==============================================================================
+# Development & Testing
+# ==============================================================================
+
+# LocalStack configuration (for local AWS testing)
+# S3_ENDPOINT=http://localhost:4566
+# S3_FORCE_PATH_STYLE=true
+
+# Debug options
+DEBUG=false
+LOG_LEVEL=info
+
+# ==============================================================================
+# Example Connection Strings for Different Providers
+# ==============================================================================
+
+# AWS S3 (with credentials in connection string)
+# S3DB_CONNECTION_STRING=s3://ACCESS_KEY:SECRET_KEY@bucket-name/databases/myapp
+
+# AWS S3 (using IAM roles - no credentials needed)
+# S3DB_CONNECTION_STRING=s3://bucket-name/databases/myapp
+
+# MinIO local development
+# S3DB_CONNECTION_STRING=s3://minioadmin:minioadmin@test-bucket/databases/dev?endpoint=http://localhost:9000&forcePathStyle=true
+
+# DigitalOcean Spaces
+# S3DB_CONNECTION_STRING=s3://DO_ACCESS_KEY:DO_SECRET_KEY@space-name/databases/prod?endpoint=https://nyc3.digitaloceanspaces.com
+
+# LocalStack (local AWS simulation)
+# S3DB_CONNECTION_STRING=s3://test:test@test-bucket/databases/local?endpoint=http://localhost:4566&forcePathStyle=true
+
+# ==============================================================================
+# Security Notes
+# ==============================================================================
+
+# IMPORTANT SECURITY CONSIDERATIONS:
+# 1. Never commit real credentials to version control
+# 2. Use IAM roles when possible instead of access keys
+# 3. Rotate credentials regularly
+# 4. Use least-privilege access policies
+# 5. Enable S3 bucket encryption and versioning
+# 6. Monitor access logs and CloudTrail events
+# 7. Use strong passphrases for S3DB encryption
+
+# ==============================================================================
+# Production Recommendations
+# ==============================================================================
+
+# For production environments:
+# - Use IAM roles instead of access keys when possible
+# - Enable S3DB versioning for data protection
+# - Use environment-specific bucket names
+# - Enable comprehensive logging
+# - Set up monitoring and alerting
+# - Use encrypted connections (HTTPS)
+# - Implement backup strategies

package/mcp/CLAUDE_CLI_SETUP.md

@@ -0,0 +1,302 @@
+# 🚀 Claude CLI Setup Guide
+
+Este guia mostra como configurar o S3DB MCP Server para usar com o Claude CLI.
+
+## 📋 Pré-requisitos
+
+```bash
+# Verificar se Claude CLI está instalado
+claude --version
+
+# Verificar se o projeto está instalado
+cd /home/ff/work/martech/s3db.js
+pnpm install
+
+# Instalar dependências do MCP (se ainda não estiver)
+pnpm add zod@3 express
+```
+
+## 🔌 Métodos de Configuração
+
+### Método 1: Stdio Transport (Recomendado para desenvolvimento)
+
+O Claude CLI vai spawnar o servidor automaticamente quando necessário.
+
+```bash
+claude mcp add s3db \
+  --transport stdio \
+  -- node /home/ff/work/martech/s3db.js/mcp/entrypoint.js --transport=stdio
+```
+
+**Variáveis de ambiente** (opcional):
+```bash
+# Editar configuração para adicionar env vars
+claude mcp edit s3db
+
+# Adicionar na seção env:
+{
+  "s3db": {
+    "transport": "stdio",
+    "command": "node",
+    "args": ["/home/ff/work/martech/s3db.js/mcp/entrypoint.js", "--transport=stdio"],
+    "env": {
+      "S3DB_CONNECTION_STRING": "s3://minioadmin:minioadmin123@localhost:9000/dev-bucket?forcePathStyle=true",
+      "S3DB_CACHE_ENABLED": "true",
+      "S3DB_CACHE_DRIVER": "memory",
+      "S3DB_VERBOSE": "false"
+    }
+  }
+}
+```
+
+### Método 2: HTTP Transport (Recomendado para produção)
+
+Primeiro, inicie o servidor em background:
+
+```bash
+# Inicie o servidor HTTP
+cd /home/ff/work/martech/s3db.js
+node mcp/entrypoint.js --transport=sse &
+
+# Ou com PM2 para auto-restart
+pm2 start mcp/entrypoint.js --name s3db-mcp -- --transport=sse
+pm2 save
+```
+
+Depois configure o Claude CLI:
+
+```bash
+claude mcp add s3db --transport http http://localhost:17500/sse
+```
+
+## 🧪 Testando a Configuração
+
+### 1. Verificar servidores configurados
+
+```bash
+claude mcp list
+```
+
+Você deve ver:
+```
+s3db - stdio://node /home/ff/work/martech/s3db.js/mcp/entrypoint.js --transport=stdio
+```
+
+### 2. Testar conexão
+
+```bash
+# Iniciar sessão do Claude
+claude
+
+# No chat, testar as tools:
+# "Can you connect to the S3DB database and list available resources?"
+```
+
+### 3. Comandos de teste no Claude Chat
+
+```
+1. Conectar ao banco:
+   "Connect to the S3DB database using dbConnect"
+
+2. Listar recursos:
+   "List all resources in the database using dbListResources"
+
+3. Criar um recurso de teste:
+   "Create a resource called 'test_users' with fields: name (string, required), email (string, required), age (number)"
+
+4. Inserir dados:
+   "Insert a test user with name 'John Doe', email 'john@example.com', age 30"
+
+5. Ver estatísticas:
+   "Show me database statistics including cache and costs"
+```
+
+## 🔧 Configurações Avançadas
+
+### Configurar para múltiplos ambientes
+
+```bash
+# Development (local MinIO)
+claude mcp add s3db-dev \
+  --transport stdio \
+  -- node /home/ff/work/martech/s3db.js/mcp/entrypoint.js --transport=stdio
+
+# Production (AWS S3)
+claude mcp add s3db-prod \
+  --transport http \
+  http://production-server:17500/sse
+```
+
+### Editar configuração existente
+
+```bash
+# Ver configuração atual
+claude mcp show s3db
+
+# Editar configuração
+claude mcp edit s3db
+
+# Remover servidor
+claude mcp remove s3db
+```
+
+## 📊 Tools Disponíveis (39 total)
+
+### 🔌 Connection Management (3)
+- `dbConnect` - Connect to S3DB database
+- `dbDisconnect` - Disconnect from database
+- `dbStatus` - Get connection status
+
+### 📦 Resource Management (2)
+- `dbCreateResource` - Create new resource/collection
+- `dbListResources` - List all resources
+
+### 🔍 Debugging Tools (5)
+- `dbInspectResource` - Detailed resource inspection
+- `dbGetMetadata` - Get raw metadata.json
+- `resourceValidate` - Validate data against schema
+- `dbHealthCheck` - Comprehensive health check
+- `resourceGetRaw` - Get raw S3 object data
+
+### 📊 Query & Filtering (2)
+- `resourceQuery` - Complex queries with filters
+- `resourceSearch` - Text search in fields
+
+### 🔧 Partition Management (4)
+- `resourceListPartitions` - List all partitions
+- `resourceListPartitionValues` - List partition values
+- `dbFindOrphanedPartitions` - Find orphaned partitions
+- `dbRemoveOrphanedPartitions` - Remove orphaned partitions
+
+### ✏️ CRUD Operations (14)
+- `resourceInsert` - Insert single document
+- `resourceInsertMany` - Insert multiple documents
+- `resourceGet` - Get document by ID
+- `resourceGetMany` - Get multiple documents
+- `resourceUpdate` - Update document
+- `resourceUpsert` - Insert or update
+- `resourceDelete` - Delete document
+- `resourceDeleteMany` - Delete multiple documents
+- `resourceExists` - Check if document exists
+- `resourceList` - List with pagination
+- `resourceListIds` - List document IDs
+- `resourceCount` - Count documents
+- `resourceGetAll` - Get all documents
+- `resourceDeleteAll` - Delete all documents
+
+### 🚀 Bulk Operations (2)
+- `resourceUpdateMany` - Update multiple documents
+- `resourceBulkUpsert` - Bulk upsert operation
+
+### 💾 Export/Import (3)
+- `resourceExport` - Export to JSON/CSV/NDJSON
+- `resourceImport` - Import from JSON/NDJSON
+- `dbBackupMetadata` - Backup metadata.json
+
+### 📈 Monitoring (4)
+- `dbGetStats` - Database statistics
+- `dbClearCache` - Clear cache
+- `resourceGetStats` - Resource statistics
+- `cacheGetStats` - Cache statistics
+
+## 🐛 Troubleshooting
+
+### Erro: "Command not found"
+
+```bash
+# Usar caminho absoluto completo
+claude mcp add s3db \
+  --transport stdio \
+  -- /home/ff/.nvm/versions/node/v22.6.0/bin/node \
+  /home/ff/work/martech/s3db.js/mcp/entrypoint.js --transport=stdio
+```
+
+### Erro: "Connection refused" (HTTP)
+
+```bash
+# Verificar se o servidor está rodando
+curl http://localhost:17500/health
+
+# Se não estiver, inicie:
+cd /home/ff/work/martech/s3db.js
+node mcp/entrypoint.js --transport=sse
+```
+
+### Erro: "Database not connected"
+
+No chat do Claude, sempre conecte primeiro:
+```
+"Please connect to the database first using dbConnect with connection string: s3://minioadmin:minioadmin123@localhost:9000/dev-bucket"
+```
+
+### Ver logs do servidor
+
+```bash
+# Se usando PM2
+pm2 logs s3db-mcp
+
+# Se rodando diretamente
+# Os logs aparecem no terminal onde iniciou o servidor
+```
+
+## 📚 Recursos Adicionais
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [S3DB Documentation](../README.md)
+- [Full MCP Documentation](../docs/mcp.md)
+- [Claude CLI Documentation](https://docs.claude.com/en/docs/claude-code)
+
+## 🎯 Exemplos de Uso
+
+### Exemplo 1: CRUD Básico
+
+```
+User: Connect to local MinIO and create a users resource
+
+Claude will:
+1. Use dbConnect with MinIO connection string
+2. Use dbCreateResource to create 'users' resource
+3. Confirm creation with dbListResources
+
+User: Insert 5 test users
+
+Claude will:
+1. Use resourceInsertMany with test data
+2. Confirm with resourceCount
+```
+
+### Exemplo 2: Análise de Performance
+
+```
+User: Analyze database performance and suggest optimizations
+
+Claude will:
+1. Use dbGetStats to get overall statistics
+2. Use cacheGetStats to check cache performance
+3. Use dbHealthCheck to find issues
+4. Provide optimization suggestions
+```
+
+### Exemplo 3: Partition Recovery
+
+```
+User: Check for orphaned partitions and fix them
+
+Claude will:
+1. Use dbFindOrphanedPartitions to detect issues
+2. Use dbRemoveOrphanedPartitions with dryRun:true to preview
+3. Execute removal with dryRun:false
+4. Verify with dbHealthCheck
+```
+
+## ✅ Checklist de Configuração
+
+- [ ] Claude CLI instalado e funcionando
+- [ ] S3DB.js projeto instalado (pnpm install)
+- [ ] Servidor MCP configurado (claude mcp add)
+- [ ] Conexão testada (claude mcp list)
+- [ ] Tools testadas no chat do Claude
+- [ ] Environment variables configuradas (se necessário)
+- [ ] Backup da configuração (claude mcp show s3db > backup.json)
+
+Pronto! Agora você pode usar todas as 39 tools do S3DB diretamente no Claude CLI! 🎉

package/mcp/Dockerfile

@@ -0,0 +1,45 @@
+# syntax=docker/dockerfile:1.9
+FROM node:20-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy package files first for better caching
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy application code
+COPY s3db_mcp_server.js ./
+
+# Create non-root user
+RUN groupadd -r s3dbmcp && useradd -r -d /app -g s3dbmcp s3dbmcp
+
+# Change ownership to app user
+RUN chown -Rv s3dbmcp:s3dbmcp /app
+
+# Switch to non-root user
+USER s3dbmcp
+
+# Set environment variables
+ENV NODE_ENV=production \
+    MCP_SERVER_HOST=0.0.0.0 \
+    MCP_SERVER_PORT=8000 \
+    MCP_TRANSPORT=sse
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:8001/health || exit 1
+
+# Default command
+CMD ["node", "s3db_mcp_server.js", "--transport=sse"]