s3db.js 11.3.1 → 12.0.0

package/mcp/examples/test-mcp.js

@@ -1,433 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * S3DB MCP Server Test Script
- * 
- * This script demonstrates how to test the S3DB MCP server functionality
- * by making direct tool calls and showing the expected responses.
- */
-
-import { createRequire } from 'module';
-const require = createRequire(import.meta.url);
-
-// Mock MCP client for testing
-class MockMCPClient {
-  constructor(serverUrl) {
-    this.serverUrl = serverUrl;
-    this.tools = [];
-  }
-
-  async initialize() {
-    console.log('🔌 Initializing MCP Client...');
-    console.log(`📡 Server URL: ${this.serverUrl}`);
-    
-    // In a real implementation, this would connect to the MCP server
-    // and fetch the available tools
-    this.tools = [
-      'dbConnect', 'dbDisconnect', 'dbStatus', 'dbCreateResource', 'dbListResources', 'dbGetStats', 'dbClearCache',
-      'resourceInsert', 'resourceGet', 'resourceUpdate', 'resourceDelete', 'resourceList'
-    ];
-    
-    console.log(`✅ Found ${this.tools.length} available tools`);
-    return this.tools;
-  }
-
-  async callTool(name, args = {}) {
-    console.log(`\n🔧 Calling tool: ${name}`);
-    console.log(`📥 Arguments:`, JSON.stringify(args, null, 2));
-    
-    // Mock successful responses for demonstration
-    const mockResponses = {
-      dbConnect: {
-        success: true,
-        message: 'Connected to S3DB database',
-        status: {
-          connected: true,
-          bucket: 'test-bucket',
-          keyPrefix: 'databases/test',
-          version: '7.2.1'
-        }
-      },
-      
-      dbStatus: {
-        connected: true,
-        bucket: 'test-bucket', 
-        keyPrefix: 'databases/test',
-        version: '7.2.1',
-        resourceCount: 2,
-        resources: ['users', 'posts']
-      },
-      
-      dbCreateResource: {
-        success: true,
-        resource: {
-          name: args.name,
-          behavior: args.behavior || 'user-managed',
-          attributes: args.attributes,
-          partitions: args.partitions || {},
-          timestamps: args.timestamps || false
-        }
-      },
-      
-      dbListResources: {
-        success: true,
-        resources: [
-          { name: 'users' },
-          { name: 'posts' }
-        ],
-        count: 2
-      },
-      
-      resourceInsert: {
-        success: true,
-        data: {
-          id: 'doc_' + Math.random().toString(36).substr(2, 9),
-          ...args.data,
-          createdAt: new Date().toISOString(),
-          updatedAt: new Date().toISOString()
-        }
-      },
-      
-      resourceGet: {
-        success: true,
-        data: {
-          id: args.id,
-          name: 'John Doe',
-          email: 'john@example.com',
-          createdAt: '2024-01-15T10:30:00Z',
-          updatedAt: '2024-01-15T10:30:00Z'
-        }
-      },
-      
-      resourceList: {
-        success: true,
-        data: [
-          {
-            id: 'doc_123',
-            name: 'John Doe',
-            email: 'john@example.com',
-            createdAt: '2024-01-15T10:30:00Z'
-          },
-          {
-            id: 'doc_456', 
-            name: 'Jane Smith',
-            email: 'jane@example.com',
-            createdAt: '2024-01-15T11:30:00Z'
-          }
-        ],
-        count: 2,
-        pagination: {
-          limit: args.limit || 100,
-          offset: args.offset || 0,
-          hasMore: false
-        }
-      },
-      
-      resourceCount: {
-        success: true,
-        count: 42,
-        resource: args.resourceName
-      },
-      
-      dbGetStats: {
-        success: true,
-        stats: {
-          database: {
-            connected: true,
-            bucket: 'test-bucket',
-            keyPrefix: 'databases/test',
-            version: '7.2.1',
-            resourceCount: 2,
-            resources: ['users', 'posts']
-          },
-          costs: {
-            total: 0.000042,
-            totalRequests: 156,
-            requestsByType: { get: 89, put: 45, list: 12, delete: 10 },
-            eventsByType: { GetObjectCommand: 89, PutObjectCommand: 45 },
-            estimatedCostUSD: 0.000042
-          },
-          cache: {
-            enabled: true,
-            driver: 'FilesystemCache',
-            size: 23,
-            directory: './test-cache',
-            ttl: 300000,
-            keyCount: 23,
-            sampleKeys: ['resource=users/action=list.json.gz', 'resource=posts/action=count.json.gz']
-          }
-        }
-      },
-      
-      dbClearCache: {
-        success: true,
-        message: args.resourceName 
-          ? `Cache cleared for resource: ${args.resourceName}`
-          : 'All cache cleared'
-      }
-    };
-    
-    const response = mockResponses[name] || { success: false, error: 'Tool not found' };
-    
-    console.log(`📤 Response:`, JSON.stringify(response, null, 2));
-    return response;
-  }
-}
-
-// Test scenarios
-async function runTests() {
-  console.log('🧪 S3DB MCP Server Test Suite');
-  console.log('================================\n');
-
-  const client = new MockMCPClient('http://localhost:8000/sse');
-  
-  try {
-    // Initialize client
-    await client.initialize();
-    
-    // Test 1: Connect to database
-    console.log('\n📋 Test 1: Database Connection');
-    console.log('-------------------------------');
-    await client.callTool('dbConnect', {
-      connectionString: 's3://test-key:test-secret@test-bucket/databases/demo',
-      verbose: false,
-      parallelism: 10,
-      enableCache: true,
-      enableCosts: true,
-      cacheDriver: 'filesystem', // Test filesystem cache
-      cacheDirectory: './test-cache',
-      cachePrefix: 'test',
-      cacheTtl: 300000
-    });
-    
-    // Test 2: Check database status
-    console.log('\n📋 Test 2: Database Status');
-    console.log('---------------------------');
-    await client.callTool('dbStatus');
-    
-    // Test 3: Create a resource
-    console.log('\n📋 Test 3: Create Resource');
-    console.log('---------------------------');
-    await client.callTool('dbCreateResource', {
-      name: 'users',
-      attributes: {
-        name: 'string|required',
-        email: 'email|required|unique',
-        age: 'number|positive',
-        profile: {
-          bio: 'string|optional',
-          avatar: 'url|optional'
-        }
-      },
-      behavior: 'user-managed',
-      timestamps: true,
-      partitions: {
-        byAge: {
-          fields: { ageGroup: 'string' }
-        }
-      }
-    });
-    
-    // Test 4: List resources
-    console.log('\n📋 Test 4: List Resources');
-    console.log('--------------------------');
-    await client.callTool('dbListResources');
-    
-    // Test 5: Insert data
-    console.log('\n📋 Test 5: Insert Document');
-    console.log('---------------------------');
-    await client.callTool('resourceInsert', {
-      resourceName: 'users',
-      data: {
-        name: 'John Doe',
-        email: 'john@example.com',
-        age: 30,
-        profile: {
-          bio: 'Software developer and AI enthusiast',
-          avatar: 'https://example.com/avatar.jpg'
-        }
-      }
-    });
-    
-    // Test 6: Get document
-    console.log('\n📋 Test 6: Get Document');
-    console.log('------------------------');
-    await client.callTool('resourceGet', {
-      resourceName: 'users',
-      id: 'doc_123'
-    });
-    
-    // Test 7: List documents
-    console.log('\n📋 Test 7: List Documents');
-    console.log('--------------------------');
-    await client.callTool('resourceList', {
-      resourceName: 'users',
-      limit: 10,
-      offset: 0
-    });
-    
-         // Test 8: Count documents
-     console.log('\n📋 Test 8: Count Documents');
-     console.log('---------------------------');
-     await client.callTool('resourceCount', {
-       resourceName: 'users'
-     });
-     
-     // Test 9: Get database statistics
-     console.log('\n📋 Test 9: Database Statistics');
-     console.log('-------------------------------');
-     await client.callTool('dbGetStats');
-     
-     // Test 10: Clear cache
-     console.log('\n📋 Test 10: Clear Cache');
-     console.log('------------------------');
-     await client.callTool('dbClearCache', {
-       resourceName: 'users'
-     });
-     
-     console.log('\n✅ All tests completed successfully!');
-     console.log('\n💡 To run against a real S3DB MCP server:');
-     console.log('   1. Start the server: npm start');
-     console.log('   2. Configure your .env file');
-     console.log('   3. Use a real MCP client to connect');
-    
-  } catch (error) {
-    console.error('\n❌ Test failed:', error.message);
-    process.exit(1);
-  }
-}
-
-// Real MCP client example (commented out - requires actual MCP client library)
-async function realMCPExample() {
-  console.log('\n🔗 Real MCP Client Example');
-  console.log('===========================');
-  
-  console.log(`
-This is how you would connect to a real S3DB MCP server:
-
-import { MCPClient } from '@modelcontextprotocol/client';
-
-const client = new MCPClient({
-  transport: 'sse',
-  url: 'http://localhost:8000/sse'
-});
-
-await client.connect();
-
-// Connect to S3DB
-const result = await client.callTool('dbConnect', {
-  connectionString: process.env.S3DB_CONNECTION_STRING
-});
-
-// Create a resource
-await client.callTool('dbCreateResource', {
-  name: 'products',
-  attributes: {
-    name: 'string|required',
-    price: 'number|positive|required',
-    category: 'string|required'
-  },
-  timestamps: true
-});
-
-// Insert data
-await client.callTool('resourceInsert', {
-  resourceName: 'products',
-  data: {
-    name: 'Laptop Pro',
-    price: 1299.99,
-    category: 'electronics'
-  }
-});
-  `);
-}
-
-// Configuration examples
-function showConfigurationExamples() {
-  console.log('\n⚙️  Configuration Examples');
-  console.log('===========================');
-  
-  console.log(`
-# AWS S3 Configuration
-S3DB_CONNECTION_STRING=s3://ACCESS_KEY:SECRET_KEY@bucket/databases/myapp
-
-# MinIO Configuration (local development)
-S3DB_CONNECTION_STRING=s3://minioadmin:minioadmin@test-bucket/databases/dev?endpoint=http://localhost:9000&forcePathStyle=true
-
-# DigitalOcean Spaces Configuration
-S3DB_CONNECTION_STRING=s3://DO_KEY:DO_SECRET@space-name/databases/prod?endpoint=https://nyc3.digitaloceanspaces.com
-
-# Claude Desktop Configuration (claude_desktop_config.json)
-{
-  "mcpServers": {
-    "s3db": {
-      "transport": "sse",
-      "url": "http://localhost:8000/sse"
-    }
-  }
-}
-
-# Cursor IDE Configuration
-{
-  "mcpServers": {
-    "s3db": {
-      "url": "http://localhost:8000/sse"
-    }
-  }
-}
-  `);
-}
-
-// Main execution
-async function main() {
-  const args = process.argv.slice(2);
-  
-  if (args.includes('--help') || args.includes('-h')) {
-    console.log(`
-S3DB MCP Server Test Script
-
-Usage:
-  node test-mcp.js [options]
-
-Options:
-  --help, -h     Show this help message
-  --config       Show configuration examples
-  --real         Show real MCP client examples
-
-Examples:
-  node test-mcp.js              # Run mock tests
-  node test-mcp.js --config     # Show configuration examples
-  node test-mcp.js --real       # Show real client examples
-    `);
-    return;
-  }
-  
-  if (args.includes('--config')) {
-    showConfigurationExamples();
-    return;
-  }
-  
-  if (args.includes('--real')) {
-    await realMCPExample();
-    return;
-  }
-  
-  // Run the test suite
-  await runTests();
-}
-
-// Handle errors
-process.on('unhandledRejection', (error) => {
-  console.error('❌ Unhandled rejection:', error);
-  process.exit(1);
-});
-
-process.on('uncaughtException', (error) => {
-  console.error('❌ Uncaught exception:', error);
-  process.exit(1);
-});
-
-// Run main function
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
-}

package/mcp/package.json

@@ -1,66 +0,0 @@
-{
-  "name": "s3db-mcp-server",
-  "version": "1.0.0",
-  "description": "Model Context Protocol (MCP) server for S3DB - Transform AWS S3 into a powerful document database",
-  "type": "module",
-  "main": "s3db_mcp_server.js",
-  "bin": {
-    "s3db-mcp": "./s3db_mcp_server.js"
-  },
-  "scripts": {
-    "start": "node s3db_mcp_server.js",
-    "start:sse": "node s3db_mcp_server.js --transport=sse",
-    "start:stdio": "node s3db_mcp_server.js --transport=stdio",
-    "dev": "node --watch s3db_mcp_server.js --transport=sse",
-    "docker:build": "docker build -t s3db-mcp-server .",
-    "docker:run": "docker run -p 8000:8000 --env-file .env s3db-mcp-server",
-    "docker:compose": "docker compose up",
-    "docker:compose:build": "docker compose up --build",
-    "test": "echo 'Tests coming soon!' && exit 0"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "s3db",
-    "s3",
-    "aws",
-    "database",
-    "document-database",
-    "ai-agent",
-    "llm"
-  ],
-  "author": "S3DB Community",
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/forattini-dev/s3db.js.git",
-    "directory": "mcp-server"
-  },
-  "bugs": {
-    "url": "https://github.com/forattini-dev/s3db.js/issues"
-  },
-  "homepage": "https://github.com/forattini-dev/s3db.js/tree/main/mcp-server#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "s3db.js": "^7.2.1",
-    "dotenv": "^16.4.5"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0"
-  },
-  "files": [
-    "s3db_mcp_server.js",
-    "README.md",
-    "Dockerfile",
-    "docker-compose.yml",
-    ".env.example",
-    "Makefile",
-    "examples/"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
-}

package/src/partition-drivers/base-partition-driver.js

@@ -1,106 +0,0 @@
-import { EventEmitter } from 'events';
-import { PartitionDriverError } from '../errors.js';
-
-/**
- * Base class for all partition drivers
- * Defines the interface that all drivers must implement
- */
-export class BasePartitionDriver extends EventEmitter {
-  constructor(options = {}) {
-    super();
-    this.options = options;
-    this.stats = {
-      queued: 0,
-      processed: 0,
-      failed: 0,
-      processing: 0
-    };
-  }
-
-  /**
-   * Initialize the driver
-   */
-  async initialize() {
-    // Override in subclasses if needed
-  }
-
-  /**
-   * Queue partition operations for processing
-   * @param {Object} operation - The partition operation to queue
-   * @param {string} operation.type - 'create', 'update', or 'delete'
-   * @param {Object} operation.resource - The resource instance
-   * @param {Object} operation.data - The data for the operation
-   */
-  async queue(operation) {
-    throw new PartitionDriverError('queue() must be implemented by subclass', {
-      driver: this.name || 'BasePartitionDriver',
-      operation: 'queue',
-      suggestion: 'Extend BasePartitionDriver and implement the queue() method'
-    });
-  }
-
-  /**
-   * Process a single partition operation
-   */
-  async processOperation(operation) {
-    const { type, resource, data } = operation;
-    
-    try {
-      this.stats.processing++;
-      
-      switch (type) {
-        case 'create':
-          await resource.createPartitionReferences(data.object);
-          break;
-          
-        case 'update':
-          await resource.handlePartitionReferenceUpdates(data.original, data.updated);
-          break;
-          
-        case 'delete':
-          await resource.deletePartitionReferences(data.object);
-          break;
-          
-        default:
-          throw new PartitionDriverError(`Unknown partition operation type: ${type}`, {
-            driver: this.name || 'BasePartitionDriver',
-            operation: type,
-            availableOperations: ['create', 'update', 'delete'],
-            suggestion: 'Use one of the supported partition operations: create, update, or delete'
-          });
-      }
-      
-      this.stats.processed++;
-      this.emit('processed', operation);
-      
-    } catch (error) {
-      this.stats.failed++;
-      this.emit('error', { operation, error });
-      throw error;
-    } finally {
-      this.stats.processing--;
-    }
-  }
-
-  /**
-   * Flush any pending operations
-   */
-  async flush() {
-    // Override in subclasses if needed
-  }
-
-  /**
-   * Get driver statistics
-   */
-  getStats() {
-    return { ...this.stats };
-  }
-
-  /**
-   * Shutdown the driver
-   */
-  async shutdown() {
-    await this.flush();
-    this.removeAllListeners();
-  }
-}

package/src/partition-drivers/index.js

@@ -1,66 +0,0 @@
-import { SyncPartitionDriver } from './sync-partition-driver.js';
-import { MemoryPartitionDriver } from './memory-partition-driver.js';
-import { SQSPartitionDriver } from './sqs-partition-driver.js';
-import { PartitionDriverError } from '../errors.js';
-
-/**
- * Partition driver factory
- */
-export class PartitionDriverFactory {
-  static drivers = {
-    sync: SyncPartitionDriver,
-    memory: MemoryPartitionDriver,
-    sqs: SQSPartitionDriver
-  };
-
-  /**
-   * Create a partition driver instance
-   * @param {string|Object} config - Driver name or configuration object
-   * @returns {BasePartitionDriver} Driver instance
-   */
-  static create(config) {
-    // Handle string shorthand
-    if (typeof config === 'string') {
-      config = { driver: config };
-    }
-    
-    // Default to memory driver
-    const driverName = config.driver || 'memory';
-    
-    // Get driver class
-    const DriverClass = this.drivers[driverName];
-    if (!DriverClass) {
-      throw new PartitionDriverError(`Unknown partition driver: ${driverName}`, {
-        driver: driverName,
-        operation: 'create',
-        availableDrivers: Object.keys(this.drivers),
-        suggestion: `Use one of the available drivers: ${Object.keys(this.drivers).join(', ')}, or register a custom driver`
-      });
-    }
-    
-    // Create and initialize driver
-    const driver = new DriverClass(config);
-    
-    return driver;
-  }
-
-  /**
-   * Register a custom driver
-   */
-  static register(name, DriverClass) {
-    this.drivers[name] = DriverClass;
-  }
-
-  /**
-   * Get available driver names
-   */
-  static getAvailableDrivers() {
-    return Object.keys(this.drivers);
-  }
-}
-
-// Export individual drivers
-export { BasePartitionDriver } from './base-partition-driver.js';
-export { SyncPartitionDriver } from './sync-partition-driver.js';
-export { MemoryPartitionDriver } from './memory-partition-driver.js';
-export { SQSPartitionDriver } from './sqs-partition-driver.js';