npm package: @giro-ds/mcp
Description: Model Context Protocol (MCP) server for Giro Design System — enables AI tools to access component metadata, design tokens and migration guides.
Latest version: 1.0.0

# @giro-ds/mcp

Model Context Protocol (MCP) server for Giro Design System — enables AI tools (GitHub Copilot, Cursor, Claude Desktop) to access component metadata, design tokens and migration guides directly.

## Tools

| Tool | Description |
|------|-------------|
| `list-giro-components` | Lists all public `@giro-ds/react` component names |
| `get-giro-component-metadata` | Returns props, types, defaults and descriptions for a component |
| `get-giro-component-examples` | Returns React usage examples for components |
| `list-giro-tokens` | Lists all design tokens from `@giro-ds/tokens` with filtering support |
| `giro-migration-guide` | Returns the breaking changes and migration guide between major versions |
| `find-giro-component` | Semantic search for components by description in PT-BR or EN |
| `review-giro-usage` | Analyzes a JSX/TSX snippet for invalid props, missing required props and outdated patterns |
| `review-giro-css` | Audits CSS/SCSS or inline `style={{}}` for hardcoded values that should be tokens |
| `resolve-giro-token` | Returns the most suitable tokens for a design intent (e.g. `"error color"`, `"large spacing"`) |
| `generate-giro-component` | Generates a ready-to-use JSX/TSX snippet from a description in PT-BR or EN |
| `get-giro-system-prompt` | Returns a system prompt that makes any AI aware of Giro DS |
| `get-giro-changelog` | Lists deprecated APIs with version, affected prop and suggested replacement |

## Usage

### VS Code (GitHub Copilot)

When you install `@giro-ds/mcp` as a dependency, a `.vscode/mcp.json` is created automatically in your project root — no manual setup needed.

If you prefer to configure it manually, or if you're using `npx` (without installing):

<details>
<summary>Manual configuration</summary>

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "giro-ds": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@giro-ds/mcp"]
    }
  }
}
```

</details>

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "giro-ds": {
      "command": "npx",
      "args": ["-y", "@giro-ds/mcp"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "giro-ds": {
      "command": "npx",
      "args": ["-y", "@giro-ds/mcp"]
    }
  }
}
```

### Local development (monorepo)

```json
{
  "servers": {
    "giro-ds": {
      "type": "stdio",
      "command": "node",
      "args": ["packages/mcp/dist/index.js"]
    }
  }
}
```

## Tool Examples

### List all components
```
list-giro-components
```

### Get Button metadata
```
get-giro-component-metadata name="Button"
```

### Get Drawer examples
```
get-giro-component-examples name="Drawer"
```

### Find a component by description
```
find-giro-component query="modal de confirmação"
```

### List color tokens
```
list-giro-tokens category="color-brand"
```

### List spacing tokens
```
list-giro-tokens category="spacing"
```

### Resolve a token by design intent
```
resolve-giro-token intent="cor de erro"
```

### Review a code snippet
```
review-giro-usage code="<Button variant='ghost' size='xl'>Save</Button>"
```

### Audit CSS for hardcoded values
```
review-giro-css code="color: #3b45f2; padding: 16px;"
```

### Generate a component from a description
```
generate-giro-component description="formulário de login com email, senha e botão de entrar"
```

### Get a system prompt for ChatGPT / Claude
```
get-giro-system-prompt
```

### Get migration guide
```
giro-migration-guide
```

### List deprecated APIs for a component
```
get-giro-changelog component="Dialog"
```

## Development

### Generate component metadata

Component metadata is auto-generated from `*.types.ts` files in `@giro-ds/react` using `ts-morph`:

```bash
pnpm --filter @giro-ds/mcp generate
pnpm --filter @giro-ds/mcp build
```

### Generate token data

Token data is auto-generated from the `@giro-ds/tokens` CSS build output:

```bash
pnpm --filter @giro-ds/tokens build
pnpm --filter @giro-ds/mcp generate:tokens
pnpm --filter @giro-ds/mcp build
```

Run these commands whenever a component or token is added or changed.