# 🤖 Autonomous AI Research Agent (MCP)

This project implements an autonomous AI Research Agent using the **Model Context Protocol (MCP)**. The agent is built with Python, leverages Google's **Gemini LLM**, and uses **FastMCP** to dynamically expose robust tools for web searching, local file management, and UI rendering via **Prefab UI**.

---

## ✨ Features

- **Autonomous Tool Execution**: The Gemini LLM automatically discovers and iteratively calls tools until its objective is met.
- **MCP Server Architecture**: Provides isolated context and tools out-of-the-box over the `stdio` transport.
- **Web Research**: Integrates `duckduckgo-search` for real-time web scraping and topic summarization.
- **File Management**: A fully functional local CRUD system that creates markdown reports.
- **Dynamic UI Generation**: Automatically spins up a **Prefab UI** dashboard in the background to visualize the research results, featuring a professional tabbed layout and dynamic metrics based on extracted data.
- **Rate Limit Resilience**: The client features an intelligent backoff system that intercepts `429` quota limits and seamlessly resumes operations without crashing.

---

## 🏗️ Architecture

The project consists of two core layers seamlessly interacting over the Model Context Protocol:

```mermaid
graph TD

    Client["client.py<br/>Agent / LLM"]
    Server["server.py<br/>FastMCP Server"]

    T1["research_topic()"]
    T2["manage_report()"]
    T3["render_dashboard()"]

    Web["Internet (DuckDuckGo / API)"]
    File["reports/ Directory"]
    UI["Prefab Dashboard"]

    Client <-->|stdio / JSON-RPC| Server

    Server --> T1
    Server --> T2
    Server --> T3

    T1 --> Web
    T2 --> File
    T3 --> UI
```

1. **`client.py`**: Initializes the Gemini LLM client, connects to the `server.py` using `stdio_client`, and translates MCP tool schemas into Gemini Function Declarations.
2. **`server.py`**: The FastMCP Server instance. Provides the LLM with the context and the capabilities it needs to interact with the environment.
3. **`dashboard.py`**: Auto-generated by the server during execution. Contains the Prefab Python UI component tree (tabbed layout with dynamic metrics).

---

## 🚀 Getting Started

### 1. Prerequisites
- Python 3.10+
- `uv` (The blazing fast Python package manager)
- A free Gemini API Key from Google AI Studio.

### 2. Installation
Install dependencies using `uv`:
```bash
uv init
uv add mcp duckduckgo-search prefab-ui google-genai python-dotenv
```

### 3. Environment Variables
Copy the `.env.example` file to `.env` and paste your API key:
```bash
GEMINI_API_KEY=your_actual_api_key_here
```
> **Security Note:** The `.env` file is excluded in `.gitignore` to prevent leaking your API keys.

### 4. Running the Agent
Simply run the client script. The server will start automatically in the background.
```bash
.venv\Scripts\python.exe client.py
```

Watch the console as the agent thinks, searches the web, writes reports, and ultimately starts the dashboard!

### 5. Viewing the Dashboard
Once the agent completes its run, it will host your research report at:
👉 **[http://127.0.0.1:5175](http://127.0.0.1:5175)**

To manually run the dashboard at any time (e.g. for a demo), run:
```bash
$env:PYTHONUTF8="1"; .venv\Scripts\prefab.exe serve dashboard.py
```
> **Windows Note:** The `PYTHONUTF8=1` environment variable is required to prevent a Unicode encoding error on Windows terminals when the Prefab CLI starts.

---

## 🔒 Security Practices

- **API Keys**: Handled securely via `python-dotenv`.
- **Git Ignore**: `.env`, `reports/`, and dynamic `.py` generations are strictly ignored.
- **Server Communication**: `server.py` communicates exclusively via `stdio`, meaning it does not expose any network ports to the public by default.