Carbon MCP

碳mcp

碳设计系统的本地MCP（模型上下文协议）服务器——用于内部演示和生产使用的高级MVP。

🚧 状态：已向Carbon提交提案

这个项目是 提案 提交给 碳设计系统 存储库。

• 问题: #20855
• 状态：等待维护人员的反馈
• 提议的：添加到Carbon monorepo或创建官方 carbon-design-system/carbon-mcp 仓库

Carbon团队正在审查该提案。一旦收到反馈，代码将相应地进行调整。

______________________________________________________________________

🚀 快速入门

1. 克隆仓库

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

1. 安装依赖项

   npm install
   # or
   pnpm install

1. 配置环境 （可选）

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

1. 启动服务器

   npm run dev

服务器将于启动 http://localhost:4000

1. 测试一下

   # 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}'

🛠️ 工具（MVP）

开发者工具

• generateComponent --生成Carbon React组件+故事书故事+测试（默认模拟运行）
• codemodReplace --应用codemods将现有组件转换为碳当量（干运行默认值）
• validateComponent --根据碳模式和可访问性指南验证组件
• tokenConverter --将设计标记（JSON）转换为CSS变量、SCSS映射和JS标记

文档工具

• searchDocs --通过语义/关键字匹配搜索本地Carbon文档索引

设计器工具

• themePreview --为Carbon主题变体（浅色/深色/自定义）生成静态HTML预览
• figmaSync --Figma令牌同步支架（环境中需要Figma_token）

🔒 安全与破坏性操作

所有破坏性更改（写入磁盘、修改文件）都需要：

• confirm_destructive: true
• dry_run: false

推荐工作流程：

1. 与一起跑步 dry_run: true （默认）预览更改
2. 查看输出/补丁
3. 再次运行 dry_run: false 和 confirm_destructive: true 应用

示例：生成组件（安全工作流）

# 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 参考

端点

工具示例

1.生成组件

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

答复：

{
  "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替换

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

答复：

{
  "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.搜索文档

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

答复：

{
  "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.令牌转换器

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

5.验证组件

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

答复：

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

6.主题预览

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

🔧 发展

项目结构

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

可用脚本

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

添加新工具

1. 在中创建处理程序 src/server/tools/myTool.ts
2. 在中创建架构 src/schemas/myTool.json
3. 注册 src/server/toolRegistry.ts
4. 更新此自述文件

🧪 测试

npm test

测试使用Jest+ts Jest。测试文件位于源文件旁边 .test.ts 扩展。

🔐 安全与隐私

• 日志中没有秘密：记录器自动编辑敏感密钥（令牌、密码、API密钥）
• 遥测选择加入：设置 ANALYTICS_ENABLED=true 在 .env 启用（默认情况下禁用）
• 文件访问：工具仅访问repo根目录中的文件
• 审核跟踪：所有操作都记录了跟踪ID以供审核

🌐 环境变量

📖 常见代码模块

btn-old-to-carbon

替换旧 ` 含碳 `

class-to-style

将Carbon代币与代币使用相匹配的Refactors className样式

replace-grid

将自定义网格替换为碳网格

image-to-asset

将内联base64图像转换为静态资源

🤝 贡献

1. 遵循TypeScript的最佳实践
2. 为新工具添加测试
3. 更新架构和文档
4. 保持工具的确定性和幂等性
5. 破坏性操作默认使用干运行

📝 许可证

麻省理工学院

🔗 资源

• 碳设计系统
• 碳反应组件
• 模型上下文协议
• TypeScript文档

______________________________________________________________________

由以下材料制成❤️ 碳设计系统社区