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 repository.

• Issue: #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

   git clone https://github.com/SandeepBaskaran/carbon-mcp.git cd carbon-mcp

2. Install dependencies

   npm install # or pnpm install

3. Configure environment (optional)

   cp .env.example .env # Edit .env to add API keys if needed (FIGMA_TOKEN, GITHUB_TOKEN)

4. Start the server

   npm run dev

   Server will start on http://localhost:4000

5. Test it out

   # 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)

📚 API Reference

Endpoints

Tool Examples

1. Generate Component

Response:

2. Codemod Replace

Response:

3. Search Docs

Response:

4. Token Converter

5. Validate Component

Response:

6. Theme Preview

🔧 Development

Project Structure

Available Scripts

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

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

📖 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

• Carbon React Components

• Model Context Protocol

• TypeScript Documentation

Made with ❤️ for the Carbon Design System community