onUI

Purpose

onUI is used to annotate and draw on any Web UI, exporting structured context for AI agents without any integration into application code. It consists of a lightweight browser extension (Chrome + Edge + Firefox) and a local MCP bridge, positioned as "annotation-first" UI pair programming.

Key Capabilities

• No integration into application code required.
• Independent ON/OFF control per tab (off by default).
• In-page annotation dialog with intent and severity.
• Drawing mode for area annotations (rectangle + ellipse).
• Compact toolbar with pop-up settings (output level + clear after copy).
• Visual markers and hover positioning.
• Export formats support compact, standard, detailed, and forensic.
• Uses Shadow DOM isolation to keep styles stable.
• Local MCP server + native bridge (no cloud backend required).

Installation

Option A: Browser Extension Store (Recommended)

• Chrome Web Store:https://chromewebstore.google.com/detail/onui/hllgijkdhegkpooopdhbfdjialkhlkan?authuser=0&hl=en-GB
• Microsoft Edge Add-ons：https://microsoftedge.microsoft.com/addons/detail/onui/fkcmlckehjhcicihbnmhkadfhjhfnond

Option B: One-Click Install from the Latest GitHub Release

Use this method if you need the latest version (store updates may lag) or want to use Firefox. The installer handles extension installation and can also set up MCP in the same flow. When prompted Set up local MCP bridge now? [y/N] , enter y to enable MCP.

After installation, load it in Chrome or Edge:

1. Open chrome://extensions or edge://extensions
2. Enable Developer mode
3. Click "Load unpacked"
4. Select ~/.onui/extensions/current (on Windows, %USERPROFILE%.onui\extensions\current) Chromium browsers require this final manual step for unpacked extensions.

Firefox manual installation (from Release artifacts):

1. Download onui-firefox-add-ons-vX.Y.Z.zip from the GitHub Release page
2. Extract it to a local folder
3. Open about:debugging#/runtime/this-firefox
4. Click "Load Temporary Add-on..."
5. Select the extracted manifest.json

Usage

1. Open a tab for any supported website.
2. Click the onUI extension icon.
3. Enable "This Tab".
4. Use the in-page launcher to open the compact toolbar.
5. Switch to annotation mode (for element targeting) or drawing mode (for area targeting).
6. Hold Shift and click multiple elements to select targets in bulk.
7. Release Shift to open the shared annotation dialog and fill in annotations for the selected targets.
8. Saving once creates one annotation for each selected element (or one area annotation in the drawing flow).
9. Open the toolbar settings to choose the output level and configure "clear after copy".
10. Copy the exported output from the toolbar.

Local MCP Setup

Recommended path: use the same installer command as above and, when prompted, enter y. To force MCP setup in non-interactive mode, you can use --mcp(macOS/Linux); Windows PowerShell sets environment variables before running the installer. MCP setup now uses prebuilt Release packages (no local build required), but Node 20+ is still required. Manual MCP setup from source is still supported.

JSON configuration for custom MCP routing/clients: If your MCP router uses an object-style mcpServers mapping, use the following canonical entry (use an absolute path for onui-cli.js; relative paths are often rejected or misresolved by routers). If your router uses a list/array structure instead of an object mapping, adapt it using the same command/args shape.

Setup/verification instructions:

• First run pnpm build:mcpso that packages/mcp-server/dist/bin/onui-cli.js exists.
• Keep the server entry name as onui-local.
• After wiring up the configuration, run pnpm doctor:mcp to confirm the local setup health status.
• When Claude Code and Codex CLI are installed, onui-local is registered automatically.
• Browser support in this version: Chrome stable + Edge stable + Firefox stable (unpacked).
• @onui/mcp-server is workspace-local (private: true), so setup/doctor must be run inside this repository.

Use cases

• Annotate and draw on the Web UI to provide structured context for AI agents.
• Annotation-first UI pair programming.

Limitations

• Chromium browsers require a manual loading step for unpacked extensions.
• MCP setup requires Node 20+.
• Browser support in this version is Chrome stable, Edge stable, Firefox stable (unpacked).
• @onui/mcp-server is workspace-local (private: true), and setup/doctor must be run inside the repository.

Maintainer build and release

app.sh is the local release entry point (does not depend on CI/CD). Local verification + artifact packaging: prerequisite checks (Node 20+, pnpm, git, zip); build order is @onui/core -> @onui/extension -> @onui/mcp-server; MCP doctor smoke check (warnings allowed, errors fail); artifacts are packaged into artifacts/vX.Y.Z/, including onui-extension-unpacked-vX.Y.Z.zip, onui-chrome-web-store-vX.Y.Z.zip (strips the manifest key for CWS), onui-edge-add-ons-vX.Y.Z.zip (strips the manifest key for Edge Add-ons), onui-firefox-add-ons-vX.Y.Z.zip, onui-mcp-bundle-vX.Y.Z.zip. Local release + GitHub release: the current branch is main, gh auth status succeeds; operations include automatic patch version bump from the root package.json, synchronizingextension + MCP runtime string versions, running the full --build, committing and tagging vX.Y.Z, pushing the commit/tag, and creating a GitHub Release with the packaged artifacts.