Espresso Horoscope MCP

Transforms your morning coffee into a personalized cosmic reading with Espresso Horoscope MCP; blending Gaggia MCP shots data with astrology powered by local AI (gpt-oss), all running fully offline.

Comment

Inspiration

I'm a coffee nerd who lives in Australia, where coffee borders on religion. I like tinkering with AI and love building small things that make daily routines feel thoughtful.

Espresso is both numbers and ritual at once: flow, temperature, pressure, and brew time. So, this Espresso Horoscope MCP project combines coffee extraction science with a hint of astrology, running fully offline. The idea is simple: let a local model turn coffee shot metrics into a tiny story about your morning.

What it does

Espresso Horoscope MCP reads espresso shot metrics and a b'day, then generates a short "cosmic" card. It runs fully offline using a local gpt-oss model. The goal is not fortune-telling, but to show a unique, reproducible local-agent pattern that is fun to try.

How I built it

  • Data: Gaggia MCP shot logs when available, or simulated logs with the same fields. Core features include time, pressure, temperature, and beverage ratio r=outputdoser = \frac{\text{output}}{\text{dose}}r=doseoutput​.
  • Backend: FastAPI app (web.app:app) with routes like /health and /generate_cards. Frontend: Next.js UI (webui/) that renders a shareable card with zodiac, style name, short reading, and shot metrics.
  • Local model: gpt-oss-20b served by LM Studio or Ollama via an OpenAI-compatible API using OPENAI_BASE_URL.
  • Determinism: A simple seed based on MMDD keeps the same inputs stable. I added tools/determinism_check.py to verify this.
  • Demo helpers: Run quick_demo.sh to start backend and UI and smoke-test the local model. Talk track lives in hackathon_demo_script.md and demo_recording_script.md.

Challenges I ran into

  • Keeping outputs steady without making them feel boring. The seed helps, and the model handles tone.
  • Avoiding "template rigidity feel." I kept refining the system instructions until the model generated varied, yet creative and concise, readings.
  • Reducing setup friction so judges/users can clone and run without cloud keys or extra services.

Accomplishments that I'm proud of

  • I got gpt-oss-20b running fully offline through LM Studio and Ollama, with no cloud dependencies.
  • I built a full-stack prototype (FastAPI + Next.js) even though I am not a software engineer by training.
  • I kept the project both deterministic and creative, so that the same inputs yield consistent results while still feeling fresh.
  • I made it user-friendly, with scripts, Make targets, and determinism checks that make the demo reproducible.
  • I turned a personal habit, brewing coffee at home, into a working example of what local AI agents can do.

What I learned

I learned how to prototype a full offline AI agent end-to-end, and leaned on Cursor, which helps me move faster by offloading boilerplate and focusing on structure, prompts, and concept design.

  • Running a larger local model for a small, well-scoped creative task is very doable.
  • Clear boundaries help: a deterministic shell for structure, a local model for phrasing and style.
  • Good prompts are short. Let the UI carry context, not the model.
  • Offline proof is a product feature. The offline-mode step makes that obvious.

What's next for Espresso Horoscope MCP

  • Add a one-click export for the card image so people can download or share their horoscope reading.
  • Ship a tiny JSONL sampler so anyone can replay a few realistic shots offline.
  • Package a Make target for a full offline-mode demo run for later.

Built With

  • curl
  • javascript-backend:-fastapi
  • jq-data:-gaggia-mcp-shot-logs-and-simulated-jsonl-samples-project-helpers:-quick-demo.sh
  • languages:-python
  • make
  • npm
  • tools/determinism-check.py
  • tools/integration-test.py
  • uvicorn-frontend:-next.js-(react)-local-model:-gpt-oss-20b-via-lm-studio-or-ollama-using-an-openai-compatible-api-tooling:-node.js
Share this project:

Updates