npm package: @just-every/12ui
Description: MCP stdio server for 12ui.com
Author: Just Every
Latest version: 0.1.89

# @just-every/12ui

MCP (Model Context Protocol) stdio server that proxies the **12ui API** (default: `https://12ui.com`) so MCP clients can create, sync, and check design runs.

## Quick start

The recommended path is to run the guided installer once. It will:

- Authenticate you (if needed)
- Install a local `12ui` launcher (no `npx` required after)
- Configure detected MCP clients (and install Skills where supported)

```bash
npx -y @just-every/12ui@latest install
```

After install, you can use `12ui` directly.

### Authenticate

Login once (interactive approval-link flow):

```bash
12ui auth login
```

If you do not have `12ui` on PATH yet, you can always run:

```bash
npx -y @just-every/12ui@latest auth login
```

If your user belongs to multiple organizations, this will prompt you to pick one.
To skip the prompt, pass `--account <slug>`.

### Run as an MCP server (stdio)

```bash
12ui
```

Fallback (no local install):

```bash
npx -y @just-every/12ui@latest
```

## Install into common MCP clients

This writes MCP server config entries for detected clients (Claude Desktop, Cursor, Gemini CLI, Qwen Code, Codex, and Every Code), and installs a small local playbook “skill” where supported.

```bash
npx -y @just-every/12ui@latest install
```

By default, install will prefer a local launcher and attempt to ensure `~/.local/bin` is on your `PATH`.
To skip modifying shell config files:

```bash
npx -y @just-every/12ui@latest install --no-path
```

To force-install into all supported clients:

```bash
npx -y @just-every/12ui@latest install --client all --yes
```

Non-interactive (skip auth login, leave existing auth untouched):

```bash
npx -y @just-every/12ui@latest install --client all --yes --skip-auth
```

To remove the MCP server + playbook skill from detected clients:

```bash
npx -y @just-every/12ui@latest remove
```

### Claude Desktop config example

```json
{
  "mcpServers": {
    "12ui": {
      "command": "/absolute/path/to/12ui",
      "args": []
    }
  }
}
```

Tip: GUI apps may not inherit your shell `PATH`, so an absolute path is recommended.

## Authentication (recommended)

This package uses the JustEvery **login approval-link** flow:

- It creates an approval request via `POST /api/auth/m2m/approval-requests`.
- You click a single approval URL in your browser.
- The CLI polls, receives a short-lived bearer token, then exchanges it for a Better Auth session token via `POST /api/auth/m2m/session`.
- The session token is stored locally and used as `better-auth.session_token` for API calls.

This avoids needing long-lived client secrets and is the lowest-friction path for humans.

## Configuration

### Config file

- Default path: `$XDG_CONFIG_HOME/just-every/12ui/mcp.json` (or `~/.config/just-every/12ui/mcp.json`)
- Override: `DESIGN_MCP_CONFIG_PATH=/path/to/mcp.json`

### Environment variables

- `DESIGN_MCP_ORIGIN` (default: `https://12ui.com`)
- `LOGIN_ORIGIN` (default: `https://login.justevery.com`)
- `DESIGN_MCP_SESSION_TOKEN` (bypass config)
- `DESIGN_MCP_ACCOUNT_SLUG` (optional; otherwise chosen from `/api/accounts`)

## MCP tools

CLIs MUST follow this order when creating a user interface or visual element:
`design.create` → `design.sync` → `design.check`.

Available tools:

- `design.create` — Create a new design. Returns run id.
- `design.sync` — Wait for completion, extract assets, and sync to a folder (can take up to 30 mins).
- `design.check` — Capture a screenshot and return guidance; accepts URL or local HTML file path.
- `design.instructions` — Return the required workflow instructions for CLIs.