mgummich/mealie-skill

Mantenimiento de Mealie

Siempre tres fases: ANÁLISIS -> PLAN -> EJECUCIÓN. No se escribe nada sin la aprobación explícita del plan. Nunca mezclar dos tipos de tarea en un mismo plan.

Elegir un modo y leer la referencia correspondiente

Leer solo la referencia para el modo actual, no todas:

Tarea	Referencia
Limpiar una receta, analizar ingredientes, rellenar campos	references/recipes.md
Alimentos: carencias, coincidencias, duplicados	references/foods.md
Unidades: carencias, duplicados, conversión a métrico	references/units.md
Etiquetas de lista de la compra: paleta, carencias, eje	references/labels.md
Consolidar categorías, etiquetas, herramientas	references/organizers.md
Crear o reelaborar un libro de cocina	references/cookbooks.md
Recetas duplicadas, líneas de ingredientes rotas, enlaces muertos, etiquetas dietéticas	references/maintenance.md
El campo extras en recetas, alimentos y unidades	references/extras.md
Plan de comidas, importación de receta desde URL, trabajar con el servidor MCP	references/mcp.md

El formato de ACCIONES es el mismo para todos los modos: references/actions.md. Leer ese archivo solo cuando la fase 2 esté pendiente.

Leer references/mcp.md cada vez que el servidor MCP mcp-mealie esté conectado — cambia la forma en que todos los demás modos recopilan sus datos.

Herramienta

scripts/mealie_ctx.py envuelve cada llamada a la API. No leer su código fuente, llamarlo con --help.

La ruta es relativa a este directorio del skill, no al directorio de trabajo — anteponerla a cada llamada, de lo contrario no se encuentra el comando:

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

setup [--check]                    verificar la conexión, almacenar credenciales
index [--refresh]                  construir el índice local de recetas
audit <qué> [--limit N]           alimentos unidades etiquetas categorías etiquetas
                                   herramientas recetas enlaces extras
ctx receta <slug> [--search T]     receta + alimentos coincidentes + organizadores
                  [--full]         JSON íntegro, raramente necesario
ctx <qué> [--limit N] [--group G] alimentos unidades categorías etiquetas herramientas
                                   libros de cocina dieta
usage <tipo> <id>                  recetas que usan un alimento/unidad/categoría/etiqueta/herramienta
convert "<cantidad>" [...]         cantidad no métrica -> métrica + la
                                   nota Original:; también °F y pulgada
rules [--init]                     reglas internas de esta instancia
seed etiquetas|unidades|todo [--out F]  acciones para un vocabulario fijo
apply <archivo> [--slug S] [--dry-run]

La primera llamada a audit construye el índice (un pase sobre todas las recetas, lleva un tiempo según el tamaño de la instancia). Cada auditoría posterior lee de él. Después de cada apply de escritura, el índice se descarta y se reconstruye.

Tres de estos reemplazan lo que de otro modo escribirías a mano, y mal:

• convert tiene la tabla de densidades y las reglas de redondeo y devuelve la nota Original:. Nunca convertir una cantidad imperial en tu cabeza.
• rules imprime las decisiones de esta instancia: configuración regional, eje de categorías, suposiciones de contenedores, la tabla que resuelve alimentos simples (pimienta -> pimienta negra [molida]). Leerlo antes de crear o renombrar cualquier cosa, y añadir una fila en lugar de decidir la misma cuestión dos veces.
• seed escribe los vocabularios fijos (las 29 etiquetas con sus colores de zona, el conjunto de unidades métricas) como un archivo de ACCIONES, omitiendo lo que ya existe.

apply registra cada acción en .mealie.changelog.jsonl con el estado que sobrescribió, rechaza un patch_recipe que acortaría un campo de lista y una carga útil de libro de cocina escrita para Mealie 1.x (un queryFilterString, nunca tags/categories/tools/requireAll*), y analiza el plan — fallando fatalmente para una unidad no métrica. --dry-run ejecuta las mismas comprobaciones. Detalles en references/actions.md.

Los comandos de contexto ya devuelven datos filtrados. Nunca cargar tablas completas sin filtrar, nunca construir bucles de recetas manualmente — para eso está el índice.

Variables de entorno: MEALIE_URL, MEALIE_TOKEN — MEALIE_API_TOKEN (el nombre de mcp-mealie para el token), MEALIE_BASE_URL y MEALIE_API_KEY también se leen. Si no están establecidas, el script las lee de .mealie.env y luego de .env en el directorio de trabajo. Cualquier comando que no encuentre ninguna aborta con una sugerencia para ejecutar setup.

El script necesita acceso de red a la instancia. En un entorno aislado, la llamada falla con un error de conexión aunque la URL y el token sean correctos — eso es un permiso del entorno, no un error en la configuración. Decirlo y dejar que el usuario permita la llamada. Nunca evitarlo con un script HTTP escrito a mano: mealie_ctx.py es el único camino hacia la API, y un segundo no tiene ni la protección de orden ni la simulación. Cuando el servidor MCP está conectado, sus llamadas pasan a través del servidor y no se ven afectadas.

setup --check solo prueba la configuración y es seguro ejecutarlo tú mismo — usarlo una vez al inicio de una sesión cuando la conexión no está clara. setup sin opciones solicita URL y token y debe ser ejecutado por el usuario, no por ti: preguntarlo y esperar. Nunca pedir el token en el chat ni escribirlo tú mismo en un archivo.

Si el servidor MCP mcp-mealie está conectado, usarlo en su lugar para el análisis: responde las preguntas de auditoría del lado del servidor, por lo que el índice no se construye en absoluto, y cubre lo que este script deliberadamente no tiene: plan de comidas, importación de receta desde URL, búsqueda interactiva de recetas. El script mantiene el lote ordenado: los planes que necesitan ORDER o una simulación sobre todo el conjunto aún pasan por actions.json y apply. Leer references/mcp.md primero.

Estilo de salida: cavernícola

Si el skill caveman está disponible, activarlo para este flujo de trabajo. Las auditorías, planes e informes son salidas tabulares largas — exactamente el caso donde la compresión vale la pena. Sin el skill: responder con normalidad, pero de forma concisa — tablas en lugar de prosa, sin repetir lo que la herramienta ya imprimió.

Solo la salida del chat se comprime — análisis, plan, informe, tus comentarios intermedios. Dos cosas se mantienen en prosa completa en ${CONTENT_LANG}:

• Todo lo escrito en Mealie, es decir, todo lo que está en actions.json. Es contenido de base de datos, no chat; ver references/actions.md.
• Advertencias sobre operaciones destructivas, preguntas cuando no estés seguro y la pregunta de aprobación. Para una fusión que reescribe 14 recetas, ser inequívoco vale más que unos pocos tokens ahorrados.

Reglas para todos los modos

No inventar nada: los ingredientes, cantidades y pasos solo se estructuran, traducen y corrigen, nunca se añaden ni se eliminan. Los valores correctos existentes se conservan.

Todo el contenido en ${CONTENT_LANG}; los términos culinarios establecidos (sous-vide, roux, ganache) se mantienen como están. Unidades métricas.

Marcar las estimaciones en el informe. Ante la duda, dejar un campo vacío en lugar de adivinar.

Buscar antes de crear — para alimentos, unidades y organizadores por igual. Verificar también variantes ortográficas, singular/plural y equivalentes en otros idiomas.

Marcar las operaciones destructivas (merge_*, delete_organizer, retag_recipe) explícitamente en el plan, con el número de recetas afectadas, y señalar que no se pueden deshacer.

Mantener lotes pequeños: como máximo 25 carencias de alimentos/unidades o 5 grupos de duplicados/organizadores por ejecución. Las recetas tienen su propia regla: una receta por plan para ingredientes, pasos y notas, cualquier número para cambios a nivel de campo; ver references/recipes.md.

En caso de aborto, no intentar reparaciones especulativas — informar del estado alcanzado y preguntar.