# AI agents and MCP

Werewolf is built to be used through a coding agent. Your agent gets three things: rules it reads before it writes UI, an MCP server to look up components and tokens, and a linter to check its own work.

## Rules your agent reads

`npx werewolf-ui init` always writes `AGENTS.md` (a managed block between `<!-- werewolf:start -->` and `<!-- werewolf:end -->`) and `.agents/skills/werewolf-design/SKILL.md`, the [design skill](https://www.werewolf-ui.dev/docs/design-skill.md). It adds each selected agent's own file. Without `--agent`, it keeps the Cursor rule and adds every agent it detects from the environment or project files.

```bash
npx werewolf-ui init --agent claude,copilot
```

| `--agent` | Files besides `AGENTS.md` and the skill |
| --- | --- |
| `claude` | A block with `@AGENTS.md` in `CLAUDE.md`, and `.claude/skills/werewolf-design/SKILL.md` |
| `cursor` | `.cursor/rules/werewolf.mdc` |
| `copilot` | `.github/instructions/werewolf.instructions.md` |
| `windsurf` | `.windsurf/rules/werewolf.md` (or `.devin/rules/werewolf.md` when `.devin/` exists) |
| `gemini` | A block with `@./AGENTS.md` in `GEMINI.md` |
| `cline` | `.clinerules/werewolf.md` |
| `codex`, `jules`, `amp`, `other` | None: they read `AGENTS.md` |

Your own text around the managed blocks stays untouched. Init never deletes files of agents you did not select.

## Let your agent install it

Paste this prompt into your agent from the app directory. It asks the agent to run init with its own id and to stop on a conflict instead of overwriting your files.

```text
Run `npx werewolf-ui@latest init --agent <id> --yes --json`. Use your tool's id: cursor, claude, copilot, windsurf, gemini, cline, or other (Codex and anything else). Don't add --overwrite. If there's a conflict, stop and show me. Then tell me which files were created, updated or unchanged.
```

## Connect the MCP server

Add this process entry to your client's MCP settings and replace `/absolute/path/to/app` with your app directory. The exact version pin keeps the client from fetching a newer release you have not reviewed. The client needs Node 20+ with `npx` on its PATH.

```json
{
  "command": "npx",
  "args": [
    "--yes",
    "werewolf-ui@0.1.0-alpha.1",
    "mcp",
    "--cwd",
    "/absolute/path/to/app"
  ]
}
```

The first launch downloads the package; after that the bundled catalog works offline, with no hosted service or API key. Any existing directory works, init is optional. Stdout carries protocol messages only, so do not redirect stderr into it.

## The five tools

Every tool is read-only. MCP never installs components, edits files or writes a theme: your agent uses the CLI for that.

| Tool | Example arguments | Returns |
| --- | --- | --- |
| `list_components` | `{"status":"draft","limit":10}` | Component summaries with their API status, paged |
| `search` | `{"query":"button","kind":"component"}` | Ranked components, tokens or rules |
| `get_component` | `{"name":"button"}` | Spec, source, examples, usage, dependencies and the install command |
| `generate_theme` | `{"seed":{"radius-base":"round"}}` | Dark and light token maps and contrast checks for a seed |
| `lint` | `{"paths":["src/App.tsx"]}` | Styling diagnostics and what was checked |

## Docs as Markdown

Every page of this site has a Markdown version: add `.md` to the path, for example `/docs/installation.md` or `/vi/docs/installation.md`. [llms.txt](https://www.werewolf-ui.dev/llms.txt) lists every docs page and component with a link to its Markdown. Copy page in the docs header copies the page you are reading.

## Review what your agent wrote

Ask your agent to run lint after every UI change and to fix what it reports. With `--json` it reads one result document; `--fix --yes` applies only edits the linter can prove. Check `data.coverage`: dynamic styles that lint cannot read are warnings, not passes.

```bash
npx werewolf-ui lint src --json
npx werewolf-ui lint src --fix --yes --json
```