promptspeak

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)