Ama Styling MCP
[!WARNING] Experimental
Description
An MCP (Model Context Protocol) server that exposes design token metadata to AI assistants for token discovery and recommendation.
It reads a styling.metadata.json file and provides tools for listing, filtering, and finding the best design tokens to use in CSS.
Tools
| Tool | Description |
|---|---|
list_design_tokens | List available design tokens with their descriptions, values, types, categories, and tags. Supports optional filtering by category, tag, type, or name pattern (regex). |
find_design_token | Given a CSS property and semantic context, recommends the best matching design tokens to use instead of hardcoded values. |
How to use with VSCode
To add the Design Tokens MCP server, you should first activate MCP with "chat.mcp.enabled": true.
Then, in your .vscode/mcp.json add:
{
"AmaStyling": {
"type": "stdio",
"command": "npx",
"args": [
"-y", "-p", "@ama-styling/mcp", "ama-styling-mcp-start",
"--metadata", "./path/to/styling.metadata.json"
],
"env": {
// Help us improve Otter by setting this to true.
// More details on our privacy policy: https://github.com/AmadeusITGroup/otter/blob/main/PRIVACY.md
"O3R_METRICS": true
}
}
}
CLI Options
| Option | Description | Default |
|---|---|---|
-m, --metadata <path> | Path to the styling.metadata.json file | ./styling.metadata.json |
--cache-path <path> | Path to the cache file | .cache/@ama-styling/mcp |
--log-level <level> | Log level: debug, info, warn, error | info |
Metadata file format
The server expects a JSON file with the following structure:
{
"variables": {
"--color-primary": {
"name": "--color-primary",
"defaultValue": "#3b82f6",
"type": "color",
"category": "brand",
"tags": ["primary", "interactive"],
"description": "Primary brand color for interactive elements",
"label": "Primary Color"
}
}
}
Each variable entry supports:
| Field | Type | Description |
|---|---|---|
name | string | CSS custom property name (required) |
defaultValue | string | Default value for the variable (required) |
type | "color" | "string" | Value type |
category | string | Token category |
tags | string[] | Categorization tags |
description | string | Human-readable description |
label | string | Display label |
references | CssVariable[] | Other tokens this variable references |
component | { library, name } | Component association |
[!NOTE] This metadata file is typically generated by the
@ama-styling/style-dictionarypackage as part of the design token build pipeline.