Summary: behavior-mcp is an MCP server that runs deterministic, ~60Hz behavior trees in browser runtimes with reactive triggers, safety guardrails, and Merkle-audited persistence.
Execute behavior trees — load, unload, or hot-swap running tree instances (load_behavior).
Control execution — abort, pause, resume, or unstick runs and disengage inputs (abort_behavior).
Tune and inspect runtime — set/get/reset execution parameters (set_parameters) and query status, history, node traversal paths, and tick counts (get_status).
Define and version trees — register, list, get, or synthesize immutable behavior tree JSON with SHA-256 hashes (manage_behaviors).
Configure reactive triggers — register priority-preempting interrupts with cooldowns (register_trigger).
Share state across nodes — read/write/delete blackboard keys, ingest perception/spatial/task/vitals slices with TTL staleness, and acquire agent mutex leases (manage_blackboard).
Capture and replay sequences — record or list deterministic browser action frame sequences (replay_recording).
Monitor telemetry — fetch tick durations, percentiles, stuck events, aggregates, comparisons, and action-outcome spool entries (get_metrics).
Maintain the database — run SQLite stats/doctor diagnostics, verify SHA-256 Merkle audit chains, and snapshot, diff, or restore state (manage_runtime_db).
Safety and CLI support — 5-layer guardrails (fail-closed evaluation, synchronous semantic checks, HMAC dispatch-token gating, rate/policy limits, kill switch with 5s watchdog) plus init, doctor, and inspect CLI commands.
Provides tools for managing the SQLite runtime database, including diagnostics, SHA-256 Merkle audit, snapshots, and checkpoint rollback.
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
# 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 inspectRelated MCP server: agent-reasoning-mcp
Tool | Actions | Purpose |
|
| Inject, initialize, or hot-swap a behavior tree in browser runtime |
|
| Dynamically update or query runtime execution parameters |
|
| Query active status, node traversal path, tick count, duration |
|
| Halt, pause, or resume behavior execution safely |
|
| Configure reactive interrupt triggers with priority preemption |
|
| Capture or inspect deterministic browser action sequences |
|
| Retrieve runtime telemetry, tick durations, and stuck events |
|
| CRUD for immutable behavior tree JSON with SHA-256 tree hashes |
|
| Read, write, or query shared behavior tree blackboard variables |
|
| SQLite diagnostics, SHA-256 Merkle audit, and checkpoint rollback |
Fail-Closed Evaluator: Unrecognized node definitions throw fatal exceptions immediately.
60Hz Tick Invariant & Synchronous semantic_check: The loop never blocks on external network calls; semantic condition checks resolve synchronously against blackboard caches.
HMAC Intention Gate Verification: Intentions dispatched to execution nodes require unexpired, cryptographically signed dispatch tokens (PENTAD_HMAC_SECRET).
Action Rate Limiter & Leaf Policy Gate: Strict 60 actions/sec maximum throughput ceiling and policy guardrails blocking irreversible mutations.
Emergency Kill Switch & Watchdog Heartbeat: Atomic safety latch and watchdog timers halting execution if tick stalls beyond 5,000ms.
📖 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.
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"mcpServers": {
"behavior-mcp": {
"command": "behavior-mcp",
"args": ["run"],
"env": {
"PENTAD_HMAC_SECRET": "your-secure-shared-secret-here"
}
}
}
}# Run full unit and integration test suite across 38 test files (266 tests)
npm testMIT © PuterVision
Immediately halt, pause, resume, or unstick behavior execution and disengage active inputs (actions: abort, pause, resume, unstick). Use abort_behavior instead of register_trigger when manually halting or recovering execution rather than configuring automatic condition interrupts.
Returns transition status, disengaged inputs, and unstick diagnostics.
Inputs: action (required), reason, project, trace_id, +1 more.
Retrieve runtime execution telemetry, tick durations, stuck events, category statistics, and 60Hz action outcome spool entries (actions: current, history, aggregate, compare, spool, drain_spool). Use get_metrics instead of get_status when evaluating tick performance, reading spooled action outcomes, or inspecting aggregated statistics rather than active node traversal.
Returns telemetry metrics, duration percentiles, stuck event counts, spooled outcome records, or drained entry counts.
Inputs: action (required), limit, project, trace_id, +3 more.
Query active behavior execution status, history, or full tree node traversal state (actions: current, history, tree_state). Use get_status instead of get_metrics when inspecting active execution state and node traversal paths rather than aggregated runtime performance telemetry.
Returns execution status, current node path, tick counters, duration, and error states.
Inputs: action (required), limit, project, execution_id.
Load, unload, or hot-swap a behavior tree instance in the browser runtime (actions: load, unload, swap). Use load_behavior instead of manage_behaviors when executing an active behavior tree instance at runtime rather than registering or inspecting definitions.
Returns execution handle, runtime state, active node, and session/intention bindings.
Inputs: action (required), behavior_name (required), project, trace_id, +7 more.
Manage immutable JSON behavior tree definitions with SHA-256 hash verification (actions: register, list, get, synthesize). Use manage_behaviors instead of load_behavior when defining, versioning, or synthesizing behavior tree structures rather than executing them.
Returns tree definition, version metadata, SHA-256 content hash, or synthesis DAG.
Inputs: action (required), name, tree, steps, +6 more.
Read, write, delete, lease, list, or ingest structured state slices into shared behavior tree blackboard state (actions: get, set, delete, lease, list, ingest_slice). Use manage_blackboard instead of set_parameters when coordinating state across behavior nodes, projecting perception/spatial slices with staleness protection, or acquiring agent mutex leases.
Returns blackboard value, lease acquisition status, key listings, or slice ingestion summary with expiry metadata.
Inputs: action (required), key, mode, value, +7 more.
Database maintenance, diagnostics, SHA-256 Merkle audit verification, and snapshot management (actions: stats, audit, doctor, snapshot, diff, restore). Use manage_runtime_db instead of get_metrics when auditing SQLite integrity and Merkle proofs or restoring database snapshots.
Returns maintenance diagnostics, Merkle audit trees, snapshot metadata, or diff reports.
Inputs: action (required), name, project, description.
Configure or list reactive interrupt triggers with priority preemption and cooldown guards (actions: register, list). Use register_trigger instead of abort_behavior when defining automatic condition-based interrupts rather than manually pausing or stopping a tree.
Returns registered trigger configuration, ID, or trigger list.
Inputs: action (required), name, project, priority, +5 more.
Capture or list deterministic browser action sequences with adaptive timing (actions: capture, list). Use replay_recording instead of load_behavior when recording or inspecting fixed action sequences rather than running a dynamic behavior tree.
Returns recording metadata, frame sequences, or list of stored recordings.
Inputs: action (required), name, frames, project, +2 more.
Dynamically set, inspect, or reset execution parameters for the active behavior runtime (actions: set, get, reset). Use set_parameters instead of manage_blackboard for tuning tree-level execution variables and thresholds rather than sharing cross-node data keys.
Returns updated parameter map and execution ID.
Inputs: action (required), project, parameters, execution_id.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool targets a distinct aspect of behavior tree runtime management, and descriptions explicitly guide against misselection (e.g., 'use X instead of Y'). Overlaps like get_status vs get_metrics and load_behavior vs manage_behaviors are clearly differentiated.
All tool names follow a consistent snake_case verb_noun pattern (e.g., load_behavior, set_parameters, get_status, manage_blackboard). No mixing of conventions or vague abbreviations.
10 tools is well-scoped for a behavior tree runtime server. Each tool earns its place by covering a unique functional area without redundancy.
The surface covers definition, execution, monitoring, data sharing, triggers, recordings, metrics, and DB maintenance. Minor gaps exist: no explicit delete/update for behavior definitions (immutability may excuse this), no release for blackboard leases, and no delete for recordings.
Live, editable canvas for AI agents — author graphs via MCP, then watch and reroute runs live.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Memory, reflection and safety for AI agents. Hosted or local, no vector database.
