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.

Related MCP server: MCP Google Workspace Server

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

   python -m venv venv
   source venv/bin/activate        # Windows: venv\Scripts\activate

2. Install dependencies

   pip install -r requirements.txt

3. Configure environment variables

   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:

python server.py

Terminal 2 -- verify the tools directly (optional but recommended before your demo):

python test_tools.py

Terminal 2 -- start the agent:

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:

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.