TaskFlow AI

Less task juggling. More follow-through.

TaskFlow AI is a hackathon MVP exploring a unified productivity workflow across task management, Gmail context, and Google Calendar. Its mission workspace follows Plan → Act → Verify → Recover: a supported request triggers a tool call, and task creation is followed by a separate task-list check.

Prototype status: This project is an MVP, not a production-ready autonomous agent. Its mission runner supports a small set of rule-based requests rather than free-form LLM planning. Reminder records can be created and listed, but they do not deliver notifications or create Google Calendar events. Before presenting the hosted demo, configure the Render and Apps Script secrets and run the checks in docs/TESTING.md.

What is in this repository?

• Index.html — TaskFlow AI web interface.

• Code.gs — Google Apps Script backend/client. It communicates with the MCP server for task and reminder tools; Gmail and Calendar reads are handled in Apps Script.

• server.py — Python/FastAPI stateless MCP server over Streamable HTTP.

• requirements.txt — Python dependencies.

• render.yaml — Render service configuration.

• docs/ — architecture, user/testing guide, product feedback, submission description, and friction log.

• LICENSE — MIT open-source license.

Related MCP server: Todolist MCP Server

MCP implementation

The server implements MCP protocol version 2025-11-25 and accepts JSON-RPC requests at POST /mcp. The Apps Script client performs initialization, sends notifications/initialized, lists tools, and makes tool calls using the MCP-Protocol-Version header.

The six tools are:

• create_task

• list_tasks

• set_task_done

• delete_task

• create_reminder

• list_reminders

The server uses a bearer token for /mcp. Keep that token in environment/script properties only; never put it in Index.html, commit it to Git, or paste it into public issue trackers.

Requirements

• A GitHub account for source control.

• A Render account (or another host capable of running the Python server) if using the hosted MCP endpoint.

• A Google account with permission to create/deploy Apps Script projects.

• A modern browser.

Deploy the MCP server on Render

1. If you already have a public GitHub repository, upload/replace the project files from this package in that repository. Otherwise, create a repository and upload the extracted files. Keep LICENSE at the repository root so GitHub can detect and display the license.

2. In Render, choose New + → Web Service and connect the repository.

3. Use these settings if Render does not automatically detect render.yaml:

   • Runtime: Python 3

   • Build command: pip install -r requirements.txt

   • Start command: uvicorn server:app --host 0.0.0.0 --port $PORT

4. Create a strong token locally:

   python3 -c "import secrets; print(secrets.token_urlsafe(32))"

5. Set MCP_API_TOKEN in the Render service's environment variables to the generated token. Do not put the value in the repository.

6. Deploy. Test https://YOUR-SERVICE.onrender.com/health; expect JSON containing "ok": true.

7. Use https://YOUR-SERVICE.onrender.com/mcp as the MCP endpoint, not /health or the site root.

The service rejects browser-origin requests to /mcp by default. Apps Script should call it server-to-server with the bearer token. Do not expose the bearer token to browser JavaScript.

Connect Google Apps Script

1. Open Google Apps Script and open the TaskFlow AI project.

2. Replace the Code.gs contents with this repository's Code.gs, and replace the Index.html contents with this repository's Index.html.

3. Open Project Settings → Script Properties and add/update the following properties:

   • MCP_SERVER_URL — the full HTTPS URL ending in /mcp.

   • MCP_API_TOKEN — exactly the same token configured in Render.

4. Save the properties. If this project uses an explicit appsscript.json, preserve needed Gmail and Calendar scopes and include https://www.googleapis.com/auth/script.external_request.

5. Choose Deploy → Manage deployments → Edit → New version → Deploy. Review and approve requested permissions.

6. Restrict the Apps Script web app to yourself or trusted users. It can read Gmail and Calendar using the accessing user's Google authorization; do not publish it with unrestricted access.

7. Open the deployed web-app URL ending in /exec.

Test the main flow

1. Navigate to Mission Control and click Test MCP. The expected result is protocol version 2025-11-25 and all six tool names.

2. Enter Add task: Finish the hackathon submission and click Run mission.

3. Inspect the activity log. The expected sequence includes create_task followed by list_tasks verification, with the new task appearing in the task list.

4. Try showing, completing, and deleting a task.

5. Create a reminder and confirm that the app describes it as a saved record. Do not claim that a notification was delivered: notifications are not implemented in this MVP.

6. Record the actual date, environment, result, and any error in docs/TESTING.md. A listed test case is not evidence that a test has passed.

Troubleshooting

Security and known limitations

• The server stores task/reminder records in a local JSON file. Some free-host filesystems are ephemeral, so data may be lost after restarts or redeploys. Production use needs persistent storage.

• The server uses a shared bearer token. owner_id separates records within the demo, but this is not a hardened multi-tenant production architecture.

• Gmail/Calendar functionality is read-only in this MVP. The app does not send email, create calendar events, or deliver reminders.

• The mission runner is rule-based for a small set of supported requests; it is not a general LLM planner.

• Do not commit real secrets, personal email/calendar data, .env files, or production credentials.

Documentation

• Architecture

• User guide

• Testing checklist

• Product feedback

• Submission description

• Friction log

License

Released under the MIT License. See LICENSE.