mcp-permission-guard 1.1.0

Pre-action authorization for AI agents: intent classification, risk scoring, rule engine, audit trail. Zero dependencies.

MCP Permission Guard — Pre-Action Authorization for AI Agents

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

Install

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

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

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

Rule Patterns

# 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

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

Inspiration

• nah — Intent-level permission guards
• Open Agent Passport — Pre-action authorization
• Beyond Permission Prompts

License

MIT — see LICENSE

Links

• PyPI
• GitHub
• Full collection