ProductDocsSetupSecurityGitHubnpm
COMPONENTS

MiraiLens Connector

Browser extension for human-authoritative AI control

The MiraiLens Connector is the browser-side control layer of the MiraiLens ecosystem. It connects the MiraiLens MCP server to an active Chrome browser while maintaining authoritative browser-control state and allowing the human to interrupt or take control at any time.

Install for ChromeView source

How it interacts

Relationship to the MCP Server

The MiraiLens MCP Server runs locally on your machine via Node/npm and coordinates tool execution requests from the AI Agent. The **MiraiLens Connector** Chrome extension connects directly to this server using a local WebSocket connection.

Ecosystem Data Flow
AI AgentIssues intent
↓
MCP Servernpx mirailens
↓ Local WebSocket (Port 8080)
MiraiLens ConnectorAuthoritative Gate
↓
Chrome BrowserLive session
↓
Web PageExecution target
Local loopback communication model: All communication happens entirely on local loopback (127.0.0.1) on port 8080. No browser data is sent to a remote MiraiLens server.

Authoritative Safety

Extension Authority

In browser automation, the AI client runs remote scripts. MiraiLens Connector protects against AI attempts to spoof authority:

  • Human Verification: Differentiates user actions from synthetic triggers.
  • State Synchronization: Syncs agent connection states to prevent stale commands.
  • Emergency Lock: State persists across tab transitions and browser reloads.

Responsibilities

Ecosystem Tasks

01Connect the browser to the MCP server
02Maintain browser-control state
03Execute authorized browser actions
04Monitor connection health
05Detect trusted human interaction
06Allow explicit human takeover
07Return control to the agent when authorized
08Abort active execution
09Provide emergency stop
10Persist safety-critical control state
11Prevent unauthorized agent control transitions

Required Permissions

Extension Access Profiles

scripting

Enables authorized browser interactions on the active page — interacting with elements and executing supported browser actions.

tabs

Identifies and manages the tab associated with an active session, and safely handles events like tab closure mid-session.

activeTab

Accesses the tab the user is actively controlling or has authorized for a session, required for core control functionality.

storage

Persists configuration and control-state information so control stays safe across extension and browser lifecycle events.

alarms

Runs periodic heartbeat checks between the extension and MCP server to detect stale connections.

host_permissions

Grants access to web pages, required for the MCP-connected agent to perform authorized interactions.

* Note: MiraiLens requests active permissions only to facilitate core browser interactions requested by the local user. It does not gather metrics or profile your browsing activities.

Control State Machine

Deterministic State Model

The MiraiLens Connector acts as a state gatekeeper. Browser-control transitions are deterministic and extension-authoritative.

Conceptual Relationship
AI Control
↑↓
Human Takeover
↑↓
Human Control

An active AI session is immediately aborted and transitioned to HUMAN_TAKEOVER when user interaction is detected. The AI cannot override this state.

State Monitor
SYS_OK
IDLE
Awaiting instruction
AGENT_RUNNING
AI executes action
HUMAN_TAKEOVER
User triggers control override
HUMAN_CONTROLLED
User retains authority
AGENT_RESUMING
AI requests restart
BLOCKED
Safety threshold triggered
COMPLETED
Workflow finished
FAILED
Execution terminated

Safety Mechanisms

Designed Around Controlled Execution

Control transitions are extension-authoritative. The MCP server mirrors browser control state but cannot override a state owned by the human.

Centralized control state machine
AI execution gatekeeping
Human takeover
Trusted event detection
In-flight action abortion
Emergency stop
WebSocket heartbeat monitoring
Disconnect safety
Tab lifecycle validation
Concurrent action protection
Persistent emergency-stop state
Protection against AI resume spoofing

Engineering Transparency

Known Limitations

We present these architectural constraints as developer transparency rather than marketing omissions:

  • Navigation Interrupts: A browser navigation API call that has already started cannot always be physically aborted midway due to underlying browser engine constraints.
  • Takeover Detection: Implicit takeover currently focuses on trusted mouse and keyboard interaction. Other event types are under active development.
  • Interaction Refining: Additional input types and gesture patterns may require future refinement to guarantee exact state synchronization.