# carbon-mcp

Local MCP (Model Context Protocol) server for the Carbon Design System — Advanced MVP for internal demos and production use.

## 🚧 Status: Proposal Submitted to Carbon

This project is a **proposal** submitted to the [Carbon Design System](https://carbondesignsystem.com/) repository.

- **Issue**: [#20855](https://github.com/carbon-design-system/carbon/issues/20855)
- **Status**: Awaiting maintainer feedback
- **Proposed**: Add to Carbon monorepo or create official `carbon-design-system/carbon-mcp` repository

The Carbon team is reviewing this proposal. Once feedback is received, the code will be adapted accordingly.

---

## 🚀 Quickstart

1. **Clone repo**
   ```bash
   git clone https://github.com/SandeepBaskaran/carbon-mcp.git
   cd carbon-mcp
   ```

2. **Install dependencies**
   ```bash
   npm install
   # or
   pnpm install
   ```

3. **Configure environment** (optional)
   ```bash
   cp .env.example .env
   # Edit .env to add API keys if needed (FIGMA_TOKEN, GITHUB_TOKEN)
   ```

4. **Start the server**
   ```bash
   npm run dev
   ```
   Server will start on `http://localhost:4000`

5. **Test it out**
   ```bash
   # List available tools
   curl http://localhost:4000/tools
   
   # Generate a component (dry-run)
   curl -X POST http://localhost:4000/tool/generateComponent \
     -H "Content-Type: application/json" \
     -d '{"component_name": "PrimaryCard", "dry_run": true}'
   ```

## 🛠️ Tools (MVP)

### Developer Tools

- **`generateComponent`** — Generate Carbon React component + Storybook story + tests (dry-run default)
- **`codemodReplace`** — Apply codemods to convert existing components to Carbon equivalents (dry-run default)
- **`validateComponent`** — Validate component against Carbon patterns and accessibility guidelines
- **`tokenConverter`** — Convert design tokens (JSON) to CSS variables, SCSS maps, and JS tokens

### Documentation Tools

- **`searchDocs`** — Search local Carbon docs index with semantic/keyword matching

### Designer Tools

- **`themePreview`** — Generate static HTML previews for Carbon theme variants (light/dark/custom)
- **`figmaSync`** — Scaffold for Figma token sync (requires FIGMA_TOKEN in environment)

## 🔒 Safety & Destructive Operations

All destructive changes (writing to disk, modifying files) require:

- `confirm_destructive: true`
- `dry_run: false`

**Recommended workflow:**
1. Run with `dry_run: true` (default) to preview changes
2. Review the output/patches
3. Run again with `dry_run: false` and `confirm_destructive: true` to apply

### Example: Generate Component (Safe Workflow)

```bash
# Step 1: Dry-run to preview
curl -X POST http://localhost:4000/tool/generateComponent \
  -H "Content-Type: application/json" \
  -d '{
    "component_name": "PrimaryCard",
    "dry_run": true,
    "explain": true
  }'

# Step 2: Apply changes
curl -X POST http://localhost:4000/tool/generateComponent \
  -H "Content-Type: application/json" \
  -d '{
    "component_name": "PrimaryCard",
    "dry_run": false,
    "confirm_destructive": true
  }'
```

## 📚 API Reference

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| GET | `/tools` | List all available tools |
| GET | `/tool/:name/schema` | Get schema for specific tool |
| POST | `/tool/:name` | Execute a tool |

### Tool Examples

#### 1. Generate Component

```json
POST /tool/generateComponent
{
  "component_name": "PrimaryCard",
  "props": {
    "compact": "boolean",
    "icon": "string"
  },
  "target_path": "src/components/PrimaryCard",
  "dry_run": true,
  "explain": true
}
```

**Response:**
```json
{
  "files": [
    {
      "path": "src/components/PrimaryCard/PrimaryCard.tsx",
      "content": "import React from 'react'..."
    }
  ],
  "changed_files": [],
  "dry_run": true,
  "logs": [...],
  "trace_id": "genc-1234567890",
  "explanation": "Generated Carbon React component..."
}
```

#### 2. Codemod Replace

```json
POST /tool/codemodReplace
{
  "codemod_name": "btn-old-to-carbon",
  "files_glob": "src/**/*.{tsx,jsx}",
  "dry_run": true
}
```

**Response:**
```json
{
  "dry_run_result": "3 files would be modified",
  "patches": [
    {
      "file": "src/pages/Home.tsx",
      "patch": "@@ -1,6 +1,6 @@..."
    }
  ],
  "changed_files": ["src/pages/Home.tsx"],
  "logs": [...],
  "trace_id": "codemod-1234567890"
}
```

#### 3. Search Docs

```json
POST /tool/searchDocs
{
  "query": "Carbon Button aria roles",
  "k": 5
}
```

**Response:**
```json
{
  "results": [
    {
      "title": "Button — Carbon React",
      "path": "docs/components/button.md",
      "snippet": "The Button component supports kinds: primary, secondary...",
      "score": 0.98
    }
  ],
  "logs": [...],
  "trace_id": "search-1234567890"
}
```

#### 4. Token Converter

```json
POST /tool/tokenConverter
{
  "input_path": "tokens/tokens.json",
  "outputs": ["css_vars", "scss_map", "js_tokens"],
  "output_dir": "tokens",
  "dry_run": true
}
```

#### 5. Validate Component

```json
POST /tool/validateComponent
{
  "file_path": "src/components/MyButton/MyButton.tsx",
  "rules": ["props", "accessibility", "tokens"]
}
```

**Response:**
```json
{
  "valid": false,
  "errors": [],
  "warnings": [
    {
      "type": "warning",
      "rule": "accessibility",
      "message": "Icon-only buttons should have aria-label"
    }
  ],
  "logs": [...],
  "trace_id": "validate-1234567890"
}
```

#### 6. Theme Preview

```json
POST /tool/themePreview
{
  "themes": ["white", "g10", "g90", "g100"],
  "output_path": "theme-previews",
  "dry_run": true
}
```

## 🔧 Development

### Project Structure

```
carbon-mcp/
├── src/
│   ├── server/
│   │   ├── index.ts                 # Server bootstrap
│   │   ├── toolRegistry.ts          # Tool registration
│   │   └── tools/                   # Tool handlers
│   │       ├── generateComponent.ts
│   │       ├── codemodReplace.ts
│   │       ├── searchDocs.ts
│   │       ├── tokenConverter.ts
│   │       ├── validateComponent.ts
│   │       ├── themePreview.ts
│   │       └── figmaSync.ts
│   ├── lib/                         # Utilities
│   │   ├── logger.ts
│   │   ├── fileUtils.ts
│   │   ├── templateUtils.ts
│   │   ├── codemodUtils.ts
│   │   ├── diffUtils.ts
│   │   └── tokenUtils.ts
│   ├── schemas/                     # JSON schemas
│   └── templates/                   # Component templates
├── package.json
├── tsconfig.json
└── README.md
```

### Available Scripts

```bash
npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to dist/
npm start            # Run production server
npm test             # Run tests
npm run lint         # Lint code
```

### Adding a New Tool

1. Create handler in `src/server/tools/myTool.ts`
2. Create schema in `src/schemas/myTool.json`
3. Register in `src/server/toolRegistry.ts`
4. Update this README

## 🧪 Testing

```bash
npm test
```

Tests use Jest + ts-jest. Test files are located next to source files with `.test.ts` extension.

## 🔐 Security & Privacy

- **No secrets in logs**: The logger automatically redacts sensitive keys (tokens, passwords, API keys)
- **Telemetry opt-in**: Set `ANALYTICS_ENABLED=true` in `.env` to enable (disabled by default)
- **File access**: Tools only access files within the repo root
- **Audit trails**: All operations are logged with trace IDs for auditing

## 🌐 Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PORT` | No | Server port (default: 4000) |
| `FIGMA_TOKEN` | No | Figma Personal Access Token for figmaSync |
| `GITHUB_TOKEN` | No | GitHub token for PR automation |
| `ANALYTICS_ENABLED` | No | Enable telemetry (default: false) |
| `CARBON_VERSION` | No | Carbon version to use (default: latest) |

## 📖 Common Codemods

### `btn-old-to-carbon`
Replaces old `<button className="btn-old">` with Carbon `<Button kind="primary">`

### `class-to-style`
Refactors className styles that match Carbon tokens into token usage

### `replace-grid`
Swaps custom grid with Carbon Grid

### `image-to-asset`
Converts inline base64 images to static assets

## 🤝 Contributing

1. Follow TypeScript best practices
2. Add tests for new tools
3. Update schemas and documentation
4. Keep tools deterministic and idempotent
5. Use dry-run by default for destructive operations

## 📝 License

MIT

## 🔗 Resources

- [Carbon Design System](https://carbondesignsystem.com/)
- [Carbon React Components](https://react.carbondesignsystem.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [TypeScript Documentation](https://www.typescriptlang.org/)

---

Made with ❤️ for the Carbon Design System community