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).

Related MCP server: mcp-web-calc

1. Features at a glance

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

Clock, alarms, reminders

News, search, compare, YouTube, trip planner, 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.