Rodolpho Lopes 200cd6c2ce kb: KB-PLUGIN-031 runbook de workflow dev/deploy de plugins + commit dos registros 021-030 pendentes

- Novo runbook KB-PLUGIN-031: nascimento do plugin ate validacao E2E no
  GLPI dev (scaffold, Forgejo local, deploy CT100, console, bootstrap
  Kernel para testes CLI). Validado de ponta a ponta com o assetinherit.
- Registros KB-PLUGIN-021..030 existiam apenas no disco (drift) e foram
  incluidos no versionamento; index.json sincronizado via kb-fix.
- Ignora lixo AppleDouble/.DS_Store do macOS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-11 17:59:47 +00:00

5.8 KiB

Raw Blame History

title

domain

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

Contexto

Esta KB é um ponto de salvamento do estado do plugin mcprotocol após a rodada de evolução de tools de Project + ProjectTask + extração da camada de validação. Serve de referência canônica para o estado atual e backlog priorizado.

Estado atual das tools

Tools de domínio (ORM direto)

Tool	Status	Notas
`glpi_ticket_get`	✅
`glpi_ticket_create`	✅
`glpi_ticket_update`	✅
`glpi_ticket_add_followup`	✅
`glpi_ticket_add_solution`	✅
`glpi_project_get`	✅	Retorna tarefas com `projecttasks_id` (hierarquia)
`glpi_project_create`	✅	Aceita estado/tipo por nome, datas, validação prévia
`glpi_project_update`	✅	Estendido com os mesmos campos do create + `percent_done`
`glpi_projecttask_get`	✅ NOVO
`glpi_projecttask_create`	✅ NOVO	Suporta hierarquia (parent task), responsável, duração, estado
`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 + ProjectTask
`src/InputValidation.php`	✅ NOVO — helpers compartilhados (KB-PLUGIN-023)
`src/TicketTools.php`	✅ Ainda usa padrão antigo — candidato a migrar pro `InputValidation`
`src/ProjectTools.php`	✅ Refatorado pra usar `InputValidation`
`src/ProjectTaskTools.php`	✅ NOVO
`ajax/mcp.php`	✅ Endpoint stateless com JWT

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)

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.
glpi_projecttask_delete — Correção #2 do KB-024. Tool de domínio bypassa REST API, usa ORM direto.
glpi_projecttask_update — completar o CRUD de tarefas. Necessário para casos como "atualizar percent_done", "remarcar datas".
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)

Migrar TicketTools para InputValidation — eliminar dívida técnica, padronizar erros, ergonomia de nomes vs IDs em campos como users_id_recipient, itilcategories_id.
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
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)

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
SSE / Streamable HTTP completo — notificações push (novo ticket, SLA estourando)
OAuth2 com escopos finos — separar permissões por escopo de tool

Métricas atuais

Tools registradas: 16 (11 domínio + 5 genéricas)
Casos reais validados: 2 projetos, 34 tarefas
KBs do plugin: 14 (incluindo este snapshot)
Bugs ativos: 3 (1 alta, 1 média, 1 baixa)
Versão atual do plugin: 1.1.0 (próxima release: 1.2.0)

Próxima versão proposta — v1.2.0

Conteúdo já no branch main do dev (a fazer push):

Adicionada src/InputValidation.php com helpers compartilhados
Adicionada src/ProjectTaskTools.php com glpi_projecttask_get e glpi_projecttask_create
Estendida src/ProjectTools.php — update agora aceita datas, estado, tipo
Atualizado src/ToolRegistry.php registrando ProjectTaskTools
KBs documentando padrões (022, 023), bugs (024, 025) e snapshot (026)

Conteúdo para v1.2.1+ (correções dos bugs documentados):

Server.php::makeRequest validando HTTP status
ProjectTaskTools::handleDelete (glpi_projecttask_delete)
glpi_projecttask_update

5.8 KiB Raw Blame History