# MCP Assistant Toolkit

A Model Context Protocol (MCP) server that exposes a small toolbox (math,
web search, email, and time tools) to an AI agent, plus a client that
connects a Groq-hosted LLM (via LangChain + LangGraph) to that server so it
can decide, on its own, which tool to call to answer a question.

Built as a course project, extending the MCP server/agent pattern taught in
class into a fuller, better-documented project.

## Architecture

```
 You
  |
  v
+-------------------------------+        MCP over HTTP        +----------------------------+
|  client.py                    |  <---------------------->   |  server.py                 |
|  - LangGraph ReAct agent      |                              |  - FastMCP tool server     |
|  - Groq LLM (reasoning)       |                              |  - add / subtract /        |
|  - dynamically wraps every    |                              |    multiply / divide /     |
|    tool the server exposes    |                              |    square_root             |
+-------------------------------+                              |  - google_search           |
                                                                 |  - send_email              |
                                                                 |  - get_current_time        |
                                                                 +----------------------------+
                                                                      |            |
                                                                      v            v
                                                                 SerpAPI      Gmail SMTP
```

The client never hard-codes what a tool's inputs look like: it asks the
server for its tool list (name, description, JSON Schema) and builds a
matching Pydantic model automatically. Add a new tool to `server.py` and the
client picks it up on the next run with no changes needed on its side.

## Project structure

```
mcp_project/
|-- server.py          # MCP tool server (run this first)
|-- client.py           # Agent client (run this second)
|-- test_tools.py        # Direct smoke test of the server's tools (no LLM needed)
|-- requirements.txt
|-- .env.example        # Copy to .env and fill in your own keys
|-- .gitignore
|-- README.md
`-- IMPLEMENTATION.md   # Write-up: design decisions, architecture, testing
```

## Setup

1. **Create and activate a virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate        # Windows: venv\Scripts\activate
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure environment variables**
   ```bash
   cp .env.example .env
   ```
   Then open `.env` and fill in:
   | Variable | Required for | Where to get it |
   |---|---|---|
   | `GROQ_API_KEY` | the agent's LLM | https://console.groq.com/keys |
   | `SERP_API_KEY` | `google_search` tool | https://serpapi.com/manage-api-key |
   | `GMAIL_USER` / `GMAIL_APP_PASSWORD` | `send_email` tool | https://myaccount.google.com/apppasswords |

   Every tool degrades gracefully with a clear error message if its key is
   missing, so you can run the project with only some keys set.

## Running it

**Terminal 1 -- start the tool server:**
```bash
python server.py
```

**Terminal 2 -- verify the tools directly (optional but recommended before your demo):**
```bash
python test_tools.py
```

**Terminal 2 -- start the agent:**
```bash
python client.py
```
This opens an interactive chat. Try:
- `What is 128 * 37?`
- `What's the current time in Asia/Karachi?`
- `Search for the latest news on the Model Context Protocol`
- `Email a summary of the last answer to you@example.com`

Or ask a one-off question without the interactive loop:
```bash
python client.py "What's 12 * 8, and what time is it in Asia/Karachi?"
```

## Notes for presenting / grading

- `test_tools.py` is the fastest way to show every tool working live, without
  depending on the LLM or the internet for the math/time tools.
- See `IMPLEMENTATION.md` for the design write-up: what changed from the
  class assignment, why, and what was learned.
- Rotate any API keys / app passwords that were used during development
  before sharing this repository publicly (e.g. on GitHub) -- `.env` is
  already excluded via `.gitignore`, but keys typed into a screen recording
  or a shared file should still be regenerated.