# 🚀 OpsMCP — AI-Powered Company Operations Agent

> An AI-powered company operations agent that uses the **Model Context Protocol (MCP)** to securely connect natural-language AI interactions with a PostgreSQL database.

## 📌 Overview

OpsMCP allows users to interact with company data using natural language instead of manually writing SQL queries or navigating complex admin panels.

The system connects an AI agent to a PostgreSQL database through MCP tools, allowing the agent to retrieve information, analyze users, and perform authorized database operations.

For sensitive write operations, the system requires explicit user confirmation before modifying the database.

---

## 🎯 Problem

Traditional internal company systems often require users to:

* Navigate multiple administrative dashboards
* Understand database structures
* Write SQL queries
* Perform repetitive operations manually
* Track database modifications separately

This creates unnecessary complexity for routine company operations.

---

## 💡 Solution

OpsMCP provides a natural-language interface for company operations.

Instead of writing:

```sql
SELECT id, name, email, role
FROM users
ORDER BY id;
```

A user can simply ask:

> "Show me all users."

The AI determines which MCP tool is required, executes it, receives the result, and converts it into a human-friendly response.

---

## 🧠 How It Works

```text
                   ┌──────────────────────┐
                   │      Web Dashboard   │
                   └──────────┬───────────┘
                              │
                              ▼
                   ┌──────────────────────┐
                   │      AI Agent        │
                   │  Natural Language    │
                   └──────────┬───────────┘
                              │
                       MCP Tool Calling
                              │
                              ▼
                   ┌──────────────────────┐
                   │     MCP Server       │
                   │                      │
                   │ Tools • Resources    │
                   │ Prompts • Security   │
                   └──────────┬───────────┘
                              │
                              ▼
                   ┌──────────────────────┐
                   │     PostgreSQL       │
                   │      Database        │
                   └──────────────────────┘
```

---

## ✨ Key Features

### 🤖 Natural-Language Database Operations

Users can interact with company data using normal language.

Examples:

```text
Show me all users.
```

```text
Find user with ID 2.
```

```text
Create a new user named Rahul with role developer.
```

```text
Change Rahul's role to manager.
```

```text
Analyze all users and tell me which role has the most users.
```

---

### 🔧 MCP Tools

The project exposes database operations as MCP tools.

Current tools include:

| Tool               | Purpose                   |
| ------------------ | ------------------------- |
| `get_users`        | Retrieve all users        |
| `get_user_by_id`   | Retrieve a specific user  |
| `create_user`      | Create a new user         |
| `update_user_role` | Update a user's role      |
| `analyze_users`    | Analyze user distribution |

---

### 📚 MCP Resources

The project also demonstrates MCP resources for providing structured contextual information to the AI agent.

Example:

```text
company://info
```

This resource contains information about:

* Departments
* Company roles
* Organization structure

---

### 🧩 MCP Prompts

Reusable MCP prompts are included for structured operations such as user analysis.

Example analysis workflow:

```text
1. Count total users
2. Group users by role
3. Identify unusual roles
4. Generate a summary
```

---

## 🔐 Security

Security is an important part of the project.

### API-Key Authentication

The MCP server supports API-key authentication using HTTP authorization headers.

Two permission levels are implemented:

```text
READ_ONLY
READ_WRITE
```

### Authorization

Read operations can be performed using the read-only permission.

Database-changing operations require:

```text
READ_WRITE
```

permission.

---

## ⚠️ Confirmation Before Write Operations

Before executing database-changing operations, the AI client asks the user for confirmation.

Example:

```text
⚠️ WRITE OPERATION REQUIRES CONFIRMATION

Tool      : update_user_role
Arguments : {
    "user_id": 2,
    "new_role": "manager"
}

Do you want to continue? (yes/no)
```

The database is modified only after explicit approval.

---

## 🛡️ Input Validation

User input is validated before database operations.

For example, supported roles are:

```text
developer
designer
product manager
manager
```

Invalid input such as:

```text
aestronuot
```

is rejected instead of being inserted into the database.

---

## 📋 Audit Logging

Database-changing operations are recorded in an audit log.

Example:

```text
action          | tool_name        | status
----------------+------------------+---------
update_user_role| update_user_role  | SUCCESS
```

This provides traceability for sensitive operations.

---

## 🗂️ Project Structure

```text
OPSMCP-AI-AGENNT/
│
├── server/
│   ├── auth/
│   ├── database/
│   │   └── connection.py
│   │
│   ├── prompts/
│   │   └── user_analysis.py
│   │
│   ├── resources/
│   │   └── company.py
│   │
│   └── tools/
│       ├── audit.py
│       └── user_tools.py
│
├── static/
│   ├── app.js
│   └── style.css
│
├── templates/
│   └── index.html
│
├── ai_client.py
├── web_app.py
├── run_server.py
├── requirements.txt
├── .gitignore
└── README.md
```

---

## 🛠️ Tech Stack

### Backend

* Python
* FastAPI
* Uvicorn

### AI

* OpenAI-compatible API
* Function/tool calling
* Natural-language interaction

### Protocol

* Model Context Protocol (MCP)
* Streamable HTTP transport

### Database

* PostgreSQL
* Psycopg

### Frontend

* HTML
* CSS
* JavaScript

### Security

* API-key authentication
* Read/write authorization
* Confirmation-based database mutations
* Input validation
* Audit logging

---

## ⚙️ Local Setup

### 1. Clone the repository

```bash
git clone https://github.com/Ayushsharma109/OPSMCP-AI-AGENNT.git

cd OPSMCP-AI-AGENNT
```

### 2. Create a virtual environment

Windows:

```powershell
python -m venv .venv
```

Activate it:

```powershell
.venv\Scripts\activate
```

### 3. Install dependencies

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

### 4. Configure environment variables

Create a `.env` file:

```env
MCP_API_KEY=your_main_api_key
MCP_READONLY_KEY=your_readonly_api_key

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=your_base_url
OPENAI_MODEL=your_model

DB_NAME=mcp_demo
DB_USER=postgres
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432
```

> Never commit `.env` or API keys to GitHub.

### 5. Start PostgreSQL

Make sure PostgreSQL is running and the required database/tables exist.

### 6. Start the MCP server

```powershell
python run_server.py
```

The MCP server runs on:

```text
http://127.0.0.1:8000
```

### 7. Start the web application

Open another terminal:

```powershell
python web_app.py
```

The dashboard will be available at:

```text
http://127.0.0.1:8080
```

---

## 🧪 Example Workflow

### User

```text
Show me all users.
```

### AI Agent

Determines that `get_users` is required.

### MCP

Executes:

```text
get_users()
```

### PostgreSQL

Returns the user records.

### AI

Converts the database result into a natural-language response.

---

## 🔄 Write Operation Workflow

```text
User Request
     ↓
AI Agent
     ↓
MCP Tool Selection
     ↓
Permission Check
     ↓
User Confirmation
     ↓
Input Validation
     ↓
PostgreSQL Update
     ↓
Audit Log
     ↓
AI Response
```

This design helps prevent accidental database modifications.

---

## 🏆 Hackathon MVP

OpsMCP was developed as a focused MVP demonstrating how MCP can be used to connect AI agents with real enterprise data and controlled backend operations.

The project focuses on:

* AI tool calling
* MCP architecture
* Secure database interaction
* Human confirmation for mutations
* Auditability
* Natural-language company operations

---

## 🚀 Future Improvements

Potential future improvements include:

* Role-based dashboard access
* More enterprise MCP tools
* Advanced analytics
* Multi-database support
* Better audit-log visualization
* Deployment-ready authentication
* Enterprise SSO integration
* More granular permissions

---

## 👨‍💻 Author

**Ayush Sharma**

Built as a solo hackathon project exploring:

**AI Agents + MCP + PostgreSQL + Secure Tool Execution**

---

## 📄 License

This project is intended primarily as a hackathon and learning project.