s3db.js 11.2.5 → 11.3.1

package/mcp/README.md

@@ -0,0 +1,125 @@
+# 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

@@ -0,0 +1,120 @@
+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