MCP Task Assistant (Learning Project)

This is Krishna's first end-to-end AI project. It combines:

1. A Task Manager — simple to-do list (add, list, complete tasks)

2. An MCP Server — exposes the task manager as "tools" that an AI can use

3. A FastAPI backend — turns everything into a real web service

4. (Next step) A RAG layer — lets the assistant also answer questions from documents

5. (Later step) Docker + AWS deployment — makes it a real, hosted app

Why this project matters

Most beginner AI projects are just a script in a notebook. This one is built the way real companies build things: as a service other programs (or an AI) can actually use.

Related MCP server: Sentinel Core Agent

Folder structure

mcp-task-assistant/
├── app/
│   ├── tasks_store.py    # the "database" (in-memory for now)
│   ├── mcp_server.py     # exposes tasks as MCP tools
│   └── main.py           # FastAPI web app
├── requirements.txt
└── README.md

How to run this on your own laptop

Step 1 — Install Python

Make sure you have Python 3.10 or newer. Check with:

python --version

Step 2 — Create a virtual environment

This keeps this project's packages separate from everything else on your computer.

python -m venv venv

Activate it:

• Windows: venv\Scripts\activate

• Mac/Linux: source venv/bin/activate

Step 3 — Install the required packages

pip install -r requirements.txt

Step 4 — Run the MCP server (this is the "tools" part)

python app/mcp_server.py

This starts a server that exposes 3 tools: add_task, list_tasks, complete_task.

Step 5 — Run the FastAPI app (this is the "web service" part)

In a second terminal (with venv activated again):

uvicorn app.main:app --reload

Then open http://127.0.0.1:8000/docs in your browser — you'll see a live, clickable page where you can test adding and listing tasks.

Step 6 — Talk to the AI agent (Groq API — free tier)

Now that create_task / get_tasks / finish_task exist as MCP tools, we can let an actual AI decide when to use them, instead of you calling them by hand. We're using the Groq API — cloud-hosted, fast, and has a generous free tier. If you already have a Groq API key from an earlier project, you can reuse it — a key belongs to your account, not to one specific app.

1. Get / find your Groq API key

Go to https://console.groq.com/keys — reuse your existing key or create a new one.

2. Set up your key

Copy .env.example to a new file named .env, and paste your real key in:

GROQ_API_KEY=your-real-key-here

3. Install the packages

pip install -r requirements.txt

4. Run the agent

python app/agent.py

You do NOT need to separately start mcp_server.py this time — the agent starts it automatically in the background.

5. Try it out

Type things like:

add a task to finish my resume
add a task to practice interview questions
show me all my tasks
mark task 1 as done

Watch the terminal — you'll see a line like [Agent is calling tool: create_task ...] right before it responds. That line is proof the AI is actually deciding to use your tool, not just chatting.

Step 7 — Add document search (RAG)

Now your assistant can also answer questions using your own documents, not just manage tasks.

1. Install the new package

pip install -r requirements.txt

(This installs chromadb, our free local search database. It also downloads a small model the first time you use it, to understand text meaning — after that first download, it works offline.)

2. Add your documents

Put any .txt files into the documents/ folder. A sample file (company_leave_policy.txt) is already there so you can test right away.

3. Build the search index

Run this every time you add or change a document:

python app/build_index.py

4. Ask questions

Run the agent as usual:

python app/agent.py

Try asking:

how many paid leave days do employees get?
what happens to unused leave at the end of the year?

You should see [Agent is calling tool: search_documents ...] before it answers — that means it actually looked in your document instead of guessing.

Step 8 — Package with Docker

Docker packages your whole app — code, packages, everything — into one "box" (called an image) that runs the exact same way on any computer or server. This is how real companies ship software, instead of saying "it works on my machine."

1. Install Docker

Download Docker Desktop from https://www.docker.com/products/docker-desktop and install it. Make sure it's running before the next steps.

2. Build the image

From the main project folder:

docker build -t task-assistant .

This reads the Dockerfile, installs everything, and builds your indexed documents right into the image.

3. Run the container

Your Groq key still needs to be provided — we never bake secrets into the image itself. Run:

docker run -p 8000:8000 --env-file .env task-assistant

4. Test it

Open http://127.0.0.1:8000/docs — same as before, but now it's running inside a container. Try the new /chat endpoint with a message like:

{"message": "add a task to finish my resume"}

What we'll add next

• Deploy on AWS or Render

• Add basic evaluation/logging

Step 9 — Frontend

There's now a real webpage, not just the /docs testing page. It lives in app/static/ (index.html, style.css, app.js) and is served automatically by FastAPI at the site's root URL.

Try it

pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://127.0.0.1:8000 (not /docs this time) — you'll see a proper chat interface with a task sidebar. Type a message like "add a task to finish my resume" and watch the assistant respond, show which tools it used (a small transparency feature — most portfolio projects skip this), and update the task list automatically.

Note: /docs still works too, for testing individual endpoints directly.