s3db.js 11.2.6 → 11.3.2

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.2" : "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.2" : "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