mcp-paperclip/CHANGELOG.md

Changelog

[Unreleased] - feature/diagnostics-db

Added

• 16 ferramentas de diagnóstico read-only/write para inspecção da base de dados Paperclip directamente via MCP, eliminando necessidade de psql nos skills /clip-*.
• Pool PostgreSQL singleton (src/db.ts) com export de COMPANY_ID e helper query() parametrizado.
• Variável de ambiente PAPERCLIP_DB_URL (default: postgres://paperclip:paperclip@localhost:54329/paperclip).
• Dependências pg ^8.13.1 e @types/pg ^8.11.10.

Diagnostic tools (read-only — 14)

1. diag_agents_by_status — contagem por status
2. diag_agent_hierarchy — árvore reports_to completa
3. diag_agents_missing_permissions — agentes sem entradas permissions
4. diag_agents_missing_heartbeat — agentes activos sem runs heartbeat
5. diag_agents_without_membership — agentes sem entrada activa em company_memberships
6. diag_budget_orphans — budget_policies/incidents a referenciar entidades inexistentes
7. diag_routine_triggers_broken — routine_triggers schedule sem next_run_at
8. diag_heartbeat_token_usage(hours) — token burn por agent últimas N horas
9. diag_prompt_too_long_errors(hours) — erros "prompt too long" últimas N horas
10. diag_false_blockers — issues blocked sem motivo real
11. diag_stuck_routines(hours) — routines presas há N horas
12. diag_zombie_parents — agentes com parent archived
13. diag_company_skills_summary — agregado company_skills por source_type
14. diag_agent_full_context(agent_name) — contexto completo de 1 agente (config + runs + membership + perms + tokens 24h)

Diagnostic tools (write — 2)

15. force_session_rotation — rotação forçada de sessão (validação posterior)
16. cancel_stuck_routine_issue — cancelar issue de routine presa (validação posterior)

Security

• 100% das queries SQL parametrizadas ($1, $2...). Zero string interpolation em SQL — verificado por grep.
• npm audit: 0 vulnerabilidades.

Fixed

• diag_agents_without_membership: corrigido erro operator does not exist: text = uuid adicionando cast a.id::text e filtros principal_type='agent' AND status='active'.

Migration

• 17 blocos psql substituídos por chamadas MCP em 5 skills /clip-*: clip, clip-agent, clip-health, clip-org, clip-routine. Skills clip-instructions/issue/skill mantêm psql (CRUD específico sem equivalente diag_*).

Refs

• Desk CRM Task #2041
• Plano: memory/mcp-paperclip-diagnostics-plan.md