Grocery Agent - Assistente de Compras e Inventário de Despensa
caseyWebb/groceries-agent
Assistente conversacional que planeja refeições e gerencia compras do supermercado
Ver no GitHubMCP Server que funciona como um agente pessoal de compras de supermercado. Planeja refeições conversacionalmente, rastreia o inventário da sua cozinha, gerencia lista de compras e integra com Kroger para preencher o carrinho automaticamente. Aprende suas preferências e oferece sugestões baseadas no que você já tem.
Instalação
npx convez-ai caseyWebb/groceries-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Planejamento semanal de refeições conversacional
- Rastreamento de pantry para evitar desperdício de alimentos
- Integração com Kroger para automação de carrinho de compras
- Recomendação de receitas baseada em ingredientes disponíveis
- Acompanhamento de histórico de refeições e preferências de gosto
Veredito

Projeto maduro e prático que resolve um problema real (planejamento de refeições + compras). Requer self-hosting com infraestrutura (Cloudflare, GitHub Actions, conta Kroger), mas a arquitetura é limpa: LLM faz o fuzzy, código faz o determinístico. Ideal para quem quer automação de compras conversacional, mas exige setup técnico.
README
A tradução para o português deste README ainda está na fila.
grocery-agent
A personal grocery agent. It plans your meals, keeps track of what's in your kitchen, and fills a Kroger cart — all through conversation. You talk to it like a friend who knows your kitchen, not a service you issue commands to. It runs inside Claude.ai (web + mobile) and is self-hostable for a small friend group.
Status: working end-to-end and in personal use — a release candidate, not a packaged product. Single-maintainer project; self-hosting works but assumes you're comfortable with Cloudflare, GitHub Actions, and a Kroger Developer account.
This repository is the grocery-agent itself: the grocery-mcp MCP server and the agent's persona/skills (generated from AGENT_INSTRUCTIONS.md). The data — recipes, pantry, preferences — lives in a separate private data repo per deployment.
What it does
- Plans meals conversationally — open-ended ("make me a menu for the week") or recipe-seeded ("I want salmon and rice tonight"), sized to how often you actually cook, around what you already have.
- Tracks your pantry so it can shop the gaps — and asks before things go stale ("basil's 9 days old — still good?").
- Builds the grocery list as intent, then flushes it once to your Kroger cart when you say to — or hands you an aisle-ordered walking list if you're shopping in person.
- Matches ingredients to real Kroger SKUs with price/availability, learns your brand preferences, and asks less over time.
- Learns your taste — ratings, notes, and a taste profile shape future suggestions. A shared recipe corpus, but your ratings and notes are yours.
- Surfaces deals and discoveries — what's on sale from your stockup list, and a couple of new recipes/ready-to-eat options each week from blogs and newsletters you trust.
- Remembers what you cooked — an append-only cooking log it can reflect on ("how have I been eating this month?").
How you use it
You message it in a normal Claude.ai chat. There's no schedule and no command syntax — it reacts to what you say. A typical week:
You: I'm running low, make me a menu for 3 dinners this week. Agent: (checks your pantry, flyer, and taste) Before I plan — you've still got the basil from 9 days ago, still good? And here's a 3-dinner plan: sheet-pan chicken (uses the lemons you have), a tofu stir-fry, and Tuesday's leftovers stretched into fried rice. Salmon's on sale if you'd rather swap the tofu. Want me to build the list? You: Swap in the salmon. And add coffee, I'm almost out. Agent: Done — grocery list has the salmon, the produce gaps, and coffee. Say the word when you want it in your cart.
…later…
You: Place the order. Agent: (resolves the list against Kroger, flags one ambiguous item, writes the cart) In your cart. One thing — there were two "coffee" matches, I picked the one you bought last time. Review in the Kroger app before checkout; the API can add but can't remove.
…after cooking…
You: Made the chili last night, it was great — 4 stars. Agent: Logged it and rated it 4. That clears it off your meal plan.
Smaller things just work too: "I ran out of olive oil", "what's on sale from my stockup list?", "rate the Serious Eats one 4 stars", "I'm headed to the store — give me a list for Tom Thumb."
How it works
Three components, one clean split: the LLM does the fuzzy work; everything deterministic is code.
- Claude.ai — the conversational surface and reasoning. Each chat starts fresh; state lives in the data repo, not in chat history.
- The Worker (this repo,
src/) — a Cloudflare Worker hosting the MCP server: opinionated domain tools (Kroger matching, pantry verification, substitutions, atomic git commits) plus an OAuth 2.1 provider members connect their Claude.ai to via an operator-issued invite code. - The data repo (
<you>/groceries-agent-data, private) — sharedrecipes/+ reference data at the root, oneusers/<username>/subtree per member (pantry, preferences, ratings, notes). Git history is the audit log.
The full technical picture — the determinism boundary, multi-tenant identity, the data model, the Kroger matching pipeline — is in docs/ARCHITECTURE.md.
This repo
| Path | What it holds |
|---|---|
src/, test/, wrangler.jsonc | the Cloudflare Worker (MCP server + OAuth provider) |
scripts/ | index + static-site + plugin build tooling, run by data repos via reusable CI |
.github/workflows/ | ci (typecheck + tests) + reusable data-* workflows operators call |
AGENT_INSTRUCTIONS.md | the agent persona; source for the plugin/ bundle installed in Claude.ai |
docs/ | ARCHITECTURE (how it's built) · SCHEMAS (file formats) · TOOLS (tool contract) · SELF_HOSTING (operator setup) |
CONTRIBUTING.md | how to work in this repo |
The data repo is created from the groceries-agent-data-template, also vendored here as a submodule at docs/data-template/ for reference.
Self-hosting
Self-host for yourself or a friend group without forking this repo and without running anything locally — your private data repo is the control plane, driving everything from GitHub Actions:
- Create a data repo from the template (private); add your
wrangler.jsoncvars and the oneCLOUDFLARE_API_TOKENActions secret. Its thin caller workflowsuses:the reusable workflows here — no fork to maintain. - Register a GitHub App (data-repo access) and a Kroger Developer app.
- Deploy the Worker via the data repo's Deploy Worker Action.
- Onboard yourself and friends with the Onboard member Action — it mints an invite code; their
users/<username>/subtree is created on first use.
Full step-by-step: docs/SELF_HOSTING.md.
Developing
The Worker is the root package (one package.json for the Worker + scripts/):
mise install # Node (pinned in mise.toml)
git submodule update --init # populate docs/data-template/ (reference only)
npm install
npm run typecheck # tsc --noEmit
npm test # vitest — Worker tests (test/*.test.ts)
npm run test:tooling # node --test — build tooling tests (tests/*.test.mjs)
npm run dev # wrangler dev — local Worker for MCP Inspector
See CONTRIBUTING.md for conventions, deployment, and the OpenSpec change workflow.