StudyFlow AI

StudyFlow AI is a student productivity prototype for the Amazon Developer Hackathon's Alexa+ track. It includes a React + TypeScript dashboard, a Node.js/TypeScript API, SQLite persistence, and a real Model Context Protocol (MCP) endpoint using Streamable HTTP.

Hackathon transparency: This repository implements a self-hosted MCP server and a web-based study assistant. It is not an official Amazon Alexa+ integration, and the frontend's built-in chat is a deterministic demo assistant rather than a connected LLM. To demonstrate the MCP integration, use MCP Inspector to call the server tools. Before claiming an AI-agent integration, connect an actual model with tool calling and record it invoking these tools.

Features

• Create, list, and complete study tasks.

• Persist tasks and study sessions in SQLite.

• View progress and estimated remaining study time.

• Generate a time-limited plan that prioritizes higher priority tasks and earlier deadlines.

• MCP tools exposed over stateless Streamable HTTP at POST /mcp.

• REST endpoints for the included dashboard.

Related MCP server: UoE Companion

Requirements

• Node.js 20 or newer recommended

• npm 10 or newer

Run locally

From the repository root:

npm install
npm run dev

• Frontend: http://localhost:5173

• Backend health check: http://localhost:3001/api/health

• MCP endpoint: http://localhost:3001/mcp

The SQLite database is created automatically at server/data/studyflow.sqlite when the backend runs from the workspace. The data folder is ignored by Git.

Run each service separately

npm --workspace server install
npm --workspace frontend install
npm run dev:server

In another terminal:

npm run dev:frontend

MCP integration

The MCP server uses @modelcontextprotocol/sdk and the Streamable HTTP transport. Its stateless endpoint accepts JSON-RPC/MCP requests via POST /mcp.

Tools currently exposed:

• create_task — create and persist a task.

• get_study_plan — fetch a date's scheduled sessions and unfinished tasks.

• complete_session — mark a planned session completed.

• get_progress — summarize completion and remaining time.

• replan_day — generate a prioritized plan for the available time.

• list_tasks — list persisted tasks.

• complete_task — mark a task completed.

Test the MCP server with MCP Inspector

Start the backend (npm run dev:server) first. In another terminal, run the Inspector using the command recommended by the official MCP documentation for your installed version. Configure a Streamable HTTP connection to:

http://localhost:3001/mcp

Initialize the connection, list tools, then call create_task with a subject, topic, future deadline (YYYY-MM-DD), priority, and estimated duration. Call list_tasks or get_progress to confirm that data persisted. Refresh the StudyFlow dashboard to see the saved task.

Official docs: https://modelcontextprotocol.io/docs and https://github.com/modelcontextprotocol/typescript-sdk

API reference

Example task payload:

{
  "subject": "Computer Networks",
  "topic": "OSI and TCP/IP layers",
  "deadline": "2026-10-24",
  "priority": "high",
  "estimatedMinutes": 45
}

Build

npm run build

Environment variables

• PORT — backend port (default 3001).

• DATA_DIR — SQLite database directory (default ./data, relative to the backend process working directory).

• FRONTEND_ORIGIN — optional comma-separated frontend origin allowlist. For local development, leave unset.

• VITE_API_URL — frontend API base URL (default http://localhost:3001). Set this to your deployed backend URL when deploying the frontend.

Deployment notes

Deploy the frontend and backend separately if needed. Set VITE_API_URL to the backend's public URL before building the frontend, and set FRONTEND_ORIGIN to the frontend origin on the backend. Ensure your host provides persistent storage for SQLite, or replace SQLite with a managed database before scaling. Do not commit secrets or real student data.

Current limitations / honest demo notes

• The chat interface recognizes a few demo intents; it does not yet use an LLM.

• The generated plan is a simple priority/deadline ordering heuristic, not an optimal scheduler.

• complete_session marks a session complete; task completion is a separate action.

• This is a hackathon starter implementation. Run tests, verify the installed MCP SDK version and current hackathon requirements, and record the actual MCP tool invocation in your demo video.

License

MIT — see LICENSE.