# 🤖 AI IT Helpdesk Agent + MCP

A simple junior-level **Agentic AI + MCP project** that demonstrates how an LLM can understand an IT support request, decide which tool to use, communicate with an MCP server, retrieve or modify data, and generate a final response.

---

## 📌 Project Overview

The **AI IT Helpdesk Agent** acts as a virtual IT support assistant.

A user can ask questions such as:

```text
My laptop is not connecting to the company network.
```

The AI Agent understands the request and decides which MCP tool should be used.

For example:

```text
User
 ↓
AI Agent
 ↓
LLM
 ↓
Tool Decision
 ↓
MCP Client
 ↓
MCP Server
 ↓
MCP Tool
 ↓
JSON Data
 ↓
MCP Result
 ↓
LLM
 ↓
Final Response
```

The project intentionally uses simple Python functions and JSON files so that beginners can understand the complete flow.

---

# 🎯 Project Objectives

This project demonstrates:

* LLM integration
* Agentic AI basics
* Tool selection
* MCP server
* MCP client
* MCP tools
* User data management
* Device information
* Device status checking
* Support ticket creation
* Support ticket retrieval
* Support ticket updates
* Streamlit frontend
* End-to-end Agent + MCP communication

---

# 🧠 Technologies Used

| Technology         | Purpose                         |
| ------------------ | ------------------------------- |
| Python             | Main programming language       |
| Groq               | LLM API                         |
| OpenAI GPT-OSS 20B | LLM model                       |
| MCP                | Tool communication              |
| FastMCP            | MCP server                      |
| Streamlit          | Web interface                   |
| JSON               | Simple data storage             |
| python-dotenv      | Environment variable management |

---

# 🚫 Technologies Not Used

This project intentionally does **not** use:

* RAG
* Embeddings
* Vector databases
* LangChain
* LangGraph
* Complex databases
* Complex agent frameworks
* Machine learning models
* Deep learning models

The goal is to understand the basic **LLM + Agent + MCP architecture** first.

---

# 🏗️ Project Architecture

```text
                         USER
                           ↓
                     STREAMLIT UI
                           ↓
                       AI AGENT
                           ↓
                    Understand Request
                           ↓
                    Decide Which Tool
                           ↓
              ┌────────────┼────────────┐
              ↓            ↓            ↓
          USER TOOL    DEVICE TOOL   TICKET TOOL
              ↓            ↓            ↓
          User Data     Device Data   Ticket Data
              └────────────┼────────────┘
                           ↓
                          LLM
                           ↓
                    Final Response
                           ↓
                      STREAMLIT
```

---

# 🔄 Complete Agent Flow

The complete application follows this process:

```text
User
 ↓
Streamlit
 ↓
run_agent()
 ↓
decide_tool()
 ↓
LLM
 ↓
Tool Decision
 ↓
execute_tool_decision()
 ↓
MCP Client
 ↓
MCP Server
 ↓
MCP Tool
 ↓
JSON Data
 ↓
Tool Result
 ↓
generate_final_response()
 ↓
LLM
 ↓
Final Answer
 ↓
Streamlit
```

---

# 📁 Project Structure

```text
ai_it_helpdesk_agent_mcp/
│
├── flow.bat
├── README.md
├── requirements.txt
├── .env
├── .gitignore
│
├── data/
│   ├── users.json
│   ├── devices.json
│   └── tickets.json
│
├── src/
│   │
│   ├── config/
│   │   └── settings.py
│   │
│   ├── data/
│   │   ├── user_data.py
│   │   ├── device_data.py
│   │   └── ticket_data.py
│   │
│   ├── llm/
│   │   └── llm.py
│   │
│   ├── mcp/
│   │   ├── server.py
│   │   ├── user_tools.py
│   │   ├── device_tools.py
│   │   └── ticket_tools.py
│   │
│   └── agent/
│       ├── prompts.py
│       └── agent.py
│
└── app/
    └── streamlit_app.py
```

---

# 📂 Folder Explanation

## `data/`

Contains simple JSON files used as the project's data storage.

### `users.json`

Stores employee information.

Example:

```json
{
    "user_id": "U001",
    "name": "Ravi",
    "department": "IT",
    "email": "ravi@company.com"
}
```

### `devices.json`

Stores employee device information.

Example:

```json
{
    "device_id": "D001",
    "user_id": "U001",
    "device_name": "Ravi-Laptop",
    "device_type": "Laptop",
    "operating_system": "Windows 11",
    "status": "Online",
    "network": "Disconnected"
}
```

### `tickets.json`

Stores support tickets.

Example:

```json
{
    "ticket_id": "T001",
    "user_id": "U001",
    "issue": "Laptop is not connecting to company network.",
    "status": "Open"
}
```

---

# 📂 `src/config/`

Contains project configuration.

### `settings.py`

Loads the Groq API key from the `.env` file.

---

# 📂 `src/data/`

Contains functions that work directly with JSON data.

### `user_data.py`

Provides:

```text
get_users()
get_user()
```

### `device_data.py`

Provides:

```text
get_devices()
get_device()
check_device_status()
```

### `ticket_data.py`

Provides:

```text
get_tickets()
create_ticket()
get_ticket()
update_ticket()
```

---

# 📂 `src/llm/`

Contains the LLM integration.

### `llm.py`

Responsible for:

```text
Python
 ↓
Groq API
 ↓
GPT-OSS 20B
 ↓
Response
```

---

# 📂 `src/mcp/`

Contains the MCP implementation.

## `server.py`

Creates the MCP server and exposes the tools.

Available tools:

```text
get_user
get_device
check_device_status
create_ticket
get_ticket
update_ticket
```

## `user_tools.py`

Contains the MCP user tool wrapper.

## `device_tools.py`

Contains the MCP device tools.

## `ticket_tools.py`

Contains the MCP ticket tools.

---

# 📂 `src/agent/`

Contains the AI Agent.

## `prompts.py`

Contains the instructions given to the LLM for selecting the appropriate tool.

## `agent.py`

Contains the main agent workflow.

Important functions:

```text
get_mcp_server_parameters()
call_mcp_tool_async()
call_mcp_tool()
decide_tool()
execute_tool_decision()
generate_final_response()
run_agent()
```

The most important function is:

```python
run_agent(question)
```

It runs the complete agent workflow.

---

# 📂 `app/`

Contains the Streamlit frontend.

### `streamlit_app.py`

Provides:

* AI Helpdesk Agent
* User Information
* Device Information
* Device Status
* Create Ticket
* Get Ticket
* Update Ticket

---

# 🛠️ MCP Tools

The project contains six MCP tools.

## 1. `get_user`

Returns information about an employee.

Example:

```text
get_user("U001")
```

Returns:

```text
Ravi
IT
ravi@company.com
```

---

## 2. `get_device`

Returns device information.

Example:

```text
get_device("U001")
```

Returns:

```text
Ravi-Laptop
Windows 11
Online
Disconnected
```

---

## 3. `check_device_status`

Checks the device and network status.

Example:

```text
check_device_status("U001")
```

Returns:

```text
Device: Ravi-Laptop
Status: Online
Network: Disconnected
```

---

## 4. `create_ticket`

Creates a new IT support ticket.

Example:

```text
create_ticket(
    "U001",
    "Laptop is not connecting to company network."
)
```

Returns:

```text
Ticket ID: T001
Status: Open
```

---

## 5. `get_ticket`

Retrieves an existing ticket.

Example:

```text
get_ticket("T001")
```

---

## 6. `update_ticket`

Updates a ticket status.

Example:

```text
update_ticket(
    "T001",
    "In Progress"
)
```

---

# 🤖 Agent Decision Examples

## Example 1 — Device Problem

User:

```text
Show me my laptop information.
```

Agent:

```text
TOOL: get_device
USER_ID: U001
```

---

## Example 2 — Network Problem

User:

```text
My laptop is not connecting to the company network.
```

Agent:

```text
TOOL: check_device_status
USER_ID: U001
```

---

## Example 3 — Create Ticket

User:

```text
My laptop is not connecting to the company network.
Please create a support ticket.
```

Agent:

```text
TOOL: create_ticket
USER_ID: U001
ISSUE: laptop is not connecting to company network
```

MCP creates:

```text
T006
Status: Open
```

The LLM then generates the final response.

---

# 🖥️ Streamlit Application

Start the application using:

```cmd
streamlit run app\streamlit_app.py
```

The application provides the following menu:

```text
AI Helpdesk Agent
User Information
Device Information
Device Status
Create Ticket
Get Ticket
Update Ticket
```

---

# ⚙️ Installation

## Step 1 — Clone or create the project

Open CMD inside the project directory.

---

## Step 2 — Create virtual environment

```cmd
python -m venv venv
```

---

## Step 3 — Activate virtual environment

Windows:

```cmd
venv\Scripts\activate
```

---

## Step 4 — Install dependencies

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

---

# 🔑 Environment Variables

Create a `.env` file:

```text
GROQ_API_KEY=your_groq_api_key_here
```

Do not commit the `.env` file to GitHub.

The `.gitignore` file already contains:

```text
.env
venv/
__pycache__/
```

---

# ▶️ Running the Application

From the project root:

```cmd
streamlit run app\streamlit_app.py
```

The application will open in Streamlit.

---

# 🧪 Testing

Testing was performed module by module.

## Test MCP Server

```cmd
python -m src.mcp.test_server
```

Expected:

```text
MCP server loaded successfully.
Server name: AI IT Helpdesk
```

---

## Test User Tool

```cmd
python -c "from src.mcp.user_tools import get_user_tool; print(get_user_tool('U001'))"
```

---

## Test Device Tool

```cmd
python -c "from src.mcp.device_tools import get_device_tool; print(get_device_tool('U001'))"
```

---

## Test Device Status

```cmd
python -c "from src.mcp.device_tools import check_device_status_tool; print(check_device_status_tool('U001'))"
```

---

## Test Ticket Creation

```cmd
python -c "from src.agent.agent import call_mcp_tool; print(call_mcp_tool('create_ticket', {'user_id': 'U001', 'issue': 'Laptop is not connecting to company network.'}))"
```

---

## Test Ticket Retrieval

```cmd
python -c "from src.agent.agent import call_mcp_tool; print(call_mcp_tool('get_ticket', {'ticket_id': 'T001'}))"
```

---

## Test Ticket Update

```cmd
python -c "from src.agent.agent import call_mcp_tool; print(call_mcp_tool('update_ticket', {'ticket_id': 'T001', 'status': 'In Progress'}))"
```

---

## Test Complete Agent

```cmd
python -c "from src.agent.agent import run_agent; print(run_agent('My laptop is not connecting to the company network. Please create a support ticket.'))"
```

Expected result:

```text
Your support ticket has been created successfully.

Ticket ID: T00X
Issue: Laptop is not connecting to the company network
Status: Open
```

---

# 📊 Project Development Progress

```text
Module 1 — Project Setup + Streamlit          ✅ 10%
Module 2 — User / Device / Ticket Data       ✅ 25%
Module 3 — LLM Integration                   ✅ 40%
Module 4 — MCP Server Basics                 ✅ 55%
Module 5 — User & Device MCP Tools           ✅ 70%
Module 6 — Ticket MCP Tools                  ✅ 80%
Module 7 — AI Agent + MCP Integration        ✅ 90%
Module 8 — Final Streamlit Application       ✅ 97%
Module 9 — End-to-End Testing                🔄
```

---

# 🎓 Learning Outcomes

After completing this project, a junior developer should understand:

### LLM

How to connect Python with an LLM API.

### Agent

How an LLM can decide what action should be performed.

### Tools

How Python functions can perform real actions.

### MCP

How tools can be exposed through an MCP server.

### MCP Client

How an application communicates with the MCP server.

### Agent + MCP

How an AI Agent can decide which MCP tool to call.

### Streamlit

How to build a simple frontend for an AI application.

---

# 💼 Interview Explanation

If asked:

**"Explain your project."**

You can explain it like this:

> I developed a simple AI IT Helpdesk Agent using Python, Groq LLM, MCP, and Streamlit. The user enters an IT problem through the Streamlit interface. The LLM understands the request and decides which tool is required. The Python agent communicates with an MCP server, which exposes tools for retrieving user information, checking device status, and managing support tickets. The selected MCP tool accesses JSON-based data and returns the result to the agent. Finally, the LLM uses the tool result to generate a clear response for the user.

---

# 🔑 Key Concepts

```text
LLM
 ↓
Reasoning / Decision
 ↓
Tool
 ↓
MCP Client
 ↓
MCP Server
 ↓
Real Data / Action
 ↓
Result
 ↓
LLM
 ↓
Response
```

The main idea is:

> **The LLM decides what needs to be done, while tools perform the actual work.**

MCP provides a standardized way for the AI application to communicate with those tools.

---

# 🚀 Future Improvements

This version intentionally stays simple.

Future versions could add:

* Real database
* User authentication
* Multiple employees
* Dynamic logged-in users
* More IT diagnostic tools
* Email notifications
* Knowledge-base integration
* RAG
* LangGraph
* Agent memory
* Multiple agents
* MCP remote server
* Cloud deployment
* Monitoring and evaluation

These features are intentionally kept outside the current beginner version.

---

# 👨‍💻 Project Level

**Level:** Junior / Beginner Agentic AI Developer

**Main Focus:**

```text
Python
+
LLM
+
Agent
+
Tools
+
MCP
+
Streamlit
```

---

# ✅ Final Project Status

The core AI IT Helpdesk Agent + MCP application is complete.

The project successfully demonstrates:

```text
User
 ↓
Streamlit
 ↓
AI Agent
 ↓
LLM
 ↓
Tool Decision
 ↓
MCP Client
 ↓
MCP Server
 ↓
MCP Tool
 ↓
JSON Data
 ↓
LLM
 ↓
Final Response
 ↓
User
```

**Project Status: 100% after final end-to-end testing.**