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 f072b1cde7 docs: marca bugs do mcprotocol como resolvidos em v1.2.0 
KB-024 (silent-success do delete): ambas correções implementadas — makeRequest
propaga 4xx/5xx (commit 09ce92c) e glpi_projecttask_delete via ORM (0ca94fc).
KB-023 (InputValidation): arquivos agora realmente implementados; corrige itens
do rascunho que não foram feitos (buildInputFromArgs, project_update estendido).
KB-026 (snapshot): atualizado para v1.2.0 — 19 tools, ProjectTask CRUD, métricas.

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

170 lines
7.9 KiB
Markdown
Raw Blame History

---
id: KB-PLUGIN-026
title: mcprotocol — Snapshot de roadmap v1.2 (pós-ProjectTask + InputValidation)
domain: plugin-dev
tags:
- mcp
- roadmap
- snapshot
- planning
status: active
severity: medium
created_at: 2026-05-26
updated_at: 2026-06-22
applies_to:
- glpi-11
- mcprotocol-plugin
related_records:
- 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)
5. **Migrar `TicketTools` para `InputValidation`** — eliminar dívida técnica, padronizar erros, ergonomia de nomes vs IDs em campos como `users_id_recipient`, `itilcategories_id`.
6. **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`
7. **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)
8. **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
9. **SSE / Streamable HTTP completo** — notificações push (novo ticket, SLA estourando)
10. **OAuth2 com escopos finos** — separar permissões por escopo de tool
## Métricas atuais (v1.2.0 — 2026-06-22)
- **Tools registradas:** 19 (13 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`
- 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` (7)
- **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)
Reference in a new issue View git blame Copy permalink