MCP 服务器

mcp-mesh

Universal MCP router and gateway that bridges LLM agents to OpenAPI, GraphQL, and AWS Lambda services with ISO/IEC 42001 AI governance, RBAC, PII redaction, semantic tool routing, and a web dashboard.

README

MCP-Mesh 🌐🔒

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

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:

📡 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.
🔌 Dynamic Adapters Hub: Manage connected OpenAPI, GraphQL, and AWS Lambda adapters with interactive modal registration forms.
🧠 Smart Router & Security Playground: Test bench to simulate LLM user prompts and inspect tool rankings and role permissions live.
🌓 Light / Dark Mode System: Custom glassmorphism design with seamless theme toggling.

📦 Installation & Setup

Prerequisites

Python 3.10 or higher

Install from Source

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:

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

Mode 2: Local Stdio Transport Mode

Run in stdio mode for local IDE integration (Antigravity IDE, Claude Desktop):

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:

python run_example.py

This script automatically:

Registers the Swagger Petstore OpenAPI endpoints into MCP-Mesh as tools.
Performs contextual tool discovery (tools/list) using the Smart Vector Router.
Executes a tool call with customer data and displays real-time PII Redaction.
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

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:

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:

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:

python -m unittest discover -s tests

📄 License

This project is licensed under the MIT License.