# AI-Orchestrator-MCP

> **An AI Database Assistant built with OpenAI Agents SDK and the Model
> Context Protocol (MCP).**

This project demonstrates how to build an AI Agent capable of
autonomously interacting with heterogeneous databases through modular
MCP tools.

Currently supported databases:

-   MySQL
-   MongoDB
-   Google BigQuery

------------------------------------------------------------------------

# Features

-   OpenAI Agents SDK
-   FastMCP Server
-   MCP Client
-   AI Database Assistant
-   Automatic Tool Discovery
-   SQLiteSession conversation memory
-   OpenAI Tracing
-   MySQL integration
-   MongoDB integration
-   Google BigQuery integration
-   Modular architecture
-   Easily extensible

------------------------------------------------------------------------

# Architecture

## High-level overview

```text
                          User
                            │
                            ▼
                 Database Assistant
                  (OpenAI Agents SDK)
                            │
                            ▼
                     SQLiteSession
                            │
                            ▼
                       MCP Client
                            │
                            ▼
                       MCP Server
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼

     MySQL Tools      MongoDB Tools     BigQuery Tools

          │                 │                 │
          ▼                 ▼                 ▼

       MySQL            MongoDB          BigQuery
```
Architecture Diagram

![Architecture](docs/images/architecture.png)
------------------------------------------------------------------------

# Technologies

-   Python 3.13
-   OpenAI Agents SDK
-   FastMCP
-   MCP (Model Context Protocol)
-   PyMySQL
-   PyMongo
-   Google Cloud BigQuery
-   python-dotenv
-   SQLiteSession

------------------------------------------------------------------------

# Project Structure

``` text
AI-Orchestrator-MCP/
│
├── config/
│   ├── config.py
│   └── .env.example
│
├── db/
│   ├── mysql.py
│   ├── mongodb.py
│   └── bigquery.py
│
├── tools/
│   ├── mysql_tools.py
│   ├── mongodb_tools.py
│   └── bigquery_tools.py
│
├── tests/
├── models/
├── logs/
│
├── mcp_client.py
├── mcp_server.py
├── requirements.txt
└── README.md
```

------------------------------------------------------------------------

# Supported Databases

## MySQL

-   Execute SQL queries
-   List databases
-   List tables
-   Search tables
-   Describe tables
-   List columns
-   Show CREATE TABLE
-   Count rows
-   List views
-   Show indexes
-   Show foreign keys
-   Database statistics
-   Explain query

## MongoDB

-   List databases
-   List collections
-   Count documents
-   Find documents
-   Sample documents

## Google BigQuery

-   List datasets
-   List tables
-   Read table schema
-   Execute SQL queries

------------------------------------------------------------------------

# How It Works

The Agent never accesses databases directly.

Workflow:

1.  The user submits a request.
2.  The Agent reasons about the request.
3.  The Agent selects the appropriate MCP tool.
4.  The MCP Client invokes the MCP Server.
5.  The selected tool queries the database.
6.  Results are returned to the Agent.
7.  The Agent generates the final response.

------------------------------------------------------------------------

# Example Conversation

**User**

``` text
How many collections are available in the MongoDB database "dating"?
```

**Assistant**

``` text
The database contains 24 collections including:

- users
- chats
- events
- email_logs
...
```

------------------------------------------------------------------------

**User**

``` text
Describe the MySQL table users.
```

**Assistant**

``` text
The table contains the following columns:

- id
- username
- email
- created_date
...
```

------------------------------------------------------------------------

**User**

``` text
List the available BigQuery datasets.
```

**Assistant**

``` text
Available datasets:

- analytics
- marketing
- reporting
...
```

------------------------------------------------------------------------

# Installation

Clone the repository:

``` bash
git clone https://github.com/yourusername/AI-Orchestrator-MCP.git
```

Create a virtual environment:

``` bash
python -m venv .venv
```

Activate it:

Windows

``` bash
.venv\Scripts\activate
```

Linux / macOS

``` bash
source .venv/bin/activate
```

Install dependencies:

``` bash
pip install -r requirements.txt
```

------------------------------------------------------------------------

# Configuration

Create a `.env` file starting from `.env.example`.

Example:

``` env
DB_HOST=
DB_PORT=3306
DB_NAME=
DB_USER=
DB_PASSWORD=

MONGO_URI_ATLAS=
MONGO_URI_LOCAL=

BIGQUERY_CREDENTIALS=C:\path\credentials.json
```

------------------------------------------------------------------------

# Running the Project

Run the application:

``` bash
python mcp_client.py
```

The client automatically starts the MCP Server and initializes the
Database Assistant.

To exit:

``` text
exit
```

or

``` text
quit
```

------------------------------------------------------------------------

# Adding a New Database

1.  Add credentials to `.env`.
2.  Create a new manager in `db/`.
3.  Implement the database methods.
4.  Create MCP tools in `tools/`.
5.  Register the tools in `mcp_server.py`.
6.  Update the Agent instructions if needed.
7.  Test the manager.
8.  Test the tools.
9.  Test the Agent.

------------------------------------------------------------------------

# Design Principles

-   Modular architecture
-   Separation of concerns
-   Independent tools
-   Reusable components
-   Extensible design
-   Clean code

------------------------------------------------------------------------

# Roadmap

-   PostgreSQL support
-   Redis integration
-   Snowflake integration
-   Vector databases
-   Automatic schema exploration
-   Query planning
-   Multi-Agent workflows
-   RAG integration

------------------------------------------------------------------------

# License

MIT License

------------------------------------------------------------------------

# About

This project was created as a personal AI Engineering project to
explore:

-   OpenAI Agents SDK
-   Model Context Protocol (MCP)
-   AI Database Assistants
-   Tool Calling
-   Multi-database orchestration
-   Agentic AI

The architecture has been designed to be modular, extensible and easily
adaptable to additional databases and external services.