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:

./start-tunnel.sh status

Teste rápido:

# 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)

// 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)

// 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)

// 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)

// 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.

// 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

// 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

# 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.5
Estado: ~95/164 tools testadas (Rounds 1, 2 & 3 completos - 58%)

PROXIMA TAREFA: Round 4 - Delete Operations & Edge Cases
- Testar soft deletes restantes
- Testar edge cases (UUIDs invalidos, limites de paginacao)
- Testar operacoes de update restantes
- Documentar resultados em TESTING-GUIDE.md

Ver CONTINUE.md para detalhes completos.

---

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