Metadata-Version: 2.4
Name: copycat-mcp
Version: 0.2.1
Summary: Thin MCP server for managing Copycat design library artifacts.
Keywords: agents,design-systems,mcp,model-context-protocol,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: mcp>=1.12.4
Requires-Dist: playwright>=1.49
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Copycat MCP

Copycat gives your coding agent a place to keep design references.

Point an MCP client at a site, give it an alias, and Copycat saves the screenshots and evidence an agent needs to describe the style: structure, links, CSS variables, computed styles, notes, design guidance, and config. Later, the agent can pull that profile back by name and use it as direction for new UI.

This avoids your agent reinventing the wheel on every new project. The agent can inspect a saved profile instead of relying on a one-time page description from an old session.

## Before and after

Copycat captures a site's visual system, then lets an agent reuse that direction for original UI work.

<table>
  <tr>
    <th>Original site</th>
    <th>With Copycat</th>
  </tr>
  <tr>
    <td><a href="examples/firecrawl-original.png"><img src="examples/firecrawl-original.png" alt="Original Firecrawl homepage" width="390"></a></td>
    <td><a href="examples/firecrawl-copycat.png"><img src="examples/firecrawl-copycat.png" alt="Copycat-generated page using Firecrawl visual direction" width="390"></a></td>
  </tr>
  <tr>
    <td><a href="examples/greptile-original.png"><img src="examples/greptile-original.png" alt="Original Greptile homepage" width="390"></a></td>
    <td><a href="examples/greptile-copycat.png"><img src="examples/greptile-copycat.png" alt="Copycat-generated page using Greptile visual direction" width="390"></a></td>
  </tr>
</table>

## How it works

A typical capture can start with one sentence:

1. You say: `Save https://linear.app as linear`.
2. Your MCP client routes the request to Copycat, and the agent calls `create` to create `~/.copycat/designs/linear/`.
3. The agent captures Linear with Playwright: screenshots plus combined page evidence (structure, links, CSS variables, computed styles).
4. The agent writes `DESIGN.md`, `config.json`, and `notes.md` on disk under the alias paths, and updates `metadata.json` pages for sampled URLs.
5. Later, you can say `Use linear as visual direction for this settings page`, and the agent can read the saved profile with `get` instead of starting over.

Each alias is isolated on disk. A profile for `linear` lives at `~/.copycat/designs/linear/`, and its screenshots stay inside that folder.

## Install

Install the MCP server & Playwright Browser:

```bash
uv tool install copycat-mcp
uvx --from playwright playwright install chromium
```

## Connect an MCP client

Use the installed `copycat-mcp` executable in your MCP client config.

```json
{
  "mcpServers": {
    "copycat": {
      "command": "copycat-mcp"
    }
  }
}
```

For opencode:

```json
{
  "mcp": {
    "copycat": {
      "type": "local",
      "command": ["copycat-mcp"],
      "enabled": true
    }
  }
}
```

Restart your MCP client after changing MCP config.

## Agent guide

Call `guide` at the start of capture or apply work. It returns the bundled markdown workflow for sampling pages, capturing evidence, authoring `DESIGN.md`, applying a profile, and legal boundaries.

Capture tools take a slug `name` only and write under `screenshots/<name>.png` or `evidence/<name>.json`. Authored profile files (`DESIGN.md`, `config.json`, `notes.md`, `metadata.json` pages) are written by the agent on disk using paths from `create` / `get`.

## Try it

Ask your MCP-aware coding agent for the result you want. You usually do not need to call the tools by hand.

```text
Capture https://vercel.com as a Copycat profile named vercel.
Call guide first, then capture desktop and mobile screenshots and evidence,
sample 5-10 representative public pages when available, and write a substantial
agent-authored DESIGN.md (~180-220 lines) with colors, typography, spacing,
layout patterns, component states, caveats.
```

```text
List my saved Copycat profiles and tell me which one fits a clean B2B SaaS
settings page.
```

```text
Use the vercel Copycat profile as visual direction for a billing settings page
in this app. Do not copy assets or text. Reuse the spacing, type scale, color
behavior, and component rhythm.
```

```text
Open the vercel Copycat profile and summarize the design config I should use
for a pricing page.
```

If your client exposes raw tools, the usual capture flow is:

```text
create
capture_screenshot
capture_page
# then agent writes DESIGN.md, config.json, notes.md, metadata.pages on disk
```

## What gets saved

Copycat writes each profile under:

```text
~/.copycat/designs/<alias>/
```

The important files are:

```text
DESIGN.md       Agent-authored human-readable design guidance
config.json     Structured colors, type, spacing, radii, shadows, and other style values
notes.md        Additional observations or agent notes
metadata.json   alias, sourceUrl, createdAt, lastUpdated, pages
screenshots/    Captured desktop and mobile screenshots
evidence/       Combined page evidence (structure, links, CSS variables, computed styles)
```

## Storage location

By default, Copycat stores profiles in:

```text
~/.copycat/designs
```

Set `COPYCAT_ROOT` to use a different design library root.

## Development

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m playwright install chromium
```

Run validation:

```bash
.venv/bin/python -m pytest
.venv/bin/python -m mypy
```

Verify the package installs as a persistent tool:

```bash
uv tool install .
uv tool list
```
