npm package: @mcp-server-shield/guard
Description: Inbound security proxy for MCP servers. Detects prompt injection, SQL/command injection, enforces input schemas, validates auth, and prevents abuse — powered by vurb.ts.
Author: Renato Marinho
Latest version: 1.0.0

<div align="center">

# 🛡️ mcp-shield

**Inbound security proxy for MCP servers.**<br>
Detects prompt injection, SQL/command injection, enforces input schemas, validates auth, and prevents abuse.<br>
Powered by [vurb.ts](https://vurb.vinkius.com) — The Express.js for MCP Servers.

[![npm version](https://img.shields.io/npm/v/@mcp-server-shield/guard.svg?color=0ea5e9&style=flat-square)](https://www.npmjs.com/package/@mcp-server-shield/guard)
[![npm downloads](https://img.shields.io/npm/dw/@mcp-server-shield/guard?color=0ea5e9&style=flat-square)](https://www.npmjs.com/package/@mcp-server-shield/guard)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
[![MCP Standard](https://img.shields.io/badge/MCP-Standard-purple?style=flat-square)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](LICENSE)

</div>

---

## Why mcp-shield?

MCP tool calls arrive from the LLM as unvetted JSON-RPC. Without protection, your server is exposed to:

- **Prompt Injection** — LLMs coerced into overriding system instructions
- **SQL Injection** — malicious query strings targeting your database
- **Command Injection** — shell metacharacters in user-controlled inputs
- **Path Traversal** — relative path sequences escaping safe directories
- **Abuse** — rapid-fire calls, oversized payloads
- **Prototype Pollution** — `__proto__` and `constructor` key injection

```
Client (LLM) ──stdin──▶ mcp-shield ──stdin──▶ MCP Server
              ◀──stdout──            ◀──stdout──
                          │
                   ┌──────┴──────┐
                   │ Shield Engine│ ← shield.yaml
                   │  7 Guards   │
                   │  Audit Log  │
                   └─────────────┘
```

---

## Quick Start

```bash
npm install @mcp-server-shield/guard

# Generate default shield.yaml
npx @mcp-server-shield/guard --init

# Run as proxy
npx @mcp-server-shield/guard -- node dist/server.js
```

---

## 7 Security Guards

### 1. 💉 Injection Detection

Fast regex detection (~30 patterns) for prompt injection, SQL injection, command injection, and path traversal. Multilingual: EN, PT, ES, FR.

### 2. 📐 Schema Validation

Validates input structure: string length limits, object nesting depth, array bounds, and prototype pollution prevention (`__proto__`, `constructor`).

### 3. 🔑 Authentication

API key, bearer token, or custom validator support via environment variables.

### 4. 🚦 Abuse Prevention

Per-tool rate limiting (sliding window), burst detection (5s window), and request payload size enforcement.

### 5. 📋 Tool Allowlist/Denylist

Control which tools the LLM is allowed to call.

### 6. 🧹 Input Sanitization

HTML stripping, control character removal, Unicode normalization (NFC), and field length truncation. Unlike other guards, this **modifies** inputs before forwarding.

### 7. 🔍 Request Fingerprinting

SHA-256 hash-based duplicate detection and replay attack prevention within a configurable time window.

---

## Policy Configuration

```yaml
# shield.yaml
guards:
  injection:
    enabled: true
    action: block
    detect:
      promptInjection: true
      sqlInjection: true
      commandInjection: true
      pathTraversal: true

  schema:
    enabled: true
    action: block
    maxStringLength: 10000
    maxDepth: 10
    maxArrayItems: 100
    disallowedKeys: [__proto__, constructor, prototype]

  auth:
    enabled: false
    mode: api_key
    envVar: MCP_API_KEY

  abuse:
    enabled: true
    action: block
    maxCallsPerMinute: 60
    maxPayloadBytes: 102400
    burstLimit: 10

  allowlist:
    enabled: false
    allow: []
    deny: [system.exec, shell.run]

  sanitize:
    enabled: true
    action: sanitize
    stripHtml: true
    stripControlChars: true
    normalizeUnicode: true
    maxFieldLength: 5000

  fingerprint:
    enabled: false
    action: log
    detectDuplicates: true
    windowSeconds: 60

audit:
  enabled: true
  outputPath: ./shield-audit.jsonl
```

---

## Ecosystem

Shield is the **inbound** complement to Firewall's **outbound** protection:

| Package | npm | Direction | Role |
|---|---|---|---|
| `mcp-doctor` | ✅ | — | 🔴 Diagnoses server problems |
| `@mcp-proxy/intercept` | ✅ | Both | 🟡 Observes JSON-RPC traffic |
| `@mcp-firewall/enforce` | ✅ | **Outbound** | 🟢 Protects data going to client |
| **`@mcp-server-shield/guard`** | ✅ | **Inbound** | 🛡️ **Protects server from attacks** |
| `@mcp-server-utils/core` | ✅ | — | 🧰 Developer utilities |

> **For native, zero-bypass security**, use [vurb.ts](https://vurb.vinkius.com) which includes `InputFirewall` (LLM-as-Judge) and `EgressGuard` as middleware.

---

## Programmatic API

```typescript
import { createShieldEngine, loadPolicy, checkInjection } from '@mcp-server-shield/guard';

// Use individual guards
const result = checkInjection(params, config);

// Full engine
const policy = loadPolicy('./shield.yaml');
const engine = createShieldEngine(policy);
const verdict = engine.evaluate(jsonRpcMessage);
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## License

[Apache-2.0](LICENSE)