Optics

Optics agent plugins

Agent plugins and skills for Optics (optics-framework on PyPI), open-source test automation for Android, iOS, Android TV, Samsung Tizen, LG webOS and web.

This repo is three things at once:

• a Claude Code plugin marketplace with one plugin, optics-framework, which adds the Optics MCP server and a skill that teaches the agent the Optics suite format;
• a Cursor plugin repo with the same plugin, for the Cursor Marketplace;
• a skills repo that skills.sh can install into Claude Code, Cursor, Codex and other agents.

With it, your agent can open a session on a phone, TV or browser, look at the screen, tap and type, and then write what it did as a CSV or YAML test suite that optics execute runs in CI.

What's inside

.claude-plugin/marketplace.json                          Claude Code marketplace "optics-agent-plugins"
.cursor-plugin/marketplace.json                          Cursor marketplace manifest
plugins/optics-framework/
  .claude-plugin/plugin.json                             Claude Code plugin manifest
  .cursor-plugin/plugin.json                             Cursor plugin manifest
  .mcp.json                                              starts `optics mcp` (optics-framework 1.11.0), used by both
  skills/optics-framework/SKILL.md                       the skill (shared by Claude Code, Cursor and skills.sh)
  assets/logo.svg, logo-plate.svg                        logo (transparent, and on a white plate)

Requirements

• uv on your PATH. The plugin starts the server with uvx, which fetches Python 3.12+ and optics-framework 1.11.0 for you.
• For Android, iOS and TV: a running Appium server with the UiAutomator2 or XCUITest driver. See Test Android apps and Test iOS apps.
• For web: a Playwright Chromium build. Install it once:

  uvx --from "optics-framework[mcp,appium,playwright]==1.11.0" playwright install chromium

The first start downloads the package and can take a minute or two. Claude Code gives an MCP server 30 seconds to start, so on a fresh machine the server shows as failed in /mcp until the download finishes. Warm the cache once before you start your agent:

uvx --from "optics-framework[mcp,appium,playwright]==1.11.0" optics --version

Or start Claude Code with a longer limit, such as MCP_TIMEOUT=180000 claude.

Install in Claude Code

/plugin marketplace add mozarkai/optics-agent-plugins
/plugin install optics-framework@optics-agent-plugins

Or from your shell:

claude plugin marketplace add mozarkai/optics-agent-plugins
claude plugin install optics-framework@optics-agent-plugins

Then ask something like "open https://example.com in a browser with Optics and list what's on the page".

Install in Cursor

Once the plugin is listed in the Cursor Marketplace, open Customize, search for "Optics" and select Install. To try it before then, copy plugins/optics-framework to ~/.cursor/plugins/local/optics-framework and reload the window. The same uv requirement and first-start download apply.

Install the skill with skills.sh

npx skills add mozarkai/optics-agent-plugins

This installs only the skill. Add the MCP server to your agent yourself, as below.

Use the MCP server with another client

Add this to your client's MCP config (Claude Desktop, Cursor, VS Code, and others use the same shape):

{
  "mcpServers": {
    "optics": {
      "command": "uvx",
      "args": ["--from", "optics-framework[mcp,appium,playwright]==1.11.0", "optics", "mcp"]
    }
  }
}

Without uv, install the package with pip (Python 3.12 or newer) and point the client at optics mcp:

pip install "optics-framework[mcp,appium,playwright]==1.11.0"

{ "mcpServers": { "optics": { "command": "optics", "args": ["mcp"] } } }

If the client can't find optics, use its full path (which optics).

MCP bundle and MCP Registry

mcpb/ is the source of an MCPB bundle that starts the same server with uv run, so nothing is vendored; it needs uv on the PATH. Each release attaches the packed .mcpb, which installs in Claude Desktop with a double-click.

server.json lists that bundle in the official MCP Registry as org.optics-framework/optics. To release a new version: bump the pin in mcpb/pyproject.toml and version in mcpb/manifest.json, run npx @anthropic-ai/mcpb pack mcpb optics-framework-<ver>.mcpb, attach it to a mcpb-v<ver> release, then update version, identifier and fileSha256 in server.json and run mcp-publisher login dns --domain optics-framework.org and mcp-publisher publish.

Learn more

• Optics docs and the docs index for agents
• MCP server reference: every tool, resource and environment variable
• Let your AI agent build tests
• optics-framework on GitHub

License

Apache-2.0