Skip to content
EspañolEnglish

MCP server

@amset/mcp is a local MCP server that gives your coding assistant (Claude Code, Cursor and any MCP client) eight tools to work with @amset/ui without making anything up. It runs on your machine, offline, and reads the version of the library that your project has installed: what it answers is what you will be able to import.

What it gives your assistant

Every tool reads from the installed package; none of them ships its own copy of the library.

search_components

Finds components by what you need ("date", "upload a file", "table with filters"), in their name and their sheet. To land on the right component without knowing what it is called.

get_component_schema

The real props of a component, taken from the compiler: type, whether it is required and what it is for. If the name does not exist, it suggests the closest one ("Did you mean Button?").

get_component_examples

The real usage code of a component, extracted from its test-bench stories by the library build. Never written by hand.

validate_code_snippet

Compiles a snippet with TypeScript against the installed library: the only reliable way to know an import, a prop or a type is right.

search_icons

Searches the 2,000+ icons by English words ("cart", "trash", "arrow down"), so nobody has to guess the exact name.

search_utilities

Searches the hooks, functions and constants the library exports ("money", "day", "aria"), so nothing that already exists gets reinvented.

get_design_tokens

The geometry and typography tokens, the colour roles in light and dark, and the CSS variables of every component.

generate_theme_from_hex

Generates the light and dark theme from your brand colours, and refuses a palette that fails the minimum contrast: the same rule as npx amset-ui theme.

Install

It lives in the same AMSET package registry as the library. One line in the project .npmrc covers both packages, and the read token goes in yours:

.npmrc
# project .npmrc (no token: that never gets committed)@amset:registry=https://gitlab.amset.tech/api/v4/packages/npm/
~/.npmrc
# ~/.npmrc, your own, outside the repository//gitlab.amset.tech/api/v4/:_authToken=YOUR_TOKEN

The token goes on /api/v4/ rather than on the registry address because each package is downloaded from its own project path: with the token only on the registry, the lookup works and the download returns 401.

Then, in the project that uses @amset/ui:

Code
npm i -D @amset/mcp

Connect it

Claude Code, from the project folder:

Code
claude mcp add --scope project amset-ui -- npx amset-mcp

That leaves a .mcp.json in the project that you can commit for the whole team:

.mcp.json
{  "mcpServers": {    "amset-ui": {      "type": "stdio",      "command": "npx",      "args": [        "amset-mcp"      ]    }  }}

Cursor, Claude Desktop and every other MCP client: the same entry (command and args) in their configuration. The server looks for @amset/ui from the folder it starts in, so it has to be launched from the project folder.

What it needs

  • A project with @amset/ui from 0.9.0 to 0.14, and Node.js 18 or later. With 0.17 or later, see the notice above.
  • get_component_examples needs @amset/ui 0.11.0 or later, the first release that publishes its examples. With an older one it says so and invents none.
  • validate_code_snippet compiles with your project types: it needs @types/react, like any React project with TypeScript.

Errors, never made up

If the component, the prop or the colour does not exist, the tool answers with the real reason (the library is not installed, the colour cannot be parsed, the palette fails contrast, the installed version does not ship examples) instead of filling the gap with something that looks right.