convez.ai
MCP ServerDesenvolvimento WebAvançado
WZBbiao

Viewglass MCP

WZBbiao/viewglass-mcp

Inspeção e automação de UI iOS para agentes Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe 15 ferramentas para inspeção e automação de UI iOS em tempo real. Permite que agentes de IA capturem snapshots, toquem elementos, façam scroll, digitalizem texto e validem estados de interface sem recompilação.

Instalação

$npx convez-ai WZBbiao/viewglass-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Testes automatizados de fluxos iOS
  • Validação visual de designs em dispositivos reais
  • Automação de interações complexas em aplicativos iOS
  • Debugging de interface através de agent AI

Veredito

Ferramenta especializada e bem-estruturada para automação de UI iOS com integração nativa em MCP. Requer conhecimento de iOS/Xcode, mas oferece leverage altíssimo para quem trabalha com desenvolvimento mobile.

README

A tradução para o português deste README ainda está na fila.

viewglass-mcp

MCP Server for Viewglass iOS UI inspection. Exposes 15 tools for AI agents — bundles the viewglass CLI binary, no separate install required.

Install the Viewglass skill

Like xcodebuildmcp, ViewglassMCP works best when its skill is installed into the AI client skill directory and the project AGENTS.md is updated.

When ViewglassMCP starts normally, it now bootstraps itself automatically like xcodebuildmcp:

  • installs the ViewglassMCP skill into detected client skill directories (for example .claude/skills and .agents/skills)
  • appends the Viewglass guidance line to the project AGENTS.md
  • creates .viewglassmcp/config.yaml, .viewglassmcp/README.md, and .viewglassmcp/recipes.yaml in the project root

viewglass-mcp init --force still exists as an explicit repair/bootstrap command, but it should not be required for the normal MCP path.

Tools

ToolDescription
ui_snapshotCapture an agent-first UI snapshot with summary, navigation candidates, budgeted searchable nodes, matched recipes, and optional rawTree.
ui_attr_getGet runtime attributes of a node by OID.
ui_tapTap a node by exact oid from ui_snapshot. Supports UIControl, gesture-backed views, UITableViewCell, and UICollectionViewCell.
ui_scrollScroll by exact oid; resolves wrapper/cell targets to a real scroll view and performs a swipe-style scroll.
ui_set_attrSet an attribute on a node at runtime (live, no recompile).
ui_invokeCall any ObjC selector on any node — the highest-leverage tool.
ui_waitPoll until a node appears, disappears, or an attribute matches.
ui_assertAssert visibility, text, count, or attribute — fails as MCP error.
ui_connectResolve and pin the active session to a specific app bundle id.
ui_screenshotCapture a PNG of the full screen or a specific node.
ui_inputType text into a UITextField / UITextView by exact oid from ui_snapshot and return an execution summary.
ui_swipeSwipe a node in a direction.
ui_long_pressLong-press a node.
ui_dismissDismiss a presented view controller by exact oid from ui_snapshot and return an execution summary.
compare_with_designScreenshot device + return Figma URL for Vision diff.

Recommended agent workflow

For page navigation, settings flows, tab switching, and custom UI:

  1. Start with ui_snapshot
    • Default output is a small action index: visible labels, groups, navigation candidates, and likely action targets.
    • For textless settings/profile icons, inspect summary.navigationCandidates and areaHint such as topRight.
    • Use ui_screenshot for visual layout and ui_attr_get for long text or detailed attributes after you know the oid.
    • Use mode=fullIndex only when the default action index is insufficient.
    • Treat it as the source of truth for "where am I right now?".
  2. Then use execution tools with exact oid
    • Extract the exact target oid from ui_snapshot.groups or ui_snapshot.nodes.
    • ui_tap, ui_scroll, ui_input, and ui_dismiss all require oid.
    • Prefer user-visible labels in the snapshot over UIKit private class guesses.
  3. Use ui_wait or another ui_snapshot to verify transitions
    • Do not assume a tap has finished a navigation animation unless you verify it.
  4. Use ui_attr_get only after the correct node is known
    • This is for reading precise runtime values such as text color or font.

Avoid this pattern:

  • guessing UITabBar, UITabBarButton, UIButton, or private UIKit classes first
  • passing guessed labels to ui_tap instead of first locating an exact oid in ui_snapshot
  • trying to infer the current page from repeated locator guesses instead of starting with ui_snapshot
  • taking a screenshot before checking the structured snapshot, unless the task is explicitly visual

Project-local experience memory

For repeated flows, keep project-local experience under:

  • .viewglassmcp/README.md
  • .viewglassmcp/recipes.yaml
  • .viewglassmcp/config.yaml

These files are maintained by the agent after successful live runs. Use config.yaml for stable project defaults like the app bundle identifier. Use recipes.yaml for reusable target-finding recipes, not fragile runtime oid values.

Recommended config / recipe signals:

  • controllerHints
  • groupRole
  • searchableTextAny
  • accessibilityIdAny
  • classHints
  • areaHint
  • success

Templates are included in this package under:

The bundled recipes.yaml is intentionally empty and generic. Agents should only write project-specific recipes after successful live runs in the current project.

  • templates/.viewglassmcp/README.md
  • templates/.viewglassmcp/recipes.yaml

Agent-first rule:

  • the agent should create .viewglassmcp/ automatically inside the current project when a task is likely to repeat
  • after a reusable live task succeeds, the agent must update .viewglassmcp/recipes.yaml in the same session before finishing the task
  • on later runs, the agent should consult .viewglassmcp/recipes.yaml before fallback exploration

Requirements

  • iOS app with ViewglassServer running (simulator or device).
  • No other dependencies — the viewglass CLI binary is bundled in this package.

Usage

Claude Desktop / any MCP client

If you installed the package globally, viewglass-mcp starts the MCP server by default and also supports viewglass-mcp init.

{
  "mcpServers": {
    "viewglass": {
      "command": "npx",
      "args": ["-y", "viewglass-mcp"]
    }
  }
}

Or install globally for faster startup:

npm install -g viewglass-mcp
{
  "mcpServers": {
    "viewglass": {
      "command": "viewglass-mcp"
    }
  }
}

Session

All tools accept an optional session in bundleId@port format (e.g. com.example.App@47164). If omitted, ViewglassMCP first checks .viewglassmcp/config.yaml for sessionDefaults.bundleId and prefers the matching running app. If no config match exists, it falls back to the first detected running app. The agent should usually rely on this automatic resolution instead of trying to scan for sessions manually.

Override binary

Set VIEWGLASS_BIN to use a specific binary (development / CI):

VIEWGLASS_BIN=/path/to/viewglass npx viewglass-mcp

Debug logging

All logs go to stderr by default so they do not corrupt the MCP stdout protocol stream.

VIEWGLASS_MCP_LOG=1 npx viewglass-mcp

Optional flags:

  • VIEWGLASS_MCP_LOG_TOOL=1: log each tool call start/end summary
  • VIEWGLASS_MCP_LOG_CLI=1: log each internal viewglass CLI command, duration, and exit status
  • VIEWGLASS_MCP_LOG_FILE=/tmp/viewglass-mcp.log: write logs to a file instead of stderr
  • VIEWGLASS_MCP_LOG_SPLIT_BY_SESSION=1: when VIEWGLASS_MCP_LOG_FILE is set, write one file per session

Export the latest contiguous run from a session log into a replay-oriented flow draft:

npm run export:flow -- /tmp/viewglass-mcp.log.com.example.app@47175.log

Optional flags:

  • -- --all-runs: export every detected run in the log file
  • -- --include-screenshots: keep screenshot steps in the draft
  • -- --gap-ms 120000: change the run split threshold

Initialize project-local experience memory in a target project: There is no required bootstrap command. The agent should create and maintain .viewglassmcp/ automatically.

When session logging is enabled, each line includes session=<bundleId@port> when the tool/CLI call has one.
With file splitting enabled, examples look like:

  • /tmp/viewglass-mcp.log.com.example.app@47175.log
  • /tmp/viewglass-mcp.log.com.example.app@47164.log

Development

npm install
npm run build          # compile TypeScript
npm test               # unit tests (Vitest)

E2E tests

  1. Start your iOS simulator with ViewglassServer enabled.
  2. Update SESSION in src/__tests__/e2e.ts.
  3. Run:
VIEWGLASS_BIN=/path/to/viewglass npm run test:e2e

Architecture

src/
  runner.ts          # CLI runner, binary resolution, injectable ExecFn
  index.ts           # MCP Server — registers all 16 tools
  tools/
    ui_snapshot.ts                    ui_attr_get.ts
    ui_tap.ts        ui_scroll.ts     ui_set_attr.ts
    ui_invoke.ts     ui_wait.ts       ui_assert.ts
    ui_scan.ts       ui_screenshot.ts ui_input.ts
    ui_swipe.ts      ui_long_press.ts ui_dismiss.ts
    compare_with_design.ts
  __tests__/
    *.test.ts        # unit tests (mock ExecFn injection)
    e2e.ts           # e2e tests against live simulator

bin/                 # bundled viewglass CLI binaries (not in git, in npm)
  viewglass-darwin-arm64
  viewglass-darwin-x64
.viewglass-cli-version   # pins the CLI version bundled in this release

Binary resolution order: VIEWGLASS_BIN env → viewglass in $PATH → bin/ bundled binary.

Ver o original no GitHub

Bom para

Relacionados