npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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/mcp

Project Installation

npm install --save-dev @optiaxiom/mcp
# or
pnpm add -D @optiaxiom/mcp

A 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@latest

Or 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@latest

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

Architecture

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 description field
  • Grouping and versioning use JSDoc tags (@group and @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 Table groups 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 as Locale (imported from @optiaxiom/react/locale/en) and DialogKit (returned by createDialogKit()). 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 by get_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: