s3db.js 11.3.1 → 11.3.2

package/mcp/README.md

@@ -1,125 +0,0 @@
-# S3DB MCP Server
-
-> **Complete documentation has been moved to [`docs/mcp.md`](../docs/mcp.md)**
-
-## ⚡ Quick Start with npx (Recommended)
-
-### For Claude CLI
-```bash
-# One command setup - no installation needed!
-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/path"
-      }
-    }
-  }
-}
-```
-
-### Standalone Server
-```bash
-# Start HTTP server in background
-npx s3db.js s3db-mcp --transport=sse
-```
-
-📖 **See [NPX_SETUP.md](./NPX_SETUP.md) for complete npx guide**
-
-## Claude Desktop Configuration
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "s3db": {
-      "command": "npx",
-      "args": ["s3db-mcp-server", "--transport=sse"],
-      "env": {
-        "S3DB_CONNECTION_STRING": "s3://ACCESS_KEY:SECRET_KEY@bucket/databases/myapp",
-        "S3DB_CACHE_ENABLED": "true",
-        "S3DB_COSTS_ENABLED": "true"
-      }
-    }
-  }
-}
-```
-
-## Available Tools (28 total)
-
-### 🔌 Connection Management
-- `dbConnect`, `dbDisconnect`, `dbStatus`
-
-### 📦 Resource Management
-- `dbCreateResource`, `dbListResources`, `dbInspectResource`
-
-### 🔍 Debugging Tools
-- `dbGetMetadata`, `resourceValidate`, `dbHealthCheck`, `resourceGetRaw`
-
-### 📊 Query & Filtering
-- `resourceQuery`, `resourceSearch`, `resourceList`, `resourceCount`
-
-### 🔧 Partition Management
-- `resourceListPartitions`, `resourceListPartitionValues`
-- `dbFindOrphanedPartitions`, `dbRemoveOrphanedPartitions`
-
-### ✏️ CRUD Operations
-- `resourceInsert`, `resourceInsertMany`, `resourceGet`, `resourceGetMany`
-- `resourceUpdate`, `resourceUpsert`, `resourceDelete`, `resourceDeleteMany`
-
-### 🚀 Bulk Operations
-- `resourceUpdateMany`, `resourceBulkUpsert`, `resourceDeleteAll`
-
-### 💾 Export/Import
-- `resourceExport`, `resourceImport`, `dbBackupMetadata`
-
-### 📈 Monitoring
-- `dbGetStats`, `resourceGetStats`, `cacheGetStats`, `dbClearCache`
-
-## Full Documentation
-
-For complete documentation including:
-- Detailed tool descriptions and parameters
-- Configuration examples for AWS, MinIO, DigitalOcean
-- Docker deployment guides
-- Performance optimization tips
-- Troubleshooting guides
-- Security best practices
-
-**See [`docs/mcp.md`](../docs/mcp.md)**
-
-## Environment Variables
-
-```bash
-# Connection
-S3DB_CONNECTION_STRING=s3://key:secret@bucket/prefix
-
-# Cache
-S3DB_CACHE_ENABLED=true
-S3DB_CACHE_DRIVER=memory  # or 'filesystem'
-S3DB_CACHE_MAX_SIZE=1000
-S3DB_CACHE_TTL=300000
-
-# Server
-MCP_TRANSPORT=sse
-MCP_SERVER_HOST=0.0.0.0
-MCP_SERVER_PORT=17500
-```
-
-## Resources
-
-- [Full MCP Documentation](../docs/mcp.md)
-- [S3DB Documentation](../README.md)
-- [GitHub Repository](https://github.com/forattini-dev/s3db.js)
-- [NPM Package](https://www.npmjs.com/package/s3db.js)

package/mcp/docker-compose.yml

@@ -1,120 +0,0 @@
-services:
-  s3db-mcp-server:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: s3db-mcp-server:latest
-    container_name: s3db-mcp-server
-    restart: unless-stopped
-    env_file:
-      - path: .env
-        required: false # Makes the file optional
-    environment:
-      # Server configuration
-      - NODE_ENV=${NODE_ENV:-production}
-      - MCP_SERVER_HOST=${MCP_SERVER_HOST:-0.0.0.0}
-      - MCP_SERVER_PORT=${MCP_SERVER_PORT:-17500}
-      - MCP_TRANSPORT=${MCP_TRANSPORT:-sse}
-      
-      # S3DB configuration
-      - S3DB_CONNECTION_STRING=${S3DB_CONNECTION_STRING}
-      - S3DB_VERBOSE=${S3DB_VERBOSE:-false}
-      - S3DB_PARALLELISM=${S3DB_PARALLELISM:-10}
-      - S3DB_PASSPHRASE=${S3DB_PASSPHRASE:-secret}
-      - S3DB_VERSIONING_ENABLED=${S3DB_VERSIONING_ENABLED:-false}
-      
-      # Plugin configuration
-      - S3DB_COSTS_ENABLED=${S3DB_COSTS_ENABLED:-true}
-      - S3DB_CACHE_ENABLED=${S3DB_CACHE_ENABLED:-true}
-      - S3DB_CACHE_DRIVER=${S3DB_CACHE_DRIVER:-memory}
-      - S3DB_CACHE_MAX_SIZE=${S3DB_CACHE_MAX_SIZE:-1000}
-      - S3DB_CACHE_TTL=${S3DB_CACHE_TTL:-300000}
-      - S3DB_CACHE_DIRECTORY=${S3DB_CACHE_DIRECTORY:-./cache}
-      - S3DB_CACHE_PREFIX=${S3DB_CACHE_PREFIX:-s3db}
-      
-      # AWS credentials (optional if using IAM roles)
-      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
-      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
-      - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN}
-      - AWS_REGION=${AWS_REGION:-us-east-1}
-      
-      # S3-compatible endpoints (MinIO, DigitalOcean, etc.)
-      - S3_ENDPOINT=${S3_ENDPOINT}
-      - S3_FORCE_PATH_STYLE=${S3_FORCE_PATH_STYLE:-false}
-    ports:
-      - "${MCP_SERVER_PORT:-17500}:8000"
-    volumes:
-      # Mount for configuration files if needed
-      - type: bind
-        source: ./config
-        target: /app/config
-      # Mount cache directory for filesystem cache persistence
-      - type: bind
-        source: ./cache-data
-        target: /app/cache
-        bind:
-          create_host_path: true
-    networks:
-      - s3db-mcp-network
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8001/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    logging:
-      driver: "json-file"
-      options:
-        max-size: "10m"
-        max-file: "3"
-
-  # Optional: LocalStack for local S3 testing
-  localstack:
-    image: localstack/localstack:3.8
-    container_name: s3db-localstack
-    restart: unless-stopped
-    environment:
-      - SERVICES=s3
-      - DEBUG=1
-      - DATA_DIR=/tmp/localstack/data
-      - DOCKER_HOST=unix:///var/run/docker.sock
-      - DEFAULT_REGION=us-east-1
-    ports:
-      - "17566:4566"
-      - "17510-17559:4510-4559"
-    volumes:
-      - "localstack-data:/tmp/localstack"
-      - "/var/run/docker.sock:/var/run/docker.sock"
-    networks:
-      - s3db-mcp-network
-    profiles:
-      - local-testing
-
-  # Optional: MinIO for local S3-compatible testing
-  minio:
-    image: minio/minio:latest
-    container_name: s3db-minio
-    restart: unless-stopped
-    environment:
-      - MINIO_ROOT_USER=${MINIO_ROOT_USER:-minioadmin}
-      - MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD:-minioadmin}
-    command: server /data --console-address ":9001"
-    ports:
-      - "17998:9000"
-      - "17999:9001"
-    volumes:
-      - "minio-data:/data"
-    networks:
-      - s3db-mcp-network
-    profiles:
-      - local-testing
-
-networks:
-  s3db-mcp-network:
-    driver: bridge
-
-volumes:
-  localstack-data:
-    driver: local
-  minio-data:
-    driver: local

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

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