perceptdot/percept

AI Visual QA. visual_check(url) screenshots a page with Cloudflare Browser Rendering and finds layout bugs with Gemini 2.5 Flash. Use it from any MCP client (Claude Code, Cursor, Windsurf, Cline) or as a GitHub Action.

License: MIT perceptdot.com

A typical page takes about 7 seconds, long pages up to ~20 seconds. Fully headless: no desktop or GUI needed.

---

Quick start

1. Get a free API key at perceptdot.com (100 credits per month, no card).
2. Add the remote MCP server. The key goes in the X-Percept-Key header.

Claude Code

claude mcp add --transport http perceptdot https://mcp.perceptdot.com/mcp --header "X-Percept-Key: YOUR_KEY"

Cursor (~/.cursor/mcp.json)

{"mcpServers":{"perceptdot":{"url":"https://mcp.perceptdot.com/mcp","headers":{"X-Percept-Key":"YOUR_KEY"}}}}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{"mcpServers":{"perceptdot":{"serverUrl":"https://mcp.perceptdot.com/mcp","headers":{"X-Percept-Key":"YOUR_KEY"}}}}

Then ask your AI: "Check https://your-site.com with perceptdot".

---

GitHub Action

The action lives in the eye-action/ folder of this repo.

name: Visual QA
on: [pull_request]

jobs:
  visual-check:
    runs-on: ubuntu-latest
    steps:
      - uses: perceptdot/percept/[email protected]
        with:
          url: ${{ steps.deploy.outputs.preview_url }}
          api_key: ${{ secrets.PERCEPT_API_KEY }}
          # fail_on_issue: true   # optional

Inputs: url (required), api_key (required), fail_on_issue (optional).

---

What it checks

• DOM audit (deterministic): viewport overflow, broken images, parent overflow, low contrast.
• AI review: each tile of the page is reviewed by Gemini 2.5 Flash for layout problems, with severity (high / medium / low).

Desktop (1280px), tablet (768px) and mobile (375px) viewports are supported.

---

Pricing

1 credit = 1 tile = a 1280×1600 px slice of the page. A short page is about 1 credit, a long landing page about 3–5 credits.

Plan	Price	Credits / month	Status
Free	$0	100 (+100 one-time bonus after submitting feedback; resets on the 1st, UTC)	Available
Pro	$19/month	10,000	Coming Soon
Team	$49/month	30,000 (fair use)	Coming Soon

Payments are handled by Paddle.

---

Privacy

Screenshots are not stored. They are sent to Google (Gemini API) and Cloudflare (Workers AI, fallback) for analysis. Analysis results (summary and issues, never screenshots) are cached for up to 10 minutes per URL and viewport. Google may use data sent to unpaid Gemini API tiers to improve its products, so do not check pages that contain personal data.

---

API

• OpenAPI spec: perceptdot.com/openapi.json
• Docs: https://perceptdot.gitbook.io/perceptdot
• Endpoints: POST /v1/eye/check, GET /v1/quota, POST /v1/free-key at https://api.perceptdot.com

curl -X POST https://api.perceptdot.com/v1/eye/check \
  -H "Content-Type: application/json" \
  -H "X-Percept-Key: YOUR_KEY" \
  -d '{"url":"https://example.com"}'

---

Legacy packages

@perceptdot/ga4, @perceptdot/vercel, @perceptdot/github, @perceptdot/sentry and @perceptdot/core belong to an earlier product and are no longer maintained.

---

License

MIT. See LICENSE.