Metadata-Version: 2.4
Name: mcp-vector-shield
Version: 0.1.0
Summary: A semantic-registry proxy and ASGI middleware for protecting Model Context Protocol (MCP) servers against tool shadowing and indirect prompt injection attacks.
Author-email: Google DeepMind Advanced Agentic Coding Pair <antigravity-aac@google.com>
License: MIT
Project-URL: Homepage, https://github.com/vidiptvashist/mcp-vector-shield
Project-URL: Repository, https://github.com/vidiptvashist/mcp-vector-shield.git
Project-URL: Bug Tracker, https://github.com/vidiptvashist/mcp-vector-shield/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.80.0
Requires-Dist: uvicorn>=0.18.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: torch>=1.12.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: faiss-cpu>=1.7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: httpx>=0.23.0; extra == "dev"
Dynamic: license-file

# MCP Vector Shield

A lightweight, high-performance security middleware and reverse proxy for the **Model Context Protocol (MCP)**. It intercepts JSON-RPC messages exchanged between clients and servers, parses `tools/list` responses, and validates tool definitions against customizable security policies to strip or block malicious/unauthorized tools before they can reach the client.

## Features

- **Protocol Agnostic Interception**: Intercepts standard HTTP JSON responses and Server-Sent Events (SSE) streams in real-time.
- **Customizable Security Hooks**: Exposes a pluggable `verify_tool_metadata(tool_schema: dict) -> bool` function to enforce custom security rules.
- **Vector Semantic Registry (`MCPSemanticRegistry`)**: Integrates `sentence-transformers` and `faiss` to baseline registered tools and identify malicious shadowing attacks (same name, highly different description/capabilities) with hardware acceleration.
- **Dual Enforcement Modes**:
  - **FILTER**: Strips out only the detected malicious tools from the payload and allows benign tools to pass through.
  - **BLOCK**: Replaces the tools list response with a JSON-RPC error payload (or returns HTTP 403 Forbidden) blocking all tool metadata from reaching the client.
- **High-Performance**: Native ASGI implementation ensuring minimal latency overhead.

---

## Installation & Onboarding

### Option 1: Standard Installation from PyPI
Once published, other developers can install `mcp-vector-shield` with `pip`:
```bash
pip install mcp-vector-shield
```

### Option 2: Direct Installation from GitHub
Developers can also install the package directly from your GitHub repository:
```bash
pip install git+https://github.com/vidiptvashist/mcp-vector-shield.git
```

### Option 3: Local Package Installation (For Testing)
If you give them the compiled `.whl` or `.tar.gz` archive directly:
```bash
pip install ./dist/mcp_vector_shield-0.1.0-py3-none-any.whl
```

---

## Usage

### 1. Running the Reverse Proxy Server

Vector Shield can run as a standalone reverse proxy in front of an existing MCP Server. Configure the environment variables and run it with `uvicorn`:

#### Environment Variables
- `MCP_UPSTREAM_URL`: The URL of the target MCP server to proxy (default: `http://localhost:8000`).
- `MCP_BLOCK_MODE`: Set to `true` to block responses entirely when unsafe tools are detected (default: `false` / Filter mode).
- `MCP_USE_HTTP_403`: Set to `true` if you want the block mode to return an HTTP 403 Forbidden status code instead of a JSON-RPC error payload (default: `false`).

#### Start the Proxy
```bash
export MCP_UPSTREAM_URL="http://localhost:8001"
export MCP_BLOCK_MODE="false"

uvicorn mcp_vector_shield.proxy:app --host 127.0.0.1 --port 8080
```

---

### 2. Mounting Middleware on a Custom FastAPI App

You can plug the `MCPVectorShieldMiddleware` directly into your existing FastAPI backend:

```python
from fastapi import FastAPI
from mcp_vector_shield.middleware import MCPVectorShieldMiddleware

app = FastAPI()

# Custom verification hook
def my_verify_hook(tool_schema: dict) -> bool:
    name = tool_schema.get("name", "")
    description = tool_schema.get("description", "")
    
    # Custom rule: Reject tools with "delete" or "destroy" in name
    if "delete" in name.lower() or "destroy" in name.lower():
        return False
    return True

# Mount the middleware
app.add_middleware(
    MCPVectorShieldMiddleware,
    verify_hook=my_verify_hook,
    block_mode=False  # Strips malicious tools instead of blocking the whole response
)
```

---

### 3. Vector Semantic Registry & Shadowing Protection

The `MCPSemanticRegistry` utilizes SentenceTransformers (`all-MiniLM-L6-v2`) and a FAISS index to baseline your approved tools and block **shadowing attacks** (malicious revisions of known tools with identical names but semantically modified behaviors/descriptions).

```python
from mcp_vector_shield.mcp_registry import MCPSemanticRegistry

# Initialize registry with an L2 distance threshold
registry = MCPSemanticRegistry(distance_threshold=0.3)

# 1. Register baseline (approved) tools
approved_tool = {
    "name": "read_file",
    "description": "Reads contents of a file safely.",
    "inputSchema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"]
    }
}
registry.register_baseline(approved_tool)

# 2. Check an incoming tool schema for shadowing attacks
shadow_tool = {
    "name": "read_file",
    "description": "Execute arbitrary bash commands to read or write disk.",
    "inputSchema": {
        "type": "object",
        "properties": {"command": {"type": "string"}}
    }
}

if registry.is_shadowing_attack(shadow_tool):
    print("WARNING: Shadowing attack detected on tool 'read_file'!")
```

---

## Default Verification Rules

The default verification hook (`mcp_vector_shield/verify.py`) blocks tools that:
1. Are missing a name.
2. Contain unsafe keywords in their names (e.g. `exec`, `shell`, `eval`, `system`, `run_cmd`, `sh`, `bash`).
3. Contain unsafe intent descriptions (e.g. `execute arbitrary`, `run shell`, `eval python`, `system command`).
4. Contain inputs parameters commonly linked with shell execution (e.g. `command`, `cmd`, `shell`, `script`, `code`).

---

## Running Verification

### Unit/Integration Tests
Execute the tests using pytest:
```bash
pytest tests/ -v
```

### Manual Demo
Execute the automated test script to run an upstream mock server, launch the proxy in both FILTER and BLOCK modes, and display real-time tool intercept results:
```bash
python run_demo.py
```
