Gaggimate MCP

Permite que um agente LLM controle sua máquina de espresso Gaggimate

GitHub
37
Experimente este MCPPatrocinado

Documentação

Servidor MCP Gaggimate

Barista de IA Faça Você Mesmo — Deixe seu agente de IA controlar diretamente sua Gaggimate

Post no Blog: Transformei o Claude em um Barista de IA controlando minha máquina de espresso

Você já pode pedir conselhos a um LLM sobre como ajustar seu espresso, e modelos como Claude, ChatGPT ou Gemini já conseguem gerar perfis Gaggimate em formato JSON.

Este repositório fornece duas coisas:

  1. Um servidor MCP que permite que seu agente LLM interaja diretamente com sua máquina Gaggimate — sem copiar e colar ou fazer upload manual. Seu agente LLM pode ler seu histórico de extrações, analisar extrações, armazenar seu feedback de degustação, enviar perfis gerados e ajustá-los com base nos seus resultados e desejos.

  2. Instruções, conhecimento e habilidades para orientar o agente sobre como ajudá-lo a ajustar seu espresso — transformando um LLM de propósito geral em um treinador de barista que entende teoria de extração, vocabulário de degustação, perfil de pressão e o sistema de perfis da Gaggimate. Agradecimentos a Charlie Hall por permitir que eu usasse e adaptasse os arquivos de conhecimento e padrões de diagnóstico do seu projeto gaggimate-barista.

Sumário

O que há neste Repositório

Servidor MCP — Nove ferramentas e oito recursos que dão ao seu IA acesso direto à sua máquina e dados locais:

  • Ler dados de extração — Curvas de temperatura, leituras de pressão, taxas de fluxo, tempo de extração
  • Gerenciar perfis — Criar, atualizar e listar perfis de preparo diretamente no seu dispositivo
  • Registrar feedback — Gravar avaliações e notas de degustação sincronizadas com sua Gaggimate
  • Navegar pelo histórico — Listar extrações recentes com filtros
  • Diagnosticar problemas — Solução de problemas de conexão automatizada
  • Gerenciar cafés — Criar e atualizar arquivos de acompanhamento de café com diário de preparo
  • Configuração do usuário — Armazenar e recuperar seus equipamentos e preferências
  • Mapa de moagem — Registrar configurações de moagem bem-sucedidas entre cafés
  • Insights de preparo — Acumular padrões e aprendizados entre cafés
  • Recursos de conhecimento — Acesso sob demanda a arquivos de conhecimento sobre espresso (incluindo subdiretórios)

Arquivos de Conhecimento (10 arquivos) — Materiais de referência que transformam um LLM de propósito geral em um treinador de barista funcional:

  • Teoria de extração de espresso, estilos de extração e hierarquia de variáveis
  • Vocabulário de degustação (como descrever azedo vs. amargo, corpo, doçura)
  • Guia de pressão com matriz de torra × processamento
  • Ciência da extração (canalização, preparo do puck, mecânica de pré-infusão)
  • Frescor e armazenamento do grão (linha do tempo de CO2, janelas de descanso)
  • Biblioteca de perfis com 8 modelos prontos para uso
  • Regras de tamanho de cesto e dose
  • Vaporização de leite e especificações de bebidas
  • Estratégias de descafeinado e blends
  • Esquema completo de perfis Gaggimate e exemplos

Habilidades (5 habilidades) — Habilidades do Claude Desktop usando divulgação progressiva (carregar referências detalhadas apenas quando necessário):

  • gaggimate-profiles — Criação de perfis com carregamento condicional de referências
  • new-coffee — Pesquisar novos grãos, recomendar parâmetros, enviar perfil
  • diagnose — Análise de telemetria de extração com correlação de dados de degustação
  • feedback — Ciclo completo de feedback de extração com registro e recomendações
  • knowledge-lookup — Roteador de perguntas e respostas de conhecimento que cita o arquivo de conhecimento correto

Veja Exemplo: Usando ChatGPT para criar perfis manualmente para Gaggimate por Dule Rabbit — este servidor MCP automatiza todo esse fluxo de trabalho.

Registro de Alterações

2026-04-22

  • Indicadores de canalização v2: Reescrito o cálculo de risco de canalização em torno de quatro indicadores independentes, cada um capturando uma assinatura física específica, com campos descritores separados dos indicadores pontuados.
    • Ajuste de janela (V4): Após o ajuste existente de rampa de pressão, também remove amostras de fluxo zero iniciais e finais (válvula fechada na entrada, corte volumétrico na saída). Elimina a classe de falsos positivos de classificação ALTA causados por caudas de pressão presas.
    • Jitter de fluxo (V5): flow_jitter_ml_s substitui o desvio padrão bruto como o principal indicador de instabilidade de fluxo. Mede o desvio padrão da primeira diferença, então rampas de fluxo projetadas não inflam mais a pontuação. Novas faixas de anotação: ESTÁVEL <0,05, JITTER_MODERADO 0,10–<0,20, COM_JITTER ≥0,20; o limite pontuado para +2 pontos começa em ≥0,10.
    • Rastreamento de alvo (V6): flow_vs_target_residual_ml_s — desvio padrão do fluxo (real − alvo) — é a impressão digital mais clara de canalização em perfis liderados por fluxo. null em perfis liderados por pressão, caso em que pressure_jitter_bar preenche o slot do indicador.
    • Fuga de fluxo tardio com tendência removida: flow_acceleration_late_ml_s2 agora é late_slope − overall_slope para que perfis com fluxo em rampa sejam lidos como estáveis em vez de "acelerando no final".
    • Renomeações de campos (quebra): ChannelingIndicators.overall_risk → channeling_risk; flow_volatility_ml_s → flow_spread_ml_s (descritor, sem pontuação); pressure_volatility_bar removido em favor de pressure_jitter_bar. pressure_stability_bar / flow_stability_ml_s por fase renomeados para pressure_jitter_bar / flow_jitter_ml_s para corresponder.
    • Anotações voltadas ao agente: Novas anotações primary_signal, guidance, flow_shape, window_confidence deixam claro para o LLM por que uma classificação foi acionada e quanta confiança dar a ela.
    • Versão da habilidade diagnose atualizada; SHOT_DIAGNOSTICS_REFERENCE.md reescrito para o novo esquema.

2026-02-23

  • Desduplicação de conhecimento Fase 3: Reduzido GAGGIMATE_PROFILE_CREATION_GUIDE.md de 1113 → 130 linhas (redução de 88%). Agora é um hub de navegação que vincula a arquivos knowledge/profiles/ detalhados em vez de duplicar seu conteúdo
  • Referência de processamento de café: Adicionado COFFEE_PROCESSING.md — guia abrangente sobre 7 métodos de processamento (lavado, natural, honey, etc.) e suas implicações na extração de espresso
  • Referências cruzadas enriquecidas: Adicionados links de métodos de processamento para PRESSURE_GUIDE.md e INSTRUCTIONS.md
  • Palavras voltadas ao agente: Reduzidas de 29.828 → 27.869 (~redução de 1.960 palavras) por meio de desduplicação enquanto preenche lacunas de conteúdo

2026-02-21

  • Diagnóstico de extração baseado em física: analyze_shot agora calcula resistência do puck (P/F²), pontuação de risco de canalização, rastreamento de desvio de temperatura, estabilidade de pressão/fluxo, métricas de conformidade de perfil e análises por fase — tudo com anotações de faixa legíveis por humanos
  • Sistema de detalhes em 3 níveis: Novo parâmetro detail (summary/per_phase/detailed) controla profundidade de diagnóstico vs. custo de tokens. Resumo para triagem, por_fase para isolar problemas, detalhado para série temporal completa
  • Limiares de diagnóstico calibrados: Faixas de taxa de queda de pressão ampliadas para ruído de amostra de 100ms, faixas de overshoot de temperatura ajustadas para corresponder à tolerância INEI ±2°C, rótulos de taxa de rampa renomeados de LENTO/RÁPIDO para SUAVE/AGRESSIVO para evitar julgamentos de valor em rampas de pré-infusão intencionalmente lentas
  • Documentação de pesquisa: Adicionado knowledge/research/ESPRESSO_PHYSICS_AND_THRESHOLD_CALIBRATION.md com fundamentação física e citações de fontes para todas as decisões de limiar

2026-02-20

  • Acompanhamento narrativo de café: Arquivos de café agora armazenam análise e insights em vez de números brutos — abordagem de preparo (narrativa), entradas de diário (análise datada) e insights-chave. Dados brutos de extração permanecem no dispositivo; o agente registra pensamento e aprendizados
  • Insights de preparo: Nova ferramenta manage_brewing_insights e recurso gaggimate://user/brewing-insights para reconhecimento de padrões entre cafés — o que funciona para qual origem, quais perfis se adequam a qual método de processamento, aprendizados gerais que se aplicam entre cafés
  • Conhecimento como recursos MCP: Movidos 10 arquivos de referência de habilidades (estrutura de perfil, modos de bomba, árvores de diagnóstico, padrões de telemetria, etc.) dos diretórios de habilidades empacotados para subdiretórios knowledge/{profiles,diagnostics,research}/, servidos via recursos MCP. As habilidades agora são arquivos SKILL.md leves de arquivo único que carregam referências sob demanda via gaggimate://knowledge/{subdir}/{filename}
  • Melhorias de integração de habilidades: Habilidade de consulta de conhecimento agora roteia para recursos de dados do usuário (mapa de moagem, configuração, cafés). Habilidade de diagnóstico lê histórico de café para contexto. Habilidade de feedback faz referência cruzada ao mapa de moagem para configurações bem-sucedidas
  • Renomeado consult → knowledge-lookup: Nome da habilidade agora descreve o que ela faz — consulta conhecimento de espresso de arquivos autoritativos
  • Ferramenta manage_coffee simplificada: Reduzida de 27 para 16 parâmetros. Substituída ação log_shot (8 colunas numéricas) por ação log_entry (data, título, corpo narrativo)
  • Cobertura de testes: 206 testes passando (acima de 192)

2026-02-15

  • Recursos MCP: Adicionados 6 recursos MCP somente leitura para acesso sob demanda a arquivos de conhecimento, arquivos de acompanhamento de café, configuração do usuário e mapa de moagem — sem necessidade de uploads manuais de arquivos
  • Ferramenta de acompanhamento de café: Nova ferramenta MCP manage_coffee para criar, atualizar, excluir arquivos de café e registrar extrações com acompanhamento persistente entre sessões
  • Ferramenta de configuração do usuário: Nova ferramenta MCP manage_user_setup para armazenar e recuperar equipamentos/preferências
  • Ferramenta de mapa de moagem: Nova ferramenta MCP manage_grind_map para registrar configurações de moagem bem-sucedidas entre cafés
  • Reestruturação de diretórios: agent-knowledge/ → knowledge/, novos diretórios coffees/ e user/ para dados locais
  • Instruções e habilidades atualizadas: Todas as instruções e habilidades do agente agora referenciam recursos e ferramentas MCP em vez de uploads de arquivos estáticos
  • Helpers de armazenamento: Novo módulo storage/markdown.py para operações CRUD de arquivos markdown

2026-02-14

  • Base de conhecimento expandida: Adicionados 7 novos arquivos de conhecimento adaptados de gaggimate-barista por Charlie Hall — guia de pressão, ciência da extração, frescor do grão, biblioteca de perfis, cestos, leite e bebidas, e categorias especiais (descafeinado/blends)
  • Conhecimento existente enriquecido: Adicionada hierarquia de variáveis, árvore de decisão de diagnóstico, regra de canalização (Scott Rao) e referências cruzadas aos arquivos existentes de fundamentos de preparo e guia de degustação
  • 4 novas habilidades: Adicionadas new-coffee (pesquisa de grãos → perfil), diagnose (análise de telemetria), feedback (ciclo de feedback de extração) e knowledge-lookup (roteador de perguntas e respostas de conhecimento)
  • Habilidade gaggimate-profiles enriquecida: Adicionada consciência de métodos de processamento, referências de matriz pressão × torra, carregamento condicional de referências e etapa de upload MCP
  • Artefato de Acompanhamento de Café: Novo conceito para memória persistente entre sessões do Claude Desktop — o agente cria um documento de acompanhamento em markdown que os usuários podem salvar e reenviar
  • Instruções do agente atualizadas: Tabela de referência de arquivos de conhecimento, diretório de habilidades, fluxo de trabalho de acompanhamento de café, hierarquia de variáveis e regra de canalização azedo-E-amargo

2026-02-03

  • Atualizações parciais de perfil: Atualize apenas os campos que deseja alterar (temperatura, fases ou nome) — campos omitidos mantêm seus valores existentes
  • Excluir perfis: Adicionado action='delete' a manage_profile com salvaguardas de segurança:
    • Apenas perfis criados por IA (terminando com [AI]) podem ser excluídos
    • Requer confirm_delete=True explícito para evitar acidentes
    • Perfis excluídos podem ser recuperados do backup local (veja Armazenamento Local de Dados)
  • Notas de extração simplificadas: action='get' agora lê do dispositivo (fonte da verdade); armazenamento local é somente backup para usuários
  • Documentação de Armazenamento Local de Dados: Adicionada documentação explicando o que é armazenado localmente e as limitações de acesso do agente
  • Correção de bug: Corrigida chamada de método get_profile → load_profile que estava causando falhas de atualização

2026-02-02

  • Marcadores de IA configuráveis (edc8d98): O sufixo de perfil de IA e o prefixo de notas agora são configuráveis via variáveis de ambiente GAGGIMATE_AI_PROFILE_SUFFIX e GAGGIMATE_AI_NOTES_PREFIX
  • Correção de bug (a350246): Atualizações de perfil agora preservam as configurações de válvula e o tipo de perfil (simples/pro) em vez de redefini-los
  • Documentação automática Pro (bfc2ca0): Adicionado guia abrangente para perfis Automáticos Pro com exemplos de pressão variável baseada em fluxo

O Fluxo 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

Melhore iterativamente seus shots com feedback guiado por IA:

  1. Extraia um shot e prove
  2. A IA pede seu feedback — ela fará perguntas direcionadas sobre equilíbrio (azedo/amargo), corpo, doçura e sabores específicos para ajudar você a articular o que está provando
  3. O feedback é salvo nas suas notas de shot no Gaggimate, criando um registro da sua jornada de ajuste
  4. A IA analisa os dados do seu shot (curvas de pressão, temperatura, fluxo) combinados com suas notas de degustação
  5. A IA sugere ajustes — explicando porquê (ex.: "essa acidez sugere subextração, vamos moer mais fino ou aumentar a temperatura")
  6. A IA atualiza seu perfil diretamente na sua máquina, ou recomenda mudanças na moagem
  7. Repita até ficar ajustado

Começando com um novo café:

  • Compartilhe uma foto do seu saco de café, ou apenas diga à IA o que você está preparando
  • A IA pesquisará seus grãos usando busca na web — encontrando informações do torrador, método de processamento, altitude, variedade e notas de degustação
  • Com base nessa pesquisa, além do seu equipamento e preferências, ela cria um perfil inicial otimizado
  • No primeiro uso, ela perguntará sobre sua configuração (máquina, moedor, tamanho do cesto) para dar melhores recomendações

Exemplos de Conversas

Começando:

"Aqui está uma foto deste café que comprei. Você pode pesquisar e criar um perfil Gaggimate para ele?"

Dando feedback:

"Acabei de extrair um shot — me pergunte sobre ele"

A IA perguntará: "Como você o avaliaria de 1 a 5? Estava azedo, equilibrado ou amargo? Mais alguma coisa que notou — doçura, corpo, sabores específicos?"

Registrando notas:

"Pode atualizar o feedback do meu shot mais recente? Estava um pouco amargo. Dê uma nota 2/5. Usei a configuração de moagem 12 com 15g de entrada e 30g de saída."

Analisando padrões:

"Por favor, veja todos os meus shots recentes com os grãos de café Amizade. Com base no meu feedback em cada shot, como devemos ajustar o perfil?"

Criando um perfil:

Você: Tenho alguns grãos etíopes de torra clara. Pode criar um perfil?

IA: Vou criar um perfil otimizado para grãos etíopes de torra clara. Torras claras geralmente se beneficiam de temperaturas mais altas e pré-infusão mais longa...

Cria o perfil "Ethiopian Light [AI]" com configurações apropriadas

Analisando um shot:

Você: Analise meu último shot, estava azedo

IA: Olhando o shot #127... A extração foi de 24 segundos com pressão média de 8,2 bar. A taxa de fluxo aumentou rapidamente após a pré-infusão, o que, combinado com o sabor azedo, sugere subextração. Eu recomendaria:

  1. Moer mais fino
  2. Aumentar a temperatura em 1-2°C
  3. Estender o tempo de pré-infusão

Acompanhando o progresso:

Você: Avalie aquele último shot com 4 estrelas - muito melhor, leve amargor restante

IA: Salvei sua avaliação e notas. Olhando sua progressão, seus últimos 3 shots melhoraram de 2 para 4 estrelas. O amargor pode indicar que agora estamos levemente superextraindo. Quer que eu ajuste o perfil?

Ferramentas MCP

Este servidor fornece oito ferramentas e seis recursos que dão aos agentes de IA as capacidades necessárias para ajudar no seu fluxo de trabalho de espresso:

Ferramentas de Dispositivo

manage_profile

Crie, visualize, atualize, exclua e liste perfis de extração no seu dispositivo Gaggimate. Os perfis definem todo o processo de extração — temperatura da água, configurações de pré-infusão, curvas de pressão e metas de fluxo. A IA pode criar perfis otimizados para grãos específicos ou estilos de preparo. Atualizações parciais são suportadas — você pode alterar apenas temperatura, fases ou nome sem reespecificar tudo. Perfis criados pela IA são automaticamente marcados com [AI] no nome para que você possa identificá-los.

analyze_shot

Recupere e analise qualquer shot com um sistema de detalhes em 3 níveis que equilibra insight vs. custo de tokens:

  • summary (padrão): Indicadores-chave para triagem rápida — resistência do puck, risco de canalização, estabilidade de temperatura, conformidade com o perfil e rótulos de anotação legíveis por humanos. Comece aqui.
  • per_phase: Diagnósticos completos mais detalhamentos por fase (taxa de rampa de pré-infusão, estabilidade de extração, suavidade do declínio) com amostras representativas. Use ao diagnosticar qual fase tem um problema.
  • detailed: Tudo em per_phase mais todas as amostras de séries temporais. Use para análise profunda quando tempos exatos importam.

Os logs binários brutos de shots são analisados e transformados em um formato amigável para IA com diagnósticos baseados em física: modelagem de resistência do puck (P/F²), pontuação de risco de canalização, rastreamento de desvio de temperatura, análise de estabilidade de pressão/fluxo e métricas de conformidade com o perfil. Cada métrica numérica é acompanhada por uma anotação de faixa (ex.: MODERATE, STABLE, SLIGHT_OVERSHOOT) para que a IA possa interpretar valores sem precisar conhecer os limites.

manage_shot_notes

Registre avaliações (0-5 estrelas), notas de degustação e parâmetros de extração para qualquer shot. As notas são sincronizadas diretamente com seu dispositivo Gaggimate via WebSocket e também armazenadas localmente como backup. Você pode acompanhar o equilíbrio do sabor (amargo/equilibrado/azedo), configurações de moagem e pesos de dose. Notas adicionadas pela IA são prefixadas com [AI]: para transparência.

list_recent_shots

Navegue pelo seu histórico de shots com filtragem opcional. Retorna uma lista de shots recentes com seus IDs, timestamps, nomes de perfil e quaisquer avaliações que você registrou. Isso ajuda a IA a entender seus padrões de extração e encontrar shots para analisar ou comparar.

diagnose_connection

Solucione problemas de conectividade entre o servidor MCP e seu dispositivo Gaggimate. Executa testes automatizados para alcance de rede, acesso à porta HTTP, disponibilidade da API e configurações incorretas comuns. Retorna recomendações específicas se problemas forem detectados.

Ferramentas de Dados Locais

manage_coffee

Crie e gerencie arquivos de rastreamento de café. Cada café recebe um arquivo markdown com perfil do grão, abordagem de extração (narrativa) e um diário de extração com entradas de análise datadas. O agente registra o que funcionou, o que não funcionou e o que tentar a seguir — não números brutos. Suporta criar novos cafés, registrar entradas de diário, atualizar conteúdo, excluir arquivos e listar todos os cafés rastreados.

manage_user_setup

Armazene e recupere sua configuração de equipamento e preferências — máquina, moedor, cesto, balança, preferências de bebida, rotina de preparo do puck. Salvo localmente e acessível em todas as sessões.

manage_grind_map

Acompanhe configurações de moagem bem-sucedidas em diferentes cafés. Quando você encontrar uma configuração que funciona (shots de 4-5 estrelas), registre-a aqui para referência futura ao revisitar um café ou tentar algo semelhante.

manage_brewing_insights

Acumule padrões e aprendizados entre cafés. Quando o agente notar padrões (ex.: "naturais brasileiros se saem bem com perfis decrescentes"), ele os registra aqui. A habilidade de novo café revisa este arquivo primeiro ao ajustar grãos desconhecidos, aproveitando a experiência passada.

Recursos MCP (Somente Leitura)

O servidor também expõe oito recursos que fornecem acesso sob demanda a arquivos locais:

URI do RecursoDescrição
gaggimate://knowledgeLista todos os arquivos de conhecimento disponíveis (incluindo subdiretórios)
gaggimate://knowledge/{filename}Lê um arquivo de conhecimento específico
gaggimate://knowledge/{subdir}/{filename}Lê um arquivo de conhecimento de um subdiretório
gaggimate://coffeesLista todos os arquivos de rastreamento de café
gaggimate://coffees/{name}Lê um arquivo de rastreamento de café específico
gaggimate://user/setupLê equipamento e preferências do usuário
gaggimate://user/grind-mapLê mapa de moagem com configurações bem-sucedidas
gaggimate://user/brewing-insightsLê padrões de extração e aprendizados entre cafés

Salvaguardas de Segurança

Para operação segura, este servidor MCP impõe os seguintes limites:

  • Sem controle de shots: A IA não pode iniciar, parar ou acionar shots de espresso. Ela só pode ler dados de shots e gerenciar perfis.
  • Limites de temperatura: Todas as temperaturas são limitadas a 25-100°C para evitar danos ou queimaduras.
  • Limites de pressão: Todas as pressões são limitadas a 0-12 bar para permanecer dentro das faixas operacionais seguras.
  • Atribuição de perfil: Perfis criados pela IA são marcados com o sufixo [AI] (ex.: "Ethiopian Light [AI]") para transparência.
  • Proteção contra exclusão: A IA só pode excluir perfis que ela criou (aqueles que terminam com [AI]). Perfis criados pelo usuário não podem ser excluídos pelo agente. Se você precisar recuperar um perfil excluído, veja Armazenamento de Dados Local — todas as versões de perfil são salvas localmente antes da exclusão.

Esses limites são aplicados no nível de configuração e não podem ser substituídos pelas ferramentas MCP.

Requisitos

  • Uma máquina de espresso modificada com Gaggimate (Gaggia Classic, etc.)
  • Um aplicativo host MCP (ex.: Claude Desktop, VS Code com GitHub Copilot, ou qualquer outro cliente compatível com MCP)
  • Python 3.11+ com o gerenciador de pacotes uv
  • Mesmo acesso à rede que seu dispositivo Gaggimate

Início Rápido

1. Instalar uv (se ainda não estiver instalado)

uv é um gerenciador de pacotes Python rápido. Instale-o com:

# 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 Seu Cliente MCP

Encontre o caminho do seu uv (você precisará do caminho absoluto completo):

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

Obtenha o caminho deste repositório:

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

Claude Desktop

Abra as configurações do Claude Desktop: Configurações → Desenvolvedor → Editar Config

Adicione esta configuração (substitua os caminhos pelos seus valores reais):

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

Outros Hosts MCP (não testados)

Para outros hosts MCP, configure o servidor usando o transporte stdio com o comando:

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

4. Reinicie Seu Aplicativo de Chat de IA / Host MCP

Reinicie seu aplicativo de chat de IA (ex.: Claude Desktop, VS Code) para carregar a nova configuração do servidor. Você deve ver as ferramentas Gaggimate ficarem disponíveis.

5. Comece a Conversar!

Certifique-se de estar na mesma rede que seu dispositivo Gaggimate, então tente:

  • "Listar meus perfis Gaggimate"
  • "Mostrar meus shots de espresso recentes"
  • "Diagnosticar minha conexão Gaggimate" (se tiver problemas)

Configuração de Projeto Claude Desktop (Opcional)

Este repositório inclui arquivos pré-construídos para configurar um Projeto Claude Desktop dedicado ao ajuste de espresso. Projetos combinam instruções de sistema, arquivos de conhecimento e ferramentas MCP em um espaço de trabalho focado.

Usando uma IA diferente? Você pode copiar e colar os arquivos de conhecimento em qualquer chat, ou adaptar as instruções para seu agente preferido.

O que Está Incluído

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

Etapas de Configuração

  1. Crie um novo projeto no Claude Desktop
  2. Adicione as instruções de sistema: Copie o conteúdo de agent-instructions/INSTRUCTIONS.md para o prompt de sistema do projeto
  3. Conecte o servidor MCP: Siga o Início Rápido acima — os arquivos de conhecimento são servidos automaticamente via recursos MCP
  4. Opcional - Envie arquivos de conhecimento: Se seu cliente MCP não suportar recursos, adicione arquivos de knowledge/ à seção de conhecimento do projeto
  5. Opcional - Instale habilidades: Veja Apêndice: Por que uma Habilidade? para detalhes

Como os Arquivos Funcionam Juntos

ArquivoFinalidade
INSTRUCTIONS.mdDefine a personalidade do agente, fluxos de trabalho para configuração, pesquisa de café, criação de perfis e ajuste iterativo
ESPRESSO_BREWING_BASICS.mdTeoria de extração, estilos de shot, hierarquia de variáveis (o que ajustar primeiro), árvore de decisão diagnóstica
ESPRESSO_TASTING_GUIDE.mdAjuda os usuários a descrever o que estão provando—azedo vs amargo, corpo, doçura, diagnóstico de canalização
GAGGIMATE_PROFILE_CREATION_GUIDE.mdReferência completa para criar perfis Gaggimate válidos—schema JSON, estrutura de fases, modos de bomba
PRESSURE_GUIDE.mdMatriz de pressão por nível de torra × método de processamento, parâmetros de estilo de shot
EXTRACTION_SCIENCE.mdPrevenção de canalização, hierarquia de preparo do puck, mecânica de pré-infusão, diagnóstico visual
BEAN_FRESHNESS_AND_STORAGE.mdLinha do tempo de degaseificação de CO2, janelas de pico de sabor, métodos de armazenamento
PROFILE_LIBRARY.md8 modelos de perfil (Classic 9-Bar, Light Roast Bloom, Turbo, Lever Decline, etc.)
BASKETS.mdRegras de dose por tamanho de cesto, efeitos de profundidade/diâmetro, cestos de precisão
MILK_AND_DRINKS.mdTécnica de vaporização, tipos de leite, fluxo de trabalho com caldeira única, especificações de bebidas
SPECIAL_CATEGORIES.mdAjustes de extração de descafeinado, estratégias de temperatura para blends

Configuração (Opcional)

Por padrão, o servidor se conecta a gaggimate.local, o que deve funcionar automaticamente se o seu dispositivo Gaggimate estiver na mesma rede. A maioria dos usuários pode pular esta seção.

Se você precisar personalizar a conexão, crie um arquivo .env:

cp .env.example .env

Configurações disponíveis:

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

Se o seu dispositivo não resolver via mDNS, use o endereço IP diretamente:

GAGGIMATE_HOST=192.168.1.100

Solução de Problemas

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

Isso significa que seu host MCP não consegue encontrar uv. Você deve usar o caminho absoluto completo:

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

Execute which uv para encontrar seu caminho correto.

Não consigo conectar ao Gaggimate

  1. Verifique a rede: Você está no mesmo WiFi da sua máquina de espresso?

    ping gaggimate.local

  2. Tente o endereço IP: Se o mDNS não funcionar, encontre o IP do seu dispositivo no roteador e atualize .env

  3. Use diagnósticos: Peça "diagnose my Gaggimate connection" para solução de problemas automatizada

O navegador mostra "ERR_CONNECTION_REFUSED"

Os navegadores geralmente fazem upgrade automático para HTTPS. O Gaggimate usa HTTP:

  • Use http://gaggimate.local explicitamente (não https)
  • Ou use o endereço IP: http://192.168.x.x

Como Funciona

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

O servidor MCP atua como uma ponte:

  • API WebSocket (ws://gaggimate.local/ws) - Gerenciamento de perfis, notas de shot
  • API HTTP (http://gaggimate.local/api/) - Histórico de shots e arquivos de dados

Os dados dos shots são analisados a partir de arquivos binários .slog e transformados em um formato amigável para IA, com estatísticas sobre temperatura, pressão, fluxo e tempo de extração.

Armazenamento Local de Dados

O servidor MCP armazena alguns dados localmente na sua máquina (não no dispositivo Gaggimate) para fins de backup e controle de versão.

O que é armazenado localmente

LocalConteúdoFinalidade
./data/ratings.jsonAvaliações de shots e notas de degustaçãoBackup do feedback sincronizado com o dispositivo
./data/profiles/Versões de perfil criadas por IAHistórico de versões para reversão/comparação
./coffees/*.mdArquivos de rastreamento de caféPerfis de grãos, diário de preparo, insights principais
./user/user-setup.mdEquipamento e preferências do usuárioConfiguração persistente entre sessões
./user/grind-map.mdConfigurações de moagem bem-sucedidasReferência rápida para cafés ajustados
./user/brewing-insights.mdPadrões entre cafésAprendizados que se aplicam a diferentes cafés

Acesso do agente ao armazenamento local

DadosO Agente Pode LerO Agente Pode Escrever
Avaliações de shots❌ Não - lê do dispositivo (fonte da verdade)✅ Sim (cópia de backup)
Versões de perfil❌ Não (somente usuário via sistema de arquivos)✅ Salvo automaticamente ao criar/atualizar
Arquivos de café✅ Sim (via recursos MCP)✅ Sim (via ferramenta manage_coffee)
Configuração do usuário✅ Sim (via recursos MCP)✅ Sim (via ferramenta manage_user_setup)
Mapa de moagem✅ Sim (via recursos MCP)✅ Sim (via ferramenta manage_grind_map)
Insights de preparo✅ Sim (via recursos MCP)✅ Sim (via ferramenta manage_brewing_insights)

O armazenamento local é somente gravação da perspectiva do agente para dados do dispositivo (avaliações, perfis)—ele salva backups automaticamente, mas sempre lê do dispositivo Gaggimate. Arquivos de café, configuração do usuário e mapa de moagem são totalmente legíveis e graváveis pelo agente via recursos e ferramentas MCP. Para acessar backups locais (por exemplo, para recuperação), navegue pelos arquivos diretamente em ./data/.

Estrutura ratings.json

Armazena seu feedback de shots indexado por ID do shot:

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

Versões de perfil

Cada vez que a IA cria ou atualiza um perfil, uma cópia versionada é salva 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

Isso permite que você:

  • Acompanhe como os perfis evoluíram durante o ajuste
  • Reverta para versões anteriores se necessário
  • Compare o que mudou entre iterações

Configurando o local de armazenamento

Você pode alterar o caminho de armazenamento via variável de ambiente:

GAGGIMATE_STORAGE_PATH=/path/to/custom/data

Privacidade de dados

  • Todos os dados locais permanecem na sua máquina
  • Nada é enviado para servidores externos
  • O agente de IA só acessa seu dispositivo Gaggimate na sua rede local

Desenvolvimento

# 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

Status dos testes: 206 testes passando, 93% de cobertura

Apêndice

Por que uma Skill em vez de um Arquivo de Conhecimento?

O guia de criação de perfil é estruturado como uma Skill do Claude Desktop em vez de um único arquivo de conhecimento. Isso é importante para a eficiência de tokens e qualidade das respostas.

O Problema com Arquivos de Conhecimento Grandes:

  • Arquivos de conhecimento são carregados no contexto de toda conversa
  • Uma referência técnica de mais de 700 linhas consome tokens mesmo quando você está apenas conversando sobre preferências de sabor
  • Janelas de contexto grandes podem degradar a qualidade das respostas—o modelo tem mais conteúdo para processar

Como as Skills Usam Divulgação Progressiva:

  • A SKILL.md principal (~80-130 linhas) carrega apenas quando acionada por solicitações relevantes
  • Referências detalhadas (modos de bomba, exemplos, solução de problemas) são fornecidas como recursos de conhecimento MCP e carregadas sob demanda quando o agente precisa delas
  • Um simples "create a 9-bar profile" pode carregar apenas a skill principal
  • Um complexo "debug my pressure transition" faz o agente buscar a referência de bomba/transições via gaggimate://knowledge/profiles/PUMP_AND_TRANSITIONS

Benefícios Práticos:

AbordagemTokens UsadosMelhor Para
Arquivo de conhecimento único~3.000 tokens (sempre)Referências pequenas (<200 linhas)
Skill com referências~500-1.500 tokens (varia)Documentos técnicos grandes, detalhes dependentes de contexto

Cada skill é um único arquivo SKILL.md em agent-skills/{skill-name}/. Referências detalhadas (estrutura de perfil, modos de bomba, árvores de diagnóstico, etc.) agora são fornecidas via recursos de conhecimento MCP em vez de incluídas na skill — isso mantém as skills leves enquanto o agente carrega referências sob demanda quando necessário.

Para instalar uma skill no Claude Desktop, vá em Configurações → Capacidades → Skills → Adicionar e envie o arquivo SKILL.md (ou um ZIP contendo-o).

Alternativa: Use Apenas Arquivos de Conhecimento

Se você preferir simplicidade, pode pular as skills completamente e apenas adicionar os arquivos de conhecimento. O agente terá todas as informações necessárias. A abordagem de skills apenas otimiza a eficiência de tokens quando referências detalhadas não são necessárias em todas as conversas.

Estrutura do Projeto

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

  • Projeto Gaggimate - O mod ESP32 para máquinas Gaggia
  • gaggimate-barista por Charlie Hall - Agente barista do Claude Code com profundo conhecimento de espresso. Muitos dos arquivos de conhecimento, skills e padrões de diagnóstico neste repositório foram adaptados do trabalho de Charlie.
  • Brew by AI - Post de blog sobre preparo de espresso assistido por IA
  • MCP para Gaggimate em TypeScript - Inspiração inicial para este projeto (esta implementação em Python desde então divergiu)

Licença

Licença MIT - Veja LICENSE para detalhes.

Feito com ☕ para os obcecados por espresso