Visora MCP server
Commit Nov 9, 2026Enables AI agents to observe, diagnose, mutate, and verify live Unity scenes using visual diagnostics and animation inspection tools.
Also known as AmaLS367/Visora
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
What is Visora MCP?
Visora enables AI agents to observe, diagnose, mutate, and verify live Unity scenes using visual diagnostics and animation inspection tools.
Summary generated from the project's README
About Visora MCP server
Helping AI agents manage live Unity scenes through visual diagnostics and structured workflows is what Visora enables. It provides a high-level interface for agents to observe, diagnose, mutate, and verify the state of a Unity Editor instance. Instead of forcing an agent to write raw C# or interpret unstructured logs, this server offers 48 registered tools designed for specific tasks like animation analysis, skeleton mapping, and viewport projection.
Developers use this server by running a Python process that communicates with an MCP client via standard input and output. The setup requires a Unity bridge, either the recommended native com.visora.editor package for Unity 6 or the legacy AnkleBreaker bridge. The system operates through a resilient HTTP transport that connects the Python server to the Unity Editor, allowing for atomic transactions that include undo and rollback capabilities to protect scene integrity during mutations.
What you can do with it
- 1Diagnose character animation issuesAn agent can inspect bone bindings, mesh bounds, or animation clips to find the cause of broken character motion.
- 2Verify visual scene changesAn agent can use camera inventory and framing calculations to ensure an object is visible within the camera frustum.
- 3Perform safe scene mutationsAn agent can apply changes to a scene and use undo-aware transactions to restore the previous state if a failure occurs.
- 4Automate asset discovery and importAn agent can find assets online, download them into a quarantine area, and instantiate them within the Unity scene.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
UNITY_BRIDGE_MODE
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableamals367/visora is public and reachablegithub.com/amals367/visora ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/amals367/visora ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub👁️ Visora
Visora is a high-level Model Context Protocol server for Unity Editor. It gives AI agents typed tools for seeing a scene, understanding its state, changing it safely, and verifying the result.
Raw editor scripting is powerful, but it is a poor interface for an autonomous agent: the agent has to invent C#, interpret unstructured logs, guess whether the camera can see an object, and clean up every temporary state change itself. Visora turns those recurring jobs into explicit workflows with validated inputs, compact structured outputs, safety checks, and visual artifacts.
🎯 Why Visora Exists
An agent working in Unity needs more than remote code execution. It needs to answer concrete diagnostic questions:
- ❓ Is the bridge unavailable, or is Unity only recompiling scripts?
- ❓ Is an object missing, outside the camera frustum, unlit, or behind the camera?
- ❓ Is a broken character caused by mesh bounds, bone bindings, the Avatar, or the animation clip?
- ❓ Did an edit actually improve motion over time, or does one screenshot only look plausible?
- ❓ Can a scene or clip mutation be undone if compilation or execution fails?
Visora makes these distinctions part of the tool contract. Its core operating loop is:
🔍 Inspect State ➔ 🩺 Diagnose ➔ 🛡️ Mutate Safely ➔ 👁️ Verify Evidence ➔ ✅ Keep / ↩️ Restore
✨ Key Capabilities
- 👁️ Visual Inspection & Lookdev — Scene cameras, neutral diagnostic lighting, framing calculations, and viewport projections.
- 📐 Framing & Viewport Projection — Camera inventory, frustum diagnostics, and world-to-viewport coordinate mapping.
- 🎬 Animation Analysis & Metrics — AnimationClip inspection, exact-time sampling, preview videos, motion metrics, and reproducible comparison records.
- 🦴 Skeleton & Kinematics — Skeleton mapping, Humanoid Avatar validation, two-bone IK solver, gaze tracking, contact analysis, and curve discontinuity detection.
- 🛡️ Undo-Aware Transactions — Atomic scene and animation transactions with explicit rollback and recovery paths.
- 📦 Asset Discovery & Quarantine — Online asset discovery (Sketchfab, Poly Pizza), quarantined downloads, archive validation, Unity import inspection, and scene instantiation.
- 🔌 Resilient HTTP Transport — Multi-port discovery, bridge flavor selection (native vs legacy), domain-reload recovery, and typed retry hints.
- ⚡ Bundled Native Companion — Native Unity package (
com.visora.editor) plus full compatibility with the legacy AnkleBreaker bridge.
The current MCP surface contains 48 registered tools. The generated source-of-truth catalog is in Agent workflows.
🧩 How It Fits Together
flowchart LR
Agent[AI agent / MCP client] -->|MCP over stdio| Python[Visora Python server]
Python --> Tools[Typed workflow tools]
Tools --> Bridge[Resilient HTTP bridge client]
Bridge -->|legacy contract| AB[AnkleBreaker]
Bridge -->|native endpoints| Native[com.visora.editor]
AB --> Unity[Unity Editor]
Native --> Unity
Unity -->|JSON results and images| Bridge
Tools --> Artifacts[Local screenshots, videos, preview records]
The Python process is the agent-facing product surface. Unity remains authoritative for scene, asset, animation, and rendering state. See Architecture for the complete request lifecycle and module boundaries.
🚀 Quick Start
1️⃣ Install the Python Server
From PyPI as an isolated command-line tool:
uv tool install visora
For development from this repository:
git clone https://github.com/AmaLS367/Visora.git
cd Visora
uv sync --locked --all-extras
Visora requires Python 3.10 or newer. Project and installation commands use uv.
2️⃣ Choose a Unity Bridge
- Native bridge (Recommended): install
unity-package/ascom.visora.editor. The current package requires Unity 6 (6000.0) or newer and exposes the complete optimized feature set. - Legacy bridge: keep an existing AnkleBreaker installation and use Visora as a high-level compatibility wrapper. Unity-version support is determined by that bridge.
The Python default is UNITY_BRIDGE_MODE=legacy; set native explicitly when using the bundled package. auto accepts either and prefers a matching legacy bridge when both are running.
3️⃣ Configure and Run
cp .env.example .env
# Set UNITY_BRIDGE_MODE=native when using com.visora.editor.
uv run visora
Visora communicates with its MCP client over standard input/output. A repository-based client configuration looks like this:
{
"mcpServers": {
"visora": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/Visora", "visora"],
"env": {
"UNITY_BRIDGE_MODE": "native"
}
}
}
}
After connecting, call get_bridge_status, then get_editor_state. Do not begin with a scene mutation.
For platform-specific installation, Docker networking, Unity Package Manager steps, and troubleshooting, read the Setup guide.
📚 Documentation Hub
Explore the full documentation suite organized by workflow and architectural domain:
| Domain | Guide | Description |
|---|---|---|
| 🧭 Overview | Documentation Index | Central hub and roadmap of all documentation resources. |
| 💡 Philosophy | Concepts & Philosophy | The problem model, design principles, and intentional limits. |
| 🛠️ Installation | Setup Guide | Python, Unity, MCP client, Docker, verification, and recovery. |
| 🤖 Agent Recipes | Agent Workflows | The complete 48-tool MCP catalog and task-oriented recipes. |
| 🏗️ Architecture | Backend Architecture | Runtime layers, module boundaries, and request lifecycle. |
| 🌐 Networking | Bridge & Failure Semantics | Discovery, native/legacy dispatch, retries, and reloads. |
| 📐 Data Contracts | Tools & Schemas | MCP registration, Pydantic contracts, and context compaction. |
| 🛡️ Scene Integrity | State & Safety | Edit/Play Mode, Undo stacks, saving rules, and state cleanup. |
| 📦 Asset Handling | Asset Pipeline | Quarantine staging, SSRF defense, archive extraction, and import. |
| 💻 Development | Development Guide | Repository workflow, tests, validation gates, and conventions. |
| 🗺️ Planning | Roadmap & Changelog | Release milestones, historical changes, and future plans. |
📁 Project Layout
backend/
app.py MCP server behavior and agent instructions
server.py process entrypoint and tool registration imports
config.py centralized Pydantic settings
bridge/ HTTP transport, discovery, recovery, typed exceptions
tools/ bridge, scene, vision, animation, mesh, and asset workflows
schemas/ Pydantic input/output vocabulary
unity-package/
Editor/Core/ HTTP server, router, main-thread dispatcher, settings
Editor/Services/ Unity-native workflow implementations
Tests/Editor/ Unity EditMode integration tests
docs/ user, agent, architecture, and contributor documentation
skills/ optional agent workflow skills
tests/ Python unit and integration tests
scripts/ catalog, distribution, Python/Unity validation helpers
⚠️ Important Operating Boundaries
[!IMPORTANT] Live Unity Companion: Visora controls a live Unity Editor instance; it is not a standalone headless replacement for Unity.
[!WARNING] Localhost Loopback Only: The native bridge listens exclusively on loopback (
127.0.0.1). Never expose this port directly to an untrusted network.
[!NOTE] Safe Transactions & Undo:
safe_transactionimproves recovery but cannot make arbitrary C# intrinsically safe. Script operations must register affected Unity objects with the Undo system.
[!CAUTION] Evidence over Assumed Success: A successful HTTP status (
success=true) confirms call completion, not creative or aesthetic correctness. Always inspect the returned evidence, motion metrics, and visual artifacts.
[!TIP] glTF / GLB Importer Requirement:
.gltfand.glbfiles require a glTF importer package installed in the target Unity project; vanilla Unity does not provide one natively.
🤝 Contributing
See CONTRIBUTING.md and the backend development guide. Visora intentionally does not keep internal Python compatibility shims: when an internal interface changes, update every caller, test, and document to the new canonical API.
📜 License
Copyright 2026 Ama.
Licensed under the Apache License, Version 2.0.
Visora MCP questions
What are the requirements for importing glTF or GLB files?
You must have a glTF importer package installed in your Unity project, as vanilla Unity does not include one natively.
How does Visora handle scene changes and errors?
It uses undo-aware transactions that allow for atomic scene and animation changes with explicit rollback and recovery paths.
Can I use Visora with older Unity setups?
Yes, you can use the legacy AnkleBreaker bridge as a high-level compatibility wrapper.