pwdev-solucoes YouTrack REST (fallback)
Você cobre o que o MCP oficial não expõe, chamando a REST API direto.
Ferramenta única
Todo acesso REST passa por ${CLAUDE_PLUGIN_ROOT}/scripts/yt-api.sh:
yt-api.sh GET "/api/agiles?fields=id,name&\$top=50"
yt-api.sh POST "/api/commands" '{"query":"State Fixed","issues":[{"idReadable":"PROJ-1"}]}'
Proibido montar curl com $YOUTRACK_TOKEN inline — um erro de citação ou
set -x vazaria o token no transcript. O helper monta o header internamente.
Degradação
Sem config (check-setup.sh acusa ausência): não execute. Entregue o comando
modelo com placeholder e aponte /pwdev-youtrack:init. Env var nova exige
reiniciar a sessão.
Convenções da API
fields=obrigatório — sem ele a resposta vem só comid. Seleção aninhada:fields=id,name,sprints(id,name).- Paginação
$top/$skipem toda lista (padrão do servidor é ~42 itens). - Boards e sprints usam ID interno (
105-2) — liste primeiro para obter; issues aceitam ID legível (PROJ-123). - Erros: 401 token · 403 permissão · 404 ID interno vs legível · 400
fields=ou JSON malformado.
Receitas por intenção
| Intenção | Caminho |
|---|---|
| Listar boards | GET /api/agiles?fields=id,name,projects(shortName) |
| Sprints de um board | GET /api/agiles/{id}/sprints?fields=id,name,start,finish,archived |
| Issues de um sprint | busca Board <nome>: {<sprint>} (REST ou MCP search_issues) |
| Mover issue para sprint | POST /api/commands query Board <nome> <sprint> |
| Comando em lote | POST /api/commands com várias issues |
| Work items (leitura) | GET /api/issues/{id}/timeTracking/workItems?fields=... |
| Anexos | GET/POST /api/issues/{id}/attachments (upload multipart) |
Receitas completas com exemplos prontos:
${CLAUDE_PLUGIN_ROOT}/references/rest-api.md.
Regras
- Mutação (
POST/DELETE) só com o comando à vista e confirmação — especialmente/api/commands, que altera várias issues de uma vez. - Leitura (
GET) roda livre. - Não substitua o MCP no que o MCP cobre (issues CRUD, comentários, artigos,
log_work) — ver skill
youtrack. - Datas de work item são epoch ms UTC — converta antes de exibir.
Limites
- Não administra a instância (usuários, permissões, workflows)
- Não deleta boards nem sprints
- Não faz upload de arquivo sem o usuário indicar o caminho explicitamente
Skills relacionadas
youtrack — dia a dia de issues via MCP oficial