Metadata-Version: 2.4
Name: mcp-permission-guard
Version: 1.2.1
Summary: Pre-action authorization for AI agents: intent classification, risk scoring, rule engine, audit trail. Zero dependencies.
Author: aaameobius-crypto
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates/tree/main/mcp-permission-guard
Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
Project-URL: Documentation, https://github.com/aaameobius-crypto/darkbot-ai-templates/tree/main/mcp-permission-guard#readme
Project-URL: Changelog, https://github.com/aaameobius-crypto/darkbot-ai-templates/blob/main/mcp-permission-guard/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/aaameobius-crypto/darkbot-ai-templates/issues
Keywords: mcp,ai,agent,harness,permission,security,authorization,guardrail,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MCP Permission Guard — Pre-Action Authorization for AI Agents

[![PyPI](https://img.shields.io/pypi/v/mcp-permission-guard)](https://pypi.org/project/mcp-permission-guard/)
[![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen)](tests/)
[![Dependencies](https://img.shields.io/badge/dependencies-zero-success)](https://pypi.org/project/mcp-permission-guard/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

> Intent-based permission system with risk scoring, rule engine, and audit trail. 11 tools, 14 intent categories. Zero dependencies.

## Install

```bash
pip install mcp-permission-guard
```

**Requirements:** Python 3.10+. Zero runtime dependencies (stdlib only).

**Type checking:** Ships with `py.typed` marker (PEP 561). Compatible with mypy, pyright, and pyrefly.

## The Problem

Agents execute destructive actions without guardrails. Binary allow/deny prompts don't work (93% auto-approved). The "lethal trifecta" — private data + untrusted content + external communication — creates risks no single tool can detect.

## The Solution

MCP Permission Guard classifies tool calls into 14 intent categories, scores risk 0-100, evaluates rules, and produces deterministic allow/deny/ask decisions with full audit trail.

## Quick Start

```python
from src.permission_engine import PermissionGuard

guard = PermissionGuard()

# Evaluate a tool call
decision = guard.evaluate(
    tool="terminal",
    args={"command": "rm -rf /tmp/build"},
    context={"user": "agent", "session": "abc"}
)
print(decision)
# {'decision': 'deny', 'risk': 80, 'intent': 'filesystem_delete', 'reason': '...'}

# Register a custom rule
guard.register_rule(
    intent="shell_command",
    action="ask",
    condition={"command_matches": "git push.*--force"}
)

# Query audit log
log = guard.audit_log(limit=20)
for entry in log:
    print(f"{entry['timestamp']} | {entry['decision']} | {entry['tool']}")
```

## 14 Intent Categories (with base risk)

| Intent | Risk | Example |
|--------|------|---------|
| `credentials_access` | 90 | Reading `.env`, API keys |
| `filesystem_delete` | 80 | `rm`, `rmdir` |
| `user_management` | 85 | Creating/deleting users |
| `package_install` | 75 | `pip install`, `apt` |
| `shell_command` | 70 | Arbitrary shell execution |
| `database_write` | 65 | INSERT, UPDATE, DELETE |
| `service_restart` | 60 | `systemctl restart` |
| `code_execution` | 60 | `eval()`, `exec()` |
| `config_change` | 55 | Modifying config files |
| `network_outbound` | 50 | `curl`, HTTP requests |
| `network_inbound` | 30 | Opening a port |
| `filesystem_write` | 40 | `write_file`, `patch` |
| `database_read` | 20 | SELECT queries |
| `filesystem_read` | 10 | `read_file`, `cat` |

## 11 Tools

| Tool | What it does |
|------|-------------|
| `classify_intent` | Map tool call to intent category |
| `risk_assess` | Score 0-100 with lethal trifecta detection |
| `register_rule` | Add allow/deny/ask rule by intent |
| `evaluate` | Full pipeline: classify + risk + rules |
| `audit_log` | Query decision history |
| `list_rules` | Show all registered rules |
| `remove_rule` | Delete a rule |
| `set_policy` | Global: allow_all / deny_all / ask_all / rules_based |
| `get_policy` | Read current policy |
| `get_stats` | Decision statistics |
| `reset` | Clear all state |

## MCP Server Setup

```json
{
  "mcpServers": {
    "permission-guard": {
      "command": "python3",
      "args": ["-m", "src.server"]
    }
  }
}
```

## Rule Patterns

```python
# Deny all credential access
guard.register_rule(intent="credentials_access", action="deny")

# Ask before package install
guard.register_rule(intent="package_install", action="ask")

# Allow filesystem reads
guard.register_rule(intent="filesystem_read", action="allow")

# Conditional: allow git push to feature branches only
guard.register_rule(
    intent="shell_command",
    action="deny",
    condition={"command_matches": "git push origin (main|master)"}
)
```

## Tests

```bash
python -m pytest tests/ -v  # 38 tests, all passing
```

## Inspiration

- [nah](https://github.com/manuelschipper/nah) — Intent-level permission guards
- [Open Agent Passport](https://arxiv.org/abs/2603.20953) — Pre-action authorization
- [Beyond Permission Prompts](https://www.anthropic.com/engineering/beyond-permission-prompts)

## License

MIT — see [LICENSE](LICENSE)

## Links

- [PyPI](https://pypi.org/project/mcp-permission-guard/)
- [GitHub](https://github.com/aaameobius-crypto/darkbot-ai-templates/tree/main/mcp-permission-guard)
- [Full collection](https://github.com/aaameobius-crypto/darkbot-ai-templates)
