# MCP-Mesh 🌐🔒

> **Universal Model Context Protocol (MCP) Router & Gateway Adapter with ISO/IEC 42001 AI Governance & Modern Web Dashboard**

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![Governance](https://img.shields.io/badge/ISO%2FIEC-42001%20Compliant-green.svg)](https://www.iso.org/standard/81230.html)
[![Dashboard UI](https://img.shields.io/badge/React%2018-Web%20Dashboard-purple.svg)](http://localhost:8000/dashboard)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io)

**MCP-Mesh** is an enterprise-grade AI Gateway, Protocol Adapter, and Smart Tool Router built for the Model Context Protocol (MCP). It bridges external legacy & cloud infrastructures (OpenAPI/REST, GraphQL, AWS Lambda) with LLM Agents, enforcing **ISO/IEC 42001 AI Governance**, **Role-Based Access Control (RBAC)**, **Automatic PII Redaction**, **Semantic Tool Routing**, and a **Modern React-based Web Dashboard UI**.

---

## 🌟 Key Features

* **📊 Modern Web Dashboard UI**: High-performance React 18 interface with live telemetry monitoring, trace inspection, interactive role preview, adapter management, and instant Light/Dark mode.
* **🌐 Universal Protocol Adapters**: Dynamic schema ingestion for OpenAPI (Swagger 3.0), GraphQL queries, and AWS Lambda functions—converting them into instantly discoverable MCP tools on the fly.
* **🛡️ ISO/IEC 42001 AI Governance**: Automated AI System Risk Assessment engine evaluating operation severity (Low, Medium, High, Critical), parameter payload complexity, and prompt/SQL injection protection.
* **🧠 Smart Semantic Tool Router**: In-memory TF-IDF & Cosine Similarity vector search index that dynamically exposes only top relevant tools to the LLM based on query context, preventing context window bloat.
* **🔒 Enterprise Security & PII Redaction**: Automatic real-time detection and masking of emails, credit cards, SSNs, phone numbers, and API credentials in both request arguments and response payloads (`[REDACTED]`).
* **🔑 OAuth2 JWT & RBAC Enforcement**: Role-Based Access Control matrix (`admin`, `developer`, `analyst`, `guest`) restricting tool discovery and execution based on agent identity.
* **⚡ Telemetry, Resilience & Replay**: Complete JSON-RPC execution audit logging, circuit breaking for downstream service isolation, and deterministic trace replay (`/admin/telemetry/replay/{trace_id}`).
* **🔌 Dual Transport Modes**: Native support for both **stdio** (for local IDEs like Antigravity & Claude Desktop) and **HTTP REST/SSE** (for distributed microservices).

---

## 📐 System Architecture

```
                                    +------------------------------+
                                    |    LLM Agent / Desktop IDE   |
                                    +------------------------------+
                                                   |
                                            (JSON-RPC 2.0)
                                                   |
                                                   v
+--------------------------------------------------------------------------------------------------+
|                                         MCP-MESH GATEWAY                                         |
|                                                                                                  |
|   +-------------------+    +----------------------+    +-------------------+    +--------------+ |
|   |  JWT & Agent Auth | -> |  RBAC Scoping Engine | -> | ISO 42001 Engine  | -> |  PII Masker  | |
|   +-------------------+    +----------------------+    +-------------------+    +--------------+ |
|                                                                                                  |
|   +------------------------------------------------------------------------------------------+   |
|   |                 Web Dashboard UI (http://localhost:8000/dashboard)                      |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                                                                  |
|                                     +--------------------------+                                 |
|                                     | Smart Semantic Router    |                                 |
|                                     | (TF-IDF Vector Index)    |                                 |
|                                     +--------------------------+                                 |
|                                                  |                                               |
|                                     +--------------------------+                                 |
|                                     | Central Tool Registry    |                                 |
|                                     +--------------------------+                                 |
|                                                  |                                               |
+--------------------------------------------------|-----------------------------------------------+
                                                   |
                        +--------------------------+--------------------------+
                        |                          |                          |
                        v                          v                          v
             +--------------------+      +-------------------+      +-------------------+
             |  OpenAPI Adapter   |      |  GraphQL Adapter  |      |   Lambda Adapter  |
             +--------------------+      +-------------------+      +-------------------+
                        |                          |                          |
                        v                          v                          v
                [ Upstream REST ]          [ Upstream GraphQL ]        [ AWS Lambda Functions ]
```

---

## 💻 Web Dashboard UI Overview

Access the live dashboard at **`http://localhost:8000/dashboard`** (or `http://localhost:8000/`).

Features:
1. **📡 Telemetry & ISO 42001 Audit Stream**: Live execution log with status filter pills (`ALL`, `SUCCESS`, `BLOCKED_RBAC`, `BLOCKED_ISO42001`), JSON payload inspector, and 1-click **Trace Replay**.
2. **🔌 Dynamic Adapters Hub**: Manage connected OpenAPI, GraphQL, and AWS Lambda adapters with interactive modal registration forms.
3. **🧠 Smart Router & Security Playground**: Test bench to simulate LLM user prompts and inspect tool rankings and role permissions live.
4. **🌓 Light / Dark Mode System**: Custom glassmorphism design with seamless theme toggling.

---

## 📦 Installation & Setup

### Prerequisites
* Python 3.10 or higher

### Install from Source
```bash
git clone https://github.com/mcp-mesh/mcp-mesh.git
cd mcp-mesh
pip install -e .
```

---

## 🚀 Quick Start & Launch Modes

### Mode 1: HTTP REST Server & Web Dashboard Mode
Launch the Gateway server and Web UI:

```bash
# Option A: Using CLI command (if installed via pip install -e .)
mcp-mesh start --host 0.0.0.0 --port 8000

# Option B: Direct Python execution
python -m uvicorn mcp_mesh.api.app:app --host 0.0.0.0 --port 8000 --reload
```

👉 Open browser at **[http://localhost:8000/dashboard](http://localhost:8000/dashboard)**.

### Mode 2: Local Stdio Transport Mode
Run in stdio mode for local IDE integration (Antigravity IDE, Claude Desktop):
```bash
mcp-mesh stdio
# OR
python -m mcp_mesh.cli stdio
```

---

## 🧪 Live Interactive Demo Script

Run the automated live demonstration script to populate telemetry traces and test adapter registration:

```bash
python run_example.py
```

This script automatically:
1. Registers the Swagger Petstore OpenAPI endpoints into MCP-Mesh as tools.
2. Performs contextual tool discovery (`tools/list`) using the Smart Vector Router.
3. Executes a tool call with customer data and displays real-time **PII Redaction**.
4. Triggers an **ISO/IEC 42001 Risk Interception** blocking a delete operation.

---

## ⚙️ Configuration Reference

Configure MCP-Mesh via environment variables (or `.env` file):

| Variable | Default Value | Description |
| :--- | :--- | :--- |
| `MCP_MESH_PORT` | `8000` | Gateway HTTP server port |
| `MCP_MESH_JWT_SECRET_KEY` | `mcp-mesh-super-secret-key...` | JWT token signing key |
| `MCP_MESH_ENABLE_AUTH` | `True` | Enforce JWT token authentication |
| `MCP_MESH_ISO42001_COMPLIANCE_MODE` | `True` | Enable ISO 42001 risk evaluation & policy enforcement |
| `MCP_MESH_ENABLE_PII_MASKING` | `True` | Enable automatic PII masking in inputs/outputs |
| `MCP_MESH_PII_REDACTION_STRING` | `[REDACTED]` | Text label substituted for PII data |
| `MCP_MESH_MAX_TOOLS_PER_PROMPT` | `15` | Max tools returned by smart router per query |
| `MCP_MESH_DATABASE_URL` | `sqlite+aiosqlite:///./mcp_mesh.db` | Telemetry database connection URI |

---

## 📖 Protocol & API Usage Examples

### 1. Dynamic OpenAPI Adapter Registration
Register a live OpenAPI endpoint or specification:
```http
POST /admin/adapters/openapi
Content-Type: application/json

{
  "name": "petstore",
  "spec_source": "https://petstore.swagger.io/v2/swagger.json"
}
```

### 2. Listing Tools with Contextual Semantic Filtering
Request tools relevant to a specific user prompt context:
```http
POST /mcp
Content-Type: application/json
X-Query-Prompt: "I need to look up pet order details and inventory"
Authorization: Bearer <YOUR_JWT_TOKEN>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

### 3. Calling an MCP Tool with Governance & PII Masking
Execute a tool through the MCP-Mesh gateway:
```http
POST /mcp
Content-Type: application/json
Authorization: Bearer <YOUR_JWT_TOKEN>

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "petstore_getOrderById",
    "arguments": {
      "orderId": 5
    }
  }
}
```

---

## 🔒 Security & AI Governance Details

### Role-Based Access Control (RBAC)
| Role | Permitted Actions / Tool Patterns |
| :--- | :--- |
| **admin** | Full access to all tools (`*`) |
| **developer** | `read_*`, `write_*`, `list_*`, `get_*`, `execute_*` |
| **analyst** | Read-only operations (`read_*`, `list_*`, `get_*`, `query_*`, `search_*`) |
| **guest** | Discovery only (`list_*`, `search_*`) |

### ISO/IEC 42001 Risk Levels
* **LOW**: Read-only operations and non-mutating queries.
* **MEDIUM**: Low-impact state modifications (drafting, local cache updates).
* **HIGH**: Destructive updates or complex writes (restricted for untrusted roles).
* **CRITICAL**: High-risk keywords (`delete`, `drop`, `truncate`, `shell`, `exec`) requiring `admin` or `supervisor` roles.

---

## 🧪 Running Unit Tests

Execute the comprehensive test suite:
```bash
python -m unittest discover -s tests
```

---

## 📄 License
This project is licensed under the MIT License.