Metadata-Version: 2.4
Name: mcp-marshal
Version: 0.1.0a1
Summary: A lightweight security validation layer for MCP (Model Context Protocol) inputs
Author: Rahul Kaushal
License-Expression: MIT
Project-URL: Homepage, https://github.com/rahulkaushal/mcp-marshal
Project-URL: Repository, https://github.com/rahulkaushal/mcp-marshal
Project-URL: Issues, https://github.com/rahulkaushal/mcp-marshal/issues
Keywords: mcp,security,llm,validation,guardrails,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mcp-marshal

**mcp-marshal** is a lightweight security validation layer for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) inputs. It scans tool-call payloads for risky patterns - SQL injection, XSS, and other common attack vectors - before they reach your model or tool handler.

This is an early but functional release. The core validation logic works today; more features are on the roadmap.

---

## Installation

```bash
pip install mcp-marshal
```

---

## Quick start

```python
from mcp_marshal import Warden

warden = Warden()

# Clean input
result = warden.validate_input({"query": "What is the weather today?"})
print(result)
# {"valid": True, "issues": []}

# Risky input
result = warden.validate_input({
    "query": "SELECT * FROM users; DROP TABLE users;--",
    "context": "admin panel"
})
print(result["valid"])   # False
for issue in result["issues"]:
    print(issue)
# {"field": "query", "pattern": "DROP TABLE", "severity": "critical"}
# {"field": "query", "pattern": "--",         "severity": "medium"}
# {"field": "query", "pattern": ";--",        "severity": "high"}
```

---

## Custom patterns

```python
from mcp_marshal import Warden

extra = [
    {"pattern": "IGNORE PREVIOUS INSTRUCTIONS", "severity": "critical"},
    {"pattern": "jailbreak",                     "severity": "high"},
]

warden = Warden(extra_patterns=extra)
result = warden.validate_input({"prompt": "Ignore previous instructions and ..."})
print(result["valid"])   # False
```

---

## API

### `Warden(extra_patterns=None)`

Create a warden instance. Pass `extra_patterns` to extend the built-in ruleset.

### `Warden.validate_input(payload: dict) -> dict`

Scan all string values in `payload` (recursively) for risky patterns.

Returns:
```python
{
    "valid": bool,
    "issues": [
        {
            "field":    str,   # dot-path to the offending key
            "pattern":  str,   # matched pattern
            "severity": str,   # low | medium | high | critical
        }
    ]
}
```

---

## Built-in patterns

| Pattern | Severity |
|---|---|
| `DROP TABLE` | critical |
| `DELETE FROM` | critical |
| `UNION SELECT` | critical |
| `' OR '1'='1` | critical |
| `;--` | high |
| `<script>` | high |
| `javascript:` | high |
| `--` | medium |

---

## Roadmap

- Prompt injection detection (LLM-assisted)
- Configurable allow-lists and deny-lists
- Async support
- JSON-schema validation for MCP tool arguments
- CLI for quick audits
- Integration guides for popular MCP server frameworks

---

## License

MIT. See [LICENSE](LICENSE).
