<div align="center">
  <h1>🧠 MongoDB Intelligence Server (v2.0 Enterprise)</h1>
  <p><b>An Autonomous, Self-Healing Model Context Protocol (MCP) Server for LLMs</b></p>

  [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
  [![Framework](https://img.shields.io/badge/Framework-FastMCP-success)](https://github.com/jlowin/fastmcp)
  [![Database](https://img.shields.io/badge/Database-MongoDB-green)](https://mongodb.com)
  [![Security](https://img.shields.io/badge/Security-PII_Masking-critical)](#%EF%B8%8F-enterprise-security--hardening)
</div>

---

## 📖 The "Blind AI" Problem

Large Language Models (like Claude, GPT-4, and Cursor) are incredibly smart at writing SQL because SQL has a strict `INFORMATION_SCHEMA`. AI can instantly read the table structures. 

**MongoDB is Schemaless.**
If you point an AI at a raw MongoDB database using the official MCP, the AI is essentially "blind." It has to guess field names, it doesn't know what collections link to each other (no Foreign Keys), and it will constantly hallucinate broken `pymongo` queries that crash your app.

### 💡 The Solution
This MCP injects a **Dynamic Intelligence Layer** between your database and the AI. Before the AI even asks a question, this server:
1. **Reverse-Engineers the Schema:** Scans all collections to infer exact data types, nullability, and Enums.
2. **Proves Foreign Keys:** Uses mathematical heuristics and `$in` queries to physically prove relationships between collections.
3. **Anonymizes Data:** Detects and masks PII (Personally Identifiable Information) so your sensitive data never leaves your local machine.

---

## 🏗️ Architectural Overview

The server is decoupled into three pluggable layers:

```mermaid
graph TD
    A[AI Agent / LLM] <-->|MCP Protocol via stdio| B[server.py - 14 Exposed Tools]
    
    subgraph "MongoDB Intelligence Server"
    B <--> C[Intelligence Layer]
    C <--> D[Data Access Layer]
    C <--> E[Presentation Layer]
    end
    
    D <-->|Safe, Paginated Queries| F[(Raw MongoDB)]
    
    C --> G[Discovery Engine]
    C --> H[Knowledge Graph]
    C --> I[Security Analyzers]
```

---

## 🛡️ Enterprise Security & Hardening

Standard AI connections are dangerous. We engineered 4 critical safeguards:

1. **Memory Protection (OOM Safety Ceiling):** 
   If an AI hallucinates a `{"$limit": 5000000}` query, it will crash your RAM. The MCP dynamically parses all incoming MQL pipelines. If a limit exceeds 1,000, it hard-caps it and returns a `Limit enforced: custom (max 1000)` flag to the LLM.
2. **PII Anonymization:** 
   The engine actively scans field names. If it detects `password`, `ssn`, `email`, or `phone`, it replaces the string payloads with `***MASKED***` before the data hits the AI's context window.
3. **Strict Mutation Gating:** 
   The server includes Write tools (`insert`, `update`, `delete`, `create_index`), but they are completely disabled by default via the `.env` `READ_ONLY=true` flag.
4. **Threaded Concurrency:** 
   Reverse-engineering a 5,000-collection ERP database sequentially takes minutes. We use `ThreadPoolExecutor` (10 workers) to map massive architectures in under ~1.5 seconds.

---

## 🛠️ The 14-Tool Arsenal

The MCP exposes exactly 14 functions to the LLM. *The AI is strictly forbidden from bypassing these tools.*

### 🔍 Core Data Operations
| Tool Name | Description |
|-----------|-------------|
| `execute_aggregation_pipeline` | The flagship query engine. Executes complex MQL natively. Automatically capped at 1000 rows. |
| `execute_find` | Dedicated high-speed query tool supporting `projection`, `sort`, and `skip`. |
| `execute_create_index` | Allows the AI to act as a DBA and create compound indexes to fix slow queries natively. |
| `execute_insert`, `update`, `delete` | Document mutation tools. (Blocked unless `READ_ONLY=false`). |
| `execute_drop_collection`, `database` | High-risk structural deletion tools. (Blocked unless `READ_ONLY=false`). |

### 🧠 Autonomous Intelligence
| Tool Name | Description |
|-----------|-------------|
| `chat_with_database` | The RAG engine. The AI asks a natural language question, and the MCP answers it using its cached Knowledge Graph. |
| `explain_collection` | Generates a deep-dive dossier on a single collection's lifecycle, dependencies, and Enums. |
| `suggest_test_cases` | Generates strict QA scenarios based on discovered schema anomalies. |
| `full_intelligence_pipeline` | The ultimate 360-audit. Runs all discovery and analysis algorithms simultaneously. |

### 📊 Multi-Modal Output Generators
| Tool Name | Description |
|-----------|-------------|
| `generate_dashboard` | Bypasses plain text and generates a premium Vanilla CSS/HTML interactive dashboard. |
| `generate_executive_report` | Compiles database findings into a formatted PDF via ReportLab. |
| `export_demo_package` | Generates a full markdown documentation bundle (architecture, onboarding, DBA recommendations). |

---

## 🚀 Installation & Setup

### 1. Prerequisites
- Python 3.11+
- A running MongoDB instance (Local or Atlas)

### 2. Clone & Install
```bash
git clone https://github.com/YOUR_USERNAME/mongodb-intelligence-mcp.git
cd mongodb-intelligence-mcp
pip install -r requirements.txt
```

### 3. Configuration
Copy the `.env.example` file to a new `.env` file:
```bash
cp .env.example .env
```
Open `.env` and set your variables:
```ini
MONGODB_URI="mongodb://localhost:27017"
# Set to false ONLY if you want the AI to mutate data
READ_ONLY=true 
# Use glob patterns to restrict analysis to specific databases (e.g., tenant_*)
DATABASE_FILTER=
```

### 4. Run the Server
```bash
python server.py
```
*Note: The server runs on `stdio` by default, awaiting an MCP Client connection.*

---

## 🤖 The `.cursorrules` (Critical for LLM Usage)

If you are using Cursor, Claude Desktop, or Antigravity, you **must** use the provided `.cursorrules` file. 

This file acts as a strict "Constitution" for the AI. It physically forbids the AI from writing slow, dangerous PyMongo scripts, and forces it to use the MCP tools. 

**The Auto-Dashboard Rule:**
The rules file contains an `AUTOMATIC REPORT GENERATION RULE`. If you ask the AI:
> *"Find the top 5 highest-paid employees."*

The AI will not just print the JSON. Because of the rules, it will autonomously query the MCP, write a background Python script, and generate a beautiful HTML dashboard without you ever explicitly asking for one.

---

## 🏗️ Project Structure
```text
d:\MCP\
├── server.py                 # FastMCP entry point (Registers all 14 tools)
├── .cursorrules              # The AI "Constitution"
├── src/
│   ├── data_access/          # Pluggable Layer (PyMongo adapters)
│   ├── intelligence/         # The Brain (Discovery, Graph Theory, Caching, PII)
│   │   └── analyzers/        # Pluggable Security & Compliance scanners
│   └── presentation/         # HTML/PDF/Markdown generators
└── outputs/                  # Timestamped artifacts (gitignored)
```

## 🤝 Extensibility
Want to add a new security compliance check (e.g., HIPAA scanning)? You don't need to rewrite the server. Simply drop a new Python script into `src/intelligence/analyzers/` by subclassing `BaseAnalyzer`. The MCP will automatically pick it up, run it during discovery, and inject the findings into the LLM context.