s3db.js 11.2.6 → 11.3.1

package/mcp/Makefile

@@ -0,0 +1,162 @@
+# S3DB MCP Server Makefile
+
+.PHONY: help server server-v2 test test-simple test-interactive health tools minio clean
+
+# Default target
+help:
+	@echo "S3DB MCP Server Commands"
+	@echo "========================"
+	@echo ""
+	@echo "Server Commands:"
+	@echo "  make server        - Start original MCP server (SSE)"
+	@echo "  make server-v2     - Start refactored MCP server v2 (SSE)"
+	@echo "  make server-stdio  - Start server with stdio transport"
+	@echo ""
+	@echo "Test Commands:"
+	@echo "  make test          - Run automated tests"
+	@echo "  make test-simple   - Run simple HTTP tests"
+	@echo "  make test-mock     - Run tests with mock client"
+	@echo "  make test-interactive - Interactive test client"
+	@echo ""
+	@echo "Utility Commands:"
+	@echo "  make health        - Check server health"
+	@echo "  make tools         - List available tools"
+	@echo "  make minio         - Start MinIO for local testing"
+	@echo "  make clean         - Clean cache and temp files"
+	@echo ""
+	@echo "Docker Commands:"
+	@echo "  make docker-build  - Build Docker image"
+	@echo "  make docker-run    - Run in Docker container"
+	@echo "  make docker-compose - Start with docker-compose"
+
+# Server targets
+server:
+	@echo "Starting MCP Server (original)..."
+	@node server.js --transport=sse
+
+server-v2:
+	@echo "Starting MCP Server v2..."
+	@node server-v2.js --transport=sse
+
+server-stdio:
+	@echo "Starting MCP Server (stdio)..."
+	@node server-v2.js --transport=stdio
+
+# Test targets
+test:
+	@echo "Running automated tests..."
+	@node test-mcp-v2.js
+
+test-simple:
+	@echo "Running simple tests..."
+	@node test-simple.js
+
+test-mock:
+	@echo "Running tests with mock client..."
+	@node test-mcp-v2.js --mock
+
+test-interactive:
+	@echo "Starting interactive test client..."
+	@node test-mcp-v2.js --interactive
+
+# Utility targets
+health:
+	@echo "Checking server health..."
+	@curl -s http://localhost:8001/health | jq '.' || echo "Server not running"
+
+tools:
+	@echo "Listing available tools..."
+	@curl -s http://localhost:8001/tools | jq '.' || echo "Server not running"
+
+minio:
+	@echo "Starting MinIO..."
+	@docker run -d \
+		--name minio-s3db \
+		-p 9000:9000 \
+		-p 9001:9001 \
+		-e MINIO_ROOT_USER=minioadmin \
+		-e MINIO_ROOT_PASSWORD=minioadmin \
+		-v minio-data:/data \
+		minio/minio server /data --console-address ":9001"
+	@echo "MinIO started at http://localhost:9000 (console: http://localhost:9001)"
+	@echo "Credentials: minioadmin/minioadmin"
+
+minio-stop:
+	@echo "Stopping MinIO..."
+	@docker stop minio-s3db && docker rm minio-s3db
+
+# Docker targets
+docker-build:
+	@echo "Building Docker image..."
+	@docker build -t s3db-mcp-server .
+
+docker-run:
+	@echo "Running in Docker..."
+	@docker run -it --rm \
+		-p 8000:8000 \
+		-p 8001:8001 \
+		-e S3DB_CONNECTION=$${S3DB_CONNECTION} \
+		s3db-mcp-server
+
+docker-compose:
+	@echo "Starting with docker-compose..."
+	@docker-compose up -d
+
+docker-compose-down:
+	@echo "Stopping docker-compose..."
+	@docker-compose down
+
+# Clean target
+clean:
+	@echo "Cleaning cache and temp files..."
+	@rm -rf cache/
+	@rm -rf ./test-cache/
+	@rm -f *.log
+	@echo "Cleaned!"
+
+# Development targets
+dev:
+	@echo "Starting development environment..."
+	@make minio
+	@sleep 2
+	@make server-v2 &
+	@sleep 2
+	@make test-simple
+
+dev-stop:
+	@echo "Stopping development environment..."
+	@pkill -f "node server" || true
+	@make minio-stop
+
+# Watch for changes
+watch:
+	@echo "Watching for changes..."
+	@nodemon --watch lib --watch server-v2.js --exec "make server-v2"
+
+# Benchmark
+benchmark:
+	@echo "Running benchmarks..."
+	@node test-mcp-v2.js --benchmark
+
+# Installation
+install:
+	@echo "Installing dependencies..."
+	@pnpm install
+	@pnpm install -D @modelcontextprotocol/sdk nodemon
+
+# Environment setup
+setup:
+	@echo "Setting up environment..."
+	@cp .env.example .env 2>/dev/null || echo "No .env.example found"
+	@echo "S3DB_CONNECTION=s3://minioadmin:minioadmin@test-bucket?endpoint=http://localhost:9000&forcePathStyle=true" >> .env
+	@echo "MCP_TRANSPORT=sse" >> .env
+	@echo "MCP_SERVER_HOST=0.0.0.0" >> .env
+	@echo "MCP_SERVER_PORT=8000" >> .env
+	@echo "Environment setup complete!"
+
+# Combined targets
+all: install setup minio server-v2
+
+test-all: test-simple test-mock
+
+.DEFAULT_GOAL := help

package/mcp/NPX_SETUP.md

@@ -0,0 +1,327 @@
+# 🚀 NPX Setup - S3DB MCP Server
+
+Use o S3DB MCP Server diretamente com `npx` - sem precisar clonar o repositório!
+
+## ⚡ Quick Start (30 segundos)
+
+### Para Claude CLI
+
+```bash
+# Adicionar o MCP server
+claude mcp add s3db \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+Pronto! Agora você pode usar todas as 39 tools do S3DB no Claude CLI.
+
+### Para Claude Desktop
+
+Edite `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou equivalente:
+
+```json
+{
+  "mcpServers": {
+    "s3db": {
+      "command": "npx",
+      "args": ["-y", "s3db.js", "s3db-mcp", "--transport=sse"],
+      "env": {
+        "S3DB_CONNECTION_STRING": "s3://ACCESS_KEY:SECRET_KEY@bucket/databases/myapp",
+        "S3DB_CACHE_ENABLED": "true",
+        "S3DB_CACHE_DRIVER": "memory",
+        "S3DB_COSTS_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+## 🔧 Configurações Avançadas
+
+### Com variáveis de ambiente
+
+```bash
+claude mcp add s3db \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# Depois edite para adicionar env vars
+claude mcp edit s3db
+```
+
+Adicione:
+```json
+{
+  "s3db": {
+    "transport": "stdio",
+    "command": "npx",
+    "args": ["-y", "s3db.js", "s3db-mcp", "--transport=stdio"],
+    "env": {
+      "S3DB_CONNECTION_STRING": "s3://minioadmin:minioadmin123@localhost:9000/dev-bucket?forcePathStyle=true",
+      "S3DB_CACHE_ENABLED": "true",
+      "S3DB_CACHE_DRIVER": "memory",
+      "S3DB_CACHE_MAX_SIZE": "1000",
+      "S3DB_CACHE_TTL": "300000",
+      "S3DB_VERBOSE": "false",
+      "S3DB_COSTS_ENABLED": "true"
+    }
+  }
+}
+```
+
+### Servidor HTTP (background)
+
+```bash
+# Iniciar servidor em background
+npx s3db.js s3db-mcp --transport=sse &
+
+# Ou com PM2
+pm2 start "npx s3db.js s3db-mcp --transport=sse" --name s3db-mcp
+
+# Configurar Claude CLI para usar HTTP
+claude mcp add s3db --transport http http://localhost:17500/sse
+```
+
+### MCP Inspector (para testes)
+
+```bash
+# Inicie o inspector
+npx @modelcontextprotocol/inspector
+
+# Configure o comando:
+npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+## 🎯 Exemplos Práticos
+
+### Exemplo 1: Development Local (MinIO)
+
+```bash
+# 1. Configurar MCP
+claude mcp add s3db-dev \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# 2. Editar para adicionar MinIO
+claude mcp edit s3db-dev
+
+# 3. Adicionar:
+{
+  "env": {
+    "S3DB_CONNECTION_STRING": "s3://minioadmin:minioadmin123@localhost:9000/dev-bucket?forcePathStyle=true"
+  }
+}
+
+# 4. Testar
+claude
+
+# No chat:
+"Connect to the database and create a test resource"
+```
+
+### Exemplo 2: Production (AWS S3)
+
+```bash
+# 1. Configurar MCP com credenciais AWS
+claude mcp add s3db-prod \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# 2. Editar configuração
+claude mcp edit s3db-prod
+
+# 3. Adicionar credenciais seguras:
+{
+  "env": {
+    "S3DB_CONNECTION_STRING": "s3://prod-data-bucket/databases/main",
+    "AWS_ACCESS_KEY_ID": "AKIA...",
+    "AWS_SECRET_ACCESS_KEY": "...",
+    "AWS_REGION": "us-east-1",
+    "S3DB_CACHE_DRIVER": "filesystem",
+    "S3DB_CACHE_DIRECTORY": "/tmp/s3db-cache"
+  }
+}
+```
+
+### Exemplo 3: Múltiplos Ambientes
+
+```bash
+# Development
+claude mcp add s3db-dev \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# Staging
+claude mcp add s3db-staging \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# Production
+claude mcp add s3db-prod \
+  --transport stdio \
+  -- npx -y s3db.js s3db-mcp --transport=stdio
+
+# Ver todos
+claude mcp list
+```
+
+## 🧪 Testando a Instalação
+
+### 1. Verificar se o comando funciona
+
+```bash
+# Testar diretamente
+npx -y s3db.js s3db-mcp --help
+
+# Deve mostrar informações do servidor
+```
+
+### 2. Verificar configuração MCP
+
+```bash
+claude mcp list
+```
+
+Deve mostrar:
+```
+s3db - stdio://npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+### 3. Testar no Claude
+
+```bash
+claude
+```
+
+No chat:
+```
+"Can you show me the S3DB MCP server status and list available tools?"
+```
+
+## 🔍 Comandos Úteis
+
+```bash
+# Ver servidores configurados
+claude mcp list
+
+# Ver detalhes de um servidor
+claude mcp show s3db
+
+# Remover servidor
+claude mcp remove s3db
+
+# Editar configuração
+claude mcp edit s3db
+
+# Testar servidor diretamente
+npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+## 📊 Variáveis de Ambiente Disponíveis
+
+### Connection
+```bash
+S3DB_CONNECTION_STRING="s3://key:secret@bucket/path"
+AWS_ACCESS_KEY_ID="AKIA..."
+AWS_SECRET_ACCESS_KEY="..."
+AWS_REGION="us-east-1"
+```
+
+### Cache
+```bash
+S3DB_CACHE_ENABLED="true"
+S3DB_CACHE_DRIVER="memory"          # ou "filesystem"
+S3DB_CACHE_MAX_SIZE="1000"          # apenas para memory
+S3DB_CACHE_TTL="300000"             # 5 minutos em ms
+S3DB_CACHE_DIRECTORY="./cache"      # apenas para filesystem
+S3DB_CACHE_PREFIX="s3db"
+```
+
+### Server
+```bash
+MCP_TRANSPORT="sse"                 # ou "stdio"
+MCP_SERVER_HOST="0.0.0.0"
+MCP_SERVER_PORT="17500"
+NODE_ENV="production"               # ou "development"
+```
+
+### S3DB Core
+```bash
+S3DB_VERBOSE="false"
+S3DB_PARALLELISM="10"
+S3DB_PASSPHRASE="secret"
+S3DB_VERSIONING_ENABLED="false"
+S3DB_COSTS_ENABLED="true"
+```
+
+## 🐛 Troubleshooting
+
+### Erro: "command not found: npx"
+
+```bash
+# Instalar Node.js/npm primeiro
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install --lts
+```
+
+### Erro: "package not found: s3db.js"
+
+```bash
+# Verificar se o pacote existe
+npm view s3db.js
+
+# Usar versão específica
+npx s3db.js@latest s3db-mcp --transport=stdio
+```
+
+### Erro: "Database not connected"
+
+No chat do Claude, sempre conecte primeiro:
+```
+"Please connect to the database using dbConnect with connection string: s3://..."
+```
+
+### Servidor não responde
+
+```bash
+# Verificar se está rodando
+ps aux | grep s3db-mcp
+
+# Matar processos antigos
+pkill -f s3db-mcp
+
+# Reiniciar
+npx -y s3db.js s3db-mcp --transport=sse
+```
+
+### Ver logs detalhados
+
+```bash
+# Ativar verbose mode
+S3DB_VERBOSE=true npx -y s3db.js s3db-mcp --transport=stdio
+```
+
+## 🎉 Vantagens do npx
+
+✅ **Sem instalação** - não precisa clonar o repo
+✅ **Sempre atualizado** - usa a última versão publicada
+✅ **Fácil de compartilhar** - um comando funciona para todos
+✅ **Zero configuração** - funciona out-of-the-box
+✅ **Multi-ambiente** - configure dev/staging/prod facilmente
+
+## 📚 Recursos
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [S3DB Documentation](../README.md)
+- [Full MCP Guide](../docs/mcp.md)
+- [Claude CLI](https://docs.claude.com/en/docs/claude-code)
+- [NPM Package](https://www.npmjs.com/package/s3db.js)
+
+## ⚡ One-Liner Setup
+
+```bash
+# Tudo em um comando:
+claude mcp add s3db --transport stdio -- npx -y s3db.js s3db-mcp --transport=stdio && echo "✅ S3DB MCP Server configured! Type 'claude' to start."
+```
+
+Pronto! Agora você pode usar `npx s3db.js s3db-mcp` de qualquer lugar! 🚀