@optiaxiom/mcp
v3.5.0
Published
MCP server for Axiom Design System - enables AI assistants to generate accurate Axiom code
Readme
@optiaxiom/mcp
MCP (Model Context Protocol) server for Axiom Design System. This server enables AI assistants like Claude Code and Cursor to access accurate component metadata, generating better code using the Axiom design system.
What is MCP?
Model Context Protocol (MCP) is an open protocol by Anthropic that allows AI assistants to securely connect to external data sources and tools. This MCP server exposes Axiom's component library metadata to AI coding assistants.
Features
- Component Metadata: Detailed information about all Axiom components including props, types, and descriptions
- Search & Discovery: Find components by name, keywords, or category
- Usage Patterns: Real-world code examples showing how components work together
- Design Tokens: Access to the complete design token system for Figma-to-code workflows
- Setup Guides: Markdown guides for getting started, CSS configuration, and icon usage
- Fast & Lightweight: Pre-generated metadata with instant response times
Important Note
All Axiom components are installed via a single npm package: @optiaxiom/react
Installation
Global Installation
npm install -g @optiaxiom/mcp
# or
pnpm add -g @optiaxiom/mcpProject Installation
npm install --save-dev @optiaxiom/mcp
# or
pnpm add -D @optiaxiom/mcpA global or project install stays on the version you installed, and its docs fall behind each release. Rerun the install to update it.
Usage
Claude Code
Add the server to your project with the Claude Code CLI:
claude mcp add --scope project axiom -- npx -y @optiaxiom/mcp@latestOr add it to .mcp.json at the root of your project yourself:
{
"mcpServers": {
"axiom": {
"command": "npx",
"args": ["-y", "@optiaxiom/mcp@latest"]
}
}
}Check .mcp.json into the repository so every contributor and agent working in it gets the server. Claude Code asks each of them to approve it the first time it starts in the project.
The @latest tag in these configurations makes npx check for a new release each time the server starts, so the server's docs keep up with @optiaxiom/react even when an older copy is installed in the project or globally.
Cursor
Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:
{
"mcpServers": {
"axiom": {
"command": "npx",
"args": ["-y", "@optiaxiom/mcp@latest"]
}
}
}VS Code
Add to .vscode/mcp.json in your project:
{
"servers": {
"axiom": {
"command": "npx",
"args": ["-y", "@optiaxiom/mcp@latest"]
}
}
}Standalone Usage
You can also run the server directly:
npx @optiaxiom/mcp@latestEmbedding in a host
Importing the package has no side effects. Call createServer() to get an McpServer with every tool registered and connect it to your own transport. Each call returns an independent instance, so HTTP hosts should create one per request:
import { createServer } from "@optiaxiom/mcp";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
app.post("/mcp", async (req, res) => {
const server = createServer();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
res.on("close", () => {
transport.close();
server.close();
});
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});Troubleshooting
If your assistant doesn't use the Axiom tools, check that the server started: run /mcp in Claude Code, or check the server's status in Cursor's settings.
npx downloads the server through the npm registry your project's .npmrc points to. If that is a private registry that needs a token, the download fails once the token is missing or expired, and the server doesn't start. Pin the public registry in the server's arguments:
{
"mcpServers": {
"axiom": {
"command": "npx",
"args": [
"-y",
"--registry",
"https://registry.npmjs.org",
"@optiaxiom/mcp@latest"
]
}
}
}Server Instructions
The server's instructions name the @optiaxiom/react release its data was generated from. They tell the assistant that when the project's types reject a documented component or prop, the project may be behind, and to offer an upgrade before building a workaround; and that when the project is newer, a newer @optiaxiom/mcp may document what's missing.
Available Tools
The MCP server provides the following tools that AI assistants can use:
get_component
Get information about an Axiom component. Returns the component's description, import statement, sub-components, and accessibility notes by default — no props. Use the optional props parameter to search for specific props by name or description.
Parameters:
name(string, required): Component name (e.g., "Badge", "Button", "Alert")props(string, optional): Search query to find specific props by name or description (e.g., "appearance size", "loading", "padding background"). Omit to get just the component description, import, and sub-components without any props.
Returns: Component metadata with description, import statement, sub-components, examples, since (the @optiaxiom/react release that added the component), accessibility (the ## Accessibility section of the component's own docs page, so a sub-component documented on its group's page has none; a ### Accessibility subsection isn't picked up), prop names or, with props, the matching prop definitions, and a required list of every prop that must be passed, whether or not props matched it (omitted when there are none). With props, a note explains the definition format, which the tool description leaves out to stay small: prop definitions use JSON Schema keywords (type, enum, anyOf, items, default, description), and object-typed props such as options list their fields under properties with a required list; tsType holds the TypeScript type where JSON Schema can't express it (functions, ReactNode, generics). Props that accept per-breakpoint values ({ base, sm, md } or [base, sm, md]) are marked responsive: true.
search_components
Search Axiom components by name, description, or keywords. Returns matching components.
Parameters:
query(string, optional): Search query (component name, keyword, or description). Leave empty to browse all components or all components in a category.category(string, optional): Filter by category (e.g., "form", "layout", "navigation", "feedback", "overlay", "data-display", "actions", "typography")limit(number, optional): Maximum results to return (default: 5)
Returns: List of matching components with names, descriptions, and import statements.
get_patterns
Find usage examples showing how Axiom components work together. Returns real working examples from the docs that demonstrate component composition patterns.
Parameters:
components(string, required): Space-separated component names to find patterns for (e.g., "Field Input Button"). Returns examples that use these components together.query(string, optional): Search example titles and the docs headings and prose that introduce them (e.g., "addon", "filter", "empty").limit(number, optional): Maximum number of examples to return (default: 5, max: 10)
Returns: Array of matching examples with code (filename → file contents) and title. Query matches rank first, then examples using more of the requested components; each requested component's own usage demo follows the top result.
get_tokens
Get design token mappings for the Axiom Design System.
Parameters:
categories(string[], optional): Filter to specific token categories (e.g.,["colors", "boxShadow"]). Returns all categories if omitted. Valid values:borderRadius,boxShadow,breakpoints,colors,duration,fontFamily,fontSize,maxSize,size,zIndex.
Returns: Token-to-value mappings for the requested categories. breakpoints holds the min-widths that responsive props' sm and md keys switch at. Useful for converting Figma design values to semantic tokens (e.g., #4F576E → fg.secondary, 32px height → h='md'). For how to consume tokens in code (style props, CSS variables, or the theme object), the description points callers at get_guides({ names: "design-tokens" }).
search_icons
Search for icons from the @optiaxiom/icons package.
Parameters:
query(string, required): Search query (icon keyword or name, e.g., "message", "arrow", "user")limit(number, optional): Maximum results to return (default: 10)
Returns: List of matching icon components with names and import statements.
get_tests
Get vetted reference test files showing the repo's testing conventions (the custom vitest.rtl render helper, role/name queries, accessibility assertions). For end-to-end (Playwright) locators, the description points callers at get_guides({ names: "test-environments" }).
Parameters:
components(string, optional): Space-separated component names to find reference tests for (e.g.,"Alert Button"). Omit to list all available reference tests.limit(number, optional): Maximum number of reference tests to return when searching by component (default: 5). Ignored when listing all tests.
Returns: The matching reference tests (with source) plus a helper note describing the vitest.rtl render helper. Listing (no components) returns every test, names only.
get_guides
Get setup, configuration, and integration guides for the Axiom Design System.
Parameters:
names(string, optional): Space-separated guide names to fetch (e.g.,"css-imports css-layers"). Omit to list all available guides (names + titles).
Returns: When names is omitted, the list of available guides (name + title). When names is provided, the markdown content for each requested guide, plus the full list of available guide names so an invalid name self-corrects.
The available guides are derived at build time from the guides section of the docs nav manifest (apps/docs/app/_meta.global.tsx) — every page listed there is surfaced automatically (separators, hidden pages, and a small exclusion list are skipped). At time of writing: getting-started, css-imports, colors, design-tokens, typography, fonts, icons, responsive-styles, css-layers, nested-overlays, module-federation, test-environments, group-migration. Run get_guides() for the current list.
The docs props/ section (one page per style prop) is not surfaced — resolved values are served by get_tokens instead. When a guide is surfaced, its <Demo> examples are inlined as fenced code blocks and its <Scale> value tables are dropped.
Example Interactions
Once configured, you can ask your AI assistant:
- "Show me how to use the Badge component"
- "Search for form components"
- "Create a form with Input and Button components from Axiom"
- "What navigation components are available?"
- "Show me patterns for Field and Select together"
- "What design tokens are available for colors?"
- "Convert this Figma color #4F576E to an Axiom token"
- "Show me the getting started guide for Axiom"
- "Search for message icons" (Optimizely staff only)
- "Find arrow icons" (Optimizely staff only)
The AI assistant will use the MCP server to get accurate, up-to-date information about Axiom components, tokens, and setup instructions.
Development
Building
pnpm -F mcp... buildArchitecture
Component Metadata Generation
The MCP server serves pre-generated component metadata that is automatically extracted from the @optiaxiom/react package at build time:
- Component descriptions come from JSDoc comments on component exports (e.g.,
packages/react/src/table/Table.tsx) - Props and types are extracted from TypeScript definitions
- Examples are pulled from demo files in
apps/docs/demos/, with the heading and prose each sits under on its docs page (apps/docs/app/**/page.mdx) - Usage warnings are embedded in JSDoc and automatically included in the
descriptionfield - Grouping and versioning use JSDoc tags (
@groupand@since)
All data is bundled into the published package — there is no filesystem or network I/O at runtime.
The generated metadata is committed to the repo as src/data.json and re-verified in CI with
git diff --exit-code. Any change to an upstream source (a @optiaxiom/react component, a
@optiaxiom/globals token, a @optiaxiom/icons icon, or the prose around a <Demo> on a docs page) therefore requires you to rebuild
(pnpm -F mcp... build), commit the regenerated src/data.json, and add an @optiaxiom/mcp patch
changeset — otherwise the CI diff check fails.
Important: When adding warnings or guidance about component usage, add them to the component's JSDoc comment rather than the MCP server code. This ensures the information is:
- Visible in IDEs (hover tooltips)
- Included in generated documentation
- Automatically served by the MCP server
- Maintained in a single source of truth
JSDoc Tags
Use these tags in component JSDoc comments:
@group: Groups related components together (e.g.,@group Tablegroups Table, TableRow, TableCell, etc.)@since: Documents the version when the component was introduced (e.g.,@since 1.4.0)@experimental: Marks components as experimental/unstable@docs opaque: Goes on a type rather than a component. Props and fields of that type show its name instead of its fields. Use it for types consumers get from the library and pass along rather than build themselves, such asLocale(imported from@optiaxiom/react/locale/en) andDialogKit(returned bycreateDialogKit()). Other object types the library owns are described field by field.@deprecated: Marks a component as deprecated and points to its replacement. Follow the pattern@deprecated since <version> use {@link Replacement} instead— the version and the{@link}replacement are parsed out and surfaced byget_component(and should steer the AI away from the deprecated component). Pair with@see Replacement.
Example:
/**
* Display tabular data using rows and columns.
*
* @group Table
* @since 1.4.0
*/
export const Table = ...Deprecation example:
/**
* Display a dropdown menu.
*
* @since 0.1.0
* @deprecated since 1.6.0 use {@link Menu} instead
* @see Menu
*/
export function DropdownMenu(...) { ... }Resources
Contributing
Contributions are welcome! Please see the main repository for contribution guidelines.
License
Apache-2.0
Support
For issues and questions:
