---
title: "AI agents"
description: "Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review."
package: "maz-ui"
url: "https://maz-ui.com/guide/ai-agents"
---

# AI agents

> Make Claude Code, Cursor, GitHub Copilot, Codex and the other AI coding agents use maz-ui and its ecosystem instead of re-implementing it - project rules, MCP server, version-matched docs, llms.txt and automatic code review.

- Package: `maz-ui`
- Web: https://maz-ui.com/guide/ai-agents

## Why

Left alone, coding agents rebuild what maz-ui already provides: native buttons instead of `MazBtn`, lodash instead of `@maz-ui/utils`, inline SVG instead of `@maz-ui/icons`, `bg-blue-500` instead of the theme colors. They also guess APIs from outdated training data.

maz-ui gives them four things:

| | What | Where |
| --- | --- | --- |
| **Rules** | How to use maz-ui in your project, loaded automatically by the agent | `.claude/rules/maz-ui.md`, `AGENTS.md` |
| **Version-matched docs** | Agent-ready markdown of the installed version: guides, component APIs, icons, Tailwind tokens | `node_modules/maz-ui/agent-docs/`, `node_modules/@maz-ui/<package>/agent-docs/` |
| **MCP server** | Search by need, exact component APIs, icons, theme tokens, setup guides, code review | `npx @maz-ui/mcp` |
| **Code review** | Static checks against the real maz-ui APIs, in the agent loop and in CI | `review_code` tool, `npx @maz-ui/mcp review` |

## Quick start

Run this command at the root of your project:

```bash
npx @maz-ui/mcp init
```

It detects the agents you use and configures them, using the docs of the maz-ui version installed in the project:

| Agent | Rules | MCP server |
| --- | --- | --- |
| Claude Code | `.claude/rules/maz-ui.md` (always loaded) | `.mcp.json` |
| Cursor | `AGENTS.md` | `.cursor/mcp.json` |
| GitHub Copilot (VS Code) | `AGENTS.md` | `.vscode/mcp.json` |
| Codex, Windsurf, Zed, Gemini CLI... | `AGENTS.md` | global config of the agent (see [MCP](https://maz-ui.com/ecosystem/mcp.md)) |

When no agent is detected, it configures Claude Code and `AGENTS.md`. Commit the generated files: your whole team and your CI agents get them.

In a project without maz-ui (only `@maz-ui/utils` or `@maz-ui/node`, for example), it only registers the MCP server, which serves the docs bundled with `@maz-ui/mcp`: the rules are about the maz-ui components and are written once maz-ui is installed. Pass `--docs <dir>` to write them anyway.

For a fast start of the MCP server, install it in the project first (`pnpm add -D @maz-ui/mcp`): the configs then start the installed version through your package manager, in about a second and at the version of your lockfile, instead of downloading it with `npx`. See [MCP server](https://maz-ui.com/ecosystem/mcp.md#in-a-project-install-it).

**Tip: It never overwrites your own instructions**

- Your `CLAUDE.md` is never touched: Claude Code loads `.claude/rules/maz-ui.md` on top of it.
- In `AGENTS.md`, maz-ui only manages the section between `<!-- BEGIN:maz-ui -->` and `<!-- END:maz-ui -->`.
- In the MCP config files, only the `maz-ui` entry is added, the formatting and comments of the file are preserved. An existing server running `@maz-ui/mcp` under another name is kept as is.
- A file you created yourself with the same path is never overwritten.
- If you edit the generated rules, your edits are kept and the rules are no longer updated: delete the file (or the section) to get the rules of a new maz-ui version. To add your own rules, write them in another file or outside the section.

### Options

```bash
npx @maz-ui/mcp init --targets claude,agents-md,cursor,vscode  # choose the agents
npx @maz-ui/mcp init --no-rules                                # MCP server only
npx @maz-ui/mcp init --no-mcp                                  # rules only
npx @maz-ui/mcp init --dry-run                                 # show the changes
npx @maz-ui/mcp init --remove                                  # remove everything init added
```

Run it again after upgrading maz-ui: the rules follow the installed version.

### Nuxt: opt-in

With [`@maz-ui/nuxt`](https://maz-ui.com/ecosystem/nuxt.md), set `agents.mcp: true` to connect the agents detected in the project to the maz-ui MCP server when you start the dev server: the module adds the `maz-ui` entry to their MCP config (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`). The instructions of the MCP server already give the maz-ui rules to the agents. Nothing is written by default.

```ts
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt'],
  mazUi: {
    // default: { rules: false, mcp: false }
    agents: {
      mcp: true, // register the maz-ui MCP server
      rules: true, // also write .claude/rules/maz-ui.md and the AGENTS.md section
      targets: ['claude', 'agents-md'], // default: the detected agents
    },
    // or enable everything: agents: true
  },
})
```

It only runs in development (never in CI, in tests or during builds), writes nothing when no agent is detected, keeps the files in sync with the installed maz-ui version and never overwrites files it does not own. In a monorepo, it writes at the root of the workspace, where the agents start (`agents.dir` to choose another folder).

### Monorepos with several Nuxt apps

Each app syncs the agent files when it starts (`nuxt dev`, `nuxt prepare`), and all of them write at the root of the workspace:

- **Same options in every app**: the first app writes the files, the next ones find them up to date and write nothing.
- **Different options**: they add up. An app with `rules: false` does not remove the rules written by an app with `rules: true` (only `npx @maz-ui/mcp init --remove` removes them), and the `targets` of each app are added. With `agents.dir`, each app writes in its own folder.
- **Apps started together** (`nx run-many -t dev`, `turbo dev`): the files are written atomically, an app never reads a file another app is writing.
- **Different maz-ui versions per app**: the rules of the most recent version are kept, an app with an older maz-ui never downgrades them. Align the versions (a pnpm catalog, for example) to get the same rules everywhere.

**Warning: One MCP server for the whole workspace**

Started at the root, the MCP server serves the docs of the first maz-ui it finds: in the root `node_modules`, then in the workspaces of the monorepo (`pnpm-workspace.yaml` or the `workspaces` field of `package.json`), in their order. When the apps install different maz-ui versions, an agent working on one app can get the docs of the version of another app. Align the versions, or point the server to the docs of an app with `--docs` (see [Version-matched docs](https://maz-ui.com/ecosystem/mcp.md#version-matched-docs)).

### Without any file in the project

The MCP server carries the rules in its instructions: registering it once for your user is enough, in every project, without writing anything in them.

- Claude Code: install the plugin, or run `claude mcp add maz-ui --scope user -- npx -y @maz-ui/mcp@latest`.
- Cursor, Windsurf, Codex...: add the server to the global MCP config of the agent (see [MCP](https://maz-ui.com/ecosystem/mcp.md#configuration)).

Write the project files (`init`, the Nuxt option) when your whole team, or agents without MCP, need the rules.

## Version-matched docs

Every package of the ecosystem ships the documentation of its own version for agents in its `agent-docs/` folder, so a package released on its own (`@maz-ui/eslint-config`, `@maz-ui/stylelint-config`, `@maz-ui/upgrade`) is never documented by another version. `maz-ui` also lists the other packages in its index:

```txt
node_modules/maz-ui/agent-docs/
├── README.md                     # index of its pages and of the other packages, start here
├── rules.md                      # the rules below
├── manifest.json                 # machine-readable index, component APIs, tokens
├── components/maz-btn.md         # usage, examples and full API of each component
├── composables/  directives/  plugins/  guide/
└── reference/tailwind-tokens.md  # every Tailwind class and CSS variable of the theme

node_modules/@maz-ui/icons/agent-docs/    # ecosystem/icons.md, reference/icons.md (the 860+ icon names)
node_modules/@maz-ui/themes/agent-docs/   # same layout for each package: README.md, manifest.json, pages
```

The pages are the ones of this website, cleaned for agents: no live demos, every example as code, and the full API of each component (props with their accepted values, `v-model`, events, slots) generated from the TypeScript sources.

Agents read the docs of **your** version, not what they remember from their training data. The MCP server serves the same files.

## MCP server

The MCP server gives agents tools that work with the needs they have, and verify their code:

| Tool | Purpose |
| --- | --- |
| `search_docs` | Find what maz-ui provides for a need ("confirm before delete", "phone input", "debounce search") |
| `get_component_api` | Exact props, values, events, slots of up to 10 components |
| `find_icons` | Icons by meaning ("delete", "settings", "france flag") with their imports |
| `get_theme_tokens` | The theme of your project (preset, `@theme` tokens, variants, utilities) and every Tailwind class and CSS variable of maz-ui |
| `get_doc` | Any page of the docs, or only some sections |
| `list_docs` | The whole catalog |
| `get_setup_guide` | Installation in a Vue or Nuxt app, with or without Tailwind |
| `review_code` | Review files against the installed maz-ui |

See [MCP](https://maz-ui.com/ecosystem/mcp.md) for the configuration of each agent.

## Claude Code plugin

The maz-ui plugin bundles the MCP server, a `maz-ui` skill (rules and workflow) and a hook that reviews every `.vue`, `.ts` and `.css` file Claude edits, so it fixes maz-ui mistakes before you see them.

```txt
/plugin marketplace add LouisMazel/maz-ui
/plugin install maz-ui@maz-ui
```

The plugin works in every project, `init` configures one project for your whole team: use both or either.

### Review hook without the plugin

The review hook of the plugin is the `review --hook` mode of the CLI. To use it alone, add it to `.claude/settings.json` (shared with your team) or `.claude/settings.local.json` (your machine only):

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "npx -y @maz-ui/mcp@latest review --hook", "timeout": 90 }]
      }
    ]
  }
}
```

Each file Claude edits is reviewed; the errors and warnings are sent back to Claude, which fixes them.

## Code review in CI

The checks of `review_code` are also available from the command line:

```bash
npx @maz-ui/mcp review "src/**/*.{vue,ts,css}"
npx @maz-ui/mcp review app --min-severity warning --max-warnings 0
npx @maz-ui/mcp review src --format json
```

The command exits with an error code when it finds errors (or more warnings than `--max-warnings`).

| Rule | Severity | Detects |
| --- | --- | --- |
| `unknown-component` | error | `<MazButton>` (did you mean `MazBtn`?) |
| `unknown-prop` | warning | A prop the component does not have (`colour`) |
| `invalid-prop-value` | error | `color="red"` on a component that accepts `primary`, `secondary`... |
| `boolean-prop-string` | error | `disabled="false"` (a truthy string) |
| `unknown-model`, `unknown-event`, `unknown-slot` | error | `v-model:foo`, `@clik`, `<template #captions>` |
| `unknown-icon` | error | An icon that does not exist in `@maz-ui/icons` |
| `prefer-maz-component` | warning | `<button>`, `<input>`, `<select>`, `<textarea>`, `<dialog>`... (a `<button>` that is a clickable card, with a layout, a component or a title and a subtitle, or an empty hit area, is left alone) |
| `inline-svg` | warning | SVG icons written inline |
| `icon-button-label` | warning | A `MazBtn` that only shows an icon, without `text`, content nor `aria-label` |
| `prefer-ecosystem`, `prefer-utils` | warning / info | lodash, VueUse, toast, icon, tooltip, date picker... libraries that maz-ui already covers |
| `theme-colors` | warning | Default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`) |
| `hardcoded-color` | warning | `bg-[#1d90ff]`, `color: #fff` |
| `internal-prefix` | error | The internal `maz:` prefix |
| `tailwind-v3` | warning | `bg-opacity-50`, `flex-shrink-0`... |
| `missing-reference` | error | `@apply` in a SFC style block without `@reference` |
| `manual-dark-mode` | warning | Dark mode handled by hand instead of `useTheme()` |
| `root-import`, `internal-import` | error | Runtime imports from `maz-ui` (types only) or from `src`/`dist` |
| `nuxt-auto-import` | info | Imports that `@maz-ui/nuxt` already auto-imports |

When something is intended, ignore it with a comment on the line above (`<!-- maz-ui-review-ignore prefer-maz-component -->`, `// maz-ui-review-ignore theme-colors`), or `maz-ui-review-ignore-file` for a whole file. Give the reason after `--`: `<!-- maz-ui-review-ignore theme-colors -- frame over the video -->`.

## llms.txt

The documentation is also published for agents that browse the web:

- [maz-ui.com/llms.txt](https://maz-ui.com/llms.txt): index of every page
- [maz-ui.com/llms-full.txt](https://maz-ui.com/llms-full.txt): the whole documentation in one file
- Each page as markdown: `https://maz-ui.com/components/maz-btn.md`

## The rules

This is what `init`, the Nuxt option, the Claude Code plugin and the MCP server teach to your agents:

This project is built with **maz-ui** and its ecosystem. Reuse what it provides instead of re-implementing it: most UI elements, helpers, icons and styles you need already exist.

### Look it up before you write it

- **MCP server `maz-ui`** (when available): `search_docs` (describe the need: "confirm before delete"), `get_component_api`, `find_icons`, `get_theme_tokens`, `get_doc`, `review_code`.
- **Version-matched docs** in `node_modules/maz-ui/agent-docs/` and `node_modules/@maz-ui/<package>/agent-docs/` (start with `node_modules/maz-ui/agent-docs/README.md`, which lists the other packages; in a monorepo, the packages of the app).

Never guess an API: only use documented props, events, slots and imports.

### Which package for what

`maz-ui` (components, composables, directives, plugins), `@maz-ui/themes` (brand colors, fonts, dark mode), `@maz-ui/icons` (icons, logos, flags), `@maz-ui/utils` (helpers), `@maz-ui/translations` (texts of the components), `@maz-ui/nuxt` (Nuxt module).

### Components

- Use `Maz*` components instead of native elements or hand-made widgets: `MazBtn` (not `<button>`), `MazLink`, `MazInput`, `MazSelect`, `MazCheckbox`, `MazDialog`, `MazDrawer`, `MazPopover`, `MazDropdown`, `MazTabs`, `MazTable`, `MazCard`, `MazAvatar`, `MazBadge`, `MazAlert`, `MazDatePicker`, `MazInputPhoneNumber`, `MazDropzone`, `MazPagination`...
- Prop values are typed: colors are `primary | secondary | accent | info | success | warning | destructive | contrast | transparent` (plus `surface` on some components), sizes `mini | xs | sm | md | lg | xl`.
- A button with only an icon needs an `aria-label`.

### Feedback, overlays and forms

- `useToast()` for notifications, `useDialog()` or `MazDialogConfirm` for confirmations, `useWait()` for loading states, `MazSkeleton` / `MazSpinner` while data loads.
- These composables need their plugin. Vue: `app.use(ToastPlugin)` from `maz-ui/plugins/toast` (`DialogPlugin`, `WaitPlugin`, `AosPlugin` likewise). Nuxt: `mazUi: { plugins: { toast: true } }`, off by default like the directives (`mazUi.directives.vTooltip`, or import the directive).
- Forms: `useFormValidator` / `useFormField` with your Standard Schema library (Zod, Valibot, ArkType).

### Icons

Use `@maz-ui/icons`, never inline SVG nor another icon library. Pick the format by usage:

- **Icon props** (`<MazBtn :start-icon>`, `<MazIcon :icon>`...): the raw SVG string, the lightest, `@maz-ui/icons/raw/MazTrash`.
- **Directly in a template**: the component, `@maz-ui/icons/static/MazTrash`, then `<MazTrash class="size-5 text-muted" />` (size and color from the text: `1em`, `currentColor`).
- **Not visible at first render** (`v-if`, menus, dialogs, tabs): the lazy component, `@maz-ui/icons/lazy/MazTrash`. Never for icons visible on load: each one is an extra request.
- `<img>` or CSS only for multicolor icons (flags, logos): `@maz-ui/icons/svg/<name>.svg`, the text color does not apply there.

### Helpers

Use `@maz-ui/utils/helpers/<name>` and the maz-ui composables instead of lodash, VueUse or hand-written code: `debounce`, `throttle`, `sleep`, `isEqual`, `formatCurrency`, `formatDate`, `formatNumber`, `formatPhoneNumber`, `capitalize`, `normalizeString`, `getCookie` / `setCookie`, `useBreakpoints`, `useWindowSize`, `useTimer`, `useIdleTimeout`, `useSwipe`, `vClickOutside`, `vTooltip`, `vLazyImg`...

### Texts and languages

The texts built in the components come from `@maz-ui/translations`: change the language with `useTranslations().setLocale('fr')` and customize the texts in its options, not in every component.

### Styling with Tailwind

The maz-ui theme is exposed to Tailwind (`@import 'maz-ui/tailwindcss/theme.css'`) and the project usually extends it. Only use theme tokens:

- **Project tokens first**: the Tailwind entry of the project adds its own `@theme` tokens, variants and utilities, and the `definePreset` file sets the brand values. `get_theme_tokens` lists both (or read these files). When a value is missing, add a token to the project `@theme` instead of an arbitrary value.
- Colors: `primary`, `secondary`, `accent`, `info`, `success`, `warning`, `destructive`, `contrast` (each with `-foreground` and `-50` to `-950`), `surface`, `foreground`, `muted`, `divider`, `overlay`, `bg-container`, `bg-input`. Example: `bg-surface text-foreground border-divider`.
- Never the default Tailwind palette (`bg-blue-500`, `text-gray-600`, `bg-white`, `text-black`) nor hard-coded colors (`#fff`, `rgb()`, `bg-[#...]`). Theme colors already adapt to dark mode: no `dark:` color overrides.
- Radius `rounded-*`, shadows `shadow-sm` to `shadow-xl` and `shadow-elevation`, spacing scale (`p-4`, `gap-2`), breakpoints `mob-*`, `tab-*`, `lap-*` (plus `sm` to `2xl`), utilities `flex-center`, `padded-container`.
- **No `maz:` prefix** in this project: it is internal to the maz-ui library.
- In custom CSS, use the variables: `var(--maz-primary)`, `var(--maz-rounded-md)`, `calc(var(--maz-space) * 4)`.

### Theme

Brand colors, fonts, radius and spacing come from a `@maz-ui/themes` preset (`definePreset`), not from overrides scattered in CSS. Use `useTheme()` for dark mode and presets (`toggleDarkMode`, `setColorMode`, `updateTheme`), never toggle the `dark` class or store the mode yourself.

### Imports

- Deep imports: `maz-ui/components/MazBtn`, `maz-ui/composables/useToast`, `maz-ui/directives/vTooltip`, `maz-ui/plugins/toast`, `@maz-ui/utils/helpers/debounce`, `@maz-ui/icons/raw/MazTrash`. The `maz-ui` root entry only exports types. Never import from `maz-ui/src` or `maz-ui/dist`.
- With `@maz-ui/nuxt`, components and composables are auto-imported: do not import them. Icons are not: import them. The theme and the translations are set in the `mazUi` options of `nuxt.config`, not with the `MazUi` Vue plugin.

### Before you finish

Run `review_code` (MCP) on the files you changed, or `npx @maz-ui/mcp review <files>`, and fix every finding.
