s3db.js 11.3.1 → 11.3.2

package/mcp/NPX_SETUP.md

@@ -1,327 +0,0 @@
-# 🚀 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! 🚀

package/mcp/PUBLISHING.md

@@ -1,281 +0,0 @@
-# 📦 Publishing S3DB MCP Server to NPM
-
-Este guia garante que o MCP server funcione perfeitamente com `npx` após publicação no NPM.
-
-## ✅ Checklist Pré-Publicação
-
-### 1. Build & Tests
-```bash
-# Build do projeto
-pnpm run build
-
-# Rodar testes rápidos
-pnpm run test:quick
-
-# Testar MCP server localmente
-pnpm run test:mcp
-```
-
-### 2. Verificar Arquivos que Serão Publicados
-```bash
-# Simular publicação (dry-run)
-npm pack --dry-run
-
-# Ver exatamente o que será publicado
-npm pack
-tar -tzf s3db.js-*.tgz | less
-
-# Limpar arquivo gerado
-rm s3db.js-*.tgz
-```
-
-### 3. Verificar Binary Entry Point
-```bash
-# Conferir que o entrypoint está executável
-ls -la mcp/entrypoint.js
-
-# Deve mostrar: -rwxrwxr-x (permissões de execução)
-# Se não tiver, executar: chmod +x mcp/entrypoint.js
-
-# Testar shebang
-head -1 mcp/entrypoint.js
-# Deve mostrar: #!/usr/bin/env node
-```
-
-### 4. Testar Localmente com NPX
-```bash
-# Simular o que o usuário vai fazer
-npx -y ./
-
-# Ou instalar localmente e testar
-npm link
-npx s3db.js s3db-mcp --transport=stdio
-npm unlink
-```
-
-## 📋 O Que Será Publicado
-
-O NPM irá incluir apenas:
-
-```
-s3db.js/
-├── dist/                      # Código compilado
-│   ├── s3db.cjs.js           # CommonJS
-│   ├── s3db.es.js            # ES Modules
-│   └── s3db.d.ts             # TypeScript definitions
-├── src/                       # Código fonte (para debugging)
-├── bin/
-│   └── cli.js                # CLI principal
-├── mcp/                       # MCP Server (completo!)
-│   ├── entrypoint.js         # 🎯 Entry point para npx
-│   ├── tools/                # Todas as tools
-│   ├── README.md             # Quick reference
-│   ├── NPX_SETUP.md          # Guia de setup
-│   └── CLAUDE_CLI_SETUP.md   # Guia Claude CLI
-├── docs/
-│   └── mcp.md                # Documentação completa
-├── package.json
-├── README.md
-├── PLUGINS.md
-├── SECURITY.md
-└── UNLICENSE
-```
-
-**Tamanho estimado**: ~2-3 MB (sem tests, examples, binários)
-
-## 🚀 Publicar no NPM
-
-### Primeira Vez
-```bash
-# Login no NPM
-npm login
-
-# Publicar (com prepublishOnly automático)
-npm publish
-
-# Ou publicar como beta
-npm publish --tag beta
-```
-
-### Atualizações
-```bash
-# Bump version (patch/minor/major)
-npm version patch -m "fix: improve MCP server performance"
-npm version minor -m "feat: add new MCP tools"
-npm version major -m "BREAKING CHANGE: new MCP API"
-
-# Publicar
-npm publish
-```
-
-## 🧪 Validar Após Publicação
-
-### 1. Testar NPX Imediatamente
-```bash
-# Aguardar 1-2 minutos para propagar no NPM CDN
-
-# Testar comando direto
-npx -y s3db.js@latest s3db-mcp --help
-
-# Testar com Claude CLI
-claude mcp add s3db-test \
-  --transport stdio \
-  -- npx -y s3db.js@latest s3db-mcp --transport=stdio
-
-# Verificar se foi adicionado
-claude mcp list
-
-# Testar no chat
-claude
-# Digitar: "Show me S3DB MCP server status"
-
-# Remover teste
-claude mcp remove s3db-test
-```
-
-### 2. Verificar Página NPM
-- Acesse: https://www.npmjs.com/package/s3db.js
-- ✅ README renderizado corretamente
-- ✅ Keywords incluem "mcp", "model-context-protocol"
-- ✅ Binaries listados: `s3db-mcp`
-- ✅ Files incluem `mcp/`
-
-### 3. Verificar Tamanho do Pacote
-```bash
-# Ver tamanho do pacote publicado
-npm view s3db.js dist.unpackedSize
-
-# Deve ser < 5MB (ideal: 2-3MB)
-```
-
-## ❌ Troubleshooting
-
-### Erro: "command not found: s3db-mcp"
-**Causa**: Shebang faltando ou permissões incorretas
-**Solução**:
-```bash
-# Adicionar shebang no início do arquivo
-echo '#!/usr/bin/env node' | cat - mcp/entrypoint.js > temp && mv temp mcp/entrypoint.js
-
-# Dar permissões de execução
-chmod +x mcp/entrypoint.js
-
-# Republicar
-npm version patch -m "fix: add executable permissions to mcp entrypoint"
-npm publish
-```
-
-### Erro: "Cannot find module '@modelcontextprotocol/sdk'"
-**Causa**: Dependência não está em `dependencies`
-**Solução**:
-```bash
-# Mover de devDependencies para dependencies
-npm install --save @modelcontextprotocol/sdk
-
-# Republicar
-npm version patch -m "fix: move MCP SDK to dependencies"
-npm publish
-```
-
-### Erro: "mcp/ directory not found"
-**Causa**: `.npmignore` bloqueando `mcp/` ou faltando em `files`
-**Solução**:
-```bash
-# Verificar package.json
-cat package.json | jq '.files'
-# Deve incluir "mcp/"
-
-# Verificar .npmignore
-cat .npmignore | grep "mcp/"
-# Não deve ter "mcp/" listado
-
-# Republicar
-npm version patch -m "fix: include mcp directory in package"
-npm publish
-```
-
-## 🎯 Comandos Úteis
-
-```bash
-# Ver informações do pacote publicado
-npm view s3db.js
-
-# Ver versões publicadas
-npm view s3db.js versions
-
-# Verificar quem tem acesso
-npm access list packages
-
-# Deprecate uma versão (se necessário)
-npm deprecate s3db.js@11.2.5 "Use version 11.2.6 or higher"
-
-# Unpublish (CUIDADO! Só nas primeiras 72h)
-npm unpublish s3db.js@11.2.6
-```
-
-## 📊 Monitoramento Pós-Publicação
-
-### Downloads
-```bash
-# Ver estatísticas de download
-npm view s3db.js
-
-# Ver downloads semanais
-open "https://www.npmjs.com/package/s3db.js"
-```
-
-### Issues
-- Monitor: https://github.com/forattini-dev/s3db.js/issues
-- Filtrar por label: `mcp`, `npx`
-
-## 🔄 Workflow Completo
-
-```bash
-# 1. Fazer mudanças no código
-vim mcp/entrypoint.js
-
-# 2. Testar localmente
-pnpm run test:mcp
-
-# 3. Commit
-git add .
-git commit -m "feat: improve MCP server"
-
-# 4. Bump version (roda prepublishOnly automaticamente)
-npm version patch -m "feat: improve MCP server"
-
-# 5. Push (com tag)
-git push && git push --tags
-
-# 6. Publicar
-npm publish
-
-# 7. Validar
-npx -y s3db.js@latest s3db-mcp --help
-
-# 8. Celebrar! 🎉
-```
-
-## 🎉 Checklist Final
-
-Antes de publicar, confirme:
-
-- [ ] ✅ `pnpm run build` - Build funcionando
-- [ ] ✅ `pnpm run test:quick` - Tests passando
-- [ ] ✅ `pnpm run test:mcp` - MCP server iniciando
-- [ ] ✅ `npm pack --dry-run` - Arquivos corretos
-- [ ] ✅ `ls -la mcp/entrypoint.js` - Permissões de execução
-- [ ] ✅ `head -1 mcp/entrypoint.js` - Shebang presente
-- [ ] ✅ `cat package.json | jq '.files'` - Inclui `mcp/`
-- [ ] ✅ `cat package.json | jq '.bin'` - Inclui `s3db-mcp`
-- [ ] ✅ `cat package.json | jq '.dependencies'` - MCP SDK incluído
-- [ ] ✅ Version bumped
-- [ ] ✅ Git committed e pushed
-- [ ] ✅ Ready to publish! 🚀
-
-## 📚 Recursos
-
-- [NPM Publishing Guide](https://docs.npmjs.com/cli/v9/commands/npm-publish)
-- [NPM Pack Documentation](https://docs.npmjs.com/cli/v9/commands/npm-pack)
-- [Semantic Versioning](https://semver.org/)
-- [MCP Documentation](https://modelcontextprotocol.io)