# Nexus-MCP ⚡

<p align="center">
  <strong>Production Enterprise MCP Gateway for Secure, Observable Agent Knowledge Access</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/release/python-3110/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg"></a>
  <a href="https://modelcontextprotocol.io"><img alt="Anthropic MCP" src="https://img.shields.io/badge/Anthropic%20MCP-v1.0-orange.svg"></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
  <a href="https://prometheus.io"><img alt="Prometheus" src="https://img.shields.io/badge/Prometheus-Telemetry-red.svg"></a>
</p>

---

## Overview

**Nexus-MCP** is an enterprise-grade Model Context Protocol (MCP) gateway and security router that gives AI agents (Claude Desktop, Cursor, LangGraph) secure, observable access to internal corporate knowledge.

Raw MCP implementations lack multi-tenancy, dynamic RBAC, tool injection protection, and audit logs. **Nexus-MCP** bridges this gap by acting as a zero-trust security router and document intelligence server.

---

## 🔁 The Enterprise Golden Path

```
MCP Client ──> Authentication & Tenant Context ──> RBAC Scope Check
                                                          │
                                                          ▼
Prometheus & OTel ◄── Response ◄── Schema Extraction ◄── Hybrid RAG (Vector+BM25)
```

---

## Key Features

* **⚡ Official Anthropic MCP SDK Integration**: Built natively on Anthropic's `mcp` specification supporting STDIO & SSE JSON-RPC transports.
* **🔒 Multi-Tenant & ACL Isolation**: Strictly isolates document search and schema extraction per `tenant_id` and user `acl_groups`.
* **🛡️ Security Router & Prompt Injection Sanitizer**: Prevents prompt/tool injection attacks (`DROP TABLE`, `IGNORE INSTRUCTIONS`).
* **🔍 Hybrid Vector + BM25 Retrieval**: Reciprocal Rank Fusion (RRF) combining dense vector similarity and BM25 term frequency.
* **📊 Prometheus & OpenTelemetry Observability**: Tracks tool execution counts, p95/p99 latency, and token expenditure.

---

## Quick Start

### Installation

```bash
pip install nexus-mcp
```

Or install locally for development:
```bash
git clone https://github.com/JasleenSingh/nexus-mcp.git
cd nexus-mcp
pip install -e .
```

---

## Code Example: Golden Path Demo

Run the included commercial contract intelligence demo:

```bash
python examples/contract_intelligence_demo.py
```

Output:
```text
🚀 Starting Nexus-MCP Enterprise Golden Path Demo...
✅ Ingested document into 4 hierarchical chunks for tenant 'tenant-acme-corp'.

🔍 Executing Tool [doc_hybrid_search]...
  Found 1 matching chunks with Hybrid Vector + BM25 search.

📋 Executing Tool [doc_extract_schema]...
  Extracted Agreement Schema (3 fields):
   • payment_terms: Net 30 days (confidence: 0.92)
   • total_contract_value: $3,500,000.00 (confidence: 0.88)
   • governing_law: State of Delaware (confidence: 0.90)

📊 Executing Tool [system_health_telemetry]...
  System Health: healthy

✨ Nexus-MCP Golden Path Execution Completed Successfully!
```

---

## Running Server & CLI

```bash
# Start Nexus-MCP server over STDIO transport
nexus-mcp serve --transport stdio
```

---

## Running Tests & Benchmarks

```bash
# Run complete unit, integration, and security test suite
pytest tests/

# Run retrieval accuracy benchmarks (Recall@K & MRR)
pytest tests/integration/test_retrieval_benchmarks.py -v
```

---

## Project Structure

```
nexus-mcp/
├── src/nexus_mcp/
│   ├── models/             # Pydantic v2 domain schemas (TenantContext, DocumentChunk, SearchQuery)
│   ├── document_processor/ # Hierarchical chunker, schema extractor, and Hybrid RAG retriever
│   ├── security/           # RBAC scope validator and input injection sanitizer
│   ├── observability/      # Prometheus metrics and OpenTelemetry trace span exporters
│   ├── mcp_server/         # Official Anthropic MCP Server & tool registrations
│   └── cli/                # Rich CLI interface (nexus-mcp serve)
├── tests/
│   ├── unit/               # Unit tests (chunker, retriever, schemas, observability)
│   ├── integration/        # MCP JSON-RPC protocol & retrieval benchmarks
│   └── security/           # Adversarial security tests (cross-tenant & prompt injection)
├── examples/               # Contract intelligence demo & sample commercial agreements
├── docs/                   # System architecture & tool specs
├── pyproject.toml
└── README.md
```

---

## License

Distributed under the [MIT License](LICENSE).