rodolpho.lopes/knowledge-base
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
knowledge-base/records/plugin-dev/KB-PLUGIN-026-mcprotocol-roadmap-snapshot-v1.2.md
Rodolpho Lopes 0c88e71f92 docs(KB-035): modelo de dados dos KPIs de Service Desk no GLPI 11 
Documenta as colunas/tabelas reais usadas pelas 7 tools de KPI (MTTR via
solve_delay_stat, FCR via solução recusada, SLA TTR/TTO, workload, backlog,
CSAT, volume). Atualiza snapshot KB-026 para 26 tools.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 22:52:14 +00:00

8.1 KiB
Raw Blame History

id title domain tags status severity created_at updated_at applies_to related_records
KB-PLUGIN-026 mcprotocol — Snapshot de roadmap v1.2 (pós-ProjectTask + InputValidation) plugin-dev
mcp
roadmap
snapshot
planning
active medium 2026-05-26 2026-06-22
glpi-11
mcprotocol-plugin
KB-PLUGIN-019
KB-PLUGIN-020
KB-PLUGIN-021
KB-PLUGIN-022
KB-PLUGIN-023
KB-PLUGIN-024
KB-PLUGIN-025

mcprotocol — Snapshot de roadmap v1.2 (pós-ProjectTask + InputValidation)

Contexto

Esta KB é um ponto de salvamento do estado do plugin mcprotocol. Serve de referência canônica para o estado atual e backlog priorizado.

⚠️ Reconciliação 2026-06-22. A versão original deste snapshot (26/05) era aspiracional: descrevia src/InputValidation.php, src/ProjectTaskTools.php e as tools glpi_projecttask_get/create como "✅ NOVO / já no branch main do dev". A auditoria de git log --all confirmou que esses arquivos nunca existiram no repositório — foram planejados mas não implementados. As tabelas abaixo foram corrigidas para refletir o estado real em disco (v1.1.1). Os itens não implementados permanecem como roadmap, agora marcados como 📋 planejado.

Estado atual das tools

Tools de domínio (ORM direto)

Tool Status Notas
glpi_ticket_get ✅ Consolida followups
glpi_ticket_bi_stats ✅ Agregador de BI por data/status/entidade + SLA estourado (commit e49d20d)
glpi_ticket_create ✅
glpi_ticket_update ✅
glpi_ticket_add_followup ✅
glpi_ticket_add_solution ✅
glpi_project_get ✅ Retorna tarefas (via $DB direto, não hierárquico)
glpi_project_create ✅ Tasks/subtasks aninhadas, estado por nome, plan_*_date (schema corrigido em 4ddd00b)
glpi_project_update ✅ Apenas name/content/percent_done — ainda NÃO estendido com datas/estado
glpi_projecttask_get ✅ Implementado em v1.2.0 (ORM)
glpi_projecttask_create ✅ Implementado em v1.2.0 (ORM, hierarquia, estado por nome)
glpi_projecttask_update ✅ Implementado em v1.2.0 (ORM)
glpi_projecttask_delete ✅ Implementado em v1.2.0 (ORM — bypassa REST v2)
glpi_ticket_search_by_status ✅

Tools genéricas (REST API v2)

Tool Status Observação
glpi_get_items ⚠️ Funcional, mas confiável só para itemtypes expostos na v2
glpi_get_item ⚠️ Idem
glpi_add_item ⚠️ Idem
glpi_update_item ⚠️ Idem
glpi_delete_item ❌ Bug do "silent success" — ver KB-PLUGIN-024

Infraestrutura

Componente Status
src/Server.php ✅ Funcional. makeRequest valida HTTP status e propaga 4xx/5xx (v1.2.0)
src/ToolRegistry.php ✅ Registra Ticket + Project + ProjectTask (v1.2.0)
src/InputValidation.php ✅ Implementado em v1.2.0 — helpers compartilhados (KB-PLUGIN-023)
src/TicketTools.php ✅ Padrão antigo de validação inline (candidato a migrar p/ InputValidation)
src/ProjectTools.php ✅ resolveStateId usa InputValidation; suporta plan_*_date
src/ProjectTaskTools.php ✅ Implementado em v1.2.0 — CRUD via ORM
src/Boot.php ✅ Registra path stateless via SessionManager
ajax/mcp.php ✅ Endpoint stateless com JWT (RS256 / oauth.pub)

Casos reais executados

Cliente Projeto Tarefas Resultado
VALGROUP Implantação GLPI 7 macros + 21 subs (hierarquia) ✅ Criado end-to-end via plugin
TCERJ Implantação GLPI 6 tarefas (datas replanejadas) ✅ Criado end-to-end via plugin

Ambos comprovam o padrão de tools nativo funcionando em fluxo real de comercial → projeto operacional.

Bugs conhecidos

ID Severidade Resumo
KB-PLUGIN-024 Alta glpi_delete_item retorna sucesso silencioso quando API retorna 404
KB-PLUGIN-024 Média ProjectTask não exposto na REST v2 do GLPI (precisa tool de domínio)
KB-PLUGIN-025 Baixa Datas sem hora explícita podem desalinhar em UI de usuários com TZ regional

Roadmap priorizado

Próxima rodada (P1)

  1. Correção #1 do KB-024 — makeRequest deve validar HTTP status e propagar 4xx/5xx como exception. Afeta todas as tools genéricas REST. Impacto alto, esforço baixo.

  2. glpi_projecttask_delete — Correção #2 do KB-024. Tool de domínio bypassa REST API, usa ORM direto.

  3. glpi_projecttask_update — completar o CRUD de tarefas. Necessário para casos como "atualizar percent_done", "remarcar datas".

  4. glpi_project_get_open_tasks — Tool semântica para casos de uso N1/PM. Filtra tarefas com percent_done < 100 e projectstates_id != Closed.

Médio prazo (P2)

  1. Migrar TicketTools para InputValidation — eliminar dívida técnica, padronizar erros, ergonomia de nomes vs IDs em campos como users_id_recipient, itilcategories_id.

  2. Tools do roadmap original (KB-020) ainda pendentes:

    • glpi_ticket_get_pending_approvals
    • glpi_ticket_assign_to_me
    • glpi_ticket_add_private_note
    • glpi_computer_get_unassigned
    • glpi_user_get_my_assets

  3. TZ contextual em normalizeDate — Correção média do KB-025, expande data sem hora no TZ do GLPI/usuário.

Longo prazo (P3 — visão estratégica)

  1. Resources MCP (KB-PLUGIN-021) — habilitar caso de uso "LLM como N1":
    • kb://{id} — artigos da KB do GLPI
    • ticket://{id} — ticket completo com followups/solutions
    • document://{id} — anexos
    • computer://{id} — CI técnico
  2. SSE / Streamable HTTP completo — notificações push (novo ticket, SLA estourando)
  3. OAuth2 com escopos finos — separar permissões por escopo de tool

Métricas atuais (v1.2.0 + KPIs — 2026-06-22)

  • Tools registradas: 26 (20 domínio + 6 genéricas)
    • Domínio Ticket (6): get, bi_stats, create, update, add_followup, add_solution
    • Domínio Project (3): get, create, update
    • Domínio ProjectTask (4): get, create, update, delete
    • Domínio KPI (7): mttr_stats, fcr_stats, sla_compliance, team_productivity, backlog_stats, satisfaction_stats, volume_stats (ver KB-PLUGIN-035)
    • Genéricas (6): get_items, get_item, add_item, update_item, delete_item, ticket_search_by_status
  • Arquivos em src/: Boot, Server, ToolRegistry, InputValidation, TicketTools, ProjectTools, ProjectTaskTools, TicketKpiTools (8)
  • Casos reais validados: 2 projetos, 34 tarefas (VALGROUP, TCERJ)
  • Bugs ativos: 1 (baixa — TZ de datas, KB-PLUGIN-025). KB-024 resolvido.
  • Versão atual do plugin: 1.2.0 (em dev origin, aguardando homologação)

O que entrou (commits no repo dev origin)

Rodada de reconciliação (manhã 2026-06-22):

  • dfe2f77 — .gitignore ignora AppleDouble (._*) do macOS
  • 12d209c — fix: glpi_get_items usa range em vez de limit + order em maiúsculas
  • e49d20d — feat: tool de domínio glpi_ticket_bi_stats
  • 4ddd00b — fix: plan_start_date/plan_end_date declarados no inputSchema do ProjectTools

Rodada v1.2.0 (correção dos bugs do roadmap):

  • e588556 — feat: src/InputValidation.php (helpers compartilhados, KB-023)
  • 2e4cdf7 — refactor: ProjectTools::resolveStateId delega a InputValidation
  • 0ca94fc — feat: src/ProjectTaskTools.php CRUD via ORM (KB-024 Correção #2)
  • 09ce92c — fix: Server::makeRequest propaga 4xx/5xx (KB-024 Correção #1, resolve silent-success)
  • 900da62 — chore(release): bump 1.1.1 → 1.2.0

Roadmap ainda em aberto

  • 🔲 glpi_project_update estendido com datas/estado/tipo (hoje só name/content/percent_done)
  • 🔲 ProjectTools::buildInputFromArgs — handleCreate ainda monta input inline
  • 🔲 Migrar TicketTools para InputValidation (dívida técnica — P2)
  • 🔲 KB-024 Correção #3 — probe/documentação de itemtypes quebrados na v2
  • 🔲 TZ contextual em normalizeDate (KB-PLUGIN-025, severidade baixa)