🤖 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.

Related MCP server: MAGI Orchestrator

🏗️ Architecture

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

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:

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:

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.

.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

To manually run the dashboard at any time (e.g. for a demo), run:

$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.