MERCURY - AI in the Real World

CONTINUOUS INTELLIGENCE CYCLE

From Intent to Real-World Effect

Mercury governs the complete closed loop between AI reasoning and physical macOS and mobile environments with refusal by default when identity, authority or the outcome of a past action is unknown, and a local operations log.

01 / SENSE

1. SENSE

Perception layer: captures displays, file structures, and connected Android/iOS hardware status.

02 / UNDERSTAND

2. UNDERSTAND

Governance & context: validates per-client identity, enforces capability scopes, and coordinates screen actions that pass through Mercury.

03 / ACT

3. ACT

Governed execution: commands run as explicit argument lists, file operations, AppleScript, and adb device actions.

04 / FEEDBACK

4. FEEDBACK

Feedback: writes each call to the local operations log, refuses to repeat an action whose outcome is unknown (UNCERTAIN), and returns the result to the AI.

V1 PRODUCTION CAPABILITIES

Governed Control Grounded in Reality

These capabilities run in the current macOS build, providing multi-AI coordination and governed access.

Per-Client Revocable Identities

Each AI client can be issued an individual revocable key with its own capability profile (by default a shared launch token is used, which is not revocable in v1). Revocation takes effect on the next request.

clientId sha256(token) revocation

Durable Effects & Idempotency

Mutating operations require a durable idempotency key. Prevents duplicate side effects, replays recorded results, and safely handles UNCERTAIN states without blind retries.

idempotencyKey replay cache UNCERTAIN

Screen Lock

An in-memory lock for calls that pass through Mercury (screenshots, opening apps, AppleScript). A second client waits up to 3 seconds and is then refused; the first client keeps the lock for 10 seconds after its last call.

RESOURCE_BUSY 10s hold macOS screen

Local Operation Log (JSON Lines)

Operations write a row to the local audit.jsonl log with client, tool, allowed/denied status, duration, and result timestamp; request payloads are not stored.

audit.jsonl json-lines local-log

Hardware & Mobile Drivers

Direct native automation on macOS host drivers, Android actions over adb, and connected iOS / iPadOS device list discovery.

Android ADB iOS list macOS host

Explicit-Argv Safe Execution

Commands run as an explicit argument list without a shell; access is governed by the client profile.

explicit-argv no-shell client profile

USE CASES

What Mercury does in practice

Practical automation workflows running through the local daemon and MCP bridge.

01

Work with project files

Ask an AI assistant to read a project folder, summarise it and write the result to a file. Give a review-only assistant a read-only token.

02

Run a build and report

Let an assistant run a program or script on your Mac with explicit arguments and read its output.

03

Use the screen

Take a screenshot, open an app or run an AppleScript. If two assistants try at once, the second waits or is refused.

04

Check a connected phone

List connected Android devices and send taps, swipes, text and key events with adb. iPhone and iPad are listed only.

05

Keep a record

Each call is written to a local operations log with the client, tool, result and time. Request contents are not stored.

Every action runs without a confirmation prompt, according to the profile you assign.

SECURITY & GOVERNANCE

Fail-Closed in Key Scenarios

Automation tools with system privileges must enforce explicit execution boundaries. In key scenarios, Mercury fails closed by default: when identity is missing, permissions are absent, or previous action outcome is unknown.

Governance Invariants

Strict File Permissions (0600) Registry and per-client token files require strict owner-only permissions (0600). The daemon checks permissions on every request and fails closed if permissions are widened.
Owner-Gated Capability Scopes Clients are bound to capability profiles (owner-full, scoped, read-only). Read-only clients are refused write, run and AppleScript capabilities.
UNCERTAIN Recovery & No Blind Retries If the outcome of an action is unknown, Mercury reports UNCERTAIN status and rejects blind retries, preventing duplicate side effects.
No Fake Success Unsupported or unauthorized capabilities return an explicit error result rather than a simulated success.

 // Mercury MCP Client Registration (0600 token isolation) // products/mercury-device-commander/docs/client-identity-and-resource-lease.md $ node src/client-admin.js create claude-code --profile owner-full
token: runtime/clients/claude-code.token (chmod 0600) $ node src/client-admin.js create auditor --profile read-only
token: runtime/clients/auditor.token (read-only enforcement) // MCP Configuration (tested with Claude; a sample configuration is available for Gemini)
{
  "mcpServers": {
    "mercury": {
      "command": "/Applications/Mercury Device Commander.app/Contents/MacOS/Mercury Device Commander",
      "args": ["mcp", "--client", "claude-code"]
    }
  }
}

CLIENT COMPATIBILITY

MCP Clients

Tested with ChatGPT and Claude. Works with MCP clients; a sample configuration is available for Gemini.

ChatGPT Tested

Cloud sessions connect via user-configured tunnel to the local Mac daemon.

Transport: User-configured tunnel · Port 17890

Claude Tested

Local engineer CLI or desktop interface connected via standard stdio MCP bridge with designated clientId token.

Transport: Stdio Bridge · claude-code token

Other MCP clients Not tested

A sample configuration is available for Gemini.

Transport: Standard MCP Bridge

SYSTEM ROADMAP

From one Mac to a fleet

Planned roadmap from the V1 local control plane to multi-machine fleets (planned).

Phase 01

ACTIVE CORE

V1 Governed Mac Runtime

Single-Mac governed control plane daemon
Per-client revocable tokens and identities
Screen lock for GUI calls (10 s hold)
Effect journal with idempotency keys
macOS + Android ADB + iOS discovery drivers
Local operation log (JSON Lines)

Phase 02

In development

V2 Fleet Management

Several Macs under a central Hub
Signed execution receipts

Phase 03

Planned

V3 (planned)

Federation between Hubs of different organizations; a wider device network is deferred
No date, no price

PHILOSOPHY

Philosophy

TWO NATURES. ONE SYSTEM. ONE REALITY.

AI systems reason, plan and request actions. Mercury is the layer that acts on the machine: the eyes, ears and hands of AI in the real world.

Mercury is not the brain. Decisions, memory and business orchestration stay with the AI and the people who use it; Mercury authenticates, authorizes, executes and records what happens on the device.

FAQ

Frequently Asked Questions

What is Mercury?

Mercury Commander is a macOS app with a local daemon and an MCP bridge. AI assistants connect to it to work with files, programs, the screen and connected Android phones on your Mac.

Is it a sandbox?

No. Mercury v1 is a privileged tool for the machine owner. See Security for the known limits.

Which AI clients work with it?

We have tested ChatGPT and Claude. Other MCP clients can connect; a sample configuration is available for Gemini.

Which computers does it run on?

Apple Silicon Macs (.app). Intel, Windows, Linux and iOS as a host are not supported.

What leaves my Mac?

The daemon listens on 127.0.0.1 only. What an AI assistant reads through Mercury goes to the AI service you connected. Reaching the daemon from a web AI needs a tunnel that you configure yourself.

How much does it cost?

Commander is 20 USD per month for one Mac. Checkout is not open yet. Fleet and Mesh prices are not announced.

How do I get help?

Write to office@merlin-partners.com.

Contact

Write to us: office@merlin-partners.com

Merlin&Partners

AI in the real world.

Sees the screen and drives apps

Works with project files

Runs builds and scripts

Controls a connected Android phone

A key and permissions for each assistant

Every action logged, never run twice