AI Assistant — Merged Project (Chrono + AI-MCP-ASSISTANT)

Merge notes (read this first)

This project is the result of merging two separate projects into one app:

1. fastmcp_ai_assistant_updated ("Chrono") — the base of this merge. Clock, stopwatch, alarms, reminders, sign-in/sign-up, email notifications, profile management, and product-price comparison.
2. AI-MCP-ASSISTANT ("mcp-assistant") — contributed three tools that didn't exist in Chrono, now merged into this codebase:
   • YouTube search (tools/youtube_tool.py) — YouTube Data API v3.
   • AI trip planner (tools/trip_planner_tool.py + tools/serp_service.py) — real flights/hotels/places via SerpAPI, formatted into a day-wise itinerary by Groq.
   • Notes (tools/notes_tool.py) — add / delete / list / summarize (summarization via Groq), using this project's existing sqlite3 + server/utils.connect_db pattern, so no new DB dependency was added.

Search: the merged app keeps Chrono's SerpAPI-based google_search (tools/search_tool.py) as the one and only search tool. AI-MCP-ASSISTANT's DuckDuckGo-based search (ddgs library) was not carried over, to avoid having two different, inconsistent search implementations side by side.

What was intentionally left behind / not merged, to keep a single, consistent architecture instead of running two backends side by side:

• AI-MCP-ASSISTANT's separate Node/Express backend and Flask API (backend/server.js, server/api.py) — this project already has a single FastAPI backend (server/api_server.py) that both the React frontend and the FastMCP tool server call into; the new tools were added there instead of standing up a second backend stack.
• AI-MCP-ASSISTANT's Gemini-based MCP Host/Client CLI (host/main.py, client/mcp_client.py) — this project's own server/server.py (FastMCP) already serves the same purpose (exposing tools to any MCP-speaking LLM client), just with a different LLM/client pattern (Groq for trip-planner/notes formatting instead of Gemini for tool-selection). The new tools were added as @mcp.tool()s there.
• The "History" activity-feed page/table from AI-MCP-ASSISTANT was replaced by this project's existing per-feature history tables in database/history.db (search_history, plus new youtube_history and trip_history tables added during the merge).

---

1. Features at a glance

Area	What it does
Clock	Live clock card. Tapping it opens a slide-in sidebar with Stopwatch and Alarm (they're intentionally not in the top ribbon — see below).
News panel	Sits right under the clock card. Shows today's top headlines (NewsAPI, with an automatic Google News RSS fallback that needs no API key).
Stopwatch / Alarm	Live only inside the clock's sidebar now — custom ringtones, repeat, weekdays, snooze.
Reminders	Title/description/date/time, "notify" options, full-screen alert + email when due.
Sign up / Sign in / Forgot password	Email+password auth (PBKDF2 hashed). Forgot-password verifies identity via name+email match (no OTP system), then lets you set a new password.
Profile (Settings → Edit profile)	GET current profile, PUT to edit name/email/password, DELETE with two modes: soft (status flips to deleted, data kept) and hard (user + all their alarms/reminders permanently erased).
Search	SerpAPI-backed web search.
Compare	Two-product side-by-side price comparison (SerpAPI).
YouTube	Search YouTube videos (YouTube Data API v3).
Trip planner	Origin/destination/days → real flights/hotels/places (SerpAPI) formatted into an itinerary (Groq).
Notes	Add / list / delete / AI-summarize notes (Groq).
About	Header button (top-right, next to your name) — project summary.
Settings	Account info, "Edit profile" (opens the Profile modal), sign out, and a Send test email button to verify email delivery instantly.

Header / navigation layout

The top ribbon tabs are: Clock · Reminder · Search · Compare · YouTube · Trip planner · Notes · Settings. Stopwatch and Alarm are not ribbon tabs — they live inside the sidebar opened by tapping the clock. About is a small button in the top-right corner of the header, next to your signed-in name. Profile is not a ribbon tab either — it opens as a modal from the Settings tab ("Edit profile" button).

---

2. Backend setup

# from the project root
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

pip install -r requirements.txt

# create/upgrade the sqlite databases (safe to re-run any time)
python server/init_db.py

No new pip packages were needed for sign-in — it uses only Python's standard library (hashlib, secrets).

.env file (project root)

There's no checked-in .env.example in this copy of the project — create a plain text file named .env in the project root yourself with the variables below (only fill in the ones for features you want working; everything else degrades gracefully instead of crashing):

# ---- Search / price comparison ----
SERPAPI_KEY=your_serpapi_key

# ---- YouTube search ----
YOUTUBE_API_KEY=your_youtube_data_api_v3_key

# ---- Trip planner itinerary + notes summarization ----
GROQ_API_KEY=your_groq_key

# ---- News under the clock (optional - falls back to Google News RSS,
#      which needs no key at all, if this is left blank) ----
NEWSAPI_KEY=
NEWS_COUNTRY=in

# ---- Email: configure Resend AND/OR SMTP - see note below ----
RESEND_API_KEY=re_your_key_here
RESEND_FROM_EMAIL=onboarding@resend.dev

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_16_character_app_password
SMTP_FROM_NAME=Chrono Assistant

How email backend selection actually works (server/email_service.py): Resend is tried first (it sends over plain HTTPS/443, so it works even on networks that block SMTP ports). On Resend's free tier without a verified domain, Resend only delivers to the address you personally signed up to Resend with — every other recipient gets a 403 "testing mode" rejection. When that specific rejection happens and SMTP is also configured, the code automatically retries that email via SMTP instead — so if you want every signed-up user to get alerts at their own inbox (not just yours), configure both, or configure SMTP alone.

Setting up Resend (2 minutes, no credit card): sign up free at https://resend.com → Dashboard → API Keys → create one → paste as RESEND_API_KEY.

Setting up Gmail SMTP: Google Account → Security → 2-Step Verification (turn on) → App passwords → generate one → paste that 16-character value into SMTP_PASSWORD. If port 465 times out, try SMTP_PORT=587 (the app automatically switches to STARTTLS for any non-465 port).

If neither Resend nor SMTP is configured, the app still works exactly the same (in-app full-screen alert + sound) — it just skips the email step and prints a warning in the terminal instead of crashing.

How to verify email is actually working (don't wait for a real alarm!)

1. Start the backend: python -m server.api_server.
2. In the frontend, sign in → Settings tab.
3. Click "Send test email" (POST /api/test-email) — emails your signed-in address immediately and shows the exact success/error message on screen.
4. Once the test email arrives, alarms and reminders will email you the same way automatically when they trigger.

Windows Notepad users: if you get "not configured" even after filling in .env correctly, Notepad may have saved the file as UTF-16, which python-dotenv can't read. Fix it in PowerShell:

(Get-Content .env -Raw) | Out-File -FilePath .env -Encoding ascii -NoNewline

Run the backend

python -m server.api_server

This starts on http://127.0.0.1:8000. Leave this terminal running.

---

3. REST API reference (server/api_server.py)

Auth & profile

Method	Path	Purpose
POST	/api/auth/signup	{name, email, password} → creates account, auto signs in, returns {token, user}
POST	/api/auth/login	{email, password} → {token, user}
POST	/api/auth/logout	Invalidates the current token
POST	/api/auth/forgot-password	{name, email, new_password} → identity check via name+email match, then resets password and signs out all sessions
GET	/api/auth/me	Resolves the current token back to a user
POST	/api/test-email	Sends a test email to the signed-in user right now
GET	/api/profile	Current user's profile
PUT	/api/profile	{name?, email?, password?} → update any subset of fields
DELETE	/api/profile?mode=soft|hard	soft (default): flips status to deleted, keeps all data. hard: permanently deletes the user + all their alarms/reminders

Clock, alarms, reminders

Method	Path	Purpose
GET	/api/time	Current server time
GET	/api/meta	Sound options, etc. for the frontend
POST/GET	/api/stopwatch/start, /stop, /delete, GET /status	Stopwatch control (single shared instance)
POST	/api/alarms	Create an alarm (requires sign-in)
GET	/api/alarms	List your own alarms
DELETE	/api/alarms/{id}	Delete your own alarm
POST	/api/alarms/{id}/stop	Stop a ringing alarm
POST	/api/alarms/{id}/snooze	Snooze a ringing alarm
POST	/api/reminders	Create a reminder (requires sign-in)
GET	/api/reminders	List your own reminders
DELETE	/api/reminders/{id}	Delete your own reminder
POST	/api/reminders/{id}/stop	Dismiss a due reminder
POST	/api/reminders/{id}/remind_later	Snooze a reminder
GET	/api/notifications	Polled every second by the frontend for due alarms/reminders

News, search, compare, YouTube, trip planner, notes

Method	Path	Purpose
GET	/api/news	Today's top headlines for the Clock page's News panel
POST	/api/search	Web search (SerpAPI)
POST	/api/ecommerce	Single-product price search
POST	/api/ecommerce/compare	{product1, product2} → both products' results side by side
GET	/api/youtube?query=...&max_results=5	YouTube search
POST	/api/trip-planner	{origin, destination, days, departure_date?} → itinerary
GET	/api/notes	List notes
POST	/api/notes	{title?, content} → add a note
DELETE	/api/notes/{id}	Delete a note
POST	/api/notes/summary	{note_ids?} → AI summary of notes

Access notes: /api/time, /api/stopwatch/*, /api/search, /api/ecommerce*, /api/news, /api/youtube, /api/trip-planner are open (no sign-in required). Alarms, reminders, and profile endpoints require an Authorization: Bearer <token> header, since that's who gets emailed and whose data it is.

MCP tools exposed by server/server.py: youtube_search, trip_planner, notes_add, notes_delete, notes_list, notes_summarize, plus the original clock/alarm/reminder/search/ecommerce tools.

---

4. Frontend setup

cd frontend
npm install
npm run dev

Open http://localhost:5173.

Frontend structure

frontend/src/
  api.js                     -> fetch() wrapper; auto-attaches the auth token
  context/AuthContext.jsx    -> signup/login/logout state, persisted in localStorage
  App.jsx                    -> Sign in/up/Forgot-password when logged out; main app when logged in
  components/
    SignInPage.jsx             -> email + password (+ "Forgot password?" link)
    SignUpPage.jsx              -> name + email + password -> auto signs in
    ForgotPasswordPage.jsx       -> name + email + new password -> resets & signs out old sessions
    Header.jsx                    -> ribbon tabs + "About" button + signed-in name
    ClockPage.jsx                   -> rotating-ring clock card, tap to open the sidebar; renders NewsPanel below it
    NewsPanel.jsx                    -> today's headlines under the clock
    Sidebar.jsx                       -> slide-in panel (opened from the clock) holding Stopwatch + Alarm
    StopwatchPage.jsx                  -> HH:MM:SS:MS input, live countdown (lives in the sidebar)
    AlarmPage.jsx                       -> HH:MM AM/PM, repeat, weekdays, sound, list (lives in the sidebar)
    ReminderPage.jsx                     -> title/description/date/time, notify dropdown, list
    SearchPage.jsx                        -> query box -> tools/search_tool.py
    EcommercePage.jsx                      -> TWO product boxes -> side-by-side price compare
    YouTubePage.jsx                         -> query box -> tools/youtube_tool.py
    TripPlannerPage.jsx                      -> origin/destination/days -> tools/trip_planner_tool.py
    NotesPage.jsx                             -> add/list/delete/summarize -> tools/notes_tool.py
    AboutPage.jsx                              -> project summary (opened via the header's About button)
    ProfilePage.jsx                             -> GET/PUT/DELETE profile modal (opened from Settings)
    SettingsPage.jsx                             -> account info, "Edit profile", sign out, send-test-email
    AlertOverlay.jsx                              -> full-screen alert (Stop/Delete, Snooze, Remind later)

---

5. Quick demo checklist

1. python server/init_db.py then python -m server.api_server
2. cd frontend && npm run dev
3. Open http://localhost:5173 → you land on Sign up → create an account → you're redirected straight into the app.
4. Tap the clock → sidebar slides in with Stopwatch/Alarm tabs.
5. Scroll down on the Clock page → today's news headlines appear below it.
6. Go to Settings → Edit profile → try updating your name, then try both delete modes (soft vs hard) on a throwaway test account.
7. Set an alarm 1–2 minutes in the future. If .env has valid email settings, check that inbox when it rings.
8. Go to Compare, type two product names, click Compare prices — both products' results appear side by side.
9. Try YouTube, Trip planner, and Notes tabs.
10. Click About (top-right of the header) to see the project summary.