Metadata-Version: 2.5
Name: resemblio-mcp
Version: 0.2.0
Summary: Model Context Protocol server for Resemblio - extract trademark-stripped, brand-faithful, code-bearing design systems from any URL. Inspirado, no copiado.
Project-URL: Homepage, https://resemblio.com
Project-URL: Repository, https://github.com/FrankCJones/resemblio-mcp
Project-URL: Issues, https://github.com/FrankCJones/resemblio-mcp/issues
Author-email: Frank Jones <frank@optsus.com>
License: MIT
License-File: LICENSE
Keywords: design-system,design-tokens,dtcg,mcp,model-context-protocol,resemblio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Description-Content-Type: text/markdown

# resemblio-mcp

Model Context Protocol server for [Resemblio](https://resemblio.com), Python edition. Lets MCP-compatible clients (Claude Desktop, Claude Code, Cursor, Codex CLI) extract trademark-stripped, brand-faithful, code-bearing design systems from any URL. Inspired by the source, not a copy of it (_inspirado, no copiado_).

## Install

```bash
pip install resemblio-mcp
# or
pipx install resemblio-mcp
```

## Configure

Set your API key (get one at https://resemblio.com):

```bash
export RESEMBLIO_API_KEY=rsmb_live_<your-key>
```

### Claude Desktop

Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "resemblio": {
      "command": "resemblio-mcp",
      "env": {
        "RESEMBLIO_API_KEY": "rsmb_live_<your-key>"
      }
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "resemblio": {
      "command": "resemblio-mcp",
      "env": {
        "RESEMBLIO_API_KEY": "rsmb_live_<your-key>"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add resemblio resemblio-mcp -e RESEMBLIO_API_KEY=rsmb_live_<your-key>
```

## Tools exposed

Identical contract to the TypeScript package `@resemblio/mcp-server`.

### `resemblio_extract`

Extract a trademark-stripped, brand-faithful design system from a URL. Wordmarks, logos, and literal trademark marks are stripped; colours, type, spacing, scale, and component patterns are preserved as a code-bearing starting point. Returns a DTCG-compatible token JSON, a signed manifest URL, and a download URL for the full ZIP bundle.

Input:
- `url` (string, required): the page to extract from
- `private` (boolean, optional): if true, run as private extraction ($10); default false ($5)
- `idempotency_key` (string, optional): client-supplied key for replay-safe retries

Charges your Resemblio account on success. Failures that are Resemblio's fault are automatically refunded.

### `resemblio_list_extractions`

List your extraction history, newest first.

Input:
- `limit` (integer, optional): page size, 1-100, default 20
- `before` (integer, optional): cursor; return rows with id less than this value

No charge.

### `resemblio_get_library_manifest`

Retrieve the verified canonical Apple library manifest. This no-input, read-only tool is free and returns the API artifact unchanged, including its record set, classification-specific facets, version, and SHA-256 digest.

### `resemblio_get_library_export`

Retrieve a no-cost Apple DTCG export. Requires an entitled Resemblio API key.
The tool returns the API's two named values unchanged: `tokens` is the pure
DTCG document, and `manifest` carries selection, provenance, attribution,
scrub policy, version, and the SHA-256 identity for
`tokens/design.tokens.json`.

Input uses one selector:
- `{ "selection": "complete" }`
- `{ "selection": "classification", "classification": "foundation" | "component" | "composition" }`
- `{ "selection": "record", "record_ids": ["component:buttons"] }` (one or more canonical record IDs)

Record IDs are deduplicated and sorted before the API request. Invalid selectors fail closed; the API's stable selection errors are preserved.

## Configuration reference

| Env var | Required | Default | Description |
|---|---|---|---|
| `RESEMBLIO_API_KEY` | yes | - | API key (starts with `rsmb_live_` or `rsmb_test_`) |
| `RESEMBLIO_BASE_URL` | no | `https://api.resemblio.com` | Override the API host (for local testing) |

Equivalent CLI flags: `--api-key`, `--base-url`.

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT. Copyright (c) 2026 Frank Jones / OptSus.
