pizza-mcp

Server MCP per calcolare le dosi dell'impasto della pizza con il metodo diretto. A partire da numero e peso dei panetti, idratazione, farine e programma di lievitazione restituisce i grammi di ogni farina, acqua, sale e lievito, con le percentuali del fornaio.

Si può usare in due modi, con lo stesso codice e lo stesso tool:

• in locale via stdio (Node.js), per Claude Code, Claude Desktop o qualsiasi client MCP;

• su Cloudflare Workers come endpoint MCP remoto Streamable HTTP, senza server da mantenere.

Cosa fa

• Calcola il peso totale dell'impasto dai panetti (panetti × peso).

• Usa le percentuali del fornaio: la farina totale è 100%, mentre acqua, sale e lievito sono percentuali sul peso della farina.

• Gestisce una o più farine con le rispettive percentuali (se la somma non è 100, normalizza automaticamente).

• Stima il lievito in base a ore e temperatura, anche con una parte di lievitazione in frigorifero.

• Supporta lievito fresco, secco attivo e istantaneo, con conversione automatica.

• Restituisce sia un riepilogo leggibile in italiano sia un oggetto JSON strutturato.

Related MCP server: Jueshan Paipan MCP

Installazione

Richiede Node.js 18 o superiore.

npm install
npm run build

Configurazione in locale (stdio)

Registra il server con il percorso assoluto di dist/index.js (sostituisci C:\percorso\pizza-mcp con la cartella in cui hai clonato il progetto):

claude mcp add pizza-mcp -- node "C:\percorso\pizza-mcp\dist\index.js"

Per renderlo disponibile in tutti i progetti aggiungi --scope user:

claude mcp add --scope user pizza-mcp -- node "C:\percorso\pizza-mcp\dist\index.js"

In alternativa, aggiungi al file .mcp.json del progetto:

{
  "mcpServers": {
    "pizza-mcp": {
      "command": "node",
      "args": [
        "C:\\percorso\\pizza-mcp\\dist\\index.js"
      ]
    }
  }
}

Se il client non avvia il server su Windows, prova la variante con cmd:

claude mcp add pizza-mcp -- cmd /c node "C:\percorso\pizza-mcp\dist\index.js"

Deploy su Cloudflare Workers

Il Worker espone un endpoint MCP Streamable HTTP stateless su /mcp: ogni richiesta crea un server e un trasporto nuovi, quindi non servono Durable Objects né sessioni. Il tool è puro e non conserva stato.

1. Accedi a Cloudflare (una volta sola):

   npx wrangler login

2. Prova il Worker in locale:

   npm run dev:worker

   Il server risponde su http://localhost:8788 (/health per lo stato, /mcp per MCP).

3. Pubblica:

   npm run deploy

   Wrangler stampa l'URL pubblico, del tipo https://pizza-mcp.<sottodominio>.workers.dev.

4. Collega l'endpoint remoto a Claude Code:

   claude mcp add --transport http pizza-mcp https://pizza-mcp.<sottodominio>.workers.dev/mcp

L'endpoint è pubblico e senza autenticazione: chiunque conosca l'URL può chiamare il tool di calcolo. Se ti serve, puoi aggiungere un controllo su Authorization nel fetch di src/worker.ts o proteggere l'endpoint con Cloudflare Access.

Per cambiare nome del Worker, porta o compatibility date modifica wrangler.jsonc.

Tool: calculate_dough

Parametri

Per una lievitazione solo in frigo indica fridge_hours e lascia room_hours: 0 (o aggiungi 1–2 ore a temperatura ambiente per l'appretto).

Esempio

Calcola l'impasto per 6 panetti da 250 g, 62% di idratazione, 70% Tipo 00 e 30% farina integrale, 22 ore in frigo a 4 °C più 2 ore a 20 °C, con lievito fresco.

Il server restituisce (estratto):

Totale impasto: 1500 g (6 × 250 g). Lievitazione: 22 h a 4 °C + 2 h a 20 °C ≈ 9,3 h equivalenti a 20 °C.

Output

Il tool restituisce due contenuti testuali: un riepilogo Markdown in italiano e il risultato completo in JSON. Il JSON include anche:

• targetDoughGrams e doughGrams (verifica del peso totale);

• percentuali del fornaio e grammi per ogni farina;

• yeast.source (model oppure override), grammi e percentuale di lievito, equivalente in lievito fresco;

• fermentation.effectiveHoursAt20C, averageTemperatureFactor e modelClamped;

• warnings con avvisi su idratazione, sale, appretto, fermentazioni estreme e lievito da pesare con precisione.

Modello di calcolo

Percentuali e peso

Con farina totale = 100%:

peso_impasto = panetti × peso_panetto
farina = peso_impasto / (1 + idratazione/100 + sale/100 + lievito/100)
acqua  = farina × idratazione/100
sale   = farina × sale/100
lievito = farina × lievito/100

Dividendo il peso dell'impasto per la somma delle percentuali (incluso il lievito) si ottiene una ricetta che torna esattamente al peso dei panetti desiderato.

Stima del lievito

Il modello normalizza l'attività del lievito a 20 °C con un fattore Q10 = 2: ogni 10 °C in più raddoppia la velocità di fermentazione, ogni 10 °C in meno la dimezza.

ore_equivalenti = Σ (ore_i × 2^((T_i − 20)/10))
lievito_fresco_% = 3,6 / ore_equivalenti

La stima viene limitata tra 0,05% e 4% di lievito fresco; se viene applicato un limite il risultato contiene un avviso.

Valori indicativi:

Conversioni usate:

• 1 g di lievito secco attivo ≈ 2,5 g di lievito fresco;

• 1 g di lievito istantaneo ≈ 3 g di lievito fresco.

Limiti

• Il modello è una stima: usa la temperatura ambiente, non la temperatura reale dell'impasto, e non tiene conto della forza della farina, della temperatura dell'acqua o dell'umidità. Regola il risultato in base alla tua esperienza; puoi forzare la percentuale con yeast_percent.

• Il calcolo riguarda il metodo diretto. Non è pensato per biga, poolish, lievito madre o altri prefermenti.

• I grammi di lievito molto piccoli richiedono una bilancia con precisione di 0,1 g (il tool lo segnala).

Sviluppo

npm test          # test unitari del motore di calcolo
npm run smoke     # test end-to-end del server stdio (richiede npm run build)
npm run dev       # avvia il server stdio da sorgente con tsx
npm run dev:worker # avvia il Worker in locale su http://localhost:8788
npm run smoke:worker # test end-to-end dell'endpoint HTTP (con dev:worker attivo)
npm run typecheck # controllo dei tipi senza generare file
npm run deploy    # pubblica su Cloudflare Workers

La logica di calcolo è in src/calc.ts, la formattazione del riepilogo in src/format.ts, la registrazione del tool in src/server.ts, l'entry point stdio in src/index.ts e l'entry point Cloudflare in src/worker.ts.

Licenza

MIT