✨ Gemini + MCP Playground

An AI agent that uses Google Gemini and the Model Context Protocol (MCP) to securely interact with data and tools.

Built with Streamlit, Gemini, Agno, and a custom MCP server — no Docker needed!

---

🏆 Why This Project?

This showcases AI Engineering skills:

Skill	How It's Shown
AI Agent Architecture	Google Gemini + Agno agent that decides which tools to call
MCP Protocol	Custom MCP server with read-only SQL tools + security guardrails
Security Engineering	Guards blocking dangerous queries (DELETE, DROP, etc.)
Full-Stack AI	Streamlit UI + AI backend + local database
Practical Features	One-click CSV/JSON/Markdown export

---

✨ Features

• Natural Language Queries — Ask questions in plain English about a sample e-commerce database
• Custom MCP Server — A local server that translates AI requests into safe database queries
• 🔒 Security Guardrails — Only SELECT queries allowed; all modifications blocked
• Multiple Export Formats — Download results as CSV, JSON, or Markdown with one click
• AI-Assisted Export — Just say "export this as CSV" and the AI handles it
• Tool Transparency — See exactly which tools the AI calls and what SQL it writes

---

🧠 How It Works

You: "Show me all products over $50"
                │
                ▼
┌───────────────────────────────────────┐
│   Streamlit Web App (github_agent.py)  │
│                                       │
│  ┌─────────────────────────────────┐  │
│  │  Gemini (Google AI)             │  │
│  │  • Understands your question    │  │
│  │  • Decides which tool to call   │  │
│  │  • Formats the answer           │  │
│  └──────────┬──────────────────────┘  │
│             │ MCP Protocol             │
│             ▼                          │
│  ┌─────────────────────────────────┐  │
│  │  MCP Server (db_mcp_server.py)   │  │
│  │  • Validates query (read-only?) │  │
│  │  • Runs SELECT on SQLite DB     │  │
│  │  • Returns formatted results    │  │
│  └──────────┬──────────────────────┘  │
│             │                          │
│             ▼                          │
│     ┌──────────────┐                  │
│     │  store.db    │  (SQLite file)    │
│     └──────────────┘                  │
└───────────────────────────────────────┘

---

🚀 Quick Start

Requirements

• Python 3.8+
• Gemini API Key — Get one free at aistudio.google.com/apikey

No Docker. No GitHub token. No OpenAI key.

Installation

# 1. Install dependencies
pip install -r requirements.txt

# 2. Generate the sample database
python seed_db.py

# 3. Start the app
streamlit run github_agent.py

Usage

1. Enter your Gemini API key in the sidebar (get one free at aistudio.google.com/apikey)
2. Type a question about the store data — e.g., "Show me all products under $50"
3. Click "Run Query" and watch the AI work!
4. Export results using the download buttons below the response

---

💬 Example Queries

Try asking the AI:

🔍 "Show me all products sorted by price"
🔍 "Which customers have placed the most orders?"
🔍 "What's the total revenue from last month?"
🔍 "Show me orders that haven't shipped yet"
🔍 "Export all products as CSV"
🔍 "How many customers do we have from each city?"

---

📁 Project Structure

File	Purpose
github_agent.py	Main Streamlit app — UI + AI agent connection
db_mcp_server.py	Custom MCP server — read-only SQL tools + export
seed_db.py	Script to generate the sample database
store.db	SQLite database with sample e-commerce data
requirements.txt	Python dependencies
exports/	Folder where exported files are saved (created on first export)

---

🗄️ Database Schema

The sample database (store.db) contains 5 tables with 30 orders, 25 products, and 10 customers:

Table	Description
categories	Product categories (Electronics, Clothing, Books, etc.)
products	Items for sale with prices and stock
customers	Customer information
orders	Orders placed with status (delivered, shipped, etc.)
order_items	Individual products within each order

---

🔒 Security Guardrails

The MCP server has layers of protection:

1. Keyword blocking — Queries starting with DELETE, DROP, INSERT, UPDATE, etc. are rejected
2. Multi-statement detection — Multiple SQL statements separated by ; are individually checked
3. Result limiting — Maximum 100 rows returned per query
4. Read-only export — Export tool also validates queries before writing files

---

🛠️ Tech Stack

Technology	Role
Streamlit	Web UI framework
Google Gemini	AI model (via google-generativeai)
Agno	AI agent framework
MCP	Model Context Protocol (tool communication standard)
SQLite	Local database (built into Python)

---

📝 License

This project is for educational purposes. Built as a demonstration of AI Agent + MCP architecture.