Executes deterministic behavior trees in browser runtimes at 60Hz with reactive triggers and blackboard state management.
Also known as putervision/behavior-mcp, behavior-mcp, @putervision/behavior-mcp
- Stars
- 8
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.4.1
- Last commit
- Oct 3, 2026
- License
- MIT
What is Behavior Runtime MCP?
Behavior Runtime executes deterministic behavior trees in browser runtimes at 60Hz with reactive triggers and blackboard state management. It exposes 10 tools, such as load_behavior, set_parameters, get_status.
Summary generated from the project's README
About Behavior Runtime MCP server
Behavior Runtime MCP provides a tactical engine for executing deterministic behavior trees within browser runtimes. Designed for AI agents, the server operates at a high frequency of approximately 60Hz to ensure rapid response times. It manages complex logic through reactive triggers and a shared blackboard state, allowing for sophisticated decision-making processes. Developers can use tools like load_behavior to inject trees or manage_blackboard to manipulate shared variables during execution.
Users set up the server by adding it to their MCP configuration files, such as those used in Cursor or VS Code. The system requires a PENTAD_HMAC_SECRET environment variable to facilitate HMAC intention gate verification for secure node dispatch. The runtime includes built-in safety features, including an action rate limiter capped at 60 actions per second and a watchdog heartbeat that halts execution if ticks stall for more than 5,000ms. It also maintains a SHA-256 Merkle audit chain via the manage_runtime_db tool for verifiable execution history.
What you can do with it
- 1Inject and swap logicAn AI agent can dynamically change its operational logic by hot-swapping behavior trees in the browser.
- 2Monitor execution telemetryDevelopers can track the health and performance of the runtime by retrieving tick durations and stuck events.
- 3Manage shared stateThe agent can read or write variables to a shared blackboard to coordinate different parts of a behavior tree.
- 4Audit execution historyYou can perform diagnostic checks and audit the execution ledger using SHA-256 Merkle chains.
Written from the project's README. Every use case is checked against a quote from it.
How to install Behavior Runtime MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Behavior Runtime MCP in Claude Code
$ claude mcp add behavior-mcp -- npx -y @putervision/behavior-mcpInstall Behavior Runtime MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"behavior-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/behavior-mcp"
]
}
}
}Install Behavior Runtime MCP in VS Code
.vscode/mcp.json
{
"servers": {
"behavior-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@putervision/behavior-mcp"
]
}
}
}Install Behavior Runtime MCP in VS Code CLI
$ code --add-mcp '{"name":"behavior-mcp","type":"stdio","command":"npx","args":["-y","@putervision/behavior-mcp"]}'Install Behavior Runtime MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"behavior-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/behavior-mcp"
]
}
}
}Install Behavior Runtime MCP in Codex
$ codex mcp add behavior-mcp -- npx -y @putervision/behavior-mcpInstall Behavior Runtime MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.behavior-mcp] command = "npx" args = ["-y", "@putervision/behavior-mcp"]
Install Behavior Runtime MCP in Gemini CLI
$ gemini mcp add -s user behavior-mcp npx -- -y @putervision/behavior-mcpInstall Behavior Runtime MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"behavior-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/behavior-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @putervision/behavior-mcp 0.4.1 in an isolated container with no network and no keys. It answered and listed 10 tools.
Behavior Runtime MCP tools 10
Read from the server with tools/listload_behaviorActionLoad, 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.
set_parametersActionDynamically 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.
get_statusRead-onlyQuery 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.
abort_behaviorActionImmediately 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.
register_triggerActionConfigure 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.
replay_recordingActionCapture 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.
get_metricsRead-onlyRetrieve 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.
manage_behaviorsActionManage 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.
manage_blackboardActionRead, 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.
manage_runtime_dbActionDatabase 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.
Configuration
PENTAD_HMAC_SECRET
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@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 & System 1 Invariants
- 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.
📚 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.jsonparameters and environment variables.
🔗 Client Configuration & Environment
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"
}
}
}
}
🧪 Testing
# Run full unit and integration test suite across 38 test files (266 tests)
npm test
📄 License
MIT © PuterVision
Behavior Runtime MCP questions
How do I add Behavior Runtime MCP to Claude Code?
Run claude mcp add behavior-mcp -- npx -y @putervision/behavior-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Behavior Runtime MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Behavior Runtime MCP provide?
It exposes 10 tools, including load_behavior, set_parameters, get_status, abort_behavior, register_trigger.
How can I initialize the runtime and seed default behavior trees?
You can initialize the runtime and seed default behavior trees in your workspace using the command 'npx @putervision/behavior-mcp init'.
Does the execution loop block on network calls?
No, the 60Hz tick invariant ensures the loop never blocks on external network calls, resolving semantic checks synchronously against blackboard caches.