# MCP Employee & Project Assistant

![Project architecture](diagram.png)

A small but practical project that shows how a Model Context Protocol (MCP) server can expose real business tools to an AI agent, so a user can ask questions in natural language and have the AI fetch live data from a database.

This project demonstrates a clean pattern:

- an MCP server exposes tools for employee and project data
- a Gemini agent decides when to use those tools
- the agent turns tool results into a readable answer

The goal is simple: instead of writing custom code for every question, the AI can use structured tools to answer real business questions.

---

## Why this project matters

A normal application would need specific integration for each question a user asks.

With MCP:

- the database logic is wrapped in small tools
- the AI sees those tools as capabilities
- the AI can decide which tool to use based on the user request
- the result is a conversational interface on top of real business systems

This is a great example of AI + tools + structured data working together.

---

## What is MCP?

MCP stands for Model Context Protocol.

In plain English, MCP is a standard way for an AI application to talk to tools and services.

Think of it like this:

- The AI is the decision-maker
- The tools are the hands and eyes
- MCP is the common language they use to work together

Without MCP, an AI model usually only knows what it was trained on. With MCP, it can access real systems such as:

- databases
- APIs
- internal tools
- business functions

In this project, the MCP server exposes functions like:

- get_employee_details
- get_project_details
- get_projects_of_employee
- get_employees_for_project

These are not just random functions. They are business tools that the AI can call when needed.

---

## Project architecture

The app is split into a few simple pieces:

- MCP server: exposes the tools
- Services: talk to the database
- Client: connects to the MCP server
- Gemini Agent: decides which tool to call and interprets the response
- PostgreSQL: stores employee and project data

High-level flow:

1. A user asks a question in natural language
2. The Gemini agent checks the available MCP tools
3. The agent chooses the best tool to answer the question
4. The MCP server runs the tool against the database
5. The result is returned to the agent
6. The agent turns the result into a friendly answer

---

## Folder structure

- server.py – MCP server that exposes business tools
- client.py – lightweight MCP client connection layer
- agent.py – Gemini-powered agent that calls MCP tools
- services/
  - employee.py – employee database logic
  - project.py – project and assignment logic
- architecture.md – architecture notes and learning path
- requirements.txt – Python dependencies

---

## How the app works in simple terms

### 1. The server exposes tools
The MCP server says: “Here are the actions I can perform.”

Examples:

- get_employee_details(employee_id)
- get_project_details(project_id)
- get_projects_of_employee(employee_id)

These tools are what the AI can call.

### 2. The AI chooses tools
When a user asks, for example:

> Tell me about projects Rahul is working at

The AI may decide:

- first look up Rahul
- then fetch Rahul’s projects
- then answer the user clearly

### 3. The database provides real answers
The tool queries PostgreSQL and returns structured data such as:

- employee name
- department
- project name
- role
- assigned date

### 4. The agent answers naturally
The agent does not dump raw JSON at the user. It converts the tool result into a proper answer such as:

> Rahul is working on the Server Migration project as Lead Engineer.

---

## Why this is a good learning project

This project teaches several important ideas in a very practical way:

### MCP basics

- tools are exposed through a protocol
- AI systems can call tools dynamically
- tool output becomes part of the model’s context
- this makes AI grounded in real systems instead of guesswork

### Python + async patterns

- async functions are used for tool execution and client communication
- the project shows how asynchronous I/O works in a simple real-world case

### Database access

- SQL queries are wrapped behind service functions
- the model sees a clean interface instead of direct database logic

### AI agent behavior

- the agent uses tools when needed
- it responds based on actual data
- it can combine multiple tool calls during one conversation

---

## Setup instructions

### 1. Install Python dependencies

```bash
pip install -r requirements.txt
```

Or with uv:

```bash
uv pip install -r requirements.txt
```

### 2. Set environment variables
Create a `.env` file in the project root with variables like:

```env
GEMINI_API_KEY=your_api_key_here
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=mcp_demo
```

### 3. Start PostgreSQL
This project expects a PostgreSQL database running with employee and project tables.

### 4. Run the MCP server

```bash
uv run server.py
```

### 5. Run the agent

```bash
uv run agent.py
```

---

## What makes this project beginner-friendly

Even if you are not a technical expert, the basic idea is very understandable:

- a database stores company information
- a server exposes that information as tools
- an AI uses those tools to answer questions
- the final experience feels like a smart assistant, but it is grounded in real data

That is the heart of MCP.

---

## Summary

This project is a simple but powerful example of:

- MCP server design
- tool-based AI interactions
- live data access
- business-friendly natural language queries

It is a good foundation for understanding both MCP and practical AI workflows.