s3db.js 11.2.5 → 11.3.1

package/mcp/examples/test-filesystem-cache.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Test script to demonstrate FilesystemCache functionality
+ * This tests the cache directly without the full MCP server
+ */
+
+import { FilesystemCache } from '../src/plugins/cache/filesystem-cache.class.js';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function testFilesystemCache() {
+  console.log('🧪 Testing FilesystemCache Implementation');
+  console.log('=========================================\n');
+
+  const cacheDir = path.join(__dirname, '../test-cache-demo');
+  
+  // Create cache instance
+  const cache = new FilesystemCache({
+    directory: cacheDir,
+    prefix: 'demo',
+    ttl: 10000, // 10 seconds for quick testing
+    enableCompression: true,
+    enableStats: true,
+    enableCleanup: true,
+    cleanupInterval: 5000, // 5 seconds for quick testing
+    createDirectory: true
+  });
+
+  console.log('📁 Cache directory:', cacheDir);
+  console.log('⚙️ Configuration:', {
+    ttl: '10 seconds',
+    compression: 'enabled',
+    cleanup: 'enabled (5s interval)'
+  });
+  console.log();
+
+  try {
+    // Test 1: Set some cache data
+    console.log('📝 Test 1: Setting cache data');
+    await cache.set('user:123', { 
+      id: 123, 
+      name: 'John Doe', 
+      email: 'john@example.com',
+      profile: { bio: 'Software developer', avatar: 'https://example.com/avatar.jpg' }
+    });
+    await cache.set('user:456', { 
+      id: 456, 
+      name: 'Jane Smith', 
+      email: 'jane@example.com' 
+    });
+    await cache.set('config:app', { 
+      theme: 'dark', 
+      language: 'en', 
+      notifications: true 
+    });
+    console.log('✅ Set 3 cache entries');
+    console.log();
+
+    // Test 2: Get cache data
+    console.log('📖 Test 2: Getting cache data');
+    const user123 = await cache.get('user:123');
+    const user456 = await cache.get('user:456');
+    const config = await cache.get('config:app');
+    console.log('✅ User 123:', user123?.name);
+    console.log('✅ User 456:', user456?.name);
+    console.log('✅ Config theme:', config?.theme);
+    console.log();
+
+    // Test 3: Cache size and keys
+    console.log('📊 Test 3: Cache statistics');
+    const size = await cache.size();
+    const keys = await cache.keys();
+    console.log('✅ Cache size:', size);
+    console.log('✅ Cache keys:', keys);
+    console.log();
+
+    // Test 4: Cache stats
+    console.log('📈 Test 4: Cache performance stats');
+    const stats = cache.getStats();
+    console.log('✅ Statistics:', {
+      hits: stats.hits,
+      misses: stats.misses,
+      sets: stats.sets,
+      directory: stats.directory,
+      compression: stats.compression
+    });
+    console.log();
+
+    // Test 5: Non-existent key
+    console.log('❓ Test 5: Getting non-existent key');
+    const notFound = await cache.get('user:999');
+    console.log('✅ Non-existent key result:', notFound);
+    console.log();
+
+    // Test 6: Clear specific key
+    console.log('🗑️ Test 6: Deleting specific key');
+    await cache.del('user:456');
+    const deletedUser = await cache.get('user:456');
+    console.log('✅ Deleted user result:', deletedUser);
+    console.log();
+
+    // Test 7: Wait for TTL expiration
+    console.log('⏱️ Test 7: Waiting for TTL expiration (10 seconds)...');
+    console.log('   This demonstrates automatic cleanup of expired files');
+    
+    // Wait 12 seconds to ensure TTL expiration
+    await new Promise(resolve => setTimeout(resolve, 12000));
+    
+    const expiredUser = await cache.get('user:123');
+    const expiredConfig = await cache.get('config:app');
+    console.log('✅ Expired user (should be null):', expiredUser);
+    console.log('✅ Expired config (should be null):', expiredConfig);
+    console.log();
+
+    // Test 8: Final cache state
+    console.log('📊 Test 8: Final cache state');
+    const finalSize = await cache.size();
+    const finalKeys = await cache.keys();
+    console.log('✅ Final cache size:', finalSize);
+    console.log('✅ Final cache keys:', finalKeys);
+    console.log();
+
+    // Test 9: Clear all cache
+    console.log('🧹 Test 9: Clearing all cache');
+    await cache.clear();
+    const clearedSize = await cache.size();
+    console.log('✅ Cache size after clear:', clearedSize);
+    console.log();
+
+    // Cleanup
+    cache.destroy();
+    console.log('✅ All FilesystemCache tests completed successfully!');
+    console.log('🗂️ Check the cache directory for any remaining files:', cacheDir);
+
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+// Run the test
+testFilesystemCache().catch(console.error);

package/mcp/examples/test-mcp.js

@@ -0,0 +1,433 @@
+#!/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

@@ -0,0 +1,66 @@
+{
+  "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"
+  }
+}