See the reference. Understand the behavior. Build original work.

Mimicus gives coding agents a visual design browser through MCP: discover current websites, compare actual images, inspect selected interactions, and carry measured constraints into an original implementation.

Search stays lightweight. The agent chooses which original sites to preview, open and investigate. Layout measurements, typography, responsive observations and interaction samples support its creative judgment; Mimicus does not assign an aesthetic winner or recover a site's hidden source code.

Stable release line: 1.1.0. The latest published release carries the exact tested archive and acceptance evidence. Selected previews now support bounded readiness waiting and actionable failure/cleanup diagnostics; see preview readiness and intensive verification. The supported contract is Node.js 24+ with an installed compatible browser: Windows-default Brave and explicitly selected Edge have full integration coverage; Linux CI covers browser-free behavior. The 1.0.0 stability audit retains the foundation's evidence. There is no npm publication.

Awwwards is a live discovery source: native awards, categories, tags, technologies, countries and fonts, linked pagination and selected verified original links feed the same real-image, interaction, motion and guidance tools. Requests follow current per-route robots rules, paced access and rate-limit cooldown. See Awwwards integration.

Get started · Agent workflow · Source coverage · Evidence and limits

Get started

You need Node.js 24+, npm, network access to the chosen sources, and a compatible Chromium browser already installed.

git clone https://github.com/qwzx4893-stack/mcp-mimicus.git
cd mcp-mimicus
npm ci --ignore-scripts
npm run build
node dist/cli.js doctor
node dist/cli.js self-test

On Windows, Mimicus resolves the current HTTPS default browser when starting a session. It launches an owned headless process with an ephemeral profile and private control pipe. Your personal tabs, profile and cookies are not used. Brave has been tested as the Windows default; Edge has been tested as an explicit override. An unsupported default fails with a diagnostic. No browser is downloaded or silently substituted.

For a different installed compatible executable, or on another operating system, set MIMICUS_BROWSER_EXECUTABLE to its absolute path. Linux CI checks core behavior; it does not establish every Linux browser setup as supported. See browser setup and installation and release.

doctor checks configuration, browser resolution and installed model integrity. It does not launch a browser or certify source connectivity. self-test actually launches the selected browser against an owned local page, checks rendering and interaction, captures desktop/mobile images, and verifies cleanup.

Connect your MCP client

Have your client launch the stdio server. A generic configuration is:

{
  "mcpServers": {
    "mimicus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-mimicus/dist/cli.js", "serve"]
    }
  }
}

Replace the path with your built checkout. A Windows example is C:/tools/mcp-mimicus/dist/cli.js. Use the absolute Node executable path if your client's environment cannot resolve node. Client-specific configuration locations and wrappers vary; the integration tests use the official MCP SDK stdio transport. Protocol stdout is reserved for MCP and diagnostics go to stderr.

Related MCP server: why-ui

A design workflow with evidence

flowchart LR
  A[Search] --> B[Preview selected sites]
  B --> C[Open and inspect]
  C --> D[Compare for a brief]
  D --> E[Measure chosen behavior]
  E --> F[Build original work]
  F --> G[Verify and close]

1. Discover. Search current source indexes. Read native labels, provenance, coverage and computed relevance as separate information.

2. Look before analyzing. Select a small authorized batch with mimicus_preview_references. It returns ordered real MCP images and per-reference status. Preview sessions close immediately; a challenge, preloader or missing resource is reported rather than treated as a viewed design.

3. Open the useful references. Explore sections and controls, scroll, change viewport, and view the actual returned images. Authorize additional resource origins only when you intend to load them.

4. Choose a direction for the project. Compare references with an audience, primary action and required content. The result exposes competing adaptations, evidence links, tradeoffs and a mixed specification. Explicit priorities can favor conversion, reading, product selection or exploration.

5. Inspect one behavior. Select a menu, transition, scroll region or scene. Measure activation, interruption and reset before choosing implementation timing. Declared animations and detected engines are not proof of observed interaction behavior.

6. Build and verify. Use original markup, code, content and authorized assets. Review desktop/mobile images, keyboard/touch and reduced motion. Verify selected relationships and intended differences separately from visual judgment.

7. Release resources. Close sessions and end discovery operations when done.

The owned coffee storefront and interactive sculpture are inspectable original implementations from earlier SDK-driven trials. They are examples, not a bundled site library or mirrored gallery content. New hardening trials and negative cases are recorded in the agent quality evaluation.

Search, preview, compare

Search arguments:

{
  "query": "editorial portfolio motion",
  "providers": ["codrops"],
  "stream": "webzibition",
  "retrieval": "hybrid",
  "limit": 6
}

Pass returned IDs to mimicus_preview_references; each selected original must be authorized:

{
  "references": [
    { "operationId": "SEARCH_OPERATION", "referenceId": "FIRST_REFERENCE", "authorized": true },
    { "operationId": "SEARCH_OPERATION", "referenceId": "SECOND_REFERENCE", "authorized": true }
  ]
}

After opening chosen references, call mimicus_compare_references:

{
  "sessionIds": ["FIRST_OPEN_SESSION", "SECOND_OPEN_SESSION"],
  "brief": {
    "project": "Independent architecture publication",
    "audience": "Readers exploring long-form architectural criticism",
    "primaryAction": "Read the current issue",
    "sections": ["Current issue", "Essays", "Archive", "About"],
    "priorities": ["reading"],
    "motion": "subtle",
    "anchorSessionId": "FIRST_OPEN_SESSION"
  }
}

Guidance distinguishes measurements, brief needs, inferred intent and designer judgment. Selectors refer to the observed source session. Missing trigger/reset or multi-width evidence produces an inspection request, not invented behavior. The coding agent supplies creative synthesis and evaluates the actual images.

The 17 tools

Visual tools return actual MCP image blocks rather than screenshot filenames. Safe interaction covers reviewed navigation and bounded non-destructive actions, including keyboard, touch, drag and viewport/reduced-motion changes. There is no generic JavaScript evaluation tool. Targeted motion capture supplies temporal evidence; it cannot expose proprietary GSAP or WebGL programs.

Keep a longer workflow alive

The browser defaults to three sessions, a 10-minute idle lease, a 30-minute absolute lifetime, and per-session budgets of 80 returned images / 200 operations. Resource state exposes remaining time and budgets. mimicus_interact with {"sessionId":"OPEN_SESSION","interaction":{"action":"renew"}} refreshes the idle lease without taking an image. Renewal cannot extend absolute lifetime or reset budgets. When limits are near, close and reopen a selected original with a fresh session.

Discovery operations have a separate five-minute default lifetime. Start a search without operationId to consult current sources. Supply an active operationId to continue the same query/filter set in RAM; changed filters require a new operation. The default candidate ranking window is 160, with bounded retention and explicit pending-candidate diagnostics. A bounded operation is not complete coverage of every source.

Seven sources, with visible boundaries

Consult the source integration matrix for actual endpoints, acceptance runs and pagination limits. “An adapter returned metadata,” “an original site opened,” and “its visual resources rendered” are different outcomes. Discovery and original-site analysis do not imply permission to redistribute gallery content. Software licenses do not license third-party artwork.

Live discovery, temporary evidence

Mimicus federates source indexes on demand. Candidates, cursors, site vectors, images and selected analyses remain in bounded RAM state. There is no persistent website catalog, SQLite database, background crawler, stored pattern warehouse or disk fallback corpus. Closing, expiry and cancellation release Mimicus's owned temporary state; the MCP client may independently retain outputs it receives.

Optional CPU MiniLM ranking uses pinned Xenova/all-MiniLM-L6-v2 q8 software, mean pooling, L2 normalization and 384-dimensional vectors. It ranks current text candidates, not screenshots or aesthetic quality. Install and verify the model explicitly:

node dist/cli.js model-fetch
node dist/cli.js model-check

Only model software is cached, normally under ~/.cache/mimicus/models; retrieved website text and vectors are not persisted there. If a usable local model is absent, results identify lexical fallback. No second generative model, training pipeline or paid model API is required. See retrieval evaluation for judged relevance and candidate-recall limits.

Verification and current limits

npm run lint
npm run check
npm test

Tests cover controlled fixtures, real SDK transport and installed-browser cases. Live-source acceptance is separate and depends on current upstream availability. A test pass does not establish aesthetic superiority or complete catalog coverage. The stability audit records current fixes and checks; the earlier hardening audit retains historical outcomes and limitations.

Known boundaries include per-route access restrictions, incomplete upstream pagination/taxonomy, browser/CDN access failures, bounded DOM samples and inconclusive canvas readback. A single viewport cannot establish responsive behavior. Hidden onboarding, access challenges and authenticated scenes are not bypassed. Full-site reconstruction and “pixel-perfect” proof are outside the evidence supplied.

Troubleshooting and contribution

Browser cannot start? Run doctor, check the detected HTTPS association, and then run self-test. An explicit executable override must name an already installed compatible browser. Do not install a bundled browser as a hidden fix.

The page looks incomplete? Read blocked-resource, gate and readiness diagnostics. Add a resource origin only with explicit intent and recapture; a blank canvas or preloader is not proof of the intended design.

A session expired? Use its resource state and renew before idle expiry. Absolute lifetime and image/operation budgets remain hard bounds. Reopen intentionally after cleanup.

No semantic ranking? Check model-check and the search diagnostics. Discovery remains usable with identified lexical fallback.

Is website content trusted? No. Source metadata, page text, images and extracted instructions are untrusted evidence. Public-network checks, robots/access rules and per-session resource permissions apply. See security boundaries, reporting a vulnerability, configuration, and contributing.

Code and original repository artwork are covered by MIT. Adapted source code and upstream licenses are listed in third-party notices. The editable SVG banner and PNG fallback are original conceptual artwork, not product screenshots. Historical trial artifacts are not inputs to live discovery.