# 🚀 MCP Agentic AI Server Project

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Flask](https://img.shields.io/badge/Flask-2.0+-green.svg)](https://flask.palletsprojects.com/)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.24+-red.svg)](https://streamlit.io/)
[![Gemini](https://img.shields.io/badge/Google-Gemini_API-yellow.svg)](https://ai.google.dev/)
[![License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)

> **A comprehensive Model Context Protocol (MCP) implementation featuring dual AI server architecture, real-time monitoring, and an interactive dashboard.**

## 🌟 Project Overview

This project demonstrates a production-ready **MCP (Model Context Protocol) Agentic AI Server** system with:

- 🔧 **Custom MCP Server** - Task-based AI processing with tool integration
- 🌐 **Public MCP Server** - Direct AI query processing
- 🎨 **Interactive Dashboard** - Real-time monitoring and user interface
- 📊 **Live Statistics** - Performance metrics and analytics
- 🛠️ **Extensible Tools** - Modular tool framework for custom functionality

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    🎨 Streamlit Dashboard                       │
│                        (Port 8501)                              │
└─────────────────────┬───────────────────────────────────────────┘
                      │
        ┌─────────────┴───────────────┐
        ▼                             ▼
┌───────────────────┐         ┌──────────────────┐
│  🔧 Custom MCP    │         │  🌐 Public MCP  │
│   (Port 8000)     │         │   (Port 8001)    │
│                   │         │                  │
│ • Task Creation   │         │ • Direct Queries │
│ • Tool Integration│         │ • Simple AI Chat │
│ • Async Processing│         │ • Real-time Stats│
└───────────────────┘         └──────────────────┘
        │                           │
        └─────────────┬─────────────┘
                      ▼
              ┌─────────────────┐
              │  🧠 Google      │
              │  Gemini API     │
              └─────────────────┘
```

## 🚀 Quick Start

### Prerequisites

- **Python 3.12+** (Conda environment recommended)
- **Google Gemini API Key** ([Get one here](https://ai.google.dev/))
- **Git** for cloning the repository

### 1. Clone & Setup

```bash
# Clone the repository
git clone <repository-url>
cd mcp_server_project

# Create and activate virtual environment (recommended)
conda create -n mcp_env python=3.12
conda activate mcp_env

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

### 2. Environment Configuration

Create a `.env` file in the project root:

```env
GEMINI_API_KEY=your_gemini_api_key_here
```

### 3. Run the Application

Open **4 terminals** and run the following commands:

#### Terminal 1: Custom MCP Server 🔧

```bash
cd mcp-agentic-ai
python -m custom_mcp.server
```

_Server will start on http://localhost:8000_

#### Terminal 2: Public MCP Server 🌐

```bash
cd mcp-agentic-ai
python -m public_mcp.server_public
```

_Server will start on http://localhost:8001_

#### Terminal 3: Streamlit Dashboard 🎨

```bash
cd mcp-agentic-ai/streamlit_demo
streamlit run app.py
```

_Dashboard will open at http://localhost:8501_

#### Terminal 4: Test the APIs 🧪

```bash
# Test Custom MCP Server
curl -X POST http://localhost:8000/task \
  -H "Content-Type: application/json" \
  -d '{"input":"Hello World","tools":["sample_tool"]}'

# Test Public MCP Server
curl -X POST http://localhost:8001/ask \
  -H "Content-Type: application/json" \
  -d '{"query":"What is artificial intelligence?"}'
```

## 🎯 Features

### 🔧 Custom MCP Server Features

- **Asynchronous Task Processing** - Create tasks with unique IDs
- **Tool Integration Framework** - Extensible tool system
- **Performance Monitoring** - Real-time statistics tracking
- **Error Handling** - Robust error management and logging

### 🌐 Public MCP Server Features

- **Direct AI Queries** - Instant responses from Gemini
- **Simple API** - Easy-to-use REST endpoints
- **Statistics Tracking** - Performance metrics and analytics
- **High Availability** - Designed for concurrent requests

### 🎨 Dashboard Features

- **Modern UI Design** - Glassmorphism effects and animations
- **Real-time Updates** - Live statistics and performance metrics
- **Responsive Design** - Mobile-friendly interface
- **Interactive Forms** - Easy server selection and input handling

## 📊 API Documentation

### Custom MCP Server (Port 8000)

#### Create Task

```http
POST /task
Content-Type: application/json

{
  "input": "Your task description",
  "tools": ["sample_tool"]
}

Response: {"task_id": "uuid-string"}
```

#### Execute Task

```http
POST /task/{task_id}/run

Response: {
  "task_id": "uuid-string",
  "output": "AI generated response"
}
```

#### Get Statistics

```http
GET /stats

Response: {
  "queries_processed": 42,
  "response_time": 1.23,
  "success_rate": 95.5,
  "uptime": 120.5
}
```

### Public MCP Server (Port 8001)

#### Ask Question

```http
POST /ask
Content-Type: application/json

{
  "query": "Your question here"
}

Response: {"response": "AI generated answer"}
```

#### Get Statistics

```http
GET /stats

Response: {
  "queries_processed": 15,
  "response_time": 0.89,
  "success_rate": 100.0,
  "todays_queries": 15
}
```

## 🛠️ Project Structure

```
mcp_server_project/
├── 📄 README.md                    # This file
├── 📄 requirements.txt             # Python dependencies
├── 📄 .env                        # Environment variables
│
├── 📁 mcp-agentic-ai/             # Main application
│   ├── 📁 custom_mcp/             # Custom MCP server
│   │   ├── 📄 server.py           # Flask server (Port 8000)
│   │   ├── 📄 mcp_controller.py   # Business logic
│   │   └── 📁 tools/              # Custom tools
│   │       └── 📄 sample_tool.py  # Example tool
│   │
│   ├── 📁 public_mcp/             # Public MCP server
│   │   ├── 📄 server_public.py    # Flask server (Port 8001)
│   │   └── 📄 agent_config.yaml   # AI configuration
│   │
│   └── 📁 streamlit_demo/         # Interactive dashboard
│       └── 📄 app.py              # Streamlit app (Port 8501)
│
└── 📁 documentation/              # Comprehensive docs
    ├── 📄 documentation.md        # Main documentation
    ├── 📄 workflows.md            # Mermaid workflows
    ├── 📄 designs.md              # Architecture diagrams
    └── 📄 tech-stack.md           # Technology details
```

## 🔧 Development

### Adding Custom Tools

1. Create a new tool file in `mcp-agentic-ai/custom_mcp/tools/`:

```python
# my_custom_tool.py
import logging

def my_custom_tool(text: str) -> str:
    """
    Your custom tool implementation
    """
    logging.info(f"Processing: {text}")
    # Your logic here
    result = text.upper()  # Example transformation
    return result
```

2. Import and use in `mcp_controller.py`:

```python
from custom_mcp.tools.my_custom_tool import my_custom_tool

# Add to the run method
if "my_custom_tool" in task["tools"]:
    text = my_custom_tool(text)
```

### Extending the Dashboard

The Streamlit dashboard can be customized by modifying `streamlit_demo/app.py`:

- Add new UI components
- Implement additional statistics
- Create new visualizations
- Add export functionality

## 📚 Documentation

Comprehensive documentation is available in the `documentation/` folder:

- **📄 [Main Documentation](documentation/documentation.md)** - Complete project guide (1500+ lines)
- **📄 [Workflows](documentation/workflows.md)** - Mermaid workflow diagrams
- **📄 [Architecture](documentation/designs.md)** - System design diagrams
- **📄 [Tech Stack](documentation/tech-stack.md)** - Technology details

## 🎓 Learning Outcomes

By completing this project, you'll learn:

- **🤖 AI Integration** - Google Gemini API, prompt engineering
- **🔧 Backend Development** - Flask, REST APIs, microservices
- **🎨 Frontend Development** - Streamlit, modern CSS, responsive design
- **📊 System Monitoring** - Real-time statistics, performance tracking
- **🏗️ Architecture Design** - Microservices, event-driven patterns
- **🔐 Security Practices** - API security, environment management

## 🚀 Deployment

### Local Development

Follow the [Quick Start](#quick-start) guide above.

### Production Deployment

For production deployment, consider:

- **🐳 Docker** - Containerize each service
- **☸️ Kubernetes** - Orchestrate containers
- **🔒 HTTPS** - SSL/TLS certificates
- **📊 Monitoring** - Prometheus, Grafana
- **🗄️ Database** - PostgreSQL, Redis

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **📚 Documentation** - Check the comprehensive docs in `/documentation/`
- **🐛 Issues** - Report bugs via GitHub Issues
- **💬 Discussions** - Join GitHub Discussions for questions
- **📧 Contact** - Reach out for additional support

## 🌟 Acknowledgments

- **Google Gemini** - For providing excellent AI capabilities
- **Streamlit** - For the amazing dashboard framework
- **Flask** - For the robust web framework
- **Python Community** - For the incredible ecosystem

---

## 🎯 Next Steps

1. **🚀 Run the Application** - Follow the Quick Start guide
2. **📚 Read Documentation** - Explore the comprehensive docs
3. **🔧 Customize Tools** - Add your own custom tools
4. **🎨 Enhance UI** - Improve the dashboard design
5. **📊 Add Features** - Implement new functionality
6. **🚀 Deploy** - Take it to production

**Ready to build the future of AI? Let's get started! 🚀**

---

_Built with ❤️ for the AI community. Star ⭐ this repo if you find it helpful!_