AFO Visual Browser Sub-Agent MCP

Cloudflare-native visual evidence and browser-investigation service. The current release is deliberately public, read-only, deterministic, and receipt-first.

Phase 1 tools

• visual_browser_status
• capture_screenshot
• capture_snapshot
• capture_multi_viewport
• enqueue_visual_audit
• get_visual_receipt
• get_visual_artifact
• create_visual_artifact_url

Capture reliability behavior

capture_screenshot is a true screenshot-only path. It captures and stores the PNG plus a minimal manifest, navigation timing, page metadata, and cheap console/network counts. It does not call page.content(), generate Markdown, request an accessibility snapshot, serialize full console/network artifacts, or create embeddings.

capture_snapshot and capture_multi_viewport retain the richer evidence pipeline. Text artifacts are limited by encoded UTF-8 byte size, and optional artifact truncation or failure is recorded in artifact_summary and warnings without invalidating a successfully stored screenshot. Successful runs with optional evidence warnings report status: "ok_with_warnings".

Artifact access behavior

get_visual_artifact retrieves only artifacts registered in a persisted run manifest. Callers provide run_id or investigation_id, an artifact_type, and optional viewport and response_mode. Arbitrary object_key, key, and r2_key inputs are rejected.

Small PNGs can be returned as native MCP image content with base64 data and MIME type. Text and JSON evidence is returned inline only below conservative limits. Oversized artifacts return metadata, byte size, SHA-256, and requires_url: true. Sensitive URL query values are redacted before text evidence is returned.

create_visual_artifact_url creates a manifest-bound HMAC-SHA-256 URL with a 10-minute default TTL and a 60-minute maximum. The signed claim covers run ID, artifact type, viewport, and expiry. The private route streams only the R2 object registered by the persisted manifest, returns Cache-Control: private, no-store, and fails closed with HTTP 403 for expiry, tampering, traversal, substitutions, unknown runs, or absent artifacts.

Required initial bindings

• Browser Rendering: BROWSER
• Workers AI: AI
• D1: DB
• R2: RECEIPTS
• Vectorize: VECTORIZE
• Queues: AUDIT_QUEUE
• Analytics Engine: ANALYTICS
• Worker secret: ARTIFACT_SIGNING_SECRET (minimum 32 characters; never commit its value)

Vectorize, Queues, and Analytics Engine are foundational requirements, not optional roadmap items.

Security boundary

The Worker accepts public https: URLs only. Localhost, private IPv4 ranges, link-local ranges, and private IPv6 ranges are blocked. Query parameters that look like credentials are redacted from receipts.

Before deployment

1. Create the D1 database, R2 bucket, Vectorize index, producer/consumer queue, dead-letter queue, and Analytics Engine dataset.
2. Confirm the D1 database ID and all binding names in wrangler.jsonc.
3. Add CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and ARTIFACT_SIGNING_SECRET to GitHub Actions or the local environment.
4. Install ARTIFACT_SIGNING_SECRET with wrangler secret put ARTIFACT_SIGNING_SECRET; never place it in wrangler.jsonc, logs, receipts, D1, or analytics.
5. Apply D1 migrations.
6. Run npm install, npm run check, and npm test.
7. Deploy and verify /status, /tools, MCP initialization, direct artifact retrieval, signed URL retrieval, strict headers, expiry rejection, and component-tampering rejection against persisted Link Lane evidence.

See ROADMAP.md for the complete build order.