Metadata-Version: 2.4
Name: mcp-permission-guard
Version: 1.0.0
Summary: Permission guard: tool call allow/deny rules for AI agents
Author: aaameobius-crypto
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates
Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
Keywords: mcp,ai,agent,harness,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

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

> Intent-based permission system with risk scoring, rule engine, and audit trail. Zero dependencies, pure Python stdlib.

## 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.

## Tools (11)

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

## Intent Categories

`filesystem_read` (10) · `filesystem_write` (40) · `filesystem_delete` (80) · `network_outbound` (50) · `network_inbound` (30) · `code_execution` (60) · `shell_command` (70) · `database_write` (65) · `database_read` (20) · `credentials_access` (90) · `config_change` (55) · `user_management` (85) · `service_restart` (60) · `package_install` (75)

## 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) — Structured authorization
- [Claude Code Auto Mode](https://www.anthropic.com/engineering/claude-code-auto-mode) — Two-stage classifier

## License

MIT — aaameobius-crypto
