@airframeui/mcp

Airframe UI MCP — a stdio server for Cursor, Claude Code, Codex, VS Code, and other hosts. Coding agents look up af-* patterns, --af-* tokens, and validate markup on demand.

It reads the catalogs that ship with @airframeui/core and @airframeui/tokens. search_patterns / get_pattern / get_example also match aliases (app-shell → app, hr → divider).

Theme tools use @airframeui/theme.

MCP does not put CSS on the page. Still install @airframeui/core in the app.

Docs: Airframe for AI agents · airframeui.com/docs/mcp · Changelog

Requires Node.js 24 or later. Keep MCP on the same version as @airframeui/core so lookups match the CSS in the app.

Connect

Treat MCP as optional. Cursor project MCP off, cloud agents, and CI often have no Airframe tools — see Without MCP.

Two ways to run the server when you do connect it. npx works before pnpm install. A dev dependency pins MCP in the lockfile next to core (recommended once the app is installed).

Each host has its own config file. Restart the airframeui server after saving.

| Host | File | | ----------- | --------------------------------------------- | | Cursor | .cursor/mcp.json (or Cursor Settings → MCP) | | Claude Code | .mcp.json | | Codex | .codex/config.toml | | VS Code | .vscode/mcp.json |

Cursor also reads ~/.cursor/mcp.json. Codex also reads ~/.codex/config.toml (project .codex/config.toml only in trusted projects). VS Code uses a top-level servers key, not mcpServers. Codex is TOML, not JSON.

Same mcpServers JSON as Cursor works in Claude Desktop (claude_desktop_config.json), Windsurf, and Gemini CLI (.gemini/settings.json).

npx (default — works before install)

Pin the version in the args so it matches @airframeui/core. @latest can drift.

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "airframeui": {
      "command": "npx",
      "args": ["-y", "@airframeui/[email protected]"]
    }
  }
}

Claude Code — .mcp.json

{
  "mcpServers": {
    "airframeui": {
      "command": "npx",
      "args": ["-y", "@airframeui/[email protected]"]
    }
  }
}

Codex — .codex/config.toml

[mcp_servers.airframeui]
command = "npx"
args = ["-y", "@airframeui/[email protected]"]

VS Code — .vscode/mcp.json

{
  "servers": {
    "airframeui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@airframeui/[email protected]"]
    }
  }
}

Dev dependency (production pin)

Pins MCP in the lockfile next to core:

npm install -D @airframeui/mcp

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "airframeui": {
      "command": "node",
      "args": ["./node_modules/@airframeui/mcp/dist/server.js"]
    }
  }
}

Claude Code — .mcp.json

{
  "mcpServers": {
    "airframeui": {
      "command": "node",
      "args": ["./node_modules/@airframeui/mcp/dist/server.js"]
    }
  }
}

Codex — .codex/config.toml

[mcp_servers.airframeui]
command = "node"
args = ["./node_modules/@airframeui/mcp/dist/server.js"]

VS Code — .vscode/mcp.json

{
  "servers": {
    "airframeui": {
      "type": "stdio",
      "command": "node",
      "args": ["./node_modules/@airframeui/mcp/dist/server.js"]
    }
  }
}

Use

Ask the coding agent for Airframe markup. It should follow this loop:

search_patterns → get_pattern → get_example → compose af-* → validate_markup

The UI language is Structure → Patterns → Blocks → Blueprints. Blocks (llms-blocks.txt) and blueprints are guides. Start from one when it is close, then edit it.

Lookup on demand. get_pattern is dense by default. When present, read useCases / guidelines / criteria (must* are hard; follow useInstead / prefer). Do not dump catalogs. Do not invent af-* or --af-* names, a parallel look, or pattern CSS. Compose existing Airframe.

Tools

| Tool | Use | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | search_patterns / get_pattern / get_example | Patterns, structure, and guide ids (blocks/blueprints → docsUrl). Dense get_pattern includes useCases, guidelines, criteria | | validate_markup | Unknown af-* / --af-*, plus htmlSemantics (E/W HTML rules; issues include ruleId) | | search_tokens / get_token | Unsuffixed --af-* names | | generate_theme / lint_theme | Map a foreign token set |

Skip list_patterns / list_tokens unless you need an inventory. map_tokens / validate_theme are available if you need a spec without full generate+lint.

Resources: airframe://ai (short loop), airframe://rules (full contract), airframe://theme/rules (theme mapping).

Without MCP

If Airframe tools are not connected, do not guess docs URLs. Read the files that ship with @airframeui/core:

1. component-catalog.json (@airframeui/core/catalog) — pattern id, classes, guidance, useCases / guidelines / criteria, docsUrl, htmlSemantics
2. examples.json (@airframeui/core/examples)
3. dist/patterns/<id>.css when the example is not enough
4. breaking.json (@airframeui/core/breaking) — version-to-version import/catalog renames (layouts.css → structure.css)

Pattern pages: https://airframeui.com/docs/patterns/{catalogId} (skip, nav-collapse). That short URL redirects to the nested docs page.

Versioning

Fixed group with @airframeui/core, @airframeui/tokens, @airframeui/theme, @airframeui/mcp, @airframeui/build, @airframeui/eslint-plugin, and IntelliSense for Airframe.

Related

• @airframeui/core — CSS system (install this in the app)
• @airframeui/tokens — token catalog (installed with core)
• @airframeui/theme — generate and lint --af-* CSS from a foreign token file
• @airframeui/build — optional PostCSS plugin, af CLI, and af init --agents (static agent file; complementary to this server)
• Airframe for AI agents — vocabulary, composition, catalogs, endpoints
• Packages
• Changelog

License

MIT