recipal-mcp-unofficial

Un servidor MCP para la API de etiquetas nutricionales de ReciPal. Permite que un asistente de IA lea y edite tus recetas, ingredientes y subrecetas directamente, incluidas operaciones masivas que llevarían horas en la interfaz web.

No oficial. No está afiliado, respaldado ni soportado por ReciPal. Creado por usuarios del producto contra su API pública.

Proyecto provisional: este repositorio se archivará. ReciPal está desarrollando un servidor MCP oficial. Cuando el suyo se publique, este se actualizará para apuntar a él y luego se archivará en modo de solo lectura. No construyas nada crítico sobre él. Consulta SUNSET.md.

Necesitas una suscripción de pago activa de ReciPal. El acceso a la API es una función de pago; la clave se obtiene en la configuración de tu cuenta, en API access. Sin ella, este servidor no puede hacer nada.

Para qué sirve

La interfaz web de ReciPal está bien para editar una receta. Es dolorosa cuando necesitas hacer lo mismo con cuarenta: corregir un tamaño de ración en todo un catálogo, renombrar ingredientes que llegaron con sufijos (copy), o crear una familia de variantes de producto que difieren en un solo ingrediente. Este servidor expone la API para que un asistente pueda hacer ese trabajo en un bucle, con una prueba en seco primero.

La herramienta que justifica su existencia es bulk_clone_and_swap: toma una receta totalmente configurada como plantilla, clónala N veces y sustituye un solo ingrediente en cada clon. La configuración de etiquetas, las etiquetas y los tamaños de ración se conservan, por lo que los clones salen coherentes.

Related MCP server: cookwith-mcp

Alcance y distribución

Deliberadamente limitado, y así seguirá:

• Código fuente que clonas y compilas. No hay un paquete de plugin de un clic, ni paquete npx, ni listado en ningún directorio o mercado de MCP. Es un compromiso adquirido con ReciPal, no un descuido ni una tarea pendiente.

• No publicado en npm. El package.json está marcado como private a propósito.

• Nombrado recipal-mcp-unofficial a petición de ReciPal, para que no se confunda con su servidor oficial.

Las solicitudes de extracción que añadan distribución empaquetada, envíos a mercados o una ruta de instalación más amigable para el consumidor serán rechazadas. Consulta CONTRIBUTING.md para saber qué es bienvenido.

Instalación

Requiere Node.js 18 o superior.

git clone https://github.com/BlackBlack/recipal-mcp-unofficial.git
cd recipal-mcp-unofficial
npm install
npm run build

Luego regístralo con tu cliente MCP. Para Claude Code:

claude mcp add --transport stdio recipal-mcp-unofficial \
  --env RECIPAL_API_KEY=your_key_here \
  -- node /absolute/path/to/recipal-mcp-unofficial/build/index.js

Para Claude Desktop, añade a claude_desktop_config.json:

{
  "mcpServers": {
    "recipal-mcp-unofficial": {
      "command": "node",
      "args": ["/absolute/path/to/recipal-mcp-unofficial/build/index.js"],
      "env": { "RECIPAL_API_KEY": "your_key_here" }
    }
  }
}

Reinicia el cliente y luego pídele que liste tus recetas. Deberías ver 19 herramientas disponibles. Guía completa en docs/SETUP.md.

⚠️ Lee esto antes de apuntarlo a un catálogo que te importa

Las protecciones confirm: true y dry_run las proporciona el modelo, no tú. Evitan que un prompt redactado de forma ambigua cause daños. No detienen a un agente decidido o confundido: un asistente que decida eliminar una receta pasará confirm: true en la misma llamada. ReciPal no tiene deshacer.

Por eso, las herramientas realmente destructivas están desactivadas por defecto. Activarlas es un acto deliberado de la persona que ejecuta el servidor, no algo que una conversación pueda hacer:

Todo lo demás (todas las lecturas y las herramientas habituales de creación/actualización) funciona sin configuración adicional. Las herramientas masivas están siempre disponibles, pero por defecto usan dry_run: true y se niegan a ejecutarse a menos que quien llama pase tanto dry_run: false como confirm: true.

Práctica recomendada en cualquier caso: trabaja primero con una receta desechable. Varios endpoints se comportan de forma distinta a lo que sugieren los documentos (consulta Limitaciones conocidas).

Configuración

Consulta .env.example.

Herramientas

22 herramientas en total, 19 expuestas por defecto. Referencia generada con cada parámetro: docs/TOOLS.md.

† deshabilitadas por defecto.

Las herramientas de escritura aceptan un objeto fields abierto en lugar de una lista fija de parámetros. Los documentos publicados de ReciPal se truncan antes de la lista completa de atributos de receta, por lo que codificar los nombres de los campos habría significado adivinar; en su lugar, fields se pasa directamente, codificado como formulario estilo Rails (recipe[name]=...). Los atributos no documentados funcionan sin cambiar el código. Establece as_json: true si un endpoint prefiere JSON.

Lee una receta real antes de escribir en una. get_recipe sobre una receta existente muestra los nombres exactos de atributos que usa tu cuenta.

Limitaciones conocidas

Estas son reales, verificadas contra la API en vivo, y vale la pena conocerlas antes de construir sobre esto:

• create_recipe_shortcut no funciona. Devuelve HTTP 422 para cada formato de matriz de ingredientes probado. Los documentos de ReciPal se truncan antes de la lista de parámetros, por lo que se desconoce la forma correcta. Usa create_recipe + create_recipe_ingredient, o scale_recipe para clonar una plantilla configurada. La herramienta se deja en su lugar para que se pueda descubrir la forma; si la averiguas, abre un PR.

• PUT /recipe_ingredients/{id} ignora silenciosamente ingredient_id. Devuelve HTTP 200 con el ingrediente original aún adjunto. Sustituir un ingrediente por otro debe hacerse como eliminar y luego crear, que es lo que hace bulk_clone_and_swap internamente.

• ReciPal envuelve dos veces casi todas las respuestas — {recipe: {recipe_ingredients: [{recipe_ingredient: {…}}]}}. Leer campos del sobre exterior produce undefined sin error. Si amplías este servidor, usa los ayudantes existentes unwrap() / extractRecords().

• Los nombres de parámetros de scale_recipe y create_subrecipe no están publicados. Funcionan mediante fields de paso directo, pero ejecuta cada uno una vez contra una receta desechable y lee la respuesta antes de hacer bucles.

• Los documentos listan /recipes/{id}/scale como PUT; POST es lo que realmente funciona. No "arregles" esto sin probarlo.

• No hay ayudante de paginación. list_recipes tiene un límite de 100 por página; recorre las páginas tú mismo.

Límites de velocidad

ReciPal documenta aproximadamente 175 000 solicitudes por semana, 1 000 por minuto (HTTP 429 más allá de eso) y un máximo de 5 renderizados de etiquetas simultáneos. Este servidor respeta el 429 con Retry-After y retroceso exponencial, avisa en stderr cuando quedan menos de 100 solicitudes y ejecuta cada bucle masivo estrictamente en secuencia con un retraso configurable. No paralelices los renderizados de etiquetas.

Desarrollo

npm run typecheck   # tsc --noEmit
npm run build       # -> build/index.js
npm test            # offline smoke tests, no API key or network needed
npm run gen:docs    # regenerate docs/TOOLS.md from the running server
npm run verify      # all of the above

docs/TOOLS.md se genera iniciando el servidor compilado y pidiéndole su propia lista de herramientas, por lo que la referencia no puede desviarse del código. CI falla si está desactualizado. Si añades o cambias una herramienta, ejecuta npm run build && npm run gen:docs y confirma el resultado.

Las contribuciones son bienvenidas dentro del alcance anterior: comienza con CONTRIBUTING.md, luego docs/TESTING.md para saber cómo verificar los cambios con una cuenta real, y docs/DESIGN.md para saber cómo encajan las piezas.

Licencia

Apache-2.0.

«ReciPal» es una marca comercial de su propietario y se usa aquí solo para describir con qué habla este software.