Gaggimate MCP

Permite que un agente LLM controle su máquina de espresso Gaggimate.

GitHub
37
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Gaggimate

Barista de IA de bricolaje — Deja que tu agente de IA controle directamente tu Gaggimate

Entrada de blog: Convertí a Claude en un barista de IA que controla mi máquina de espresso

Ya puedes pedir consejo a un LLM sobre cómo ajustar tu espresso, y modelos como Claude, ChatGPT o Gemini ya pueden generar perfiles de Gaggimate en formato JSON.

Este repositorio proporciona dos cosas:

  1. Un servidor MCP que permite a tu agente LLM interactuar directamente con tu máquina Gaggimate—sin copiar y pegar ni subir archivos manualmente. Tu agente LLM puede leer tu historial de shots, analizar extracciones, almacenar tus comentarios de cata, subir perfiles generados y ajustarlos según tus resultados y deseos.

  2. Instrucciones, conocimientos y habilidades para guiar al agente sobre cómo ayudarte a ajustar tu espresso—convirtiendo un LLM de propósito general en un entrenador de barista que entiende la teoría de extracción, el vocabulario de cata, los perfiles de presión y el sistema de perfiles de Gaggimate. Gracias a Charlie Hall por permitirme usar y adaptar los archivos de conocimiento y los patrones de diagnóstico de su proyecto gaggimate-barista.

Tabla de contenidos

Qué hay en este repositorio

Servidor MCP — Nueve herramientas y ocho recursos que dan a tu IA acceso directo a tu máquina y a tus datos locales:

  • Leer datos de shots — Curvas de temperatura, lecturas de presión, caudales, tiempos de extracción
  • Gestionar perfiles — Crear, actualizar y listar perfiles de preparación directamente en tu dispositivo
  • Registrar comentarios — Guardar valoraciones y notas de cata sincronizadas con tu Gaggimate
  • Explorar historial — Listar shots recientes con filtros
  • Diagnosticar problemas — Solución de problemas de conexión automatizada
  • Gestionar cafés — Crear y actualizar archivos de seguimiento de café con diario de preparación
  • Configuración de usuario — Almacenar y recuperar tu equipo y preferencias
  • Mapa de molido — Registrar ajustes de molido exitosos entre cafés
  • Información de preparación — Acumular patrones y aprendizajes entre cafés
  • Recursos de conocimiento — Acceso bajo demanda a archivos de conocimiento sobre espresso (incluidos subdirectorios)

Archivos de conocimiento (10 archivos) — Materiales de referencia que transforman un LLM de propósito general en un entrenador de barista funcional:

  • Teoría de extracción de espresso, estilos de shots y jerarquía de variables
  • Vocabulario de cata (cómo describir ácido vs. amargo, cuerpo, dulzor)
  • Guía de presión con matriz de tueste × procesamiento
  • Ciencia de la extracción (canalización, preparación de la pastilla, mecánica de la preinfusión)
  • Frescura y almacenamiento del grano (cronología de CO2, ventanas de reposo)
  • Biblioteca de perfiles con 8 plantillas listas para usar
  • Reglas de tamaño de cesta y dosis
  • Vaporizado de leche y especificaciones de bebidas
  • Estrategias de descafeinado y mezclas
  • Esquema completo de perfiles de Gaggimate y ejemplos

Habilidades (5 habilidades) — Habilidades de Claude Desktop con divulgación progresiva (cargan referencias detalladas solo cuando es necesario):

  • gaggimate-profiles — Creación de perfiles con carga de referencias condicional
  • new-coffee — Investigar nuevos granos, recomendar parámetros, subir perfil
  • diagnose — Análisis de telemetría de shots con correlación de datos de cata
  • feedback — Bucle completo de comentarios de shots con registro y recomendaciones
  • knowledge-lookup — Enrutador de preguntas y respuestas de conocimiento que cita el archivo de conocimiento correcto

Consulta Ejemplo: Uso de ChatGPT para crear perfiles manualmente para Gaggimate por Dule Rabbit — este servidor MCP automatiza todo ese flujo de trabajo.

Registro de cambios

2026-04-22

  • Indicadores de canalización v2: Reescrito el cálculo de riesgo de canalización en torno a cuatro indicadores independientes, cada uno detectando una firma física específica, con campos descriptores separados de los indicadores puntuados.
    • Recorte de ventana (V4): Después del recorte de rampa de presión existente, también elimina las muestras de flujo cero iniciales y finales (válvula cerrada al entrar, corte volumétrico al salir). Elimina la clase de falsos positivos de calificación ALTA causados por colas de presión atrapada.
    • Fluctuación de flujo (V5): flow_jitter_ml_s reemplaza la desviación estándar bruta como indicador principal de inestabilidad de flujo. Mide la desviación estándar de la primera diferencia, por lo que las rampas de flujo diseñadas ya no inflan la puntuación. Nuevas bandas de anotación: ESTABLE <0.05, FLUCTUACIÓN_MODERADA 0.10–<0.20, FLUCTUANTE ≥0.20; el umbral puntuado para +2 puntos comienza en ≥0.10.
    • Seguimiento de objetivo (V6): flow_vs_target_residual_ml_s — desviación estándar de (flujo real − objetivo) — es la huella de canalización más clara en perfiles liderados por flujo. null en perfiles liderados por presión, en cuyo caso pressure_jitter_bar llena el espacio del indicador.
    • Fuga de flujo tardío sin tendencia: flow_acceleration_late_ml_s2 ahora es late_slope − overall_slope para que los perfiles con flujo en rampa se lean como estables en lugar de "acelerando al final".
    • Renombrado de campos (ruptura): ChannelingIndicators.overall_risk → channeling_risk; flow_volatility_ml_s → flow_spread_ml_s (descriptor, sin puntuar); pressure_volatility_bar eliminado en favor de pressure_jitter_bar. pressure_stability_bar / flow_stability_ml_s por fase renombrados a pressure_jitter_bar / flow_jitter_ml_s para coincidir.
    • Anotaciones orientadas al agente: Nuevas anotaciones primary_signal, guidance, flow_shape, window_confidence dejan claro al LLM por qué se activó una calificación y cuánta confianza darle.
    • Versión de la habilidad de diagnóstico incrementada; SHOT_DIAGNOSTICS_REFERENCE.md reescrito para el nuevo esquema.

2026-02-23

  • Deduplicación de conocimiento Fase 3: Reducido GAGGIMATE_PROFILE_CREATION_GUIDE.md de 1113 → 130 líneas (reducción del 88%). Ahora es un centro de navegación que enlaza a archivos knowledge/profiles/ detallados en lugar de duplicar su contenido
  • Referencia de procesamiento de café: Añadido COFFEE_PROCESSING.md — guía completa de 7 métodos de procesamiento (lavado, natural, honey, etc.) y sus implicaciones para la extracción de espresso
  • Referencias cruzadas enriquecidas: Añadidos enlaces de métodos de procesamiento a PRESSURE_GUIDE.md y INSTRUCTIONS.md
  • Palabras orientadas al agente: Reducidas de 29,828 → 27,869 (reducción de ~1,960 palabras) mediante deduplicación mientras se llenan vacíos de contenido

2026-02-21

  • Diagnóstico de shots basado en física: analyze_shot ahora calcula resistencia de pastilla (P/F²), puntuación de riesgo de canalización, seguimiento de desviación de temperatura, estabilidad de presión/flujo, métricas de cumplimiento de perfil y desgloses por fase — todo con anotaciones de banda legibles por humanos
  • Sistema de detalle de 3 niveles: Nuevo parámetro detail (summary/per_phase/detailed) controla la profundidad del diagnóstico frente al costo de tokens. Resumen para triaje, por_fase para aislar problemas, detallado para series temporales completas
  • Umbrales de diagnóstico calibrados: Bandas de tasa de caída de presión ampliadas para ruido de muestreo de 100 ms, bandas de sobreimpulso de temperatura ajustadas para coincidir con la tolerancia INEI ±2°C, etiquetas de tasa de rampa renombradas de LENTO/RÁPIDO a SUAVE/AGRESIVO para evitar juicios de valor sobre rampas de preinfusión intencionalmente lentas
  • Documentación de investigación: Añadido knowledge/research/ESPRESSO_PHYSICS_AND_THRESHOLD_CALIBRATION.md con justificación física y citas de fuentes para todas las decisiones de umbral

2026-02-20

  • Seguimiento narrativo de café: Los archivos de café ahora almacenan análisis e ideas en lugar de números brutos — enfoque de preparación (narrativo), entradas de diario (análisis fechado) e ideas clave. Los datos brutos de shots permanecen en el dispositivo; el agente registra pensamiento y aprendizajes
  • Información de preparación: Nueva herramienta manage_brewing_insights y recurso gaggimate://user/brewing-insights para reconocimiento de patrones entre cafés — qué funciona para qué origen, qué perfiles se adaptan a qué método de procesamiento, aprendizajes generales que se transfieren entre cafés
  • Conocimiento como recursos MCP: Movidos 10 archivos de referencia de habilidades (estructura de perfiles, modos de bomba, árboles de diagnóstico, patrones de telemetría, etc.) de directorios de habilidades incluidos a subdirectorios knowledge/{profiles,diagnostics,research}/, servidos a través de recursos MCP. Las habilidades ahora son archivos SKILL.md ligeros de un solo archivo que cargan referencias bajo demanda a través de gaggimate://knowledge/{subdir}/{filename}
  • Mejoras de integración de habilidades: La habilidad de búsqueda de conocimiento ahora enruta a recursos de datos de usuario (mapa de molido, configuración, cafés). La habilidad de diagnóstico lee el historial de café para contexto. La habilidad de comentarios referencia cruzada el mapa de molido para configuraciones exitosas
  • Renombrado consult → knowledge-lookup: El nombre de la habilidad ahora describe lo que hace — busca conocimiento de espresso en archivos autorizados
  • Herramienta manage_coffee simplificada: Reducida de 27 a 16 parámetros. Reemplazada la acción log_shot (8 columnas numéricas) con la acción log_entry (fecha, titular, cuerpo narrativo)
  • Cobertura de pruebas: 206 pruebas pasando (desde 192)

2026-02-15

  • Recursos MCP: Añadidos 6 recursos MCP de solo lectura para acceso bajo demanda a archivos de conocimiento, archivos de seguimiento de café, configuración de usuario y mapa de molido — sin necesidad de subir archivos manualmente
  • Herramienta de seguimiento de café: Nueva herramienta MCP manage_coffee para crear, actualizar, eliminar archivos de café y registrar shots con seguimiento persistente entre sesiones
  • Herramienta de configuración de usuario: Nueva herramienta MCP manage_user_setup para almacenar y recuperar equipo/preferencias
  • Herramienta de mapa de molido: Nueva herramienta MCP manage_grind_map para registrar ajustes de molido exitosos entre cafés
  • Reestructuración de directorios: agent-knowledge/ → knowledge/, nuevos directorios coffees/ y user/ para datos locales
  • Instrucciones y habilidades actualizadas: Todas las instrucciones y habilidades del agente ahora referencian recursos y herramientas MCP en lugar de subidas de archivos estáticos
  • Ayudantes de almacenamiento: Nuevo módulo storage/markdown.py para operaciones CRUD de archivos markdown

2026-02-14

  • Base de conocimiento ampliada: Añadidos 7 nuevos archivos de conocimiento adaptados de gaggimate-barista por Charlie Hall — guía de presión, ciencia de extracción, frescura de grano, biblioteca de perfiles, cestas, leche y bebidas, y categorías especiales (descafeinado/mezclas)
  • Conocimiento existente enriquecido: Añadida jerarquía de variables, árbol de decisión de diagnóstico, regla de canalización (Scott Rao) y referencias cruzadas a los archivos existentes de fundamentos de preparación y guía de cata
  • 4 nuevas habilidades: Añadidas new-coffee (investigación de grano → perfil), diagnose (análisis de telemetría), feedback (bucle de comentarios de shots) y knowledge-lookup (enrutador de preguntas y respuestas de conocimiento)
  • Habilidad gaggimate-profiles enriquecida: Añadida conciencia de métodos de procesamiento, referencias de matriz de presión × tueste, carga de referencias condicional y paso de subida MCP
  • Artefacto de seguimiento de café: Nuevo concepto para memoria persistente entre sesiones de Claude Desktop — el agente crea un documento de seguimiento markdown que los usuarios pueden guardar y volver a subir
  • Instrucciones del agente actualizadas: Tabla de referencia de archivos de conocimiento, directorio de habilidades, flujo de trabajo de seguimiento de café, jerarquía de variables y regla de canalización ácido-Y-amargo

2026-02-03

  • Actualizaciones parciales de perfiles: Actualiza solo los campos que quieras cambiar (temperatura, fases o nombre) — los campos omitidos conservan sus valores existentes
  • Eliminar perfiles: Añadido action='delete' a manage_profile con medidas de seguridad:
    • Solo se pueden eliminar perfiles creados por IA (que terminan en [AI])
    • Requiere confirm_delete=True explícito para prevenir accidentes
    • Los perfiles eliminados se pueden recuperar desde la copia de seguridad local (consulta Almacenamiento de datos local)
  • Notas de shots simplificadas: action='get' ahora lee del dispositivo (fuente de verdad); el almacenamiento local es solo copia de seguridad para usuarios
  • Documentación de almacenamiento de datos local: Añadida documentación que explica qué se almacena localmente y las limitaciones de acceso del agente
  • Corrección de errores: Corregida la llamada al método get_profile → load_profile que causaba fallos de actualización

2026-02-02

  • Marcadores de IA configurables (edc8d98): El sufijo del perfil de IA y el prefijo de notas ahora son configurables mediante las variables de entorno GAGGIMATE_AI_PROFILE_SUFFIX y GAGGIMATE_AI_NOTES_PREFIX
  • Corrección de errores (a350246): Las actualizaciones de perfil ahora conservan la configuración de válvulas y el tipo de perfil (simple/pro) en lugar de restablecerlos
  • Documentación automática de Pro (bfc2ca0): Se agregó una guía completa para perfiles Automáticos Pro con ejemplos de presión variable basados en flujo

El Flujo de Ajuste

flowchart LR
    A[☕ Pull shot] --> B[💬 AI asks for feedback]
    B --> C[📝 Stored in shot notes]
    C --> D[🤖 AI analyzes & suggests]
    D --> E[📋 AI updates profile]
    E --> A

Mejora iterativamente tus shots con retroalimentación guiada por IA:

  1. Prepara un shot y pruébalo
  2. La IA te pide retroalimentación—hará preguntas específicas sobre el equilibrio (ácido/amargo), cuerpo, dulzura y sabores específicos para ayudarte a expresar lo que estás degustando
  3. La retroalimentación se guarda en tus notas del shot en Gaggimate, creando un registro de tu proceso de ajuste
  4. La IA analiza los datos de tu shot (curvas de presión, temperatura, flujo) combinados con tus notas de cata
  5. La IA sugiere ajustes—explicando el porqué (por ejemplo, "esa acidez sugiere extracción insuficiente, muele más fino o aumenta la temperatura")
  6. La IA actualiza tu perfil directamente en tu máquina, o recomienda cambios en la molienda
  7. Repite hasta que esté perfectamente ajustado

Cómo empezar con un café nuevo:

  • Comparte una foto de tu bolsa de café, o simplemente dile a la IA qué estás preparando
  • La IA investigará tus granos usando búsqueda web—encontrando información del tostador, método de procesamiento, altitud, variedad y notas de cata
  • Basándose en esa investigación más tu equipo y preferencias, crea un perfil inicial optimizado
  • En el primer uso, preguntará sobre tu configuración (máquina, molinillo, tamaño de cesta) para dar mejores recomendaciones

Conversaciones de Ejemplo

Cómo empezar:

"Aquí hay una foto de este café que conseguí. ¿Puedes investigarlo y crear un perfil de Gaggimate para él?"

Dando retroalimentación:

"Acabo de preparar un shot—pregúntame sobre él"

La IA preguntará: "¿Cómo lo calificarías del 1 al 5? ¿Era ácido, equilibrado o amargo? ¿Notaste algo más—dulzura, cuerpo, sabores específicos?"

Registrando notas:

"¿Puedes actualizar la retroalimentación de mi shot más reciente? Sabía un poco amargo. Dale una calificación de 2/5. Usé la configuración de molienda 12 con 15g adentro y 30g afuera."

Analizando patrones:

"Por favor, mira todos mis shots recientes con los granos de café Amizade. Basándote en mi retroalimentación en cada shot, ¿cómo deberíamos ajustar el perfil?"

Creando un perfil:

Tú: Tengo algunos granos etíopes de tueste claro. ¿Puedes crear un perfil?

IA: Crearé un perfil optimizado para granos etíopes de tueste claro. Los tuestes claros típicamente se benefician de temperaturas más altas y pre-infusión más larga...

Crea el perfil "Ethiopian Light [AI]" con la configuración adecuada

Analizando un shot:

Tú: Analiza mi último shot, sabía ácido

IA: Mirando el shot #127... La extracción fue de 24 segundos con una presión promedio de 8.2 bar. La tasa de flujo aumentó rápidamente después de la pre-infusión, lo que combinado con el sabor ácido sugiere extracción insuficiente. Recomendaría:

  1. Moler más fino
  2. Aumentar la temperatura en 1-2°C
  3. Extender el tiempo de pre-infusión

Seguimiento del progreso:

Tú: Califica ese último shot con 4 estrellas—mucho mejor, queda un ligero amargor

IA: He guardado tu calificación y notas. Mirando tu progresión, tus últimos 3 shots han mejorado de 2 a 4 estrellas. El amargor podría indicar que ahora estamos sobreextrayendo ligeramente. ¿Quieres que ajuste el perfil?

Herramientas MCP

Este servidor proporciona ocho herramientas y seis recursos que dan a los agentes de IA las capacidades que necesitan para ayudar con tu flujo de trabajo de espresso:

Herramientas de Dispositivo

manage_profile

Crea, ve, actualiza, elimina y lista perfiles de preparación en tu dispositivo Gaggimate. Los perfiles definen todo el proceso de extracción—temperatura del agua, configuración de pre-infusión, curvas de presión y objetivos de flujo. La IA puede construir perfiles optimizados para granos específicos o estilos de preparación. Se admiten actualizaciones parciales—puedes cambiar solo la temperatura, fases o nombre sin reespecificar todo. Los perfiles creados por IA se etiquetan automáticamente con [AI] en su nombre para que puedas identificarlos.

analyze_shot

Recupera y analiza cualquier shot con un sistema de detalle de 3 niveles que equilibra información vs. costo de tokens:

  • summary (predeterminado): Indicadores clave para triaje rápido—resistencia del puck, riesgo de canalización, estabilidad de temperatura, cumplimiento del perfil y etiquetas de anotación legibles. Comienza aquí.
  • per_phase: Diagnósticos completos más desgloses por fase (tasa de rampa de pre-infusión, estabilidad de preparación, suavidad de reducción) con muestras representativas. Úsalo al diagnosticar qué fase tiene un problema.
  • detailed: Todo en per_phase más todas las muestras de series temporales. Úsalo para análisis profundo cuando los tiempos exactos importan.

Los registros binarios crudos de shots se analizan y transforman en un formato amigable para IA con diagnósticos basados en física: modelado de resistencia del puck (P/F²), puntuación de riesgo de canalización, seguimiento de desviación de temperatura, análisis de estabilidad de presión/flujo y métricas de cumplimiento del perfil. Cada métrica numérica va acompañada de una anotación de banda (por ejemplo, MODERATE, STABLE, SLIGHT_OVERSHOOT) para que la IA pueda interpretar valores sin necesidad de conocer los umbrales.

manage_shot_notes

Registra calificaciones (0-5 estrellas), notas de cata y parámetros de preparación para cualquier shot. Las notas se sincronizan directamente con tu dispositivo Gaggimate a través de WebSocket y también se almacenan localmente como respaldo. Puedes rastrear el equilibrio del sabor (amargo/equilibrado/ácido), configuraciones de molienda y pesos de dosis. Las notas agregadas por IA se prefijan con [AI]: para transparencia.

list_recent_shots

Explora tu historial de shots con filtrado opcional. Devuelve una lista de shots recientes con sus IDs, marcas de tiempo, nombres de perfil y cualquier calificación que hayas registrado. Esto ayuda a la IA a entender tus patrones de preparación y encontrar shots para analizar o comparar.

diagnose_connection

Soluciona problemas de conectividad entre el servidor MCP y tu dispositivo Gaggimate. Ejecuta pruebas automatizadas de alcance de red, acceso al puerto HTTP, disponibilidad de API y configuraciones incorrectas comunes. Devuelve recomendaciones específicas si se detectan problemas.

Herramientas de Datos Locales

manage_coffee

Crea y gestiona archivos de seguimiento de café. Cada café obtiene un archivo markdown con el perfil del grano, enfoque de preparación (narrativo) y un diario de preparación con entradas de análisis fechadas. El agente registra qué funcionó, qué no y qué probar a continuación—no números crudos. Admite crear nuevos cafés, registrar entradas de diario, actualizar contenido, eliminar archivos y listar todos los cafés rastreados.

manage_user_setup

Almacena y recupera tu configuración de equipo y preferencias—máquina, molinillo, cesta, báscula, preferencias de bebida, rutina de preparación del puck. Se guarda localmente y es accesible en todas las sesiones.

manage_grind_map

Rastrea configuraciones de molienda exitosas en diferentes cafés. Cuando encuentres una configuración que funcione (shots de 4-5 estrellas), regístrala aquí para referencia futura cuando vuelvas a un café o pruebes algo similar.

manage_brewing_insights

Acumula patrones y aprendizajes entre cafés. Cuando el agente note patrones (por ejemplo, "los naturales brasileños funcionan bien con perfiles descendentes"), los registra aquí. La habilidad de café nuevo revisa este archivo primero al ajustar granos desconocidos, aprovechando la experiencia pasada.

Recursos MCP (Solo Lectura)

El servidor también expone ocho recursos que proporcionan acceso bajo demanda a archivos locales:

URI del RecursoDescripción
gaggimate://knowledgeLista todos los archivos de conocimiento disponibles (incluyendo subdirectorios)
gaggimate://knowledge/{filename}Lee un archivo de conocimiento específico
gaggimate://knowledge/{subdir}/{filename}Lee un archivo de conocimiento de un subdirectorio
gaggimate://coffeesLista todos los archivos de seguimiento de café
gaggimate://coffees/{name}Lee un archivo de seguimiento de café específico
gaggimate://user/setupLee el equipo y preferencias del usuario
gaggimate://user/grind-mapLee el mapa de molienda con configuraciones exitosas
gaggimate://user/brewing-insightsLee patrones de preparación y aprendizajes entre cafés

Salvaguardas de Seguridad

Para una operación segura, este servidor MCP aplica los siguientes límites:

  • Sin control de shots: La IA no puede iniciar, detener o disparar shots de espresso. Solo puede leer datos de shots y gestionar perfiles.
  • Límites de temperatura: Todas las temperaturas están limitadas a 25-100°C para prevenir daños o quemaduras.
  • Límites de presión: Todas las presiones están limitadas a 0-12 bar para mantenerse dentro de rangos operativos seguros.
  • Atribución de perfiles: Los perfiles creados por IA se marcan con el sufijo [AI] (por ejemplo, "Ethiopian Light [AI]") para transparencia.
  • Protección de eliminación: La IA solo puede eliminar perfiles que ella creó (aquellos que terminan con [AI]). Los perfiles creados por el usuario no pueden ser eliminados por el agente. Si necesitas recuperar un perfil eliminado, consulta Almacenamiento de Datos Local—todas las versiones de perfiles se guardan localmente antes de la eliminación.

Estos límites se aplican a nivel de configuración y no pueden anularse a través de las herramientas MCP.

Requisitos

  • Una máquina de espresso Gaggimate-modificada (Gaggia Classic, etc.)
  • Una aplicación host MCP (por ejemplo, Claude Desktop, VS Code con GitHub Copilot, o cualquier otro cliente compatible con MCP)
  • Python 3.11+ con el gestor de paquetes uv
  • Mismo acceso de red que tu dispositivo Gaggimate

Inicio Rápido

1. Instalar uv (si no está ya instalado)

uv es un gestor de paquetes Python rápido. Instálalo con:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

2. Clonar e Instalar

git clone https://github.com/julianleopold/gaggimate-mcp.git
cd gaggimate-mcp
uv sync

3. Configurar Tu Cliente MCP

Encuentra tu ruta de uv (necesitarás la ruta absoluta completa):

which uv
# Example output: /opt/homebrew/bin/uv

Obtén la ruta de este repositorio:

pwd
# Example output: /Users/yourname/code/gaggimate-mcp

Claude Desktop

Abre la configuración de Claude Desktop: Configuración → Desarrollador → Editar Config

Agrega esta configuración (reemplaza las rutas con tus valores reales):

{
  "mcpServers": {
    "gaggimate": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/code/gaggimate-mcp",
        "run",
        "mcp",
        "run",
        "src/gaggimate_mcp/server.py"
      ]
    }
  }
}

Otros Hosts MCP (no probados)

Para otros hosts MCP, configura el servidor usando el transporte stdio con el comando:

uv --directory /path/to/gaggimate-mcp run mcp run src/gaggimate_mcp/server.py

4. Reinicia Tu Aplicación de Chat IA / Host MCP

Reinicia tu aplicación de chat IA (por ejemplo, Claude Desktop, VS Code) para cargar la nueva configuración del servidor. Deberías ver que las herramientas de Gaggimate están disponibles.

5. ¡Empieza a Chatear!

Asegúrate de estar en la misma red que tu dispositivo Gaggimate, luego prueba:

  • "Lista mis perfiles de Gaggimate"
  • "Muestra mis shots de espresso recientes"
  • "Diagnostica mi conexión de Gaggimate" (si tienes problemas)

Configuración de Proyecto Claude Desktop (Opcional)

Este repositorio incluye archivos preconstruidos para configurar un Proyecto Claude Desktop dedicado al ajuste de espresso. Los proyectos combinan instrucciones de sistema, archivos de conocimiento y herramientas MCP en un espacio de trabajo enfocado.

¿Usas una IA diferente? Puedes copiar y pegar los archivos de conocimiento en cualquier chat, o adaptar las instrucciones para tu agente preferido.

Qué Incluye

agent-instructions/
└── INSTRUCTIONS.md              # System primer for the espresso dialing agent

knowledge/
├── ESPRESSO_BREWING_BASICS.md            # Extraction fundamentals, variable hierarchy, diagnostic tree
├── ESPRESSO_TASTING_GUIDE.md             # Shot evaluation, sour vs bitter, tasting methodology
├── GAGGIMATE_PROFILE_CREATION_GUIDE.md   # Complete JSON schema for Gaggimate profiles
├── PRESSURE_GUIDE.md                     # Pressure by roast × processing method
├── EXTRACTION_SCIENCE.md                 # Channeling, puck prep, pre-infusion mechanics
├── BEAN_FRESHNESS_AND_STORAGE.md         # CO2 timeline, rest windows, storage
├── PROFILE_LIBRARY.md                    # 8 ready-to-use profile templates
├── BASKETS.md                            # Dose rules, basket sizing
├── MILK_AND_DRINKS.md                    # Steaming, drink specs, single-boiler workflow
├── SPECIAL_CATEGORIES.md                 # Decaf adjustments, blend strategies
├── profiles/                             # Profile creation references (structure, pumps, examples)
├── diagnostics/                          # Diagnostic trees, telemetry patterns, shot diagnostics reference
└── research/                             # Research checklists, espresso physics & threshold calibration

agent-skills/
├── gaggimate-profiles/     # Profile creation with conditional reference loading
├── new-coffee/             # Research beans → recommend parameters → upload profile
├── diagnose/               # Shot telemetry analysis with taste correlation
├── feedback/               # Shot feedback loop: gather → analyze → record → recommend
└── knowledge-lookup/       # Knowledge Q&A router (cites correct knowledge file)

coffees/                    # Coffee tracking files (created by AI, gitignored)
user/                       # User setup and grind map (created by AI, gitignored)
├── user-setup.example.md   # Template for user equipment/preferences
└── grind-map.example.md    # Template for grind settings tracking

Pasos de Configuración

  1. Crea un nuevo proyecto en Claude Desktop
  2. Agrega las instrucciones de sistema: Copia el contenido de agent-instructions/INSTRUCTIONS.md en el prompt del sistema del proyecto
  3. Conecta el servidor MCP: Sigue el Inicio Rápido anterior—los archivos de conocimiento se sirven automáticamente a través de los recursos MCP
  4. Opcional - Sube archivos de conocimiento: Si tu cliente MCP no admite recursos, agrega archivos de knowledge/ a la sección de conocimiento del proyecto
  5. Opcional - Instala habilidades: Consulta Apéndice: ¿Por qué una Habilidad? para más detalles

Cómo Funcionan los Archivos Juntos

ArchivoPropósito
INSTRUCTIONS.mdDefine la personalidad del agente, flujos de trabajo para configuración, investigación de café, creación de perfiles y ajuste iterativo
ESPRESSO_BREWING_BASICS.mdTeoría de extracción, estilos de shot, jerarquía de variables (qué ajustar primero), árbol de decisión de diagnóstico
ESPRESSO_TASTING_GUIDE.mdAyuda a los usuarios a describir lo que saborean: ácido vs. amargo, cuerpo, dulzura, diagnóstico de canalización
GAGGIMATE_PROFILE_CREATION_GUIDE.mdReferencia completa para crear perfiles Gaggimate válidos: esquema JSON, estructura de fases, modos de bomba
PRESSURE_GUIDE.mdMatriz de presión por nivel de tueste × método de procesamiento, parámetros de estilo de shot
EXTRACTION_SCIENCE.mdPrevención de canalización, jerarquía de preparación del puck, mecánica de pre-infusión, diagnóstico visual
BEAN_FRESHNESS_AND_STORAGE.mdCronología de desgasificación de CO2, ventanas de sabor óptimo, métodos de almacenamiento
PROFILE_LIBRARY.md8 plantillas de perfiles (Classic 9-Bar, Light Roast Bloom, Turbo, Lever Decline, etc.)
BASKETS.mdReglas de dosis por tamaño de cesto, efectos de profundidad/diámetro, cestos de precisión
MILK_AND_DRINKS.mdTécnica de vaporizado, tipos de leche, flujo de trabajo de caldera simple, especificaciones de bebidas
SPECIAL_CATEGORIES.mdAjustes de extracción para descafeinado, estrategias de temperatura para blends

Configuración (Opcional)

Por defecto, el servidor se conecta a gaggimate.local, lo cual debería funcionar automáticamente si tu dispositivo Gaggimate está en la misma red. La mayoría de los usuarios pueden omitir esta sección.

Si necesitas personalizar la conexión, crea un archivo .env:

cp .env.example .env

Configuraciones disponibles:

GAGGIMATE_HOST=gaggimate.local    # Device hostname or IP
GAGGIMATE_PROTOCOL=ws             # Protocol (ws or http)
GAGGIMATE_LOG_LEVEL=INFO          # Logging level

Si tu dispositivo no se resuelve mediante mDNS, usa la dirección IP directamente:

GAGGIMATE_HOST=192.168.1.100

Solución de problemas

"Failed to spawn process: No such file or directory"

Esto significa que tu host MCP no puede encontrar uv. Debes usar la ruta absoluta completa:

  • ❌ "command": "uv"
  • ✅ "command": "/opt/homebrew/bin/uv"

Ejecuta which uv para encontrar tu ruta correcta.

No se puede conectar a Gaggimate

  1. Verifica la red: ¿Estás en el mismo WiFi que tu máquina de espresso?

    ping gaggimate.local

  2. Prueba con la dirección IP: Si mDNS no funciona, encuentra la IP de tu dispositivo en tu router y actualiza .env

  3. Usa diagnósticos: Pregunta "diagnostica mi conexión Gaggimate" para solución automatizada de problemas

El navegador muestra "ERR_CONNECTION_REFUSED"

Los navegadores suelen actualizar automáticamente a HTTPS. Gaggimate usa HTTP:

  • Usa http://gaggimate.local explícitamente (no https)
  • O usa la dirección IP: http://192.168.x.x

Cómo funciona

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP Client    │────▶│  Gaggimate MCP   │────▶│   Gaggimate     │
│  (Claude, etc.) │◀────│     Server       │◀────│   (ESP32)       │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                       │                        │
        │    MCP Protocol       │    WebSocket/HTTP      │
        │    (stdio)            │    (local network)     │

El servidor MCP actúa como un puente:

  • API WebSocket (ws://gaggimate.local/ws) - Gestión de perfiles, notas de shot
  • API HTTP (http://gaggimate.local/api/) - Historial de shots y archivos de datos

Los datos de los shots se analizan desde archivos binarios .slog y se transforman en un formato amigable para IA con estadísticas sobre temperatura, presión, flujo y tiempo de extracción.

Almacenamiento local de datos

El servidor MCP almacena algunos datos localmente en tu máquina (no en el dispositivo Gaggimate) con fines de respaldo y seguimiento de versiones.

Qué se almacena localmente

UbicaciónContenidoPropósito
./data/ratings.jsonCalificaciones de shots y notas de cataRespaldo de comentarios sincronizados con el dispositivo
./data/profiles/Versiones de perfiles creados por IAHistorial de versiones para reversión/comparación
./coffees/*.mdArchivos de seguimiento de caféPerfiles de granos, diario de preparación, ideas clave
./user/user-setup.mdEquipo y preferencias del usuarioConfiguración persistente entre sesiones
./user/grind-map.mdConfiguraciones de molido exitosasReferencia rápida para cafés ajustados
./user/brewing-insights.mdPatrones entre cafésAprendizajes que se aplican entre cafés

Acceso del agente al almacenamiento local

DatosEl agente puede leerEl agente puede escribir
Calificaciones de shots❌ No - lee desde el dispositivo (fuente de verdad)✅ Sí (copia de respaldo)
Versiones de perfiles❌ No (solo usuario mediante sistema de archivos)✅ Auto-guardado al crear/actualizar
Archivos de café✅ Sí (mediante recursos MCP)✅ Sí (mediante herramienta manage_coffee)
Configuración del usuario✅ Sí (mediante recursos MCP)✅ Sí (mediante herramienta manage_user_setup)
Mapa de molido✅ Sí (mediante recursos MCP)✅ Sí (mediante herramienta manage_grind_map)
Ideas de preparación✅ Sí (mediante recursos MCP)✅ Sí (mediante herramienta manage_brewing_insights)

El almacenamiento local es solo de escritura desde la perspectiva del agente para datos del dispositivo (calificaciones, perfiles): guarda respaldos automáticamente pero siempre lee desde el dispositivo Gaggimate. Los archivos de café, la configuración del usuario y el mapa de molido son totalmente legibles y escribibles por el agente mediante recursos y herramientas MCP. Para acceder a los respaldos locales (por ejemplo, para recuperación), navega por los archivos directamente en ./data/.

Estructura de ratings.json

Almacena tus comentarios de shots indexados por ID de shot:

{
  "000105": {
    "shot_id": "000105",
    "rating": 4,
    "notes": "Updated by [AI]: Dark chocolate notes, syrupy body...",
    "timestamp": "2026-01-29T08:46:08.525676"
  }
}

Versiones de perfiles

Cada vez que la IA crea o actualiza un perfil, se guarda una copia versionada localmente:

./data/profiles/
├── Agent-Ethiopian_Light__AI__v1.json
├── Agent-Ethiopian_Light__AI__v2.json   # After first adjustment
└── Agent-Ethiopian_Light__AI__v3.json   # After second adjustment

Esto te permite:

  • Rastrear cómo evolucionaron los perfiles durante el ajuste
  • Revertir a versiones anteriores si es necesario
  • Comparar qué cambió entre iteraciones

Configurar la ubicación de almacenamiento

Puedes cambiar la ruta de almacenamiento mediante una variable de entorno:

GAGGIMATE_STORAGE_PATH=/path/to/custom/data

Privacidad de datos

  • Todos los datos locales permanecen en tu máquina
  • Nada se envía a servidores externos
  • El agente de IA solo accede a tu dispositivo Gaggimate en tu red local

Desarrollo

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=gaggimate_mcp --cov-report=html

# Development mode (for debugging)
uv run mcp dev src/gaggimate_mcp/server.py

Estado de pruebas: 206 pruebas aprobadas, 93% de cobertura

Apéndice

¿Por qué una Skill en lugar de un archivo de conocimiento?

La guía de creación de perfiles está estructurada como una Skill de Claude Desktop en lugar de un único archivo de conocimiento. Esto importa para la eficiencia de tokens y la calidad de respuesta.

El problema con archivos de conocimiento grandes:

  • Los archivos de conocimiento se cargan en el contexto en cada conversación
  • Una referencia técnica de más de 700 líneas consume tokens incluso cuando solo estás conversando sobre preferencias de sabor
  • Los contextos grandes pueden degradar la calidad de respuesta: el modelo tiene más que examinar

Cómo las Skills usan divulgación progresiva:

  • La SKILL.md principal (~80-130 líneas) se carga solo cuando se activa mediante solicitudes relevantes
  • Las referencias detalladas (modos de bomba, ejemplos, solución de problemas) se sirven como recursos de conocimiento MCP y se cargan bajo demanda cuando el agente las necesita
  • Un simple "crea un perfil de 9 bares" podría cargar solo la skill principal
  • Un complejo "depura mi transición de presión" activa al agente para obtener la referencia de bomba/transiciones mediante gaggimate://knowledge/profiles/PUMP_AND_TRANSITIONS

Beneficios prácticos:

EnfoqueTokens usadosMejor para
Archivo de conocimiento único~3,000 tokens (siempre)Referencias pequeñas (<200 líneas)
Skill con referencias~500-1,500 tokens (variable)Documentos técnicos grandes, detalle dependiente del contexto

Cada skill es un único archivo SKILL.md en agent-skills/{skill-name}/. Las referencias detalladas (estructura de perfiles, modos de bomba, árboles de diagnóstico, etc.) ahora se sirven mediante recursos de conocimiento MCP en lugar de incluirse en la skill — esto mantiene las skills ligeras mientras el agente carga referencias bajo demanda cuando las necesita.

Para instalar una skill en Claude Desktop, ve a Configuración → Capacidades → Skills → Agregar y sube el archivo SKILL.md (o un ZIP que lo contenga).

Alternativa: Solo usa archivos de conocimiento

Si prefieres simplicidad, puedes omitir las skills por completo y simplemente agregar los archivos de conocimiento. El agente tendrá toda la información que necesita. El enfoque de skills solo optimiza la eficiencia de tokens cuando no se necesitan referencias detalladas en cada conversación.

Estructura del proyecto

gaggimate-mcp/
├── src/gaggimate_mcp/
│   ├── server.py           # MCP server with 9 tools
│   ├── config.py           # Configuration management (Pydantic)
│   ├── resources.py        # MCP resource endpoints (8 resources)
│   ├── errors.py           # Structured error codes
│   ├── diagnostics.py      # Connection diagnostics
│   ├── logging_config.py   # Structlog JSON logging setup
│   ├── api/                # Device communication
│   │   ├── websocket.py    # WebSocket client (profiles, shot notes)
│   │   └── http.py         # HTTP client (shot history)
│   ├── parsers/            # Binary file parsers
│   │   ├── shot.py         # .slog shot file parser (V4/V5)
│   │   └── index.py        # index.bin parser
│   ├── models/             # Pydantic data models
│   │   ├── profile.py      # Brewing profile structure
│   │   ├── shot.py         # Shot data and statistics
│   │   └── rating.py       # Shot ratings and feedback
│   ├── transformers/       # Data transformation
│   │   └── shot.py         # Binary → AI-friendly format
│   └── storage/            # Local persistence
│       ├── ratings.py      # Shot ratings (JSON)
│       ├── profiles.py     # AI-created profile versions
│       └── markdown.py     # Coffee/user markdown file CRUD
├── agent-instructions/     # Claude Desktop system prompt
├── knowledge/              # 10 espresso knowledge files (served via MCP resources)
├── agent-skills/           # 5 Claude Desktop skills (profile, new-coffee, diagnose, feedback, knowledge-lookup)
├── coffees/                # Coffee tracking files (created by AI, gitignored)
├── user/                   # User setup and grind map (gitignored, with .example templates)
├── tests/                  # 206 unit tests
└── data/                   # Local data (gitignored)
    ├── ratings.json        # Your shot ratings
    └── profiles/           # AI-created profile backups

Relacionados

  • Proyecto Gaggimate - El mod ESP32 para máquinas Gaggia
  • gaggimate-barista por Charlie Hall - Agente barista de Claude Code con profundo conocimiento de espresso. Muchos de los archivos de conocimiento, skills y patrones de diagnóstico en este repositorio fueron adaptados del trabajo de Charlie.
  • Brew by AI - Publicación de blog sobre preparación de espresso asistida por IA
  • MCP para Gaggimate en TypeScript - Inspiración inicial para este proyecto (esta implementación en Python ha divergido desde entonces)

Licencia

Licencia MIT - Consulta LICENSE para más detalles.

Hecho con ☕ para los obsesionados con el espresso