mcp-outline-postgresql/docs/audits/2026-01-31-v1.2.1/ROADMAP.md

Task List - MCP Outline PostgreSQL v2.0.0

Projecto: MCP Outline PostgreSQL
Versão Actual: 1.2.1
Versão Alvo: 2.0.0 (Production-Ready)
Data Início: 2026-01-31

---

🔴 FASE 1: Segurança Crítica (P0) - 2 semanas

1.1 SQL Injection (Semana 1)

• 1.1.1 Auditar queries vulneráveis

  • Executar grep para identificar template strings em queries
  • Catalogar todas as ocorrências em vulnerable-queries.txt
  • Priorizar por criticidade (write > read)

• 1.1.2 Criar SafeQueryBuilder

  • Implementar src/utils/query-builder.ts
  • Adicionar métodos: addParam(), buildILike(), buildIn()
  • Escrever testes unitários
  • Documentar uso

• 1.1.3 Refactoring de queries - Módulos Core

  • documents.ts (19 tools) - 2 dias
  • collections.ts (14 tools) - 1.5 dias
  • users.ts (9 tools) - 1 dia
  • groups.ts (8 tools) - 1 dia

• 1.1.4 Refactoring de queries - Módulos Search/Analytics

  • advanced-search.ts (6 tools) - 1 dia
  • analytics.ts (6 tools) - 1 dia
  • search-queries.ts (2 tools) - 0.5 dias

• 1.1.5 Refactoring de queries - Restantes módulos

  • 27 ficheiros restantes - 2 dias
  • Testar cada módulo após refactoring

• 1.1.6 Adicionar linting rule

  • Configurar ESLint rule para detectar template strings em queries
  • Executar linter e corrigir warnings
  • Adicionar ao CI

1.2 Transacções (Semana 2)

• 1.2.1 Identificar operações críticas

  • Listar todas as operações multi-write
  • Priorizar por risco de inconsistência
  • Documentar em TRANSACTION-AUDIT.md

• 1.2.2 Criar Transaction Helper

  • Implementar src/utils/transaction.ts
  • Adicionar retry logic para deadlocks
  • Escrever testes unitários

• 1.2.3 Refactoring com transacções

  • bulk-operations.ts (6 tools)
  • desk-sync.ts (2 tools)
  • export-import.ts (2 tools)
  • collections.ts - memberships (4 tools)
  • documents.ts - create/update com memberships (2 tools)

• 1.2.4 Testes de rollback

  • Criar tests/transactions.test.ts
  • Testar rollback em cada operação crítica
  • Verificar integridade de dados

1.3 Validação de Inputs (Semana 2)

• 1.3.1 Implementar validação automática

  • Instalar ajv e ajv-formats
  • Criar src/utils/validation.ts
  • Implementar validateToolInput() e withValidation()

• 1.3.2 Adicionar validações específicas

  • validateUUIDs() para arrays
  • validateEnum() para enums
  • validateStringLength() para strings
  • Escrever testes unitários

• 1.3.3 Aplicar validação a todos os tools

  • Envolver handlers com withValidation()
  • Testar validação em cada módulo

1.4 Audit Logging (Semana 2)

• 1.4.1 Criar sistema de audit log

  • Implementar src/utils/audit.ts
  • Criar logAudit() e withAuditLog()
  • Integrar com tabela events

• 1.4.2 Aplicar audit log

  • Identificar operações de escrita (create, update, delete)
  • Envolver com withAuditLog()
  • Testar logging

---

🟡 FASE 2: Performance (P1) - 1 semana

2.1 Eliminar N+1 Queries

• 2.1.1 Identificar N+1 queries

  • Auditar collections.ts:1253-1280
  • Auditar documents.ts:530-577
  • Auditar analytics.ts

• 2.1.2 Refactoring com JOINs

  • export_all_collections - usar json_agg
  • list_drafts - optimizar query
  • Analytics queries - usar CTEs

• 2.1.3 Testar performance

  • Benchmark antes/depois
  • Verificar planos de execução (EXPLAIN)

2.2 Criar Índices

• 2.2.1 Criar migrations

  • Criar migrations/001_indexes.sql
  • Adicionar índices GIN para full-text search
  • Adicionar índices B-tree para queries comuns
  • Adicionar índices para memberships

• 2.2.2 Documentar índices

  • Adicionar secção em SPEC-MCP-OUTLINE.md
  • Documentar impacto de cada índice
  • Criar guia de deployment

2.3 Optimizar Connection Pool

• 2.3.1 Tuning de pool

  • Adicionar defaults em src/config/database.ts
  • Configurar max, min, timeouts
  • Adicionar maxUses para recycling

• 2.3.2 Pool monitoring

  • Criar src/utils/monitoring.ts
  • Adicionar logging de pool stats
  • Adicionar alertas de saturação

2.4 Cursor-Based Pagination

• 2.4.1 Implementar cursor pagination

  • Criar src/utils/pagination.ts
  • Implementar paginateWithCursor()
  • Escrever testes

• 2.4.2 Migrar tools principais

  • list_documents
  • list_collections
  • list_users

---

🟢 FASE 3: Qualidade (P2) - 2 semanas

3.1 Testes Unitários (Semana 1)

• 3.1.1 Setup de testing

  • Instalar Vitest + Testcontainers
  • Criar vitest.config.ts
  • Configurar coverage

• 3.1.2 Testes de utils

  • tests/utils/security.test.ts
  • tests/utils/query-builder.test.ts
  • tests/utils/validation.test.ts
  • tests/utils/transaction.test.ts
  • tests/utils/audit.test.ts

• 3.1.3 Testes de tools

  • tests/tools/documents.test.ts
  • tests/tools/collections.test.ts
  • tests/tools/users.test.ts
  • tests/tools/bulk-operations.test.ts

• 3.1.4 Testes de integração

  • Setup PostgreSQL container
  • Testes end-to-end de workflows
  • Testes de transacções

3.2 CI/CD (Semana 2)

• 3.2.1 GitHub Actions

  • Criar .github/workflows/ci.yml
  • Configurar test job
  • Configurar lint job
  • Configurar build job

• 3.2.2 Code coverage

  • Integrar Codecov
  • Configurar thresholds (>80%)
  • Adicionar badge ao README

• 3.2.3 Automated releases

  • Configurar semantic-release
  • Automatizar CHANGELOG
  • Automatizar tags

3.3 Refactoring (Semana 2)

• 3.3.1 Tool factory

  • Criar src/utils/tool-factory.ts
  • Implementar createTool()
  • Adicionar validação automática
  • Adicionar transacção automática
  • Adicionar audit log automático

• 3.3.2 Aplicar factory

  • Refactoring de documents.ts
  • Refactoring de collections.ts
  • Refactoring de users.ts
  • Refactoring de restantes módulos

• 3.3.3 Type safety

  • Activar TypeScript strict mode
  • Corrigir type errors
  • Adicionar tipos genéricos

3.4 Documentação

• 3.4.1 Actualizar README

  • Adicionar badges (CI, coverage)
  • Melhorar getting started
  • Adicionar troubleshooting

• 3.4.2 API documentation

  • Documentar cada tool
  • Adicionar exemplos de uso
  • Criar guia de best practices

---

🟢 FASE 4: Funcionalidades (P3) - Ongoing

4.1 Rate Limiting Distribuído

• 4.1.1 Integrar Redis

  • Adicionar dependência ioredis
  • Configurar Redis client
  • Criar src/utils/redis-rate-limit.ts

• 4.1.2 Implementar rate limiting

  • Substituir Map por Redis
  • Adicionar sliding window
  • Testar em multi-instância

• 4.1.3 CAPTCHA

  • Integrar reCAPTCHA
  • Adicionar a operações sensíveis
  • Testar bypass em testes

4.2 Autorização

• 4.2.1 Implementar RBAC

  • Criar src/utils/authorization.ts
  • Implementar checkPermission()
  • Definir roles e permissions

• 4.2.2 Aplicar autorização

  • Adicionar middleware de autorização
  • Verificar permissões antes de operações
  • Testar cenários de acesso negado

• 4.2.3 Testes de autorização

  • Testes de RBAC
  • Testes de permission checks
  • Testes de edge cases

4.3 Monitoring

• 4.3.1 Prometheus

  • Adicionar prom-client
  • Criar métricas (query duration, pool stats, etc)
  • Expor endpoint /metrics

• 4.3.2 Grafana

  • Criar dashboard
  • Adicionar alertas
  • Documentar setup

• 4.3.3 Logging estruturado

  • Migrar para Winston ou Pino
  • Adicionar correlation IDs
  • Configurar log levels por ambiente

4.4 Documentação Avançada

• 4.4.1 OpenAPI spec

  • Gerar OpenAPI 3.0 spec
  • Adicionar Swagger UI
  • Publicar documentação

• 4.4.2 Deployment guide

  • Docker Compose setup
  • Kubernetes manifests
  • Production checklist

• 4.4.3 Troubleshooting guide

  • Common errors
  • Performance tuning
  • Debug tips

4.5 Melhorias Incrementais

• 4.5.1 Caching

  • Implementar cache de queries frequentes
  • Usar Redis para cache distribuído
  • Adicionar cache invalidation

• 4.5.2 Webhooks

  • Implementar webhook dispatcher
  • Adicionar retry logic
  • Testar delivery

• 4.5.3 Bulk import/export

  • Optimizar import de grandes volumes
  • Adicionar progress tracking
  • Implementar streaming

---

📊 Progress Tracking

Fase 1: Segurança Crítica

• Total: 12 tarefas
• Concluídas: 0
• Em Progresso: 0
• Bloqueadas: 0
• Progress: 0%

Fase 2: Performance

• Total: 10 tarefas
• Concluídas: 0
• Em Progresso: 0
• Bloqueadas: 0
• Progress: 0%

Fase 3: Qualidade

• Total: 15 tarefas
• Concluídas: 0
• Em Progresso: 0
• Bloqueadas: 0
• Progress: 0%

Fase 4: Funcionalidades

• Total: 15 tarefas
• Concluídas: 0
• Em Progresso: 0
• Bloqueadas: 0
• Progress: 0%

---

🎯 Próximos Passos Imediatos

1. Aprovar plano de melhorias
2. Criar branch security-fixes
3. Iniciar tarefa 1.1.1: Auditar queries vulneráveis
4. Daily standup: actualizar progress

---

Task list criada em 2026-01-31 | MCP Outline PostgreSQL v1.2.1 → v2.0.0