QuokkaPix MCP Runner

Local-first MCP adapter and cloud-to-local execution bridge for private QuokkaPix image workflows.

QuokkaPix MCP Runner lets AI agents process local image files with QuokkaPix by opening the QuokkaPix web app in a local browser, applying an official recipe or direct settings payload, uploading files through the browser file input, downloading the result, and writing a machine-readable `quokkapix-result.json`.

It supports two compatible modes:

• local `stdio` for Claude Desktop, Cursor, LM Studio/Ollama wrappers and other local MCP clients;
• `bridge` for remote MCP clients such as Claude web, while Chromium and image processing remain on the user's computer.

Repository:

npm package:

Glama listing:

mcpservers.org listing:

Browser compatibility matrix:

Browser benchmark:

Quick start:

npx quokkapix-mcp

Cloud-to-local bridge:

npx quokkapix-mcp bridge --input-root ./images --output-root ./quokkapix-output

What This Is

This package is a local automation adapter around the browser app at:

https://quokkapix.com/#agent=1

The adapter uses Playwright to drive a local Chromium browser. The browser runs the same QuokkaPix editor that humans use, including the in-browser `window.QuokkaPixAgent` API.

Image files are processed in the user's browser runtime. During normal processing, source image bytes are not uploaded to a QuokkaPix image-processing server.

The optional bridge mode connects outward to the QuokkaPix control plane. The remote MCP endpoint relays tool settings, relative file names, status and result metadata. It does not expose an image upload endpoint and does not relay source or output image bytes.

What This Is Not

This package is not:

• a public server-side image processing API;
• a hosted image-processing service (the remote MCP control plane only coordinates a paired local bridge);
• a GPU/CPU image-processing backend run by QuokkaPix;
• a way to pass local file paths to `quokkapix.com` by URL;
• a replacement for browser memory limits.

Local file paths are available only to the local MCP runner on the user's machine. The public QuokkaPix website still receives files only through the browser file input or dropzone.

Why Use It

Use this adapter when an AI agent needs to run repeatable image workflows like:

• prepare product photos for Shopify, Amazon, or Google Merchant;
• validate marketplace and social image outputs against sourced rule profiles;
• compress images to WebP for a website;
• remove EXIF/GPS metadata;
• generate social media image packs;
• watermark a batch of images;
• generate favicon and app icon packs;
• run custom QuokkaPix settings without manually clicking the UI.

The main value is privacy and low infrastructure cost: the agent gets a practical image workflow tool, while image processing remains local in the user's browser.

Architecture

AI agent / MCP client
        |
        | stdio MCP
        v
quokkapix-mcp
        |
        | Playwright
        v
local Chromium browser
        |
        | window.QuokkaPixAgent + stable data-agent selectors
        v
https://quokkapix.com/#agent=1
        |
        | local browser processing
        v
downloaded output + quokkapix-result.json

Remote clients use the same package in bridge mode:

Claude web / remote MCP client
        |
        | OAuth 2.1 + Streamable HTTP (commands and metadata only)
        v
QuokkaPix control plane
        |
        | outbound authenticated long poll
        v
quokkapix-mcp bridge on the user's computer
        |
        | Playwright
        v
local Chromium -> local output + quokkapix-result.json

The adapter saves:

• the generated image, ZIP, or PDF output;
• `quokkapix-result.json`;
• a `qa` object returned to the agent.

Requirements

• Node.js `>=20`
• npm
• Playwright Chromium
• internet access for loading QuokkaPix and browser-side dependencies/models when needed
• local file paths that the MCP process can read

Bridge mode additionally requires explicit input and output roots. Remote calls cannot read or write outside those roots.

Install dependencies:

npm install
npx playwright install chromium

Remote MCP And Bridge Setup

1. Start the existing package in bridge mode:

npx -y quokkapix-mcp bridge \
  --input-root /absolute/path/to/input \
  --output-root /absolute/path/to/output

2. Approve the one-time pairing URL printed by the command.

3. Add `https://quokkapix.com/mcp` as a custom remote MCP connector.

4. Complete OAuth authorization in the browser.

The bridge stores its random device credential in `~/.quokkapix/bridge.json` with owner-only permissions where the operating system supports them. Use `--pair` to approve another browser session or `--reset` to revoke the old device authorization and create a new credential.

Remote processing paths are relative to `--input-root` and `--output-root`. The bridge rejects path traversal and does not return absolute local paths to the cloud client.

MCP Tools

`list_recipes`

Lists official QuokkaPix recipes.

Use first when the agent does not know which workflow to run.

`get_recipe`

Returns one recipe by id, including:

• `applySettings`;
• file limits;
• expected output;
• QA contract;
• payment requirement.

Input:

{
  "id": "shopify_product_pack"
}

`validate_recipe`

Validates a custom recipe object before processing.

This does not upload files and does not start processing.

`list_rule_profiles`

Lists sourced marketplace and social image rule profiles.

Use this when an agent needs facts for Amazon, Shopify, Google Merchant, Etsy, eBay, Walmart, TikTok Shop, Mercado Libre, Temu, Shopee, Instagram, YouTube, LinkedIn, X, Pinterest, Facebook or TikTok before choosing a workflow or checking an output.

Every profile declares:

• `sourceType`: `official` or `secondary`;
• `sourceUrl`;
• `confidence`;
• requirements and recommendations that were found from the named source.

The runner does not invent missing marketplace requirements. Temu, Mercado Libre, Shopee and some YouTube entries are marked as secondary or category/country-specific where official public specs were limited.

`get_rule_profile`

Returns one rule profile by id, for example:

{
  "id": "amazon.product.image"
}

Agents can pass the returned facts into their own planning, or call `validate_result_manifest` with `ruleProfileId`.

`validate_result_manifest`

Validates an existing `quokkapix-result.json` against a recipe or custom QA contract.

This is useful when an agent wants to inspect a previous run and decide whether the output is acceptable.

Optional input:

{
  "ruleProfileId": "amazon.product.image",
  "manifest": {}
}

When `ruleProfileId` is provided, the QA report includes sourced marketplace checks such as supported formats, dimensions, source type and URL. If the browser result manifest includes `outputs[].pixelQa`, the validator also evaluates supported pixel-level visual checks such as white background, subject centering, safe margins and transparent background.

`process_images`

Processes local image files through QuokkaPix using either:

• an official `recipeId`;
• a full custom recipe object.

It opens a browser, applies the recipe, uploads files, starts processing, downloads the output, writes `quokkapix-result.json`, and returns QA results.

Optional local asset files:

• `watermarkLogoFile`: local logo/image file uploaded into QuokkaPix's watermark logo input.
• `backgroundImageFile`: local image file uploaded into QuokkaPix's background replacement image input.

These assets are still uploaded only into the local browser page. They are not passed as URL paths to the public QuokkaPix website.

`process_with_settings`

Processes local image files using a direct QuokkaPix `applySettings` payload.

Use this when the agent already knows the exact editor settings and does not want to wrap them in a recipe.

This is the broadest tool surface. It can drive the same settings surface as:

window.QuokkaPixAgent.applySettings(payload)

Supported editor areas depend on the QuokkaPix browser contract and include:

• resize;
• crop;
• rotate;
• convert;
• compress;
• advanced export to browser-supported formats and experimental JPEG XL when the browser-loaded encoder is available;
• metadata removal/reporting;
• PDF merge/split/extract tools through `tool=pdf` and `pdf.operation` for uploaded PDF files only; ZIP archives are accepted only for PDF merge and only PDF entries are extracted;
• background removal/replacement settings;
• watermark;
• effects;
• rename;
• constructor/scenario workflows.

For custom scenarios, prefer the explicit structured form:

{
  "mode": "batch",
  "tool": "constructor",
  "steps": [
    {
      "tool": "resize",
      "settings": { "mode": "fit", "width": 1200, "height": 1200 }
    },
    {
      "tool": "watermark",
      "settings": { "type": "text", "text": "Brand", "layout": "tiled", "angle": -20 }
    },
    {
      "tool": "compress",
      "settings": { "format": "webp", "quality": 0.82 }
    }
  ]
}

Step `settings` use the same section keys as `window.QuokkaPixAgent.applySettings`.

PDF tools use PDF uploads instead of image uploads:

{
  "tool": "pdf",
  "pdf": {
    "operation": "extract",
    "extractPages": "1,3-5",
    "extractOutput": "pdf"
  }
}

Use `operation: "split"` to export one uploaded PDF as a ZIP of one-page PDFs. Use `operation: "extract"` with `extractPages` to create one PDF containing only the selected pages from one uploaded PDF; page order is preserved, so `extractPages: "3,1"` exports page 3 before page 1. Set `extractOutput: "zip"` when the selected pages should be returned as separate one-page PDFs inside a ZIP. `tool: "pdf"` defaults to split. Split and extract are single-PDF workflows because page numbers refer to one source PDF. Use `operation: "merge"` to combine multiple PDFs into one PDF in the current browser file order; merge is a batch workflow and switches the browser editor to batch mode. Human users can reorder merge files in the UI; MCP clients should pass files in the desired merge order.

ZIP upload is batch-only. If a user or agent selects a `.zip` in batch mode, QuokkaPix unpacks it locally in the browser and adds supported images from the archive to the batch queue. RAR and 7z are not accepted.

`get_payment_options`

Fetches QuokkaPix agent payment policy and x402 endpoints.

This does not perform a payment.

`explain_payment_flow`

Explains the current x402 payment flow for agents.

Important: this local MCP adapter does not sign x402 payments by itself. An x402-capable client or wallet must call the paid unlock endpoint and return an `unlockToken`.

`verify_unlock_token`

Verifies a paid agent unlock token before processing.

Use `consume: false` for preflight checks.

Only use `consume: true` if you intentionally want to consume the unlock immediately.

Remote-only bridge tools

The hosted remote MCP endpoint also exposes:

• `get_bridge_status` to check pairing and local availability;
• `get_billing_status` to check whether a verified one-time unlock is staged;
• `set_unlock_token` to stage an x402 unlock for the next paid local batch.

Remote `verify_unlock_token` is preflight-only and never consumes the token. Actual consumption remains inside the local browser start path.

Official Recipes

The runner loads recipes from the local project if present. If local recipe files are absent, it falls back to:

https://quokkapix.com/agent-recipes/

Current official recipes:

Agents should usually call `list_recipes`, choose the closest recipe, then call `process_images`.

Use `process_with_settings` when the desired workflow is not covered by a recipe.

Install From Source

From the `mcp-runner` folder:

npm install
npx playwright install chromium
npm run check

Start the MCP server:

npx quokkapix-mcp

Direct CLI run without an MCP client:

npx quokkapix-runner --recipe website_webp_compress --input ./photo.jpg --output ./out

MCP Client Configuration

For most users, configure the published npm package directly:

{
  "mcpServers": {
    "quokkapix": {
      "command": "npx",
      "args": ["-y", "quokkapix-mcp"],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Use absolute paths for `cwd`.

Claude Desktop From Source

If you cloned the GitHub repository instead of using npm, add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "quokkapix": {
      "command": "node",
      "args": ["src/server.mjs"],
      "cwd": "/absolute/path/to/quokkapix-mcp",
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Cursor From Source

If you cloned the GitHub repository instead of using npm, use the same server definition in Cursor MCP settings:

{
  "mcpServers": {
    "quokkapix": {
      "command": "node",
      "args": ["src/server.mjs"],
      "cwd": "/absolute/path/to/quokkapix-mcp",
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Local Development

Run QuokkaPix locally and point the runner to it:

QUOKKAPIX_APP_URL=http://127.0.0.1:4177/#agent=1 npx quokkapix-mcp

Override the local site root:

QUOKKAPIX_SITE_ROOT=/path/to/quokkapix-site npx quokkapix-mcp

Override the public recipe source:

QUOKKAPIX_RECIPE_BASE_URL=https://quokkapix.com/agent-recipes npx quokkapix-mcp

Override payment base URL:

QUOKKAPIX_PAYMENT_BASE_URL=https://quokkapix.com npx quokkapix-mcp

`appUrl` is intentionally restricted for local-file safety. By default the runner only opens:

• `https://quokkapix.com/` and `https://www.quokkapix.com/`;
• `http://127.0.0.1`, `http://localhost` and local HTTPS equivalents.

This prevents a malicious prompt or recipe from pointing the browser runner at an unrelated page and uploading local files there. For trusted development only, custom app URLs can be enabled with:

QUOKKAPIX_ALLOW_CUSTOM_APP_URL=1 npx quokkapix-mcp

Example: Process Product Photos For Shopify

Tool: `process_images`

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-1.jpg",
    "/Users/me/products/photo-2.jpg"
  ],
  "outputDir": "/Users/me/products/out",
  "headless": true
}

Expected output:

• a ZIP file in `outputDir`;
• `quokkapix-result.json`;
• a returned `qa` report.

The tool result separates processing success from QA success:

• `processingOk: true` means QuokkaPix completed and produced an output file;
• `qaOk: true` means the output passed the recipe QA checks;
• top-level `ok` follows `qaOk`, so agents should not treat a failed QA run as fully successful.

Example: Direct Custom Settings

Tool: `process_with_settings`

{
  "settings": {
    "mode": "single",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82,
        "targetEnabled": false
      }
    }
  },
  "settingsId": "custom-webp-compress",
  "expectedResultQa": {
    "profile": "custom-webp-compress",
    "expectedFormat": "webp"
  },
  "inputFiles": ["/Users/me/images/photo.jpg"],
  "outputDir": "/Users/me/images/out"
}

Use this for custom workflows that are not official recipes.

Example: Logo Watermark Asset

Tool: `process_with_settings`

{
  "settings": {
    "mode": "single",
    "tool": "watermark",
    "settings": {
      "watermark": {
        "type": "image",
        "layout": "single",
        "position": "center",
        "scalePercent": 20,
        "opacity": 0.25
      }
    }
  },
  "watermarkLogoFile": "/Users/me/brand/logo.svg",
  "inputFiles": ["/Users/me/images/photo.jpg"],
  "outputDir": "/Users/me/images/out"
}

Example: Background Image Asset

Tool: `process_with_settings`

{
  "settings": {
    "mode": "batch",
    "tool": "constructor",
    "steps": [
      {
        "tool": "background",
        "settings": {
          "mode": "replace",
          "replaceMode": "chroma",
          "fill": "image",
          "sourceColor": "#ffffff",
          "tolerance": 36,
          "exportFormat": "webp"
        }
      },
      {
        "tool": "compress",
        "settings": { "format": "webp", "quality": 0.82 }
      }
    ]
  },
  "backgroundImageFile": "/Users/me/backgrounds/studio.webp",
  "inputFiles": ["/Users/me/products/photo-1.jpg", "/Users/me/products/photo-2.jpg"],
  "outputDir": "/Users/me/products/out"
}

This two-file batch is inside the free small-batch limit. Add an `unlockToken` only for larger paid agent batch/scenario runs.

Example: Metadata Cleanup

Tool: `process_images`

{
  "recipeId": "metadata_clean_batch",
  "inputFiles": [
    "/Users/me/private/photo-1.jpg",
    "/Users/me/private/photo-2.jpg"
  ],
  "outputDir": "/Users/me/private/clean"
}

For batch runs, see the payment section below.

Example: QA-Only Validation

Tool: `validate_result_manifest`

{
  "recipeId": "shopify_product_pack",
  "manifest": {
    "status": "done",
    "source": {
      "count": 1,
      "totalBytes": 1000
    },
    "outputs": [
      {
        "sourceName": "photo.jpg",
        "outputName": "shopify_1.webp",
        "outputWidth": 2048,
        "outputHeight": 2048,
        "format": "webp",
        "sizeBytes": 250000,
        "warnings": []
      }
    ],
    "warnings": []
  }
}

The result contains:

{
  "ok": true,
  "profile": "shopify-product",
  "summary": {
    "checks": 8,
    "failures": 0,
    "warnings": 0,
    "outputs": 1
  },
  "checks": []
}

Result Manifest

After processing, the runner writes:

quokkapix-result.json

The manifest is returned by:

window.QuokkaPixAgent.getResultManifest()

It contains machine-readable local processing facts:

• `schemaVersion`;
• `status`;
• `success`;
• `tool`;
• `mode`;
• `source.count`;
• `source.totalBytes`;
• `outputs[]`;
• source/output dimensions when available;
• output file names;
• formats;
• byte sizes;
• warnings;
• `processingMs`;
• browser capabilities;
• optional planned backend routes in `capabilities.backends`;
• stable `errorCode`.

The manifest does not contain image bytes.

`capabilities.backends` is additive and advisory. The current MCP adapter already

passes unknown browser manifest fields through unchanged, so this field does not

require a new adapter release. Continue to use terminal status, `errorCode` and QA

results to decide whether a run succeeded.

QA Validation

The runner validates result manifests against recipe QA contracts.

Each check includes `name`, `ok`, `severity`, `expected`, `actual`, `message` and `remediation`, so agents can report both what failed and what setting to change.

Current QA checks include:

• run status is `done`;
• source count is positive;
• source count is within recipe limit;
• outputs are present;
• expected format;
• expected width/height;
• max width/height;
• square output when required;
• max output size in KB when per-file size is available;
• output name prefix;
• required warning absence;
• ZIP entries are represented in the manifest;
• expected minimum output count for packs.
• pixel-level checks when the browser manifest contains `outputs[].pixelQa` metrics:
  • white background;
  • subject centered;
  • safe margins;
  • transparent background.

Semantic checks such as watermark presence, promotional text, old-background remnants or subjective cutout quality are not marked as passed without a measurable signal in the manifest. If a custom QA contract requests an unsupported visual check, the validator reports it as a warning instead of silently treating it as passed.

Those require a future semantic analyzer or another explicit measurable signal. The runner does not currently pretend to verify them.

Agent Payments And x402

Human QuokkaPix UI and reward-ad flows are unchanged.

Agent payment rules apply only to agent batch or batch-scenario runs above the

free small-batch limit.

Current policy:

• single image agent run: free;
• single image scenario: free;
• agent batch up to 5 files: free;
• agent batch or batch scenario from 6 to 50 files: `0.01 USDC`;
• provider: Coinbase x402;
• currency/networks: USDC on Base (`eip155:8453`, default), Polygon (`eip155:137`), Arbitrum (`eip155:42161`) and World Chain (`eip155:480`) when exposed by `/api/agent-payment/options`;
• payment options endpoint: `/api/agent-payment/options`;
• paid unlock endpoint: `/api/agent-unlock/coinbase-x402`;
• verify endpoint: `/api/agent-unlock/verify`;
• formal API contract: `/x402-api.md`.

The MCP runner can:

• fetch payment options;
• explain the payment flow;
• verify an unlock token;
• pass an unlock token into processing.

The MCP runner does not sign x402 payments itself. An x402-capable client or wallet must obtain the `unlockToken`.

Bridge mode does not add a second fee and WebMCP has no separate charge. A remote client can call `set_unlock_token` once after obtaining an x402 unlock. The control plane keeps that token only in memory, sends it to the paired bridge for one eligible run, and removes it when local processing starts. The browser payment endpoint remains the authority that consumes the unlock.

Always call `get_payment_options` when an agent is unsure whether a run is free or paid. The live response includes `freeBatchMaxFiles`, `paidMinFiles`, `maxFiles`, `price`, `currency`, supported x402 networks and endpoint URLs.

Paid batch workflow for 6-50 files:

1. Call `get_payment_options`.

2. Use an x402-capable client to call `/api/agent-unlock/coinbase-x402`.

3. Read `unlockToken` from the paid response.

4. Optional: call `verify_unlock_token` with `consume: false`. The adapter fetches current `/api/agent-payment/options` first and uses the live `scope`, `price` and `currency` unless you explicitly override them.

5. Call `process_images` or `process_with_settings` and pass `unlockToken`.

Example:

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/products/photo-1.jpg",
    "/Users/me/products/photo-2.jpg"
  ],
  "outputDir": "/Users/me/products/out",
  "unlockToken": "eyJhbGciOiJIUzI1NiIs..."
}

Recommended Agent Prompt

Use this prompt in your local AI client:

Use QuokkaPix only through the MCP tools. First call list_recipes unless I give exact settings. For standard product, web, metadata, social, watermark or favicon workflows, prefer process_images with an official recipe. For custom image settings, use process_with_settings. After processing, inspect qa.ok and quokkapix-result.json. If qa.ok is false, report the failing checks and do not claim the output is ready. Do not say images were uploaded to a QuokkaPix processing server.

CLI

The package also exposes a direct CLI:

quokkapix-runner --recipe website_webp_compress --input ./photo.jpg --output ./out

Options:

--recipe, --recipe-id   Official recipe id.
--input, --file         Input image path. Repeat for multiple files.
--output, --output-dir  Output directory.
--app-url               QuokkaPix URL, default https://quokkapix.com/#agent=1.
--unlock-token          Paid x402 unlock token for agent batch/scenario runs.
--headed                Show browser window.
--timeout-ms            Timeout in milliseconds.

The CLI currently runs recipe-based processing. For direct settings, use the MCP tool `process_with_settings`.

Bridge command:

npx quokkapix-mcp bridge --input-root ./images --output-root ./quokkapix-output

Use `npx quokkapix-mcp bridge --help` for pairing, config, headed browser and diagnostic options. Running `npx quokkapix-mcp` without `bridge` remains the original stdio MCP server.

Tests

Fast checks:

npm run check

This checks:

• syntax of MCP server files;
• recipe loading and validation;
• direct settings workflow generation;
• QA validator;
• payment helper tools;
• CLI parser.

GitHub Actions runs the same checks on Node 20 and Node 24 on Windows and Linux.

The Linux/Node 24 job also uploads the generated `.tgz` as a short-lived workflow

artifact, so a green run verifies the actual package archive.

End-to-end browser processing test against an already running QuokkaPix app:

QUOKKAPIX_E2E_APP_URL=http://127.0.0.1:4180/#agent=1 npm run test:e2e

The free e2e tests process one local fixture, direct custom settings and logo-watermark asset upload. Paid batch e2e tests are skipped unless real unlock tokens are supplied.

For paid e2e tests:

QUOKKAPIX_E2E_APP_URL=http://127.0.0.1:4180/#agent=1 \
QUOKKAPIX_E2E_UNLOCK_TOKENS=token1,token2,token3,token4 \
npm run test:e2e

The paid tests use separate tokens because unlocks are one-time consumable.

Publication Check

Before publishing or tagging a release:

npm run check
npm pack --dry-run

Pushing an audited `vX.Y.Z` tag runs `.github/workflows/release.yml`, builds the

package again and attaches the `.tgz` to a GitHub Release. npm publication is a

separate manual workflow. Configure npm Trusted Publisher for this repository,

workflow `publish-npm.yml` and GitHub environment `npm`, then run **Publish npm

package** with the existing release tag. The workflow uses OIDC and does not

store an npm token in the repository.

The package whitelist includes only:

• `src/`;
• `examples/`;
• `CHANGELOG.md`;
• `LICENSE`;
• `README.md`;
• `SECURITY.md`;
• `package.json`.

`node_modules`, test artifacts and the full QuokkaPix website are not included in the npm package.

Security And Privacy Notes

• Source image files are read from local paths by the MCP runner.
• Files are uploaded only into the local browser page through Playwright.
• QuokkaPix browser processing does not upload source images to a QuokkaPix processing server.
• The public website still cannot read arbitrary local paths.
• Payment tokens should be treated as short-lived secrets.
• Do not commit real unlock tokens, private files, or local output folders.
• Bridge device secrets stay in the local config and are stored as hashes by the control plane.
• OAuth uses authorization code with PKCE, audience-bound access tokens and rotating refresh tokens. Processing tools additionally require the `bridge:execute` scope; `mcp:tools` alone is read-only.
• Remote file arguments are restricted to configured roots; `..` traversal and out-of-root absolute paths are rejected.
• The control plane has no image upload route. It receives commands, relative names, status and result metadata.
• A cloud AI can receive image bytes only if the user separately uploads or shares an output with that AI; bridge mode does not do that automatically.

Limitations

• Browser RAM is the hard limit for large batches.
• Background removal may download browser-side AI model files and depends on browser/device capability.
• WebGPU/WebNN availability depends on the user's browser and hardware.
• HEIC/AVIF/WebP support depends on browser and optional browser-side encoders.
• JPEG XL export is experimental and requires the browser-loaded advanced encoder; it has no Canvas fallback.
• PDF merge/split/extract expects PDF files. The existing images-to-PDF recipe expects image files.
• ZIP import works only in batch mode and only extracts supported image files.
• GIF background removal is not supported.
• Pixel-level QA is deterministic and limited to measurable image facts. It does not claim semantic recognition of text, watermark content or subjective retouching quality.
• The adapter currently uses Playwright browser automation, not a native image-processing library.
• In bridge mode the remote client must know relative paths under the configured input root; directory browsing is intentionally not exposed.
• Active bridge jobs are memory-only and fail closed during a control-plane restart.

Troubleshooting

Playwright browser is missing

Run:

npx playwright install chromium

The agent cannot find files

Use absolute local file paths. The MCP process must have permission to read them.

Batch run says payment is required

Single image runs, single-image scenarios and agent batches up to 5 files are free. Larger agent batch and batch-scenario runs may require a valid x402 unlock token.

Browser runs out of memory

Reduce batch size, resize first, avoid very large images, or use smaller workflows. The runner cannot bypass browser RAM limits.

QA reports unsupported visual checks

That is expected for semantic visual requirements that cannot be proven from the browser manifest. The validator uses `outputs[].pixelQa` for measurable checks and leaves unsupported semantic checks unclaimed.

Related QuokkaPix Agent Files

Public discovery and documentation:

• `https://quokkapix.com/agents.md`
• `https://quokkapix.com/agents.html`
• `https://quokkapix.com/llms.txt`
• `https://quokkapix.com/agent-manifest.json`
• `https://quokkapix.com/.well-known/ai-catalog.json`
• `https://quokkapix.com/agent-test.html`
• `https://quokkapix.com/mcp-runner.html`
• `https://quokkapix.com/x402-api.md`

License

MIT. See `LICENSE`.