Metadata-Version: 2.4
Name: shieldclaw-mcp
Version: 0.1.0
Summary: A permission layer for AI agent tool calls — wrap any MCP server and enforce allow/deny/ask policy with full audit.
Author-email: ShieldClaw <cole@shieldclaw.xyz>
License: MIT
Project-URL: Homepage, https://shieldclaw.xyz
Project-URL: Source, https://github.com/colepresley000-hub/shieldclaw-mcp-proxy
Keywords: mcp,model-context-protocol,ai-agents,security,permissions,proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# ShieldClaw-MCP

**A permission layer for AI agent tool calls.** Wrap any [MCP](https://modelcontextprotocol.io)
server so every `tools/call` is checked against a policy — allowed, denied,
or held for approval — and audited. We don't ask models to behave. We
technically restrict what they can do.

```
  agent (Claude / GPT / any MCP client)
        │  tools/call: shell_exec "rm -rf /"
        ▼
  ┌───────────────┐
  │ ShieldClaw-MCP│  ──►  🚫 blocked by policy (never reaches the server)
  └───────────────┘
        │  tools/call: read_file
        ▼
  your real MCP server
```

## Install

```bash
pip install shieldclaw-mcp
```

## Use

Write a policy (`policy.json`):

```json
{
  "default": "deny",
  "rules": {
    "read_file": "allow",
    "web_search": "allow",
    "db_delete": "deny",
    "shell_exec": "deny",
    "send_email": "ask",
    "*_secret": "ask"
  }
}
```

Wrap your MCP server. Wherever your agent/client launches the server, put
`shieldclaw-mcp wrap` in front of it:

```bash
shieldclaw-mcp wrap --policy policy.json -- python my_mcp_server.py
```

For example, in a Claude Desktop `mcpServers` config, change the command
from `python my_mcp_server.py` to
`shieldclaw-mcp wrap --policy /path/policy.json -- python my_mcp_server.py`.

### Decisions

| Decision | Effect |
|----------|--------|
| `allow`  | Forwarded to the server unchanged |
| `deny`   | Blocked; the agent gets a JSON-RPC error, the server never sees it |
| `ask`    | Blocked too (**fail-closed**) and tagged "requires approval" |

Rules match exact tool names first, then glob patterns (`db_*`, `*_secret`),
then fall back to `default`. The default default is `deny`.

### Audit

Every decision is appended to `~/.shieldclaw-mcp/audit.jsonl`. Tool
arguments are **never** logged in full — only a short sha256 fingerprint,
so you can correlate without leaking secrets. Set `SHIELDCLAW_CONTROL_PLANE`
(or `--control-plane URL`) to also stream events to a dashboard.

### Other commands

```bash
shieldclaw-mcp check --policy policy.json shell_exec   # -> deny
shieldclaw-mcp version
```

## How it works

ShieldClaw-MCP is a transparent stdio proxy. The client launches it instead
of the real server; it spawns the real server as a child and relays the
newline-delimited JSON-RPC traffic both ways, intercepting only
`tools/call`. Everything else (`initialize`, `tools/list`, notifications)
passes through untouched, so it works with any compliant MCP server.

## Develop

```bash
pip install -e ".[dev]"
pytest -q
```

## License

MIT
