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

pip install nexus-mcp

Or install locally for development:

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:

python examples/contract_intelligence_demo.py

Output:

🚀 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

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

---

Running Tests & Benchmarks

# 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.