mcp-trustguard 0.1.0
TrustGuard integration for MCP (Model Context Protocol) - secure your AI tools
License: MIT
Requires Python: >=3.9
Keywords: mcp, model-context-protocol, ai-security, trustguard, prompt-injection, tool-security

# MCP TrustGuard

Security integration for [MCP (Model Context Protocol)](https://github.com/anthropics/mcp) - protect your AI tools from malicious content.

## Installation

```bash
pip install mcp-trustguard
```

## Features

- **MCPGuard** - Scan tool descriptions and responses for threats
- **ProtectedMCPClient** - Wrap any MCP client with automatic security
- **TrustGuardMiddleware** - Add security to MCP servers

## Quick Start

### Scan Tools Before Registration

```python
from mcp_trustguard import MCPGuard

guard = MCPGuard(api_key="ta_xxx...")

# Scan a tool description
result = guard.scan_tool(
    name="file_reader",
    description="Reads files from disk",
    schema={"type": "object", "properties": {...}}
)

if result.is_safe:
    register_tool(tool)
else:
    print(f"Blocked: {result.reasoning}")
    print(f"Threats: {[t['pattern_name'] for t in result.threats]}")
```

### Protected MCP Client

Automatically filter unsafe tools and scan responses:

```python
from mcp import Client
from mcp_trustguard import ProtectedMCPClient

# Wrap your MCP client
base_client = Client()
client = ProtectedMCPClient(
    base_client,
    api_key="ta_xxx...",
    block_unsafe_tools=True,
    block_unsafe_responses=True,
)

# Only returns safe tools
tools = await client.list_tools()

# Scans response before returning
result = await client.call_tool("web_search", {"query": "python tutorials"})
```

### Server Middleware

Add security to your MCP server:

```python
from mcp.server import Server
from mcp_trustguard import TrustGuardMiddleware

server = Server()
middleware = TrustGuardMiddleware(api_key="ta_xxx...")

@server.list_tools()
async def list_tools():
    tools = get_all_tools()
    return middleware.filter_tools(tools)  # Filters unsafe tools

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    # Scan arguments for prompt injection
    middleware.scan_arguments(name, arguments)
    return await execute_tool(name, arguments)
```

---

## API Reference

### MCPGuard

Core scanning functionality.

```python
guard = MCPGuard(
    api_key="ta_xxx...",     # TrustGuard API key
    strict_mode=False,        # If True, block on MEDIUM threats
    timeout=30.0,             # Request timeout
)

# Scan a tool
result = guard.scan_tool(name, description, schema)
print(result.is_safe)         # bool
print(result.verdict)         # 'allow', 'caution', 'block'
print(result.threats)         # List of detected threats

# Scan a response
result = guard.scan_response(tool_name, response_content)

# Filter a list of tools
safe_tools = guard.filter_tools(tools, on_blocked="warn")
```

### ProtectedMCPClient

Wraps an MCP client with automatic scanning.

```python
client = ProtectedMCPClient(
    base_client,
    api_key="ta_xxx...",
    block_unsafe_tools=True,      # Filter tools from list_tools
    block_unsafe_responses=False,  # Raise on unsafe responses
    strict_mode=False,
)

tools = await client.list_tools()          # Filtered
result = await client.call_tool(name, args) # Scanned

# Check if a tool is safe
is_safe = client.is_tool_safe("web_search")
```

### TrustGuardMiddleware

For MCP server integration.

```python
middleware = TrustGuardMiddleware(
    api_key="ta_xxx...",
    strict_mode=False,
    log_events=True,
    on_threat_detected=my_callback,  # Optional callback
)

# Scan during registration
result = middleware.scan_tool_registration(name, description, schema)

# Filter tools for list_tools response
safe_tools = middleware.filter_tools(tools)

# Scan arguments
middleware.scan_arguments(tool_name, arguments, block_on_threat=True)

# Get unsafe tools
unsafe = middleware.get_unsafe_tools()
```

---

## What Gets Detected

**Tool Description Threats:**
- Hidden instructions ("Always run X first...")
- Capability escalation attempts
- Data exfiltration patterns
- Schema manipulation

**Response Threats:**
- Prompt injection attempts
- Hidden instructions
- Malicious payloads

---

## Error Handling

```python
from mcp_trustguard import UnsafeToolError, UnsafeResponseError

try:
    result = await client.call_tool("suspicious_tool", args)
except UnsafeToolError as e:
    print(f"Tool blocked: {e.tool_name}")
    print(f"Reason: {e.result.reasoning}")
except UnsafeResponseError as e:
    print(f"Response blocked from: {e.tool_name}")
    print(f"Threats: {e.result.threats}")
```

---

## Statistics

```python
stats = guard.get_stats()
print(f"Tools scanned: {stats['tools_scanned']}")
print(f"Tools blocked: {stats['tools_blocked']}")
print(f"Responses scanned: {stats['responses_scanned']}")
```

## License

MIT License

## Links

- **TrustAgents:** https://trustagents.dev
- **MCP Protocol:** https://github.com/anthropics/mcp
- **GitHub:** https://github.com/jd-delatorre/trustlayer