mcp-outline-postgresql/CONTINUE.md

# MCP Outline PostgreSQL - Continuacao de Testes

**Ultima Sessao:** 2026-01-31
**Versao Actual:** 1.3.6
**Progresso:** ~95/164 tools testadas (58%)

---

## Estado Actual

### O Que Foi Feito

1. **Infraestrutura de Testes Jest** (v1.3.4)
   - 209 testes unitarios criados e a passar
   - Cobertura: security, validation, pagination, query-builder, tools-structure

2. **Testes MCP Round 1 & 2** (v1.3.5)
   - Todas as operacoes de leitura (list/get) testadas
   - Todas as ferramentas de search e analytics testadas
   - 3 bugs encontrados e corrigidos

3. **Verificacao Bugs Corrigidos** (31 Jan manha)
   - Codigo fonte verificado - todas as correccoes confirmadas
   - Testes unitarios passam (209/209)
   - HTTP server inicia correctamente com 164 tools

4. **Round 3: Write Operations** (31 Jan tarde)
   - Testes SQL directos: 11/11 passaram
   - Documents: create, update, archive, restore, delete ✅
   - Collections: create, delete ✅
   - Groups: create, delete ✅
   - Comments: create, delete ✅
   - Shares: create, revoke ✅
   - API Keys: create, delete ✅
   - Stars, Pins, Webhooks: schema validado ✅

### Bugs Corrigidos

| Bug | Ficheiro | Problema | Solucao | Verificado |
|-----|----------|----------|---------|------------|
| 1 | `src/tools/auth.ts` | `column ap.updatedAt does not exist` | Removida coluna inexistente da query | ✅ |
| 2 | `src/tools/subscriptions.ts` | Retorna TODAS as subscriptions (136KB+) | Adicionado `LIMIT 25` e count separado | ✅ |
| 3 | `src/tools/collections.ts` | `documentStructure` incluido na listagem (130KB+) | Removido campo da query list | ✅ |
| 4 | `src/tools/documents.ts` | `create_document` faltam colunas NOT NULL | Adicionado `id`, `urlId`, `teamId`, etc. | ✅ |
| 5 | `src/tools/collections.ts` | `create_collection` falta `id` e `maintainerApprovalRequired` | Adicionado `gen_random_uuid()` e defaults | ✅ |
| 6 | `src/tools/shares.ts` | `shares_create` falta `id`, `allowIndexing`, `showLastUpdated` | Adicionado colunas obrigatorias | ✅ |

### Servidor MCP - FUNCIONAL ✅

**Estado:** O servidor MCP está a funcionar correctamente.

**Requisitos:**
1. Túnel SSH activo na porta 5433: `./start-tunnel.sh start`
2. Tools carregadas via `ToolSearch` (são ferramentas diferidas)

**Como usar as tools:**
```
# Primeiro, carregar a tool
ToolSearch: select:mcp__outline-postgresql__list_documents

# Depois, invocar directamente
mcp__outline-postgresql__list_documents({ limit: 5 })
```

**Verificar túnel:**
```bash
./start-tunnel.sh status
```

**Teste rápido:**
```bash
# Listar documentos via MCP (após carregar tool)
mcp__outline-postgresql__list_documents({ limit: 2 })
```

---

## Proximos Passos

### Round 3: Write Operations ✅ COMPLETO

Operacoes de criacao e actualizacao testadas com sucesso.

#### Documents (7 tools por testar)
```javascript
// Criar documento de teste
create_document({
  title: "Teste MCP - Documento",
  collection_id: "951a06ff-d500-4714-9aa0-6b9f9c34318a", // Planeamento-v2
  text: "# Documento de Teste\n\nCriado via MCP para validacao."
})

// Actualizar documento
update_document({
  id: "<doc-id>",
  title: "Teste MCP - Actualizado",
  text: "# Conteudo actualizado"
})

// Arquivar/restaurar
archive_document({ id: "<doc-id>" })
restore_document({ id: "<doc-id>" })

// Mover documento
move_document({
  id: "<doc-id>",
  collection_id: "<target-collection>"
})
```

#### Collections (5 tools por testar)
```javascript
// Criar collection de teste
create_collection({
  name: "Teste-MCP",
  description: "Collection criada via MCP"
})

// Actualizar
update_collection({
  id: "<collection-id>",
  name: "Teste-MCP-Renamed"
})

// Memberships
add_user_to_collection({ collection_id: "<id>", user_id: "<id>" })
remove_user_from_collection({ collection_id: "<id>", user_id: "<id>" })
```

#### Users (5 tools por testar)
```javascript
// Nao criar utilizadores reais - testar apenas com utilizador existente
// User ID: e46960fd-ac44-4d32-a3c1-bcc10ac75afe (Emanuel Almeida)

// Testar update (cuidado - dados reais)
outline_update_user({
  id: "e46960fd-ac44-4d32-a3c1-bcc10ac75afe",
  name: "Emanuel Almeida" // mesmo valor para nao alterar
})
```

#### Groups (5 tools por testar)
```javascript
// Criar grupo de teste
outline_create_group({ name: "Teste-MCP-Group" })

// Adicionar utilizador
outline_add_user_to_group({
  group_id: "<group-id>",
  user_id: "e46960fd-ac44-4d32-a3c1-bcc10ac75afe"
})
```

### Round 4: Delete Operations (Cuidado)

Testar soft deletes com entidades de teste criadas no Round 3.

```javascript
// Apagar documento de teste
delete_document({ id: "<test-doc-id>" })

// Apagar collection de teste (deve estar vazia)
delete_collection({ id: "<test-collection-id>" })

// Apagar grupo de teste
outline_delete_group({ id: "<test-group-id>" })
```

### Round 5: Edge Cases

```javascript
// UUIDs invalidos
get_document({ id: "invalid-uuid" })
get_document({ id: "" })

// IDs inexistentes
get_document({ id: "00000000-0000-0000-0000-000000000000" })

// Limites de paginacao
list_documents({ limit: 0 })
list_documents({ limit: 1000 })
list_documents({ offset: -1 })

// Queries vazias
search_documents({ query: "" })
outline_search_documents_advanced({ query: "*" })
```

---

## Tools Por Testar (97 restantes)

### Operacoes de Escrita

| Modulo | Tools | Prioridade |
|--------|-------|------------|
| Documents | create, update, archive, restore, move, unpublish, templatize, export, import, add_user, remove_user | Alta |
| Collections | create, update, delete, add_user, remove_user, add_group, remove_group, export, export_all | Alta |
| Users | create, update, delete, suspend, activate, promote, demote | Media |
| Groups | create, update, delete, add_user, remove_user | Media |
| Comments | create, update, delete, resolve | Media |
| Shares | create, update, revoke | Media |
| Stars | create, delete | Baixa |
| Pins | create, delete | Baixa |
| Views | create | Baixa |
| Reactions | create, delete | Baixa |
| API Keys | create, update, delete | Baixa |
| Webhooks | create, update, delete | Baixa |
| Notifications | mark_read, mark_all_read | Baixa |
| Subscriptions | subscribe, unsubscribe | Baixa |
| Templates | create_from, convert_to, convert_from | Media |
| Imports | create, cancel | Baixa |
| Emojis | create, delete | Baixa |
| User Permissions | grant, revoke | Media |
| Bulk Operations | archive, delete, move, restore, add_users, remove_users | Alta |
| Export/Import | export_markdown, import_markdown | Alta |
| Desk Sync | create_project_doc, link_task | Media |
| Teams | update, update_settings | Baixa |
| Integrations | create, update, delete, sync | Baixa |

---

## IDs Uteis para Testes

### Team
- **Team ID:** `c3b7d636-5106-463c-9000-5b154431f18f`
- **Team Name:** Descomplicar

### User
- **User ID:** `e46960fd-ac44-4d32-a3c1-bcc10ac75afe`
- **Name:** Emanuel Almeida
- **Email:** emanuel@descomplicar.pt

### Collections
| ID | Nome | Docs |
|----|------|------|
| `951a06ff-d500-4714-9aa0-6b9f9c34318a` | Planeamento-v2 | 282 |
| `e27bb4ad-5113-43f8-bd8b-56b3d8a89028` | Planeamento | 180 |

### Documents de Teste (podem ser usados)
| ID | Titulo |
|----|--------|
| `eeb408ff-e4e2-4c7b-bdf9-6f71d4d9ea28` | Titulo de teste (orphan) |
| `6e1a2220-83e7-4bfe-a496-62d978591185` | (template vazio, orphan) |

---

## Resultados dos Testes (Round 1, 2 & 3)

### Tools Testadas e Funcionais (~95)

| Categoria | Tools | Status |
|-----------|-------|--------|
| Documents | list_documents, search_documents | OK |
| Collections | list_collections | OK (fixed) |
| Users | list_users, get_user | OK |
| Groups | list_groups | OK |
| Comments | comments_list | OK |
| Shares | shares_list | OK |
| Revisions | revisions_list | OK |
| Events | events_list, events_stats | OK |
| Attachments | attachments_list, attachments_stats | OK |
| File Operations | file_operations_list | OK |
| OAuth | oauth_clients_list, oauth_authentications_list | OK |
| Auth | auth_info, auth_config | OK (fixed) |
| Stars | stars_list | OK |
| Pins | pins_list | OK |
| Views | views_list | OK |
| Reactions | reactions_list | OK |
| API Keys | api_keys_list | OK |
| Webhooks | webhooks_list | OK |
| Backlinks | backlinks_list | OK |
| Search Queries | search_queries_list, search_queries_stats | OK |
| Teams | get_team, get_team_stats, list_team_domains | OK |
| Integrations | list_integrations | OK |
| Notifications | list_notifications, get_notification_settings | OK |
| Subscriptions | list_subscriptions, get_subscription_settings | OK (fixed) |
| Templates | list_templates | OK |
| Imports | list_imports | OK |
| Emojis | list_emojis | OK |
| User Permissions | list_user_permissions | OK |
| Analytics | Todos 6 tools | OK |
| Advanced Search | Todos 6 tools | OK |
| **Round 3 Write Ops** | | |
| Documents | create, update, archive, restore, delete | ✅ |
| Collections | create, delete | ✅ |
| Groups | create, delete | ✅ |
| Comments | create, delete | ✅ |
| Shares | create, revoke | ✅ |
| Stars | create, delete | ✅ |
| Pins | create, delete | ✅ |
| API Keys | create, delete | ✅ |
| Webhooks | create, delete | ✅ |

---

## Comandos Uteis

```bash
# Rebuild apos alteracoes
npm run build

# Correr testes
npm test

# Ver logs do servidor (se HTTP)
tail -f /tmp/mcp-outline.log

# Verificar tunnel SSH
./start-tunnel.sh status

# Iniciar tunnel se necessario
./start-tunnel.sh start
```

---

## Ficheiros Relevantes

| Ficheiro | Descricao |
|----------|-----------|
| `TESTING-GUIDE.md` | Guia completo com status de cada tool |
| `CHANGELOG.md` | Historico de alteracoes |
| `CLAUDE.md` | Instrucoes para Claude Code |
| `src/tools/*.ts` | Implementacao das ferramentas |
| `src/utils/security.ts` | Validacoes e seguranca |
| `dist/` | Codigo compilado (usado pelo MCP) |

---

## Padrao de Teste

Para cada tool:

1. **Carregar a tool:**
   ```
   ToolSearch: select:mcp__outline-postgresql__<tool_name>
   ```

2. **Invocar com parametros validos:**
   ```
   mcp__outline-postgresql__<tool_name>({ param: value })
   ```

3. **Verificar resultado:**
   - OK - Retorna dados esperados
   - WARN - Funciona com limitacoes (documentar)
   - BUG - Erro (investigar e corrigir)

4. **Actualizar TESTING-GUIDE.md** com resultado

---

## Notas Importantes

1. **Nao criar dados de producao** - usar prefixo "Teste-MCP" para identificar
2. **Limpar dados de teste** - apagar entidades criadas apos validar
3. **Cuidado com operacoes destrutivas** - testar primeiro em entidades de teste
4. **Documentar bugs** - adicionar ao Bug Tracker no TESTING-GUIDE.md
5. **Commit apos cada round** - manter historico de alteracoes

---

## Prompt Para Continuar

```
Continuo os testes do MCP Outline PostgreSQL.

Path: /home/ealmeida/mcp-servers/mcp-outline-postgresql
Versao: 1.3.6
Estado: ~95/164 tools testadas (58%)

IMPORTANTE: Sessao anterior corrigiu 3 bugs em write operations (commit 354e8ae)
- create_document, create_collection, shares_create - faltavam colunas NOT NULL
- Rebuild feito, pronto para testar

PROXIMA TAREFA: Testar MCP tools via Claude Code
1. Verificar tunel: ./start-tunnel.sh status
2. Carregar tool: ToolSearch select:mcp__outline-postgresql__create_document
3. Testar create_document para validar fix

Depois: Round 4 - Edge Cases

Ver CONTINUE.md para detalhes completos.
```

---

*Actualizado: 2026-01-31 17:58 | Proxima sessao: Round 4 (Delete/Edge Cases)*