Carbon MCP

# 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