# 🌐 Enterprise Model Context Protocol (MCP) Agent Framework

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![Protocol: Model Context Protocol](https://img.shields.io/badge/Protocol-MCP-orange.svg)](https://modelcontextprotocol.io)
[![Standard: Open Interoperability](https://img.shields.io/badge/Standard-Open_Standards-green.svg)](https://www.undp.org)

> An open-standard, production-grade **Model Context Protocol (MCP)** implementation and **Multi-Server Gateway** designed for enterprise agentic workflows, dynamic tool discovery, and vendor-agnostic AI orchestration.

---

## 📌 Executive Summary

Modern AI systems require seamless, reliable, and standardized communication with external software tools, databases, and enterprise workspaces. Traditional integrations suffer from brittle hardcoded bindings and proprietary vendor lock-in.

This repository implements the **Model Context Protocol (MCP)** — the emerging industry standard for connecting AI models to contextual tools and external APIs:
* **Zero-Hardcoding**: Tools are declared with strict JSON Schema definitions and discovered dynamically at runtime via `/tools/list`.
* **Central MCP Gateway**: Aggregates distributed MCP servers, manages namespacing, handles route dispatching, and exports standardized function definitions for any Large Language Model (Anthropic Claude, OpenAI, Gemini, Groq, Llama).
* **Enterprise Productivity Adapters**: Built-in modules for real-time web intelligence, document parsing (PDF/RAG), calendar scheduling, and email communication.
* **Alignment with Digital Public Goods & Open Standards**: Fully open-source, modular, and privacy-first architecture suitable for public sector organizations (e.g., United Nations, UNDP), multilateral agencies, and global enterprises.

---

## 🏗 Architecture Overview

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                     LLM / AGENTIC ORCHESTRATOR                         │
 │           (OpenAI, Anthropic Claude, Gemini, Groq, Llama)              │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ Dynamic Tool Call (JSON Schema)
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │                         MCP SERVER GATEWAY                             │
 │   - Multi-server Discovery & Schema Aggregation                        │
 │   - Namespacing & Collision Avoidance                                  │
 │   - Fault-tolerant Fallback & In-Memory Routing                        │
 └──────────────┬────────────────────────────┬────────────────────────────┘
                │ HTTP Stream / JSON-RPC     │ HTTP Stream / JSON-RPC
                ▼                            ▼
 ┌──────────────────────────────┐ ┌──────────────────────────────────────┐
 │     CORE WORKSPACE SERVER    │ │        WEB INTELLIGENCE SERVER       │
 │   - Meeting & Calendar Sync  │ │   - Live DuckDuckGo / Tavily Search  │
 │   - Email Dispatch           │ │   - Source Extraction & Verification │
 │   - Drive / Document Parsing │ └──────────────────────────────────────┘
 └──────────────────────────────┘
```

---

## 🛠 Key Capabilities

| Tool / Capability | Protocol Action | Description |
| :--- | :--- | :--- |
| **`web_search`** | `tools/call` | Real-time web intelligence and reference gathering with structured citations. |
| **`parse_document`** | `tools/call` | Extracts structured text and metadata from PDF, Markdown, and TXT files for RAG pipelines. |
| **`schedule_meeting`** | `tools/call` | Creates calendar events with automated virtual meeting room generation. |
| **`send_email`** | `tools/call` | Drafts and dispatches communications with structured recipients and audit logs. |
| **`list_drive_files`** | `tools/call` | Navigates hierarchical enterprise repositories and file trees. |
| **MCP Gateway** | `tools/list` | Dynamic aggregation bus with automated conversion to LLM function calling schemas. |

---

## 🚀 Quickstart in 60 Seconds

### 1. Clone & Set Up Environment

```bash
# Clone the repository
git clone https://gitlab.com/your-username/mcp-agent-showcase.git
cd mcp-agent-showcase

# Create and activate virtual environment
python -m venv .venv
# On Linux/macOS: source .venv/bin/activate
# On Windows: .venv\Scripts\activate

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

### 2. Run the Interactive End-to-End Demo

Execute the self-contained demonstration script:

```bash
python quickstart_demo.py
```

This script automatically:
1. Spawns the MCP Server in the background.
2. Initializes the MCP Gateway and discovers published tools dynamically.
3. Generates the exact JSON Schemas used for LLM Function Calling.
4. Executes a full 4-step automated agentic workflow (Web Search ➔ Document Parsing ➔ Meeting Scheduling ➔ Email Confirmation).

---

## 📦 Project Structure

```text
mcp-agent-showcase/
├── mcp_server.py           # Core MCP Server (FastMCP / JSON-RPC endpoints)
├── mcp_gateway.py          # Central Gateway aggregating multiple MCP servers
├── quickstart_demo.py      # End-to-end multi-step workflow demonstration
├── requirements.txt        # Minimal, clean Python dependencies
├── .env.example            # Configuration template
├── LICENSE                 # Apache 2.0 Open Source License
├── tools/                  # Standardized tool adapters
│   ├── __init__.py
│   ├── web_search.py       # DuckDuckGo search integration
│   ├── document_parser.py  # Text and PDF extractor for RAG
│   └── workspace_tools.py  # Email, Calendar, Drive & Sheets adapters
└── tests/                  # Automated verification suite
    ├── __init__.py
    └── test_mcp_gateway.py # Gateway and tool schema validation tests
```

---

## 🧪 Testing & Verification

Run automated test suites using `pytest`:

```bash
pytest tests/ -v
```

All tool schemas, parameter validation, and gateway registry mappings are verified to ensure deterministic execution.

---

## 🌍 Strategic Relevance for Multilateral Agencies (e.g., UNDP)

* **Open Standards & Digital Public Goods**: Fully compliant with open protocol definitions, preventing dependence on proprietary walled gardens.
* **Administrative Automation**: Streamlines reporting, multi-stakeholder meeting scheduling, and document synthesis.
* **Security & Transparency**: Deterministic JSON Schemas provide auditable boundaries for AI tool execution, enabling human-in-the-loop oversight.

---

## 📄 License

This project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.