# Enterprise MCP Suite

[![MCP Standard](https://img.shields.io/badge/MCP-FastMCP%202.x-blue.svg)](https://modelcontextprotocol.io)
[![LangGraph](https://img.shields.io/badge/Agent-LangGraph-orange.svg)](https://github.com/langchain-ai/langgraph)
[![Security](https://img.shields.io/badge/Security-Zero--Trust%20AST-brightgreen.svg)]()
[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)]()
[![Docker](https://img.shields.io/badge/Docker-PostgreSQL%2016-2496ED.svg)]()

> **Enterprise-Grade AI Agent Security & Integration Infrastructure**  
> Connecting LLMs to PostgreSQL, GitHub, Mock ERP, and Slack via Anthropic's Model Context Protocol (MCP) standard with zero-trust AST SQL inspection and Human-in-the-Loop safeguards.

---

## 🚀 Commercial & Client Demonstration Assets

Everything you need to pitch, demonstrate, and deploy this platform for enterprise clients:

- 🎮 **Live Interactive Showcase:** `python demo_showcase.py` (Single-command menu covering all live client scenarios)
- 📊 **[Executive Briefing & Pitch Deck](COMMERCIAL_DECK.md):** ROI models, architecture comparison, enterprise pricing tiers
- 📢 **[Sales & Marketing Outreach Kit](SALES_PITCH_KIT.md):** LinkedIn copy, CTO cold emails, discovery scripts, objection handling
- 🧪 **[End-to-End QA Test Guide](TEST_GUIDE.md):** Complete step-by-step verification manual (12/12 automated tests)

---

## Real-World Scenario: What This Platform Solves

Imagine an alert fires at 02:45 AM:  
**"Payment gateway intermittent failure — checkout transactions stalling!"**

### Traditional Manual SRE Workflow (45–60 Minutes):
1. An on-call engineer wakes up and connects via VPN.
2. Manually parses noisy PostgreSQL logs across shards (20 mins).
3. Queries the ERP database to identify impacted high-value customers (15 mins).
4. Correlates GitHub commits or issue trackers for recent deployments (10 mins).
5. Drafts and broadcasts a high-priority incident debrief on Slack (10 mins).

### Autonomous Enterprise MCP Workflow (10–12 Seconds):
You supply a natural language goal:
```bash
python run_investigation.py "Investigate incident INC-902 and quantify revenue exposure."
```

**The Agent Autonomously:**
1. Formulates an execution plan via OpenAI GPT-4o.
2. Executes safe, read-only SQL via AST-validated `db_query_tool`.
3. Identifies the root cause: HTTP 502 Bad Gateway in `payment-gateway`.
4. Discovers the affected VIP customer (`Priya Nair / InfraStack Solutions Pvt.`).
5. Pinpoints the exact failed order (`$62,400 USD`).
6. Generates a structured executive debrief with source citations and an audit trail.

---

## System Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│                     Enterprise MCP Suite                              │
│                                                                      │
│  ┌─────────────┐     stdio / SSE      ┌────────────────────────────┐│
│  │   Claude    │◄──────────────────── │   FastMCP Server           ││
│  │   Desktop   │                      │   (server/mcp_server.py)   ││
│  │   / Cursor  │                      │                            ││
│  └─────────────┘                      │  ┌──────┐ ┌────────────┐  ││
│                                       │  │Tools │ │ Resources  │  ││
│  ┌─────────────────────────────────┐  │  └──────┘ └────────────┘  ││
│  │  LangGraph Agent (OpenAI GPT-4o)│  │  ┌─────────────────────┐  ││
│  │                                 │  │  │     Prompts         │  ││
│  │  Planner → MCPExecutor → HITL   │  │  └─────────────────────┘  ││
│  │         → Synthesizer           │  └────────────────────────────┘│
│  └─────────────────────────────────┘           │                     │
│                                                 ▼                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐               │
│  │PostgreSQL│ │ GitHub   │ │ Mock ERP │ │  Slack   │               │
│  │ (Docker) │ │   API    │ │ REST API │ │ Webhooks │               │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘               │
└──────────────────────────────────────────────────────────────────────┘
```

### Security Pipeline

```
Agent Tool Request ──► SafeQueryInspector (sqlglot AST) ──► Blocked if DROP/DELETE
                              │                                  (0 ms, pre-connection)
                              ▼
                     Connection Pool ──► Read-Only PostgreSQL
                              │
             [Mutating Tools] ──► HITL Guard ──► Awaits approval_token='APPROVED'
```

---

## Project Structure

```
enterprise-mcp-suite/
├── docker-compose.yml              # PostgreSQL 16 Alpine container with healthcheck
├── init-db/
│   └── 01_seed_enterprise.sql     # 4 schemas + 30+ enterprise seed rows (INC-902 scenario)
├── requirements.txt                # Pinned production dependencies
├── .env.example                    # Comprehensive environment template
├── config.py                       # Pydantic v2 typed settings with SecretStr protection
├── demo_showcase.py                # Interactive CLI client presentation panel
├── run_investigation.py            # Turnkey CLI autonomous investigation runner
├── COMMERCIAL_DECK.md              # Executive briefing, ROI calculations, commercial tiers
├── SALES_PITCH_KIT.md              # Marketing kit, LinkedIn posts, CTO cold email templates
├── TEST_GUIDE.md                   # 7-group QA and testing manual
├── server/
│   ├── security.py                 # AST SQL validator + HITL decorator + sanitizers
│   ├── tools/
│   │   ├── db_tools.py             # PostgreSQL tools (psycopg connection pool)
│   │   ├── github_tools.py         # GitHub REST API tools
│   │   ├── erp_tools.py            # ERP tools (with in-memory mock fallback)
│   │   └── notification_tools.py   # Slack Block Kit notification tools
│   ├── resources/
│   │   └── schema_resources.py     # Dynamic postgres://schema/* and system://health
│   ├── prompts/
│   │   └── enterprise_prompts.py   # System incident, customer 360, security audit prompts
│   └── mcp_server.py               # FastMCP 2.x server application entry point
├── client/
│   ├── mcp_client.py               # Async stdio/SSE MCP client wrapper
│   └── agent_workflow.py           # LangGraph 4-node autonomous state machine
├── test_end_to_end.py              # 12-test automated verification suite
├── claude_desktop_config.json      # Native Claude Desktop configuration
└── README.md                       # Master platform documentation
```

---

## Quick Start

### 1. Prerequisites
- Python 3.11+
- Docker & Docker Compose running locally
- OpenAI API Key (`sk-proj-...` from platform.openai.com)

### 2. Environment Setup
```powershell
# Navigate to workspace
cd C:\Users\HP\.gemini\antigravity\scratch\enterprise-mcp-suite

# Activate virtual environment
.venv\Scripts\activate

# Install production dependencies
pip install -r requirements.txt

# Create your .env file
copy .env.example .env
```

Open `.env` and configure your `OPENAI_API_KEY`:
```env
OPENAI_API_KEY=sk-proj-your-actual-key-here
```

### 3. Start Database Infrastructure
```powershell
docker-compose up -d

# Verify healthy status (wait ~20 seconds)
docker-compose ps
```

### 4. Run the Automated Verification Suite
```powershell
python test_end_to_end.py
```
*Expected result:* **`Total: 12 | 12 passed | 0 failed`**

### 5. Run an Autonomous Investigation
```powershell
# Single-command default investigation (INC-902):
python run_investigation.py

# Or provide a custom investigation prompt:
python run_investigation.py "Find all enterprise customers with failed transactions."
```
The report is displayed on the console and automatically saved to `latest_investigation_report.md`.

### 6. Launch the Interactive Client Showcase
```powershell
python demo_showcase.py
```
Access all 5 demonstration scenarios live through an interactive terminal interface.

---

## MCP Tools Reference

| Tool Name | Description | Requires HITL |
|---|---|:---:|
| `db_query_tool` | Execute safe SQL query (read-only by default) | No |
| `db_list_tables_tool` | List all user tables in enterprise catalogue | No |
| `github_triage_issue_tool` | Triage and annotate GitHub issues | Comment only |
| `github_list_open_issues_tool` | List open repository issues | No |
| `github_get_commit_status_tool` | Fetch CI/CD pipeline commit status | No |
| `erp_get_order_tool` | Retrieve ERP order details and fulfillment history | No |
| `erp_list_customer_orders_tool` | List customer order portfolio | No |
| `erp_dispatch_order_tool` | Trigger warehouse order dispatch | **Yes** |
| `slack_send_alert_tool` | Send Slack notification (Block Kit formatted) | Error/Critical |

## MCP Resources Reference

| URI Pattern | Description |
|---|---|
| `postgres://schema/{table_name}` | Real-time DDL table schema from PostgreSQL catalogue |
| `system://health` | Live connection pool telemetry, service latency, server status |

## MCP Prompts Reference

| Prompt Name | Description |
|---|---|
| `triage_system_incident` | End-to-end SRE incident triage workflow |
| `customer_360` | 360-degree account and revenue intelligence dossier |
| `security_audit` | Security and vulnerability audit workflow |

---

## Claude Desktop Integration

To register this server natively with Claude Desktop:

1. Copy the contents of [`claude_desktop_config.json`](claude_desktop_config.json).
2. Paste into your Claude Desktop config file:
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Update `OPENAI_API_KEY` and working directory paths.
4. Restart Claude Desktop. The server will appear under the **enterprise-core** hammer icon.

---

## Security Architecture

### Pre-Connection AST Inspection
Traditional regex validation is fragile and vulnerable to dialect obfuscation. The `SafeQueryInspector` parses incoming queries into an Abstract Syntax Tree (AST) using `sqlglot`. Statements containing `Drop`, `Delete`, `TruncateTable`, `Update`, `Insert`, `Create`, or `Alter` are intercepted and rejected **prior to opening any database socket**.

### Human-in-the-Loop (HITL) Enforcement
Mutating operations utilize the `@requires_hitl_approval()` decorator. Any invocation lacking `approval_token='APPROVED'` raises a structured `HITLRequiredError`. In the LangGraph agent workflow, execution pauses at the `hitl_guard` node, prompting a human supervisor before re-routing.

---

## License

Enterprise Proprietary / Apache 2.0 Dual License.