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 c5947a39d8 docs(KB-026): reconcilia snapshot mcprotocol com estado real (v1.1.1) 
O snapshot original (26/05) era aspiracional e dava como prontos arquivos
que git log --all confirmou nunca terem existido: src/InputValidation.php,
src/ProjectTaskTools.php e as tools glpi_projecttask_*. Tabelas de estado,
métricas e seção de versão corrigidas para refletir o disco. Itens não
implementados rebaixados de 'feito' para 'planejado'. Documentados os
commits que realmente entraram (bi_stats, fix range, schema plan_*_date).

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

7.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 — NÃO estendido com datas/estado
glpi_projecttask_get 📋 planejado Nunca implementado
glpi_projecttask_create 📋 planejado Nunca implementado
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. Pendente: validar HTTP status em makeRequest (KB-024 Correção #1)
src/ToolRegistry.php ✅ Registra Ticket + Project apenas (não ProjectTask)
src/InputValidation.php ❌ Não existe — planejado em KB-PLUGIN-023, nunca implementado
src/TicketTools.php ✅ Padrão antigo de validação inline (sem camada compartilhada)
src/ProjectTools.php ✅ Validação inline; suporta plan_*_date e estado por nome
src/ProjectTaskTools.php ❌ Não existe — planejado, nunca implementado
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 (reconciliadas em 2026-06-22)

  • Tools registradas: 15 (9 domínio + 6 genéricas)
    • Domínio: 6 de Ticket (get, bi_stats, create, update, add_followup, add_solution) + 3 de Project (get, create, update)
    • Genéricas: get_items, get_item, add_item, update_item, delete_item, ticket_search_by_status
  • Arquivos em src/: Boot, Server, ToolRegistry, TicketTools, ProjectTools (5)
  • Casos reais validados: 2 projetos, 34 tarefas (VALGROUP, TCERJ)
  • Bugs ativos: 3 (1 alta, 1 média, 1 baixa)
  • Versão atual do plugin: 1.1.1

O que realmente entrou desde o snapshot original

Reconciliação 2026-06-22 (commits no repo dev forgejo):

  • 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

Roadmap NÃO implementado (rebaixado de "feito" para "planejado")

Itens que o snapshot original dava como prontos, mas que nunca existiram:

  • src/InputValidation.php — camada de validação compartilhada (KB-PLUGIN-023)
  • src/ProjectTaskTools.php — glpi_projecttask_get / glpi_projecttask_create
  • glpi_project_update estendido com datas/estado
  • Server.php::makeRequest validando HTTP status (Correção #1 do KB-024 — ainda aberto)
  • glpi_projecttask_delete / glpi_projecttask_update