chrbailey/promptspeak-mcp-server

**Pre-execution governance for AI agents. Blocks dangerous tool calls before they execute.**
AI agents call tools (file writes, API requests, shell commands) with no validation layer between intent and execution. A prompt injection, hallucinated argument, or drifting goal can trigger irreversible actions. PromptSpeak intercepts every MCP tool call, validates it against deterministic rules, and blocks or holds risky operations for human approval — in 0.1ms, before anything executes.
When to use this
- You run AI agents that call tools (MCP servers, function calling, tool use) and need a governance layer between the agent and the tools.
- You need human-in-the-loop approval for high-risk operations (production deployments, financial transactions, legal filings).
- You want to detect behavioral drift — an agent gradually shifting away from its assigned task.
- You need an audit trail of every tool call an agent attempted, whether it was allowed or blocked.
- You operate in a regulated domain (legal, financial, healthcare) where agent actions must be deterministically constrained.
Install
Claude Code
Add to ~/.claude/settings.json (or project-level .claude/settings.json):
Restart Claude Code. All 56 governance tools are immediately available.
Claude Desktop
Add to claude_desktop_config.json:
As a library
From source
Usage examples
1. Validate a governance frame
Validate that a PromptSpeak frame is structurally and semantically correct before using it. Frames encode governance constraints as symbol sequences — mode first, then domain, action, and entity.
Invalid frames return actionable suggestions:
2. Hold queue workflow — human-in-the-loop approval
When an agent attempts a risky operation (high drift score, low confidence, security finding), the action is held for human review instead of executing. This is the full hold lifecycle: list, inspect, approve or reject.
**Step 1: List pending holds**
**Step 2: Approve with modifications (or reject)**
To reject instead:
3. Security scanning — catch vulnerabilities before execution
Scan code content for security issues before an agent writes it to disk. Critical findings block execution; high-severity findings are held for human review.
Use ps_security_gate instead of ps_security_scan to enforce the policy — it blocks on critical, holds high-severity for human review, and warns on medium:
How it works: 9-stage validation pipeline
Every tool call passes through this pipeline. If any stage fails, execution is blocked.
Stages 1-6 are **pre-execution** — the tool never runs if any check fails. Stages 8-9 are **post-execution** — they detect drift and can halt the agent for future calls.
Security scanning
When an agent writes code (write_file, edit_file, create_file, patch_file), the content is scanned against 10 detection patterns before execution. Severity determines enforcement:
| Severity | Enforcement | What it catches |
|----------|-------------|-----------------|
| **CRITICAL** | **Blocked** — execution denied | SQL injection via template literals, hardcoded API keys/passwords/tokens |
| **HIGH** | **Held** — queued for human review | Security-related TODOs, logging sensitive data, insecure defaults (cors(), 0.0.0.0, debug: true) |
| **MEDIUM** | **Warned** — logged, execution continues | Empty catch blocks, hedging comments ("probably works"), disabled tests |
| **LOW** | **Logged** — no enforcement | DROP TABLE, rm -rf (flagged for awareness) |
What works (tested)
All claims below are backed by passing tests (104 tests across 5 test files):
- **Pattern detection works.** Each of the 10 patterns is tested for true positives AND false positives. Example: api_key = "sk-1234567890abcdef" is caught; API_KEY = process.env.API_KEY is not. SQL injection catches \SELECT * FROM users WHERE id = ${id}\ but not parameterized queries (db.query("SELECT * FROM users WHERE id = ?", [id])).
- **Severity enforcement works.** Critical findings block execution. High findings hold for review. Medium findings warn but allow. Tested end-to-end through the interceptor pipeline.