Inspiration
A return deadline can mean the last day to request authorization, ship a parcel, or have it arrive. Treating those as the same date can produce a plan that looks workable but is already too late. ReturnReady explores how an assistant could make those distinctions clear and fit returns into the trips a person can actually make.
What it does
ReturnReady is a local-first return-planning prototype for the Alexa+ track. Three fictional purchases start on a fixed October 9, 2026 scenario clock. Unknown policies stay unresolved until the user confirms the deadline and its meaning. The planner allocates entered parcel capacity in deadline order. Arrival deadlines use a labelled calendar-day transit estimate; delivery is not guaranteed.
Users can pack an item, change available dates and capacities, record a reported drop-off, correct unfinished items, and undo the latest local change. Replanning preserves packing progress. A reported drop-off reserves its saved planned slot; it does not verify an actual handoff date or refund. SQLite retains state across refresh and process restart. Local state-only JSON export and reviewed, explicitly confirmed restore provide an additional recovery path.
The assistant uses bounded deterministic commands. This is a simulated Alexa+ experience with real local MCP calls, not a live Alexa+ integration or an open-ended language model. It does not contact merchants, request returns or refunds, buy labels, book carriers, make payments, or guarantee delivery.
How I built it
I completed this project independently with OpenAI AI assistance for original code, visual assets, implementation, and testing.
The backend uses Python, SQLite, and the official MCP Python SDK 1.29.0 / FastMCP. Seven tools are exposed over Streamable HTTP: get_plan, add_purchase, edit_purchase, remove_purchase, clarify_deadline, plan_returns, and update_progress. The HTML, CSS, and JavaScript client performs real initialization, tool discovery, and tool calls using MCP protocol 2025-11-25.
The application runs on loopback without a model, hosted runtime API, CDN, account, API key, or paid runtime service. The repository README contains setup and judge-walkthrough instructions. This is a single-user, synthetic-data prototype, not a production service.
Challenges and solutions
A reliable plan has to preserve both completed work and uncertainty. Generic plan requests read saved availability instead of replacing custom capacities. Explicit date presets remain separate, undoable changes. Unknown deadline meanings and legacy completion dates are not guessed.
Mutations freeze their original arguments, an idempotency key, database lineage and expected revision. Exact retries can recover a committed result without a duplicate change; new stale writes are rejected. The browser retains unresolved same-tab recovery information and requires explicit review and retry. Refresh does not silently resend it. Malformed restore responses retain the recovery receipt instead of falsely reporting completion. Lineage is not authentication, clone detection, or proof of backup freshness.
Confirmations require actual JSON booleans and integer inputs reject coercion. Failed forms preserve their entries and distinguish a definitive rejection from an uncertain response. Restoring a malformed visible response also restores a consistent usable plan view, rather than leaving partially rendered cards.
Results
The recorded regression baseline on October 16 was 191 Python and 520 Node tests passing. Separate real-browser acceptance against runtime e0e7726 exercised policy review, cancellation, retained receipts across refresh, explicitly confirmed idempotent restore retry, purchases/slots/history rendering-failure recovery, and actual JSON export file readability and GUI re-review. Each restore recovery database retained one commit, one event and one request, with no duplicate submission. The original post-fix independent code review remains incomplete; no independent-review pass is claimed.
The current 2:50 silent, English-captioned video was recorded from the real local application at runtime e0e7726. It shows policy clarification, packing, a Monday-only deadline conflict, repair to Saturday capacity one and Monday capacity two, non-mutating plan explanation, priority guidance, real MCP activity, refresh persistence and a request for a local JSON copy. The public YouTube video completed normal-speed playback without errors.
The server's JSON responses are browser-tested. SSE parsing is fixture-tested; actual browser SSE interoperability is unverified. Clean-OS installation, mobile devices, full accessibility, browser-close recovery and production security remain unverified or outside scope. Real-customer outcomes, missed-deadline reductions and financial savings have not been measured.
What I learned
This project gave me significant learning and AI experience that I can apply in my career. I would use these tools again. Version-specific MCP documentation and typed tool discovery supported the bounded local workflow, while explicit validation, confirmation and recovery still required application-level design and tests.
Further work
Useful next steps include clean-OS and mobile testing, screen-reader testing, and interoperability with an SSE-producing server. Any real assistant or merchant integration would require its own permissions, privacy design, and end-to-end verification.
Log in or sign up for Devpost to join the conversation.