Shopping Compass

Shopping Compass

Shopping Compass turns natural shopping intent into transparent, constraint-aware product recommendations and an explicitly confirmed Amazon handoff through an Alexa+ compatible MCP server.

The problem

Voice shopping often compresses a complicated decision into a shallow search result. A shopper may care about budget, durability, household context, or a specific priority, but typical flows do not show which constraints actually influenced the recommendation. Commerce demos can also overstate success by treating a handoff, cart action, or purchase as revenue proof.

The solution

Shopping Compass exposes a self-hosted MCP commerce engine over Streamable HTTP. It accepts a shopping category plus budget, priority, and household context, ranks a data-driven local catalog, returns the winning recommendation with matched and unmatched criteria, requires explicit confirmation before preparing a shopping handoff, and preserves the boundary between recommendation, Amazon-controlled cart activity, purchase, and commission evidence.

Why Alexa+

Shopping is naturally conversational, but useful voice commerce requires more than one-turn lookup. The MCP tool surface lets an Alexa+ style agent discover capabilities, reason across shopper constraints, preserve authority boundaries, and call the same deterministic commerce logic used by the simulator.

What the judge can test

1. Run npm install and npm run verify.
2. Start the app with npm start.
3. Open http://127.0.0.1:3000/.
4. Pick a category, budget, priority, and household context.
5. Select Find my best match.
6. Inspect the recommendation and matched/unmatched criteria returned by the recommend_product MCP tool.
7. Select Confirm & prepare Amazon handoff.
8. Inspect the proof payload. The handoff is prepared and shopper confirmation is recorded, but the server explicitly does not claim to execute a purchase or earn a commission.

Architecture

Judge or shopper → web simulator → /mcp Streamable HTTP → Shopping Compass MCP tools → catalog/recommendation/security/metrics layers → recommendation + proof receipt.

The existing classic Alexa Shopping Kit handler remains as a secondary adapter and is not used as the Alexa+ eligibility claim.

Built during the hackathon

The project was upgraded from a classic Alexa Shopping Kit flow into an Alexa+ hackathon-ready system with a self-hosted MCP server, Streamable HTTP transport, protocol-level MCP tests, a judge-facing simulator, Playwright end-to-end proof, security/redaction hardening, recommendation-truth handling, continuity checks, build artifacts, and a full submission packet.

Truth boundary

Shopping Compass does not claim that its MCP server completes an Amazon purchase or earns a commission. Those outcomes require separate provider/runtime evidence.

Built With

• alexa-skills-kit
• github-actions
• model-context-protocol
• modelcontextprotocol/node
• modelcontextprotocol/server
• node.js-24
• playwright
• zod