PromptSpeak Governance

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):

{

"mcpServers": { "promptspeak": { "command": "npx", "args": ["promptspeak-mcp-server"] } } }

Restart Claude Code. All 56 governance tools are immediately available.

Claude Desktop

Add to claude_desktop_config.json:

{

"mcpServers": { "promptspeak": { "command": "npx", "args": ["promptspeak-mcp-server"] } } }

As a library

npm install promptspeak-mcp-server

From source

git clone https://github.com/chrbailey/promptspeak-mcp-server.git

cd promptspeak-mcp-server npm install && npm run build npm start

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.

// Tool call: ps_validate

{ "name": "ps_validate", "arguments": { "frame": "⊕◊▶α", "validationLevel": "full" } }

// Response

{ "valid": true, "frame": "⊕◊▶α", "parsedFrame": { "mode": { "symbol": "⊕", "meaning": "strict" }, "domain": { "symbol": "◊", "meaning": "financial" }, "action": { "symbol": "▶", "meaning": "execute" }, "entity": { "symbol": "α", "meaning": "primary" } }, "parseConfidence": 1.0, "report": { "valid": true, "errors": [], "warnings": [ { "code": "ACTION_MISSING_DOMAIN", "message": "Consider adding domain context", "severity": "warning" } ] }, "summary": { "errors": 0, "warnings": 1, "passed": 16 } }

Invalid frames return actionable suggestions:

// Tool call: validate a frame with conflicting modes

{ "name": "ps_validate", "arguments": { "frame": "⊕⊖▶", "validationLevel": "semantic" } }

// Response: blocked — strict + flexible modes conflict { "valid": false, "summary": { "errors": 1, "warnings": 0, "passed": 10 }, "suggestions": ["Remove either ⊕ (strict) or ⊖ (flexible) - cannot have both"] }

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

// Tool call: ps_hold_list

{ "name": "ps_hold_list", "arguments": {} }

// Response: one hold awaiting human review

{ "holds": [ { "holdId": "hold_7k2m9x", "agentId": "devops-agent", "frame": "⊕◈▶α", "tool": "deploy_to_production", "severity": "high", "reason": "drift_prediction", "state": "pending", "evidence": { "driftScore": 0.72, "predictedDrift": 0.85 } } ], "count": 1, "expiredCount": 0 }

Step 2: Approve with modifications (or reject)

// Tool call: ps_hold_approve — approve but downgrade to staging

{ "name": "ps_hold_approve", "arguments": { "holdId": "hold_7k2m9x", "reason": "Reviewed — safe for staging, not production", "modifiedArgs": { "environment": "staging" } } }

// Response

{ "success": true, "decision": { "holdId": "hold_7k2m9x", "state": "approved", "decidedBy": "human", "reason": "Reviewed — safe for staging, not production" }, "executionResult": { "success": true } }

To reject instead:

{

"name": "ps_hold_reject", "arguments": { "holdId": "hold_7k2m9x", "reason": "Drift too high — recalibrate agent first", "haltAgent": true } } // Agent is halted (circuit breaker tripped) and the operation is denied.

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.

// Tool call: ps_security_scan

{ "name": "ps_security_scan", "arguments": { "content": "const query = SELECT * FROM users WHERE id = ${userId};\nconst API_KEY = '[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]';" } }

// Response: two findings — one critical (blocked), one critical (blocked)

{ "findings": [ { "patternId": "sql-injection", "severity": "critical", "match": "SELECT * FROM users WHERE id = ${userId}", "line": 1, "context": "const query = SELECT * FROM users WHERE id = ${userId};", "suggestion": "Use parameterized queries or prepared statements instead of template literals" }, { "patternId": "hardcoded-secret", "severity": "critical", "match": "API_KEY = '[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]'", "line": 2, "context": "const API_KEY = '[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]';", "suggestion": "Move secrets to environment variables or a secrets manager" } ], "scannedAt": "2026-03-19T12:00:00.000Z", "contentLength": 98, "patternsChecked": 10, "enforcement": { "blocked": [ { "patternId": "sql-injection", "severity": "critical" }, { "patternId": "hardcoded-secret", "severity": "critical" } ], "held": [], "warned": [], "logged": [] } }

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:

// Tool call: ps_security_gate — scan AND enforce

{ "name": "ps_security_gate", "arguments": { "content": "app.use(cors());\napp.listen(0.0.0.0, 3000);", "action": "write_file" } }

// Response: held for review (insecure defaults = high severity) { "decision": "held", "reason": "Security: 1 high-severity finding(s) held for review — insecure-defaults", "scan": { "findings": [{ "patternId": "insecure-defaults", "severity": "high", "line": 1 }] } }

How it works: 9-stage validation pipeline

Every tool call passes through this pipeline. If any stage fails, execution is blocked.

Agent calls tool

│ ├─ 1. Circuit Breaker ──── Halted agents blocked instantly (no further checks) ├─ 2. Frame Validation ─── Structural, semantic, and chain rule checks ├─ 3. Drift Prediction ─── Pre-flight behavioral anomaly detection ├─ 4. Hold Check ────────── Risky operations held for human approval ├─ 5. Interceptor ───────── Final permission gate (confidence thresholds) ├─ 6. Security Scan ─────── Scans write actions for vulnerabilities (see below) ├─ 7. Tool Execution ────── Only reached if all 6 pre-checks pass ├─ 8. Post-Audit ────────── Confirms behavior matched prediction └─ 9. Immediate Action ──── Halts agent if critical drift detected post-execution

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:

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.
• Only write actions are scanned. read_file and other non-write actions pass through without scanning, even if their arguments contain vulnerable code. Tested.
• Runtime configuration works. Patterns can be enabled/disabled and severity can be changed at runtime via ps_security_config. A disabled pattern stops firing immediately. Changing a pattern from medium to critical makes it block instead of warn. Tested end-to-end.
• Performance is fine. 100-line file scans complete in under 10ms. Tested.
• Multiple findings in one file work. A file with 6 different vulnerability types correctly classifies each into the right severity bucket. Tested.

What does NOT work yet

• ~~No hold queue integration for HIGH findings.~~ FIXED. HIGH-severity security findings now create real holds in HoldManager via security_finding HoldReason. They appear in ps_hold_list and can be approved/rejected through the normal hold flow.
• No auto-scan on `ps_execute`. The security scan only triggers in the interceptor's intercept() method for direct tool calls. If an agent uses ps_execute (the governed execution path), the scan runs only if the inner tool is a write action AND the content is passed as a top-level arg. Nested argument structures may bypass scanning. Why: ps_execute wraps tool calls in its own argument schema; the scanner checks proposedArgs.content, not deeply nested fields.
• No file-path-based scanning. The scanner only examines content passed as arguments. It cannot scan files already on disk — it doesn't read from the filesystem. Why: The scanner is a pure function that takes a string. Adding filesystem access would change the security model.
• Patterns are regex-based, not AST-aware. The patterns use regular expressions, which means they can't u