mgummich/mealie-skill

Manutenção Mealie

Sempre três fases: ANÁLISE -> PLANO -> EXECUÇÃO. Nada é escrito sem aprovação explícita do plano. Nunca misture dois tipos de tarefa em um único plano.

Escolha um modo e leia a referência correspondente

Leia apenas a referência para o modo atual, não todas elas:

Tarefa	Referência
Limpar uma receita, analisar ingredientes, preencher campos	references/recipes.md
Alimentos: lacunas, correspondência, duplicatas	references/foods.md
Unidades: lacunas, duplicatas, conversão para métrico	references/units.md
Rótulos de lista de compras: paleta, lacunas, eixo	references/labels.md
Consolidar categorias, tags, ferramentas	references/organizers.md
Criar ou reformular um livro de receitas	references/cookbooks.md
Receitas duplicadas, linhas de ingredientes quebradas, links mortos, tags de dieta	references/maintenance.md
O campo extras em receitas, alimentos e unidades	references/extras.md
Planejamento de refeições, importação de receita de uma URL, trabalho com o servidor MCP	references/mcp.md

O formato AÇÕES é o mesmo para todos os modos: references/actions.md. Leia esse arquivo somente quando a fase 2 estiver programada.

Leia references/mcp.md sempre que o servidor MCP mcp-mealie estiver conectado — ele muda como todos os outros modos coletam seus dados.

Ferramenta

O script scripts/mealie_ctx.py encapsula todas as chamadas à API. Não leia seu código-fonte, chame-o com --help.

O caminho é relativo ao diretório deste skill, não ao diretório de trabalho — prefixe cada chamada com ele, caso contrário o comando não é encontrado:

python .agents/skills/mealie/scripts/mealie_ctx.py <comando>

setup [--check]                    verifica a conexão, armazena credenciais
index [--refresh]                  constrói o índice local de receitas
audit <o que> [--limit N]          alimentos unidades rótulos categorias tags
                                   ferramentas receitas links extras
ctx receita <slug> [--search T]    receita + alimentos correspondentes + organizadores
                    [--full]       JSON completo, raramente necessário
ctx <o que> [--limit N] [--group G] alimentos unidades categorias tags ferramentas
                                   livros de receitas dieta
uso <tipo> <id>                    receitas usando um alimento/unidade/categoria/tag/ferramenta
converter "<quantidade>" [...]     quantidade não métrica -> métrica + a
                                   Observação Original; também °F e polegada
regras [--init]                    regras da casa desta instância
semente rótulos|unidades|tudo [--out F] ações para um vocabulário fixo
aplicar <arquivo> [--slug S] [--dry-run]

A primeira chamada audit constrói o índice (uma passagem sobre todas as receitas, demora um tempo dependendo do tamanho da instância). Todas as auditorias posteriores leem dele. Após cada aplicar com escrita, o índice é descartado e reconstruído.

Três destes substituem coisas que você escreveria à mão, mal feitas:

• converter contém a tabela de densidades e as regras de arredondamento e retorna a nota Original:. Nunca converta uma quantidade imperial de cabeça.
• regras imprime as decisões desta instância - localidade, eixo de categoria, suposições de recipiente, a tabela que resolve alimentos genéricos (pimenta -> pimenta preta [moída]). Leia antes de criar ou renomear qualquer coisa, e adicione uma linha em vez de decidir a mesma questão duas vezes.
• semente escreve os vocabulários fixos - os 29 rótulos com suas cores de zona, o conjunto de unidades métricas - como um arquivo AÇÕES, pulando o que já existe.

aplicar registra cada ação em .mealie.changelog.jsonl com o estado que sobrescreveu, recusa um patch_recipe que encurtaria um campo de lista e um payload de livro de receitas escrito para Mealie 1.x (um queryFilterString, nunca tags/categories/tools/requireAll*), e verifica o plano - fatalmente para uma unidade não métrica. --dry-run executa as mesmas verificações. Detalhes em references/actions.md.

Comandos de contexto retornam dados filtrados. Nunca carregue tabelas completas não filtradas, nunca construa loops de receitas manualmente - é para isso que serve o índice.

Variáveis de ambiente: MEALIE_URL, MEALIE_TOKEN — MEALIE_API_TOKEN (o nome do mcp-mealie para o token), MEALIE_BASE_URL e MEALIE_API_KEY são lidas também. Se não estiverem definidas, o script as lê de .mealie.env e depois de .env no diretório de trabalho. Qualquer comando que não encontrar nenhuma aborta com uma dica para setup.

O script precisa de acesso de rede à instância. Em um ambiente isolado a chamada falha com um erro de conexão mesmo que a URL e o token estejam corretos - isso é uma permissão do ambiente, não um bug na configuração. Diga isso e deixe o usuário permitir a chamada. Nunca contorne isso com um script HTTP escrito à mão: mealie_ctx.py é o único caminho para a API, e um segundo não tem a proteção de ordem nem a simulação. Onde o servidor MCP estiver conectado, suas chamadas passam pelo servidor e não são afetadas.

setup --check apenas testa a configuração e é seguro executar sozinho - use-o uma vez no início de uma sessão quando a conexão não estiver clara. O setup simples solicita URL e token e deve ser executado pelo usuário, não por você: pergunte e aguarde. Nunca peça o token no chat e nunca o escreva em um arquivo você mesmo.

Se o servidor MCP mcp-mealie estiver conectado, use-o para análise em vez disso: ele responde às perguntas de auditoria no lado do servidor, então o índice não é construído, e cobre o que este script deliberadamente não possui — planejamento de refeições, importação de receita de uma URL, pesquisa interativa de receitas. O script mantém o lote ordenado: planos que precisam de ORDER ou uma simulação sobre todo o conjunto ainda passam por actions.json e aplicar. Leia references/mcp.md primeiro.

Estilo de saída: homem das cavernas

Se o skill caveman estiver disponível, ative-o para este fluxo de trabalho. Auditorias, planos e relatórios são saídas tabulares longas - exatamente o caso onde a compressão compensa. Sem o skill: responda normalmente, mas de forma concisa - tabelas em vez de prosa, sem repetir o que a ferramenta já imprimiu.

Apenas a saída do chat é comprimida - análise, plano, relatório, seus comentários intermediários. Duas coisas permanecem em prosa completa ${CONTENT_LANG}:

• Tudo escrito para o Mealie, ou seja, tudo em actions.json. É conteúdo de banco de dados, não chat; veja references/actions.md.
• Avisos sobre operações destrutivas, perguntas quando estiver em dúvida e a pergunta de aprovação. Para uma mesclagem que reescreve 14 receitas, ser inequívoco vale mais do que alguns tokens salvos.

Regras para todos os modos

Nada invente: ingredientes, quantidades e passos são apenas estruturados, traduzidos e corrigidos, nunca adicionados ou removidos. Valores corretos existentes permanecem.

Todo o conteúdo em ${CONTENT_LANG}; termos culinários consagrados (sous-vide, roux, ganache) permanecem como estão. Unidades métricas.

Marque estimativas no relatório. Quando em dúvida, deixe um campo vazio em vez de adivinhar.

Pesquise antes de criar - para alimentos, unidades e organizadores igualmente. Verifique também variantes ortográficas, singular/plural e equivalentes em língua estrangeira.

Marque operações destrutivas (merge_*, delete_organizer, retag_recipe) explicitamente no plano, com o número de receitas afetadas, e aponte que elas não podem ser desfeitas.

Mantenha lotes pequenos: no máximo 25 lacunas de alimentos/unidades ou 5 grupos duplicados/de organizadores por execução. Receitas têm sua própria regra - uma receita por plano para ingredientes, passos e notas, qualquer número para alterações em nível de campo; veja references/recipes.md.

Em caso de aborto, nenhuma tentativa especulativa de reparo - relate o estado alcançado e pergunte.