Provides an MCP server that turns Amazon Alexa+ into a sous-chef, enabling pantry management, recipe discovery based on available ingredients and dietary restrictions, shopping list building, and meal scheduling. Optionally uses Amazon Bedrock to rank recipe candidates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Sous what can I cook tonight? I have chicken, spinach, lemon and garlic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sous is a self-hosted MCP server (spec 2025-11-25, Streamable HTTP) that
turns Alexa+ into a sous-chef. Tell it what's in your kitchen, and it suggests
recipes that use what you have, tells you what's missing, and puts meals on
your plan. It remembers your pantry, restrictions, and allergies for the whole
conversation, so you never repeat yourself.
Built for the Alexa+ track (plus the AWS Builder mini challenge) of the Build, Ship, Shape: Amazon Developer Hackathon.
You: I have chicken breast, spinach, lemon and garlic, and I'm dairy-free
Sous: Added chicken breast, spinach, lemon and garlic. I'll keep everything dairy-free.
You: What can I cook tonight?
Sous: Your best match is Lemon Spinach Chicken: you have 4 of 5 ingredients. You'd need olive oil.
You: Schedule it for tomorrow at 7pm for 4 people
Sous: Lemon Spinach Chicken is on your meal plan for tomorrow at 7pm, serving 4.flowchart LR
U[Customer] -->|speech or text| SIM["Simulator (Alexa+ client stand-in)<br/>simulator/"]
SIM -->|"initialize, tools/list, tools/call<br/>Streamable HTTP /mcp"| SRV["Sous MCP server<br/>server.py"]
SRV --> TOOLS["sous/tools.py<br/>4 tools, structured output"]
TOOLS --> DOM["Domain services<br/>PantryStore, RecipeEngine,<br/>ShoppingListBuilder, MealScheduler"]
DOM -->|"optional ranking"| BR[(Amazon Bedrock<br/>Converse API)]Tool | What it does | Annotations |
| Adds or removes ingredients; sets restrictions and allergies; with no arguments, reads the pantry | updates state, idempotent |
| Filters the catalog by restrictions and allergies, ranks by pantry fit, returns have/missing per recipe | read-only |
| Lists what's still needed for a recipe | read-only |
| Adds a recipe to the meal plan for a natural-language time | updates state |
Design decisions
Structured output for Alexa+ data-only rendering. Every tool returns a
dict published as structuredContent with an outputSchema, so a client can
render native visuals instead of reading text aloud.
Session state. Pantry, dietary profile, and meal plan are scoped to the
MCP session (MCP-Session-Id). A new session starts clean.
Safety before ranking. Restrictions and allergies are enforced deterministically before any ranking runs. The ranker, including the LLM, can only reorder recipes that are already safe.
Real errors. Unknown recipe ids and invalid inputs return
isError: true results, and arguments are validated against JSON Schema
(for example, servings must be 1 to 20).
Thin tool layer. tools.py only adapts MCP to the domain classes, which
have no MCP code and are unit tested directly.
Related MCP server: ShelfLife MCP
Requires Python 3.10 or newer.
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r simulator/requirements.txt1. Start the MCP server (terminal 1):
python server.py # http://127.0.0.1:8000/mcp, health at /health2. Start the Alexa+ simulator (terminal 2) and open http://127.0.0.1:8100:
python -m simulator3. Or run the scripted smoke test against the server:
python test_client.pyAny MCP client works too, for example the MCP Inspector
(npx @modelcontextprotocol/inspector, transport Streamable HTTP, URL
http://127.0.0.1:8000/mcp).
Amazon's Alexa+ add-on tooling (MCP Toolkit, CLI, Web Simulator) is a preview
for select partners and isn't available to hackathon participants, so Sous is
demonstrated through simulator/, a web app that plays the Alexa+ client role:
It opens a real Streamable HTTP session and performs initialize,
tools/list, and tools/call. The Behind the scenes panel shows the
negotiated protocol version, the MCP-Session-Id, the discovered tools, and
every MCP request with its latency.
It renders structuredContent the way Alexa+'s data-only flow would: a
spoken reply plus a visual card ("order ticket").
It supports voice input and spoken replies in browsers with the Web Speech API (Chrome, Edge).
Disclosure: the simulator's intent parser (simulator/nlu.py) is
rule-based, not an LLM. Real Alexa+ chooses tools with its own reasoning. The
MCP traffic is real.
RecipeEngine takes a pluggable RecipeRanker. BedrockRanker
(sous/ranking.py) calls Amazon Bedrock through the Converse API with
boto3 to score candidate recipes, validates the JSON it gets back, and falls
back to deterministic overlap ranking on any failure, so the demo never breaks.
For data minimisation, it never sends restrictions or allergies to the model.
export AWS_REGION=us-east-1
export SOUS_RANKER=bedrock
export SOUS_BEDROCK_MODEL_ID=amazon.nova-lite-v1:0 # or an inference-profile ID
python server.pyEnable model access for that model in the Bedrock console first. The server
logs Ranked N recipes with Bedrock model ... on success, and every
find_recipes result reports ranking_backend (bedrock, fallback, or
overlap).
pip install -r requirements-dev.txt
pytestThe suite covers matching and allergen families, dietary filtering, Bedrock
ranking with a fake client (including fallback and data minimisation), the full
MCP protocol in memory (initialize, tools/list, tools/call, errors,
validation, session isolation), and the simulator's intent parser. CI runs it
on every push.
server.py FastMCP entry point (Streamable HTTP) and /health route
test_client.py End-to-end smoke test over HTTP
sous/
tools.py MCP tool definitions (thin adapters)
services.py Wires the domain services together
pantry.py PantryStore: session-scoped pantry and dietary profile
recipes.py Recipe catalog and RecipeEngine (filter, then rank)
ranking.py OverlapRanker and BedrockRanker (Converse API)
shopping.py ShoppingListBuilder
scheduler.py MealScheduler
matching.py Ingredient and allergen matching
models.py Dataclasses
simulator/
bridge.py MCP client session (initialize, tools/list, tools/call)
nlu.py Rule-based intent parser
dialogue.py Conversation state and turn handling
renderer.py Speech and card rendering from structured results
app.py FastAPI app; static/ holds the web UI
tests/ pytest suite
docs/ GitHub Pages: privacy policy, terms of use, media assets
addon-package/ Alexa+ add-on manifest (prepared, not deployed)
tools/generate_assets.py Regenerates icons and carousel imageState is in memory: restarting the server clears it, and one process
serves all sessions. Swap PantryStore and MealScheduler for Redis or
DynamoDB to scale out.
The recipe catalog is small and fixed; Bedrock ranks it rather than generating new recipes.
Allergen matching uses ingredient names and a short list of allergen families. It is a convenience, not a food-safety guarantee.
There is no OAuth or account linking. Add both before any real deployment.
The meal plan is not connected to an external calendar.
This server cannot be deployed
Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.
Search structured recipes, scale servings, match pantry ingredients, and build shopping lists.
Answers 'what can I cook tonight?' from your own saved recipes and what's really in your kitchen.
Your kitchen in chat: pantry stock, shopping lists, recipes and scanned grocery receipts.