s3db.js 11.2.6 → 11.3.2

package/mcp/tools/debugging.js

@@ -0,0 +1,299 @@
+/**
+ * Debugging Tools
+ * Provides inspection, validation, and health check capabilities
+ */
+
+export const debuggingTools = [
+  {
+    name: 'dbInspectResource',
+    description: 'Inspect detailed information about a resource including schema, partitions, behaviors, and configuration',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource to inspect'
+        }
+      },
+      required: ['resourceName']
+    }
+  },
+  {
+    name: 'dbGetMetadata',
+    description: 'Get raw metadata.json from the S3 bucket for debugging',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  {
+    name: 'resourceValidate',
+    description: 'Validate data against resource schema without inserting',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource'
+        },
+        data: {
+          type: 'object',
+          description: 'Data to validate'
+        }
+      },
+      required: ['resourceName', 'data']
+    }
+  },
+  {
+    name: 'dbHealthCheck',
+    description: 'Perform comprehensive health check on database including orphaned partitions detection',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeOrphanedPartitions: {
+          type: 'boolean',
+          description: 'Include orphaned partitions check',
+          default: true
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'resourceGetRaw',
+    description: 'Get raw S3 object data (metadata + body) for debugging',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource'
+        },
+        id: {
+          type: 'string',
+          description: 'Document ID'
+        }
+      },
+      required: ['resourceName', 'id']
+    }
+  }
+];
+
+export function createDebuggingHandlers(server) {
+  return {
+    async dbInspectResource(args, database) {
+      server.ensureConnected(database);
+      const { resourceName } = args;
+      const resource = server.getResource(database, resourceName);
+
+      const inspection = {
+        success: true,
+        resource: {
+          name: resource.name,
+          behavior: resource.behavior,
+          version: resource.version,
+          createdBy: resource.createdBy || 'user',
+
+          schema: {
+            attributes: resource.attributes,
+            attributeCount: Object.keys(resource.attributes || {}).length,
+            fieldTypes: {}
+          },
+
+          partitions: resource.config.partitions ? {
+            count: Object.keys(resource.config.partitions).length,
+            definitions: resource.config.partitions,
+            orphaned: resource.findOrphanedPartitions ? resource.findOrphanedPartitions() : null
+          } : null,
+
+          configuration: {
+            timestamps: resource.config.timestamps,
+            paranoid: resource.config.paranoid,
+            strictValidation: resource.strictValidation,
+            asyncPartitions: resource.config.asyncPartitions,
+            versioningEnabled: resource.config.versioningEnabled,
+            autoDecrypt: resource.config.autoDecrypt
+          },
+
+          hooks: resource.config.hooks ? {
+            beforeInsert: resource.config.hooks.beforeInsert?.length || 0,
+            afterInsert: resource.config.hooks.afterInsert?.length || 0,
+            beforeUpdate: resource.config.hooks.beforeUpdate?.length || 0,
+            afterUpdate: resource.config.hooks.afterUpdate?.length || 0,
+            beforeDelete: resource.config.hooks.beforeDelete?.length || 0,
+            afterDelete: resource.config.hooks.afterDelete?.length || 0
+          } : null,
+
+          s3Paths: {
+            metadataKey: `${database.keyPrefix}metadata.json`,
+            resourcePrefix: `${database.keyPrefix}resource=${resourceName}/`
+          }
+        }
+      };
+
+      // Analyze field types
+      for (const [fieldName, fieldDef] of Object.entries(resource.attributes || {})) {
+        const typeStr = typeof fieldDef === 'string' ? fieldDef : fieldDef.type;
+        inspection.resource.schema.fieldTypes[fieldName] = typeStr;
+      }
+
+      return inspection;
+    },
+
+    async dbGetMetadata(args, database) {
+      server.ensureConnected(database);
+
+      const metadataKey = `${database.keyPrefix}metadata.json`;
+
+      try {
+        const response = await database.client.getObject({
+          Bucket: database.bucket,
+          Key: metadataKey
+        });
+
+        const metadataContent = await response.Body.transformToString();
+        const metadata = JSON.parse(metadataContent);
+
+        return {
+          success: true,
+          metadata,
+          s3Info: {
+            key: metadataKey,
+            bucket: database.bucket,
+            lastModified: response.LastModified,
+            size: response.ContentLength,
+            etag: response.ETag
+          }
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message,
+          key: metadataKey
+        };
+      }
+    },
+
+    async resourceValidate(args, database) {
+      server.ensureConnected(database);
+      const { resourceName, data } = args;
+      const resource = server.getResource(database, resourceName);
+
+      try {
+        // Use the schema validator if available
+        const validationResult = resource.schema.validate(data);
+
+        return {
+          success: true,
+          valid: validationResult === true,
+          errors: validationResult === true ? [] : validationResult,
+          data: data
+        };
+      } catch (error) {
+        return {
+          success: false,
+          valid: false,
+          error: error.message,
+          data: data
+        };
+      }
+    },
+
+    async dbHealthCheck(args, database) {
+      server.ensureConnected(database);
+      const { includeOrphanedPartitions = true } = args;
+
+      const health = {
+        success: true,
+        timestamp: new Date().toISOString(),
+        database: {
+          connected: database.isConnected(),
+          bucket: database.bucket,
+          keyPrefix: database.keyPrefix,
+          version: database.s3dbVersion
+        },
+        resources: {
+          total: Object.keys(database.resources || {}).length,
+          list: Object.keys(database.resources || {}),
+          details: {}
+        },
+        issues: []
+      };
+
+      // Check each resource
+      for (const [name, resource] of Object.entries(database.resources || {})) {
+        const resourceHealth = {
+          name,
+          behavior: resource.behavior,
+          attributeCount: Object.keys(resource.attributes || {}).length,
+          partitionCount: resource.config.partitions ? Object.keys(resource.config.partitions).length : 0
+        };
+
+        // Check for orphaned partitions
+        if (includeOrphanedPartitions && resource.findOrphanedPartitions) {
+          const orphaned = resource.findOrphanedPartitions();
+          if (Object.keys(orphaned).length > 0) {
+            resourceHealth.orphanedPartitions = orphaned;
+            health.issues.push({
+              severity: 'warning',
+              resource: name,
+              type: 'orphaned_partitions',
+              message: `Resource '${name}' has ${Object.keys(orphaned).length} orphaned partition(s)`,
+              details: orphaned
+            });
+          }
+        }
+
+        health.resources.details[name] = resourceHealth;
+      }
+
+      health.healthy = health.issues.length === 0;
+
+      return health;
+    },
+
+    async resourceGetRaw(args, database) {
+      server.ensureConnected(database);
+      const { resourceName, id } = args;
+      const resource = server.getResource(database, resourceName);
+
+      try {
+        // Build S3 key
+        const key = `${database.keyPrefix}resource=${resourceName}/id=${id}.json`;
+
+        const response = await database.client.getObject({
+          Bucket: database.bucket,
+          Key: key
+        });
+
+        const body = await response.Body.transformToString();
+        const bodyData = body ? JSON.parse(body) : null;
+
+        return {
+          success: true,
+          s3Object: {
+            key,
+            bucket: database.bucket,
+            metadata: response.Metadata || {},
+            contentLength: response.ContentLength,
+            lastModified: response.LastModified,
+            etag: response.ETag,
+            contentType: response.ContentType
+          },
+          data: {
+            metadata: response.Metadata,
+            body: bodyData
+          }
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message,
+          id,
+          resource: resourceName
+        };
+      }
+    }
+  };
+}

package/mcp/tools/export-import.js

@@ -0,0 +1,281 @@
+/**
+ * Export/Import Tools
+ * Handles data export (JSON, CSV, NDJSON), import, and metadata backup
+ */
+
+export const exportImportTools = [
+  {
+    name: 'resourceExport',
+    description: 'Export resource data to JSON, CSV, or NDJSON format',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource'
+        },
+        format: {
+          type: 'string',
+          description: 'Export format',
+          enum: ['json', 'ndjson', 'csv'],
+          default: 'json'
+        },
+        filters: {
+          type: 'object',
+          description: 'Optional filters to export subset of data'
+        },
+        fields: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Specific fields to export (exports all if not specified)'
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of records to export'
+        }
+      },
+      required: ['resourceName']
+    }
+  },
+  {
+    name: 'resourceImport',
+    description: 'Import data from JSON or NDJSON format into a resource',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resourceName: {
+          type: 'string',
+          description: 'Name of the resource'
+        },
+        data: {
+          type: 'array',
+          description: 'Array of documents to import'
+        },
+        mode: {
+          type: 'string',
+          description: 'Import mode',
+          enum: ['insert', 'upsert', 'replace'],
+          default: 'insert'
+        },
+        batchSize: {
+          type: 'number',
+          description: 'Batch size for bulk operations',
+          default: 100
+        }
+      },
+      required: ['resourceName', 'data']
+    }
+  },
+  {
+    name: 'dbBackupMetadata',
+    description: 'Create a backup of the metadata.json file',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        timestamp: {
+          type: 'boolean',
+          description: 'Include timestamp in backup name',
+          default: true
+        }
+      },
+      required: []
+    }
+  }
+];
+
+export function createExportImportHandlers(server) {
+  return {
+    async resourceExport(args, database) {
+      server.ensureConnected(database);
+      const { resourceName, format = 'json', filters, fields, limit } = args;
+      const resource = server.getResource(database, resourceName);
+
+      try {
+        // Get data
+        let data;
+        if (filters) {
+          data = await resource.query(filters, limit ? { limit } : {});
+        } else if (limit) {
+          data = await resource.list({ limit });
+        } else {
+          data = await resource.getAll();
+        }
+
+        // Filter fields if specified
+        if (fields && fields.length > 0) {
+          data = data.map(doc => {
+            const filtered = {};
+            for (const field of fields) {
+              if (doc[field] !== undefined) {
+                filtered[field] = doc[field];
+              }
+            }
+            return filtered;
+          });
+        }
+
+        let exportData;
+        let contentType;
+
+        switch (format) {
+          case 'json':
+            exportData = JSON.stringify(data, null, 2);
+            contentType = 'application/json';
+            break;
+
+          case 'ndjson':
+            exportData = data.map(doc => JSON.stringify(doc)).join('\n');
+            contentType = 'application/x-ndjson';
+            break;
+
+          case 'csv':
+            // Simple CSV conversion
+            if (data.length === 0) {
+              exportData = '';
+            } else {
+              const headers = Object.keys(data[0]);
+              const csvRows = [headers.join(',')];
+              for (const doc of data) {
+                const row = headers.map(h => {
+                  const val = doc[h];
+                  if (val === null || val === undefined) return '';
+                  if (typeof val === 'object') return JSON.stringify(val);
+                  return String(val).includes(',') ? `"${val}"` : val;
+                });
+                csvRows.push(row.join(','));
+              }
+              exportData = csvRows.join('\n');
+            }
+            contentType = 'text/csv';
+            break;
+
+          default:
+            throw new Error(`Unsupported format: ${format}`);
+        }
+
+        return {
+          success: true,
+          resource: resourceName,
+          format,
+          recordCount: data.length,
+          exportData,
+          contentType,
+          size: exportData.length
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message,
+          resource: resourceName,
+          format
+        };
+      }
+    },
+
+    async resourceImport(args, database) {
+      server.ensureConnected(database);
+      const { resourceName, data, mode = 'insert', batchSize = 100 } = args;
+      const resource = server.getResource(database, resourceName);
+
+      try {
+        const results = [];
+        let processed = 0;
+
+        // Process in batches
+        for (let i = 0; i < data.length; i += batchSize) {
+          const batch = data.slice(i, i + batchSize);
+
+          let batchResults;
+          switch (mode) {
+            case 'insert':
+              batchResults = await resource.insertMany(batch);
+              break;
+
+            case 'upsert':
+              batchResults = await Promise.all(batch.map(doc => resource.upsert(doc)));
+              break;
+
+            case 'replace':
+              // Delete all first if first batch
+              if (i === 0) {
+                await resource.deleteAll();
+              }
+              batchResults = await resource.insertMany(batch);
+              break;
+
+            default:
+              throw new Error(`Unsupported mode: ${mode}`);
+          }
+
+          results.push(...batchResults);
+          processed += batch.length;
+        }
+
+        return {
+          success: true,
+          resource: resourceName,
+          mode,
+          importedCount: results.length,
+          totalRecords: data.length,
+          batchSize
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message,
+          resource: resourceName,
+          mode,
+          processed
+        };
+      }
+    },
+
+    async dbBackupMetadata(args, database) {
+      server.ensureConnected(database);
+      const { timestamp = true } = args;
+
+      try {
+        const metadataKey = `${database.keyPrefix}metadata.json`;
+
+        // Read current metadata
+        const response = await database.client.getObject({
+          Bucket: database.bucket,
+          Key: metadataKey
+        });
+
+        const metadataContent = await response.Body.transformToString();
+
+        // Create backup key
+        const backupSuffix = timestamp ? `-backup-${Date.now()}` : '-backup';
+        const backupKey = metadataKey.replace('.json', `${backupSuffix}.json`);
+
+        // Save backup
+        await database.client.putObject({
+          Bucket: database.bucket,
+          Key: backupKey,
+          Body: metadataContent,
+          ContentType: 'application/json'
+        });
+
+        return {
+          success: true,
+          message: 'Metadata backup created',
+          backup: {
+            key: backupKey,
+            bucket: database.bucket,
+            timestamp: new Date().toISOString(),
+            size: metadataContent.length
+          },
+          original: {
+            key: metadataKey
+          }
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error.message
+        };
+      }
+    }
+  };
+}

package/mcp/tools/index.js

@@ -0,0 +1,67 @@
+/**
+ * MCP Tools Registry
+ * Exports all tool definitions and handlers organized by domain
+ */
+
+import { connectionTools, createConnectionHandlers } from './connection.js';
+import { resourceManagementTools, createResourceManagementHandlers } from './resources.js';
+import { crudTools, createCrudHandlers } from './crud.js';
+import { debuggingTools, createDebuggingHandlers } from './debugging.js';
+import { queryTools, createQueryHandlers } from './query.js';
+import { partitionTools, createPartitionHandlers } from './partitions.js';
+import { bulkTools, createBulkHandlers } from './bulk.js';
+import { exportImportTools, createExportImportHandlers } from './export-import.js';
+import { statsTools, createStatsHandlers } from './stats.js';
+
+/**
+ * Get all tool definitions
+ */
+export function getAllTools() {
+  return [
+    ...connectionTools,
+    ...resourceManagementTools,
+    ...crudTools,
+    ...debuggingTools,
+    ...queryTools,
+    ...partitionTools,
+    ...bulkTools,
+    ...exportImportTools,
+    ...statsTools
+  ];
+}
+
+/**
+ * Create all tool handlers
+ * @param {Object} server - Server instance with helper methods
+ * @returns {Object} Map of tool name -> handler function
+ */
+export function createAllHandlers(server) {
+  return {
+    ...createConnectionHandlers(server),
+    ...createResourceManagementHandlers(server),
+    ...createCrudHandlers(server),
+    ...createDebuggingHandlers(server),
+    ...createQueryHandlers(server),
+    ...createPartitionHandlers(server),
+    ...createBulkHandlers(server),
+    ...createExportImportHandlers(server),
+    ...createStatsHandlers(server)
+  };
+}
+
+/**
+ * Get tools organized by category
+ */
+export function getToolsByCategory() {
+  return {
+    connection: connectionTools,
+    resources: resourceManagementTools,
+    crud: crudTools,
+    debugging: debuggingTools,
+    query: queryTools,
+    partitions: partitionTools,
+    bulk: bulkTools,
+    exportImport: exportImportTools,
+    stats: statsTools
+  };
+}