# Pixso MCP Server

[简体中文](./README.zh-CN.md)

Bring Pixso design context into your AI coding workflow. Pixso MCP Server helps
AI assistants understand design layers, component variants, variables, and local
styles so they can answer design questions and produce implementation-ready code.

## What you can do

- Turn a selected Pixso layer into React, Vue, HTML/CSS, or other frontend code.
- Inspect layout, hierarchy, text, fills, typography, effects, and other layer details.
- Understand every state and property combination in a component variant set.
- Extract design variables and variable groups for design-token workflows.
- Review local color, text, effect, and grid styles from a design file.
- Compare an implementation with its design source or generate theme configuration.

## Available tools

| Tool | What it provides | Required input |
| --- | --- | --- |
| `get_node_dsl` | Structured details for a selected layer, including its hierarchy, layout, content, and visual properties. This is the main tool for design-to-code tasks. | `file_key`, `guid` |
| `get_variants` | All variants associated with a component set, a variant component, or an instance whose main component belongs to a variant set. | `file_key`, `guid` |
| `get_variable_sets` | The variable groups defined in a design file, useful for understanding its token organization. | `file_key` |
| `get_variables` | Design variables associated with the selected layer, such as reusable colors, spacing, sizes, and other token values. | `file_key`, `guid` |
| `get_local_styles` | Reusable local styles defined in the file, including color, text, effect, and grid styles. | `file_key` |

You normally do not need to choose a tool yourself. Share a Pixso link and tell
your AI assistant what you want; it can select the appropriate tool.

## Requirements

- Node.js 20 or newer
- A Pixso account and valid Pixso Token
- An MCP-compatible AI coding client

## Configure your MCP client

Add the following server entry to your MCP client configuration:

```json
{
  "mcpServers": {
    "pixso": {
      "command": "npx",
      "args": [
        "-y",
        "@pixso/pixso-stdio-mcp",
        "--token",
        "YOUR_PIXSO_TOKEN"
      ]
    }
  }
}
```

Replace `YOUR_PIXSO_TOKEN` with your Pixso Token, then restart or reconnect the
server in your MCP client. The default Pixso URL is `https://pixso.cn/api/mcp/mcp`.

### Private or custom Pixso deployment

If your organization uses another Pixso deployment, add its complete MCP URL:

```json
{
  "mcpServers": {
    "pixso": {
      "command": "npx",
      "args": [
        "-y",
        "@pixso/pixso-stdio-mcp",
        "--url",
        "https://example.pixso.cn/api/mcp/mcp",
        "--token",
        "YOUR_PIXSO_TOKEN"
      ]
    }
  }
}
```

Keep your Token private. Do not commit a real Token to a repository or include it
in screenshots, logs, or issue reports.

## Use a Pixso design link

Copy a link to the layer you want the AI assistant to inspect. A layer link looks
like this:

```text
https://{pixso-domain}/app/design/{file_key}?item-id={guid}
```

- `file_key` identifies the design file.
- `item-id` is the layer `guid` used by layer-specific tools.
- `page-id` is not a layer `guid`. For layer-specific tasks, share a link that
  contains `item-id`.

File-level tools such as `get_variable_sets` and `get_local_styles` only need the
design file and can work without a selected layer.

## Example requests

```text
Implement this Pixso layer as a React component using Tailwind CSS:
https://pixso.cn/app/design/FILE_KEY?item-id=LAYER_GUID
```

```text
Analyze all variants of this button component and generate its TypeScript props.
```

```text
Extract the variables and local styles from this design file and generate CSS
custom properties for the project theme.
```

```text
Explain the layout, typography, colors, and spacing used by this selected layer.
```

## License

MIT