promptspeak-mcp-server

Purpose

PromptSpeak MCP Server provides pre-execution governance for AI agents. When an AI agent calls tools (file writes, API requests, shell commands), there is no verification layer between intent and execution; a single prompt injection, hallucinated parameter, or goal drift can trigger an irreversible operation. PromptSpeak intercepts every MCP tool call, verifies it against deterministic rules, and blocks or suspends high-risk operations within 0.1 milliseconds pending human approval, all before any execution occurs.

Applicable situations include:

• You run AI agents that call tools (MCP servers, function calling, tool use) and need to add 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 document submissions).
• You want to detect behavioral drift—when an agent gradually deviates from its established task.
• You need an audit trail that records every tool call an agent attempts, whether allowed or blocked.
• You are in a regulated domain (legal, financial, medical) where agent operations must be subject to deterministic constraints.

Key Capabilities

Core governance capabilities cover: pre-execution verification, behavioral drift detection, circuit breakers, a human-in-the-loop suspension queue, audit trails, a symbol registry (entity tracking), and safe execution.

Security scanning scans content against 10 detection patterns (before execution) when an agent writes code (write_file, edit_file, create_file, patch_file). Severity level determines the execution policy:

• Critical: Block execution.
• High: Suspend pending human review.
• Medium: Warn but allow execution.

Only write operations are scanned; read_file and other non-write operations are not scanned even if their parameters contain vulnerable code. Patterns can be enabled/disabled at runtime via ps_security_config, and severity levels can also be changed at runtime. ps_security_gate can be used instead of ps_security_scan to enforce policy (block on critical severity, suspend pending human review on high severity, warn on medium severity).

Tool call verification: verify that a PromptSpeak frame is structurally and semantically correct before use. A frame encodes governance constraints as a symbol sequence—pattern first, then domain, action, and entity. Invalid frames return actionable correction suggestions.

Suspended queue workflow (human-in-the-loop approval): When an agent attempts a high-risk operation (high drift score, low confidence, safety finding), the operation is suspended for human review rather than being executed directly. The complete lifecycle includes: listing pending suspensions, inspecting, approving (possibly with modifications), or rejecting.

How to use

Add to ~/.claude/settings.json (or project-level .claude/settings.json), or add to claude_desktop_config.json, then restart Claude Code, and all 56 governance tools become immediately available. The repository does not provide the complete text of specific installation commands; it only describes the above configuration file locations.

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—if any check fails, the tool never runs. Stages 8-9 are post-execution—they detect drift and can halt the agent's future calls.

Applicable scenarios

Regulated domains that need to deterministically constrain agent behavior on the front end, such as legal, financial, and healthcare; scenarios requiring human approval for high-risk operations such as production deployments, financial transactions, and legal document submissions; scenarios requiring detection of agent behavior drift; environments requiring a complete audit trail of tool calls.

Performance

Adds governance to every tool call with sub-millisecond overhead. The benchmark environment is Apple M2 Pro, Node.js 22, Vitest 4.0, including latency (pre-execution checks, 1000 iterations) and throughput (concurrent operations) tests.

Runtime requirements

• Node.js >= 20.0.0
• TypeScript 5.3+ (built from source)
• No external services required—uses SQLite for symbol and governance persistence

Test coverage notes (the parts already tested and working in the repository)

• Pattern detection works. Each of the 10 patterns was tested for true positives and false positives. For example, api_key = "sk-1234567890abcdef" will be caught; API_KEY = process.env.API_KEY will not. SQL injection can catch SELECT * FROM users WHERE id = ${id} but cannot catch the parameterized query db.query("SELECT * FROM users WHERE id = ?", [id]).
• Severity-level enforcement is effective. Critical findings block execution; High findings are queued for review; Medium findings warn but allow. Tested end-to-end through the interceptor pipeline.
• Only write operations are scanned. read_file and other non-write operations are not scanned even if their arguments contain vulnerable code. Tested.
• Runtime configuration is effective. Modes can be enabled/disabled, and severity levels can be changed at runtime via ps_security_config. Disabled modes stop triggering immediately. Changing a mode from medium to critical causes it to block instead of warn. Tested end-to-end.
• Performance is acceptable. Scanning a 100-line file completes within 10ms. Tested.
• Multiple findings in a single file work. A file containing 6 different vulnerability types is correctly classified into the right severity bucket for each. Tested.

Known limitations (parts of the repository that explicitly do not yet work)

• Pending queue integration for HIGH findings: fixed. Security findings at HIGH severity now create real pending holds in HoldManager via the security_finding HoldReason. They appear in ps_hold_list and can be approved/rejected through the normal pending workflow.
• ps_execute has no automatic scanning: security scanning is triggered only in the interceptor's intercept() method for direct tool calls. If an agent uses ps_execute (the governed execution path), then scanning runs only when the inner tool is a write operation and the content is passed as a top-level argument. Nested argument structures may bypass scanning. Reason: ps_execute wraps the tool call in its own argument schema; the scanner checks proposedArgs.content, not deeply nested fields.
• No file-path-based scanning: the scanner only checks content passed as arguments. It cannot scan files already on disk - it does not read from the filesystem. Reason: the scanner is a pure function that accepts strings. Adding filesystem access would change the security model.
• Patterns are regex-based and not AST-aware: patterns use regular expressions and cannot understand code structure. Hardcoded secrets in test fixtures or SQL injection in comments will still trigger. The false positive rate varies between 25-70% depending on the pattern (documented per pattern). Reason: AST parsing would add dependencies and complexity. Regex is fast and sufficient as a governance layer, to queue for human review rather than silently block.
• Partial persistence: pending holds and circuit breaker state are now persisted to SQLite (data/governance.db) and can survive server restarts. However, mode configuration changes (enable/disable via ps_security_config, severity level changes) still exist only in memory and reset after restart. Reason: mode configuration is lightweight and rarely changes; full configuration persistence would require a separate configuration store.

Privacy and data handling

PromptSpeak does not collect personal data, has no telemetry, and stores all governance data locally in SQLite. For standard data processing terms related to platform integrations (such as Anthropic Connectors), see the DPA link provided by the repository. PromptSpeak acts as a data processor; there are no subprocessors and no external data transfers.

Related projects

deeptrend - a structured AI trends source for autonomous agents. Curated from 14+ sources, synthesized through LLM Counsel, and published every 6 hours as a JSON Feed, RSS, and llms.txt. Designed as a data source for agent monitoring pipelines.