@putervision/behavior-mcp

High-Frequency (~60Hz) In-Browser Behavior Tree Tactical Runtime Engine for AI Agents

@putervision/behavior-mcp is a Model Context Protocol (MCP) server that executes deterministic behavior trees directly in browser runtimes at ~60Hz with reactive trigger preemption, frame recordings, SHA-256 Merkle audit chains, and a 5-layer safety guardrail stack.

🌐 Official Documentation: putervision.com • Interactive Web Docs

---

⚡ 15-Second Quick Start

# 1. Initialize runtime & seed default behavior trees in your workspace
npx @putervision/behavior-mcp init

# 2. Run system diagnostic and health checks
npx @putervision/behavior-mcp doctor

# 3. Inspect active executions, blackboard state, and reactive triggers
npx @putervision/behavior-mcp inspect

---

🛠️ 10 Core MCP Tools

Tool	Actions	Purpose
load_behavior	load, unload, swap	Inject, initialize, or hot-swap a behavior tree in browser runtime
set_parameters	set, get, reset	Dynamically update or query runtime execution parameters
get_status	current, history, tree_state	Query active status, node traversal path, tick count, duration
abort_behavior	abort, pause, resume	Halt, pause, or resume behavior execution safely
register_trigger	register, list	Configure reactive interrupt triggers with priority preemption
replay_recording	capture, list	Capture or inspect deterministic browser action sequences
get_metrics	current, history	Retrieve runtime telemetry, tick durations, and stuck events
manage_behaviors	register, get, list	CRUD for immutable behavior tree JSON with SHA-256 tree hashes
manage_blackboard	get, set	Read, write, or query shared behavior tree blackboard variables
manage_runtime_db	stats, audit, snapshot, restore	SQLite diagnostics, SHA-256 Merkle audit, and checkpoint rollback

---

🛡️ 5-Layer Safety Guardrail Stack

1. Fail-Closed Evaluator: Unrecognized node definitions throw fatal exceptions immediately.
2. Watchdog Heartbeat Timer: Halts execution if tick evaluation stalls beyond 5,000ms.
3. Action Rate Limiter: Strict 60 actions/sec maximum throughput ceiling.
4. Leaf Policy Gate: Blocks irreversible, high-risk mutations (delete_item, spend_currency).
5. Emergency Kill Switch: Atomic safety latch (EmergencySafety.engageKillSwitch()) halts all runtimes.

---

📚 Deep Documentation Guides

• 📖 Formal API Reference: Full parameter tables, type definitions, and tool schemas.
• 💡 Core Architecture & Concepts: Behavior tree execution model, ~60Hz loop, and trigger lifecycle.
• 🖥️ CLI Usage Guide: Complete CLI command reference (init, doctor, inspect, run).
• 💾 Database Schema: SQLite table structures, indexes, and Merkle audit ledger.
• ⚙️ Configuration Reference: .behavior-mcp.json parameters and environment variables.

---

🔗 Client Configuration

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "behavior-mcp": {
      "command": "behavior-mcp",
      "args": ["run"]
    }
  }
}

---

🧪 Testing

# Run full unit and integration test suite across 15 test files (87 tests)
npm test

---

📄 License

MIT © PuterVision