DevLab Suite

Modular testing and automation MCP servers for Android devices, desktop browsers, canvas games, and visual regression.

DevLab MCP Suite
├── @tanguito/android-dev-mcp        ← Android device automation (ADB)
├── @tanguito/browser-dev-mcp        ← Desktop browser automation (Playwright)
├── @tanguito/visual-regression-mcp  ← Visual regression & pixel diff
└── @tanguito/devlab-shared          ← Shared contracts and helpers

The Testing Triangle

             ┌──────────────────────┐
             │   visual-regression   │  ← pixel-perfect diffs
             │   screenshot compare  │
             └──────────┬───────────┘
                        │
         ┌──────────────┴──────────────┐
         │                             │
  ┌──────┴──────┐              ┌───────┴──────┐
  │  android     │              │   browser     │
  │  device tests│              │   canvas/web  │
  └──────────────┘              └──────────────┘

browser-dev-mcp screenshot  →  visual-regression-mcp diff  →  markdown report

Three independent testing layers, same tool patterns, same evidence system, single monorepo.

5-Minute Quick Start

# 1. Clone and install
git clone https://github.com/Tanguito86/devlab-mcp.git
cd devlab-mcp
pnpm install

# 2. Environment check + auto-fix
pnpm setup

# 3. Build and test
pnpm build
pnpm test          # 67 tests: 42 android + 8 browser + 8 visual + 9 shared

# 4. Your first browser workflow
node examples/browser-hello-world/run-hello-world.js

You just ran a 5-step browser workflow: open → screenshot → console → errors → report. Takes ~5 seconds.

Package Table

Package	Purpose	Version	Tests	npm	Status
@tanguito/devlab-shared	Types, schemas, helpers	0.1.0	9	@tanguito/devlab-shared	Pending publish
@tanguito/android-dev-mcp	Device automation (ADB)	1.2.0	42	@tanguito/android-dev-mcp	✅ Published
@tanguito/browser-dev-mcp	Browser/canvas (Playwright)	1.0.0	8	@tanguito/browser-dev-mcp	Pending publish
@tanguito/visual-regression-mcp	Screenshot diffing	0.1.0	8	@tanguito/visual-regression-mcp	Pending publish

Total: 67 tests | 70 tools | 4 packages

Publishing: android-dev-mcp is already on npm. shared, browser, and visual-regression are ready. See publishing guide for exact commands.

Case Study: Galaxy Raiders

We validated browser-dev-mcp and visual-regression-mcp against a real 68-script HTML5 Canvas shmup with 5 bosses across 20 levels.

Browser Testing

Metric	Result
Workflows executed	4 (smoke, boss ladder, performance, console audit)
Total steps	81/81 (100%)
Page errors	0 across all workflows
Bosses validated	5/5 (Crabtron, Serpentrix, Colossus, Lieutenant, Emperor)
Screenshots	13 real rendered canvas captures
Leak test	3/3 consecutive cycles clean

Visual Regression

boss-lv5:   81 kB, 360×640, 0 changed pixels, ✅ PASS
boss-lv20:  90 kB, 360×640, 0 changed pixels, ✅ PASS

Pipeline: browser-dev-mcp captures canvas screenshots → visual-regression-mcp diffs against baselines → markdown report with pass/fail.

Read the full case study →

Packages

browser-dev-mcp

Desktop browser automation via Playwright. 24 tools for navigation, screenshots, canvas game testing, JavaScript evaluation, keyboard/mouse input, and evidence capture.

pnpm --filter @tanguito/browser-dev-mcp build
pnpm --filter @tanguito/browser-dev-mcp test
pnpm --filter @tanguito/browser-dev-mcp run doctor

Key tools: browser_open_url, browser_screenshot, browser_screenshot_canvas, browser_click, browser_click_percent, browser_press_key, browser_type_text, browser_evaluate_js, browser_evaluate_game_state, browser_wait_for_canvas_change, browser_get_console_logs, browser_get_page_errors, and 12 more.

Full README →

visual-regression-mcp

Visual regression testing — pixel comparison, diff generation, markdown reporting. 4 tools: visual_compare_images, visual_create_baseline, visual_compare_folder, visual_generate_report. Zero native dependencies — pure Node.js PNG parsing with zlib.

pnpm --filter @tanguito/visual-regression-mcp build
pnpm --filter @tanguito/visual-regression-mcp test
pnpm --filter @tanguito/visual-regression-mcp run doctor

Full README →

android-dev-mcp

Android device automation via ADB. 42 tools for device inspection, app management, UI interaction, screenshots, logcat, and workflow execution.

pnpm --filter @tanguito/android-dev-mcp build
pnpm --filter @tanguito/android-dev-mcp test

Full README →

devlab-shared

Minimal shared contracts: textResponse, sanitizeName, validateSessionId, RegisterTool, WorkflowStep, StepResult, and base evidence types. Zero IO, zero runtime dependencies. 9 tests, full doctor check. 107 lines.

pnpm --filter @tanguito/devlab-shared build
pnpm --filter @tanguito/devlab-shared test
pnpm --filter @tanguito/devlab-shared run doctor

Full README →

Examples

Example	Time	What it does
browser-hello-world	~5s	Opens test page, takes screenshot, collects console/errors
galaxy-raiders	~15s	Loads Galaxy Raiders, starts game, captures canvas, jumps to boss
galaxy-visual-regression	~2s	Pixel-diff Galaxy Raiders boss screenshots against baselines

# Hello World
node examples/browser-hello-world/run-hello-world.js

# Galaxy Raiders (requires game running on localhost:5173)
node examples/galaxy-raiders/run-galaxy-smoke.js

Scripts

Command	Description
pnpm setup	Detect environment, auto-install Chromium, suggest fixes
pnpm build	Build all packages
pnpm test	Run all 67 tests
pnpm doctor	Health checks per package (use pnpm --filter <pkg> run doctor)
pnpm typecheck	TypeScript type checking
pnpm clean	Remove dist/ from all packages
pnpm pack:dry-run	Preview npm package contents
pnpm changeset	Create a version changeset
pnpm changeset:version	Bump versions from changesets
pnpm changeset:publish	Publish changed packages to npm

Troubleshooting

"Browser not open" on WSL

WSL's headless Chromium shell is missing shared libraries. browser-dev-mcp automatically uses the full Chromium binary if PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH is set.

# Find your Chromium binary
ls ~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome

# Set the env var
export PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/home/user/.cache/ms-playwright/chromium-1223/chrome-linux64/chrome

Run pnpm setup — it detects WSL and suggests the fix automatically.

Playwright not found

pnpm setup       # Auto-detects and suggests fixes
npx playwright install chromium   # Manual install

ADB not found (android-dev-mcp only)

ADB is optional — only needed for @tanguito/android-dev-mcp.

# Install Android SDK Platform Tools
# https://developer.android.com/tools/releases/platform-tools

Repository Structure

devlab-mcp/
  pnpm-workspace.yaml
  package.json              # Root scripts + pnpm setup
  .changeset/               # Changesets configuration
  .github/workflows/ci.yml  # CI matrix (Node 20/22)
  scripts/
    devlab-setup.js         # Environment detector + auto-fixer
  packages/
    shared/                    # @tanguito/devlab-shared (107 lines)
    android-dev-mcp/           # @tanguito/android-dev-mcp (42 tools)
    browser-dev-mcp/           # @tanguito/browser-dev-mcp (24 tools)
    visual-regression-mcp/     # @tanguito/visual-regression-mcp (4 tools)
  examples/
    browser-hello-world/       # 5-step first workflow
    galaxy-raiders/            # Real canvas game smoke test
    galaxy-visual-regression/  # Pixel-diff boss screenshots
  docs/
    devlab-suite-v1-freeze.md      # v1 freeze document
    architecture.md                # Suite architecture decisions
    case-study-galaxy-raiders.md   # Full Galaxy Raiders validation
    publishing.md                  # How to version and publish

Architecture

• Monorepo with pnpm workspaces — shared iteration, single CI
• Independent packages — each installable, runnable, testable in isolation
• Shared is minimal — 107 lines of pure contracts, zero runtime coupling
• Changesets for independent versioning within the monorepo
• Workflow-first — declarative JSON test plans executed by MCP servers

Full architecture → Freeze document →

License

MIT — see individual package LICENSE files.