identityforge-mcp

<p align="center">
  <a href="https://identityforge.io">
    <img src="https://identityforge.io/opengraph-image.png" alt="Identity Forge branding pipeline from names and design kits to agent-ready systems" width="1200">
  </a>
</p>

<h1 align="center">Identity Forge MCP</h1>

<p align="center"><strong>The branding pipeline for the agentic era.</strong></p>

<p align="center">Give coding agents a complete design system, then carry it from first build to later updates and client handoff.</p>

<p align="center">
  <a href="#for-people">For people</a> ·
  <a href="#for-agents">For agents</a> ·
  <a href="#capabilities">Capabilities</a> ·
  <a href="#watch-it-work">Watch it work</a> ·
  <a href="#reference">Reference</a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/identityforge"><img src="https://img.shields.io/npm/v/identityforge" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/identityforge"><img src="https://img.shields.io/npm/dw/identityforge?label=weekly%20downloads" alt="weekly npm downloads"></a>
  <a href="https://github.com/KasayoDotCom/identityforge-mcp/actions/workflows/ci.yml"><img src="https://github.com/KasayoDotCom/identityforge-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/identityforge" alt="MIT license"></a>
</p>

## For people

- **Start with a complete design kit.** Typography, semantic color tokens, layout, spacing, motifs, dos and don'ts, and an implementation-ready `DESIGN.md` travel together.
- **Choose with evidence.** Your agent can search the catalog, rank kits for the product and its surfaces, inspect the full brief, and compare nearby directions.
- **Apply safely.** Identity Forge writes the brief, tokens, and a version stamp, then protects files that changed locally.
- **Compose the whole brand.** Add an image direction, interface style, and page recipes while keeping the supplied product, person, or object recognizable.
- **Carry decisions forward.** Version history, drift checks, naming and domain research, saved projects, client shares, and feedback stay in the same workflow.

Public Free kits are ready immediately. An account adds persistent projects, saved work, authenticated quota, and Pro access.

[Browse the design kits](https://identityforge.io/kits) · [See the agent workflow](https://identityforge.io/for-agents) · [Read the HTTP API](https://identityforge.io/api/v1)

## For agents

Install the local MCP server into your coding agent:

```bash
npx --yes identityforge@latest install --client claude-code
```

Use `cursor`, `vscode`, `codex`, `gemini`, `opencode`, or `pi` in place of
`claude-code`. The installer merges the MCP entry into the client's existing
configuration.

Then tell your agent:

> Use Identity Forge to pick a theme that fits this product, apply it, and follow the DESIGN.md.

Sign in when you want persistent projects, saved work, authenticated quota, or Pro access:

```bash
npx --yes identityforge@latest login
```

No account yet? In the browser, sign up, complete the security check, select
`Send verification email`, and open its link. Then select
`Confirm email and continue`, approve the resumed authorization, and the CLI
receives the key automatically.

## Capabilities

Once connected, your agent gets 61 tools grouped around real jobs:

- **Find the right system:** search, rank, compare, and inspect complete design kits.
- **Build from it:** export `DESIGN.md`, CSS, Tailwind v3 or v4, shadcn registry data, DTCG tokens, or JSON.
- **Apply and maintain it:** preview writes, protect local changes, inspect status, compare versions, and follow drift.
- **Direct the presentation:** codify image directions, interface styles, and page recipes around the chosen kit.
- **Build a client-ready brand:** compose variations, generate mockups, share a review link, and act on feedback.
- **Name and research:** manage a persistent naming board and collect domain, trademark, registrar, DNS, RDAP, and search evidence.

## Watch it work

The three-minute lifecycle film follows a design system from the first choice through later updates, an older-site rebuild, and a client handoff. The Aubade storefront, Shiftly rebuild, and Kestrel rebrand are complete one-shot agent builds from real Identity Forge design systems.

https://github.com/user-attachments/assets/ea90ffc2-d3c5-432a-8cd6-f2d81ca29aba

[Download the full-resolution 1080p WebM](https://github.com/KasayoDotCom/identityforge-mcp/releases/download/v0.3.10/identity-forge-lifecycle-explainer.webm).

## Reference

The complete behavior and command inventory stays here for agents and implementation work. Expand only the part you need.

<details>
<summary><strong>Discovery and installation details</strong></summary>

## Judged discovery

Every kit in the catalog is scored per use case against concrete criteria measured on its own tokens: chart-series distinctness, text contrast, information density, and similar, rather than keyword matching. The per-lane prose justification is switched off catalogue-wide pending re-enrichment, so a score arrives without a sentence explaining it. Your agent can use the scores directly:

- `list_themes({ use: "data-dashboard" })` re-orders the catalog by fitness for dashboards rather than narrowing it, each kit carrying a score from 0 to 100 computed from its own tokens against the lane's criteria.
- `list_themes({ q: "calm fintech dashboard" })` runs a synonym-aware ranked search across moods, industries, and use cases.
- `search_themes` returns the whole catalog unranked so the agent can weigh a subtle brief itself.

Read the order, not the number. The score measures how well a kit is built against a lane's criteria, and every catalog kit is well built, so the scores cluster high and the documented cut excludes almost nothing. A lane changes which kits come first, not which kits come back.

For the data lanes there is a better answer than the score. Every kit summary carries a `charts` block measured on the mode the kit ships in: `minDeltaE` and `cvdMinDeltaE` (the closest pair of series colors, plain and under colorblind simulation), `distinct`, `hueFamilies`, `severityHeadroom` (how close any series comes to the destructive, warning and success roles — 0 means a category color IS a status color), `sequentialReady`, and `designed`, which is `false` when the kit defines no chart slots and the five were cycled from its brand roles. Those are measurements, so unlike the fitness score they can be stated to a user as the reason for a recommendation.

Use-case lanes: `data-dashboard`, `admin-internal-tool`, `saas-marketing`, `landing-page`, `ecommerce-store`, `portfolio`, `editorial-blog`, `docs-knowledge-base`, `mobile-app`, `business-services`, `community-social`, `ai-agent-chat`.

The same discovery runs the [kit gallery](https://identityforge.io/kits) and the [HTTP API](https://identityforge.io/api/v1) (`GET /api/v1/kits?use=…&q=…`, see [llms.txt](https://identityforge.io/api/v1/llms.txt)).

## Install into an agent

`install --client <name>` writes the MCP server config for that agent, merging into any existing config:

| Client | `--client` | Config file |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` |
| Cursor | `cursor` | `.cursor/mcp.json` |
| Codex | `codex` | `~/.codex/config.toml` |
| Gemini CLI | `gemini` | `.gemini/settings.json` |
| VS Code / Copilot | `vscode` | `.vscode/mcp.json` |
| opencode | `opencode` | `opencode.json` |
| Pi | `pi` | `.pi/agent/mcp.json` |

All of them run the same local stdio server via `npx -y identityforge@latest mcp`.

### Install the agent plugin and skill

The repository also bundles the MCP server with an Agent Skill that tells the agent when
to use Identity Forge, how free and authenticated access differ, and how to guide a human
through `Send verification email` before the pending browser authorization resumes.

Claude Code:

```bash
claude plugin marketplace add KasayoDotCom/identityforge-mcp
claude plugin install identity-forge@identity-forge
```

GitHub Copilot CLI:

```bash
copilot plugin marketplace add KasayoDotCom/identityforge-mcp
copilot plugin install identity-forge@identity-forge
```

Codex and other Agent Skills-compatible clients:

```bash
npx skills add KasayoDotCom/identityforge-mcp
```

Cursor metadata is included for directory distribution. Until it is listed there, use
the `install --client cursor` command above to connect the same MCP server.

</details>

<details>
<summary><strong>MCP tools, workflows, safety, and version behavior</strong></summary>

## MCP tools

Once connected, your agent gets 61 tools. Browsing free kits needs no key; scopes are noted where they apply.

### Find a design kit

- `list_themes`: browse the catalog as compact summaries. Rank by use-case lane with `use`, run ranked search with `q`, page with `offset`, sort by `featured`, `popular`, `recent`, `name`, or `fit`.
- `search_themes`: return the whole catalog unranked, for briefs too subtle to rank against a lane.
- `similar_themes`: given a kit slug, find neighbours by palette, tags, and audience.
- `match_palette`: given existing brand colors, rank kits by perceptual color distance.

### Read and apply one

- `get_design_md`: fetch a kit's DESIGN.md, the full design brief.
- `get_tokens`: fetch tokens as `dtcg`, `css`, `tailwind-v3`, `tailwind-v4`, `shadcn-registry`, or `json`.
- `apply_theme`: write DESIGN.md, a tokens file, and an `identityforge.json` stamp into the project. It refuses rather than overwriting a file it did not write, see below.

## What `apply` writes, and what it will not overwrite

`apply_theme` (and `identityforge apply`) writes three files into the target directory:

| File | What it is |
| --- | --- |
| `DESIGN.md` | the design brief the agent builds from |
| `<slug>.css` / `.json` / `.js` | the tokens, named for the format you asked for |
| `identityforge.json` | the stamp: which kit was applied, at whi