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.

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/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:

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)

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.

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.

Options

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: connected by default

With @maz-ui/nuxt, the agents detected in the project are connected to the maz-ui MCP server when you start the dev server: the module only 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, so no rule file is written by default.

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

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).

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).

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

Version-matched docs

Each maz-ui release ships its documentation for agents in node_modules/maz-ui/docs/:

node_modules/maz-ui/docs/
├── README.md                     # index of every page, start here
├── rules.md                      # the rules below
├── manifest.json                 # machine-readable index, component APIs, icons, tokens
├── components/maz-btn.md         # usage, examples and full API of each component
├── composables/  directives/  plugins/  guide/
├── ecosystem/                    # themes, translations, icons, nuxt, utils, node...
└── reference/
    ├── tailwind-tokens.md        # every Tailwind class and CSS variable of the theme
    └── icons.md                  # the 860+ icon names

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 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.

/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):

{
  "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:

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>...
inline-svg	warning	SVG icons written inline
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: index of every page
• 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 (@maz-ui/themes, @maz-ui/icons, @maz-ui/utils, @maz-ui/translations, @maz-ui/nuxt). 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

Before creating a component, composable, helper, icon or style, check what maz-ui offers:

• MCP server maz-ui (when available): search_docs (describe the need: "confirm before delete", "phone input"), get_component_api (exact props, events, slots), find_icons, get_theme_tokens (Tailwind classes of the project and of maz-ui), get_doc, review_code.
• Version-matched docs in node_modules/maz-ui/docs/ (start with README.md; in a monorepo, resolve maz-ui from the app package). Read the relevant page before using an API.

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

Components

• Use Maz* components instead of native elements or hand-made widgets: MazBtn (not <button>), MazInput, MazSelect, MazCheckbox, MazSwitch, MazTextarea, MazDialog, MazDialogConfirm, MazDrawer, MazBottomSheet, MazPopover, MazDropdown, MazTabs, MazTable, MazCard, MazAvatar, MazBadge, MazAlert, MazSkeleton, MazSpinner, MazDatePicker, MazInputPhoneNumber, MazDropzone, MazStepper, MazSidebar, 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.
• Feedback and overlays: useToast() for notifications, useDialog() or MazDialogConfirm for confirmations, useWait() for loading states.
• Forms: useFormValidator / useFormField with your Standard Schema library (Zod, Valibot, ArkType).

Icons

Use @maz-ui/icons (860+ icons: MazTrash, MazXMark, MazMagnifyingGlass, MazFlagFR, MazLogoVue...). Never inline SVG or add another icon library. Pass icon components to icon props: <MazBtn :start-icon="MazTrash">.

Helpers and composables

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

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 (the CSS file that imports maz-ui/tailwindcss/theme.css) adds its own @theme tokens (fonts, animations, colors...), @custom-variant and @utility, and the definePreset file sets the brand values of the maz-ui tokens. get_theme_tokens lists both; without the MCP server, read these files. When a value is missing, add a token to the project @theme and use its class 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, plus bg-container and bg-input. Example: bg-surface text-foreground border-divider, bg-primary text-primary-foreground, text-muted.

• Never use 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: do not add 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 and its documentation.

• 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/utils/helpers/debounce, @maz-ui/icons/static/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.

Before you finish

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