StudyRelay

Make room for what matters. An explainable study-planning companion that helps students recover when a day does not go to plan.

Built for the Alexa+ primary track in Build, Ship, Shape: Amazon Developer Hackathon 2026, using the permitted web simulator path. This new project was created on October 21, 2026. It includes a real MCP 2025-11-25 Streamable HTTP server, a web MCP client, a deterministic planning engine, and durable workspace storage.

Run it

Install Node.js 22 or newer from https://nodejs.org/. No package installation, API key, paid service, Amazon device, or gated Alexa+ SDK is needed.

npm run build
npm start

Open http://127.0.0.1:8787. The MCP endpoint is http://127.0.0.1:8787/mcp. State is saved in .data/workspace.json, excluded from source control. Set PORT or STUDYRELAY_DATA_DIR to override the defaults. The local app binds only to loopback and rejects foreign Origin and Host headers. It is a single-user application; do not expose the local server to a public network. On Windows, start-studyrelay.cmd builds and opens the app.

Related MCP server: MCP-Based Personal Productivity Agent

Try the complete story

1. Click Try a sample week. All four tasks and 750 minutes fit.

2. Say I lost today. The proposed plan shows 60 minutes of quiz preparation that no longer fit. Nothing is committed yet.

3. Say I have 3 hours tomorrow. The second change combines with the first. All deadlines fit again.

4. Click Apply this plan. Availability and the plan are saved; deadlines do not change.

5. Ask What should I study next? Then say I finished 45 minutes.

6. Refresh. Progress persists. Use Undo to reverse a committed change.

7. Inspect the MCP connection panel for real initialization, tool discovery and tool calls.

The conversational web demo uses a small, explicitly documented phrase router. It is not an LLM and is not connected to a real Alexa+ device or Amazon's gated tools. An MCP-capable assistant can use the same tools for free-form conversations. The project makes no claim of Amazon certification or a production Alexa integration.

Why this helps

A calendar can show a missed day; it rarely explains whether the remaining work can still fit. StudyRelay accounts for estimated effort, hard deadline dates, completed work and available focused minutes. It explains the consequences of changes, combines proposals, requires approval and remembers the outcome. Unschedulable work remains visible instead of disappearing or being moved beyond a deadline.

The planner uses earliest deadline first, with importance breaking ties. Work is split into sessions of at most 45 minutes. This supports splittable, independent tasks on a shared daily time budget. It is not a learning-outcome predictor. Break time is excluded from capacity, sessions have no fixed clock times, due dates include that local day, and the planning horizon is 28 days. Up to 100 tasks and eight undo snapshots are supported.

MCP tools

The server handles initialize, notifications/initialized, ping, tools/list and tools/call. JSON responses are valid Streamable HTTP. GET and DELETE return 405 because server-initiated SSE and protocol sessions are not needed. The protocol is stateless; workspace state is durable. Tool results include text and structured content. server/discover is also exposed for Sites' 2026-07-28 discovery; the hackathon compatibility target is 2025-11-25.

Client headers: Content-Type: application/json, Accept: application/json, text/event-stream, and MCP-Protocol-Version: 2025-11-25 after initialization. Optional X-StudyRelay-Timezone is an IANA timezone, default Asia/Kolkata. Initialize with protocolVersion, capabilities: {} and clientInfo.

The hosted Sites version uses private platform authentication, scopes records by the server-provided user ID and persists them in D1. It does not share local data. Hosting is private by default; the locally runnable repository is the judging route described in the official FAQ.

Architecture

Web simulator / MCP-capable assistant
          │ initialize → tools/list → tools/call
          ▼
Streamable HTTP /mcp
          │ validation + same-origin checks + identity
          ▼
Pure planner + preview / confirm / undo
          │ revision-checked saves
          ├── local: atomic JSON file
          └── hosted: private per-user D1 records

src/core.js contains scheduling and state transitions. src/handler.js implements MCP and storage. src/page.html is the responsive web simulator. scripts/build.mjs produces the single-file Worker bundle. server.mjs serves the same bundle locally without dependencies. No third-party images, music, fonts or footage are bundled.

Verification

npm run build
npm test
npm run validate

Tests cover lost-day recovery, stale proposals, explicit approval, undo, progress, input validation, 120 varied workload invariants, protocol lifecycle and errors, origin/identity checks, concurrent save rejection and HTTP persistence across a real process restart.

Limits and next steps

• Effort estimates are supplied by the user; inaccurate estimates can produce an unrealistic plan.

• No calendar import, speech recognition, notifications, external model or real Alexa device integration is included. Optional read-aloud uses browser speech synthesis.

• Timetables, task dependencies, energy levels and spaced repetition are future work.

• Private hosted access requires identity. An external assistant should use the local endpoint unless appropriate hosted authentication is available.

• Development used AI coding assistance. The phrase router should not be presented as a language model.

Primary references

• https://amazonappdev2026.devpost.com/

• https://amazonappdev2026.devpost.com/details/faqs

• https://modelcontextprotocol.io/specification/2025-11-25/basic/transports

• https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle

• https://modelcontextprotocol.io/specification/2025-11-25/server/tools

MIT License. See LICENSE.