s3db.js 11.2.5 → 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

@@ -13125,6 +13125,71 @@ ${errorDetails}`,
     }
     return true;
   }
+  /**
+   * Find orphaned partitions (partitions that reference non-existent fields)
+   * @returns {Object} Object with orphaned partition names as keys and details as values
+   * @example
+   * const orphaned = resource.findOrphanedPartitions();
+   * // Returns: { byRegion: { missingFields: ['region'], definition: {...} } }
+   */
+  findOrphanedPartitions() {
+    const orphaned = {};
+    if (!this.config.partitions) {
+      return orphaned;
+    }
+    for (const [partitionName, partitionDef] of Object.entries(this.config.partitions)) {
+      if (!partitionDef.fields) {
+        continue;
+      }
+      const missingFields = [];
+      for (const fieldName of Object.keys(partitionDef.fields)) {
+        if (!this.fieldExistsInAttributes(fieldName)) {
+          missingFields.push(fieldName);
+        }
+      }
+      if (missingFields.length > 0) {
+        orphaned[partitionName] = {
+          missingFields,
+          definition: partitionDef,
+          allFields: Object.keys(partitionDef.fields)
+        };
+      }
+    }
+    return orphaned;
+  }
+  /**
+   * Remove orphaned partitions (partitions that reference non-existent fields)
+   * WARNING: This will modify the resource configuration and should be followed by uploadMetadataFile()
+   * @param {Object} options - Options
+   * @param {boolean} options.dryRun - If true, only returns what would be removed without modifying (default: false)
+   * @returns {Object} Object with removed partition names and details
+   * @example
+   * // Dry run to see what would be removed
+   * const toRemove = resource.removeOrphanedPartitions({ dryRun: true });
+   * console.log('Would remove:', toRemove);
+   *
+   * // Actually remove orphaned partitions
+   * const removed = resource.removeOrphanedPartitions();
+   * await database.uploadMetadataFile(); // Save changes to S3
+   */
+  removeOrphanedPartitions({ dryRun = false } = {}) {
+    const orphaned = this.findOrphanedPartitions();
+    if (Object.keys(orphaned).length === 0) {
+      return {};
+    }
+    if (dryRun) {
+      return orphaned;
+    }
+    for (const partitionName of Object.keys(orphaned)) {
+      delete this.config.partitions[partitionName];
+    }
+    this.emit("orphanedPartitionsRemoved", {
+      resourceName: this.name,
+      removed: Object.keys(orphaned),
+      details: orphaned
+    });
+    return orphaned;
+  }
   /**
    * Apply a single partition rule to a field value
    * @param {*} value - The field value
@@ -15218,7 +15283,7 @@ class Database extends EventEmitter {
     this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = tryFn(() => true ? "11.2.5" : "latest");
+      const [ok, err, version] = tryFn(() => true ? "11.3.1" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};
@@ -16022,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,