SmartEmbed MCP Server

SmartEmbed MCP Server 是一个基于 Model Context Protocol (MCP) 的智能嵌入式开发助手服务器，通过 AI 驱动的方式简化嵌入式开发流程。它集成了丰富的嵌入式开发知识库，可以智能分析项目需求、诊断错误并提供专业建议。

🚀 快速安装

使用 npm（推荐）

# 全局安装
npm install -g @toponextech/smartembed-mcp-server

# 或使用 npx 直接运行
npx @toponextech/smartembed-mcp-server --help

在 Cline 中配置

在 VS Code 的 Cline 扩展设置中添加：

{
  "mcpServers": {
    "smartembed": {
      "command": "npx",
      "args": ["@toponextech/smartembed-mcp-server"]
    }
  }
}

🚀 核心特性

三大智能工具

1. smartembed_project - 自然语言项目创建

   • 支持中英文混合输入
   • 智能识别开发板类型和项目需求
   • 自动生成完整的项目结构和代码模板

2. smartembed_diagnose - 智能错误诊断

   • 解析编译错误并提供精准解决方案
   • 包含 15+ 种常见错误模式
   • 提供具体的代码修复示例

3. smartembed_suggest - 设备识别与智能建议

   • 自动识别连接的开发板
   • 提供上下文感知的开发建议
   • 根据项目阶段推荐下一步操作

📚 知识库架构

知识库文件组织结构

smartembed-mcp-server/src/tools/knowledge/
├── best-practices-kb.ts    # 最佳实践知识库
├── diagnostic-kb.ts        # 错误诊断知识库
└── index.ts                # 知识库导出文件

1. 最佳实践知识库 (src/tools/knowledge/best-practices-kb.ts)

知识库包含 10 个类别的最佳实践：

• BOARD_CONFIG - 开发板配置
• MEMORY_OPTIMIZATION - 内存优化
• POWER_MANAGEMENT - 电源管理
• DEBUGGING - 调试技巧（注：实际为 DEBUGGING，不是 DEBUG_TECHNIQUES）
• CONNECTIVITY - 连接性配置
• SENSORS - 传感器使用
• LIBRARIES - 库推荐（注：实际为 LIBRARIES，不是 LIBRARY_RECOMMENDATIONS）
• PROJECT_STRUCTURE - 项目结构
• SECURITY - 安全实践
• PERFORMANCE - 性能优化

每个最佳实践包含：

• id - 唯一标识符
• category - 所属类别
• title - 标题
• description - 详细描述
• recommendations - 建议列表
• codeExamples - 代码示例
• relatedBoards - 相关开发板
• tags - 标签

2. 诊断知识库 (src/tools/knowledge/diagnostic-kb.ts)

包含常见错误的诊断和解决方案：

• 编译错误模式匹配
• 库依赖问题解决
• 内存溢出处理
• 权限问题修复
• 硬件连接问题

每个诊断条目包含：

• errorPattern - 错误模式（正则表达式或字符串）
• errorType - 错误类型（引用自 error-parser.ts 的 ErrorType 枚举）
• solutions - 解决方案数组
• tags - 相关标签

每个解决方案（DiagnosticSolution）包含：

• description - 问题描述
• steps - 解决步骤数组
• codeExample - 修复代码示例（可选）
• relatedDocs - 相关文档链接（可选）
• applicableBoards - 适用的开发板（可选）

3. 设备识别数据库 (src/tools/parsers/device-parser.ts)

内置 VID:PID 数据库，支持识别：

• ESP32 系列
• Arduino 系列
• STM32 系列
• RP2040 (Raspberry Pi Pico)
• 其他主流开发板

设备解析器包含：

• VID:PID 映射表（VID_PID_MAP）
• 设备描述模式匹配
• 设备识别算法
• 连接建议生成

🗂️ 项目文件结构

smartembed-mcp-server/
├── src/
│   ├── index.ts                           # 主入口文件
│   ├── server.ts                          # MCP 服务器实现
│   └── tools/                             # 核心工具模块
│       ├── types.ts                       # 类型定义
│       ├── registry.ts                    # 工具注册系统
│       ├── index.ts                       # 工具导出文件
│       ├── project.ts                     # 项目创建工具
│       ├── diagnose.ts                    # 错误诊断工具
│       ├── suggest.ts                     # 智能建议工具
│       ├── parsers/                       # 解析器模块
│       │   ├── nlp-parser.ts             # 自然语言解析器
│       │   ├── error-parser.ts           # 错误解析器
│       │   ├── device-parser.ts          # 设备解析器
│       │   └── index.ts
│       ├── knowledge/                     # 知识库模块 🔥
│       │   ├── best-practices-kb.ts      # 最佳实践知识库
│       │   ├── diagnostic-kb.ts          # 错误诊断知识库
│       │   └── index.ts
│       ├── generators/                    # 生成器模块
│       │   ├── command-generator.ts      # 命令生成器
│       │   ├── suggestion-generator.ts   # 建议生成器
│       │   ├── context-suggestion-generator.ts # 上下文建议生成器
│       │   └── index.ts
│       └── templates/                     # 模板生成器
│           ├── template-generator.ts     # 文件模板生成器
│           └── index.ts
├── tests/                                 # 测试文件
├── dist/                                  # 编译输出
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

🛠️ 如何自定义和扩展知识库

1. 添加新的最佳实践

编辑 src/tools/knowledge/best-practices-kb.ts：

export const BEST_PRACTICES_KB: BestPractice[] = [
  // 添加新的最佳实践
  {
    id: 'your_practice_id',
    category: PracticeCategory.BOARD_CONFIG, // 选择合适的类别
    title: '您的实践标题',
    description: '详细描述这个最佳实践',
    recommendations: [
      '建议1：具体的操作步骤',
      '建议2：注意事项',
      '建议3：优化技巧'
    ],
    codeExamples: [
      {
        title: '示例代码标题',
        language: 'cpp', // 或 'ini', 'yaml' 等
        code: `// 您的示例代码
void setup() {
  // 初始化代码
}`
      }
    ],
    relatedBoards: ['esp32', 'esp8266'], // 相关开发板
    tags: ['wifi', 'optimization'] // 相关标签
  },
  // ... 现有的最佳实践
];

2. 扩展错误诊断库

编辑 src/tools/knowledge/diagnostic-kb.ts：

export const DIAGNOSTIC_KB: DiagnosticEntry[] = [
  // 添加新的错误模式
  {
    errorPattern: /your error pattern/i, // 使用正则表达式
    errorType: 'compilation', // 或 'library', 'memory' 等
    solutions: [
      {
        title: '解决方案标题',
        steps: [
          '步骤1：检查某某配置',
          '步骤2：修改某某文件',
          '步骤3：运行某某命令'
        ],
        commands: [
          'pio lib install "library-name"',
          'pio run -t clean'
        ],
        codeExample: `// 修复后的代码示例
#include <CorrectHeader.h>`,
        documentationUrl: 'https://docs.link'
      }
    ]
  },
  // ... 现有的诊断条目
];

3. 添加新的开发板支持

编辑 src/tools/parsers/device-parser.ts 中的 VID:PID 映射：

private readonly VID_PID_MAP = new Map<string, BoardInfo>([
  // 添加新的开发板
  ['XXXX:YYYY', { 
    board: 'your_board_name', 
    confidence: 'high',
    description: '开发板描述'
  }],
  // ... 现有的映射
]);

4. 自定义项目模板

编辑 src/tools/templates/template-generator.ts 添加新的项目类型：

private generateMainCpp(board: string, projectType: string): string {
  // 添加新的项目类型判断
  if (projectType === 'your-project-type') {
    return `#include <Arduino.h>
// 您的项目特定代码模板
void setup() {
  // 初始化代码
}

void loop() {
  // 主循环代码
}`;
  }
  // ... 现有的模板逻辑
}

🔧 开发和测试

安装依赖

npm install

编译 TypeScript

npm run build

运行测试

npm test

开发模式

npm run dev

📋 知识库维护指南

1. 保持知识库更新

• 定期收集新的错误模式和解决方案
• 跟踪 PlatformIO 和各开发板的更新
• 添加社区贡献的最佳实践

2. 知识库质量标准

• 准确性：所有解决方案必须经过测试验证
• 完整性：包含详细的步骤和代码示例
• 时效性：标注适用的版本和更新日期
• 可读性：使用清晰的中文描述

3. 测试新增内容

为新增的知识库内容编写测试：

// tests/knowledge.test.ts
describe('Custom Knowledge Base', () => {
  it('should provide solution for new error pattern', () => {
    const error = 'your new error message';
    const solutions = findSolutions(error, 'compilation');
    expect(solutions).toHaveLength(1);
    expect(solutions[0].title).toBe('期望的解决方案标题');
  });
});

🤝 贡献指南

欢迎提交知识库改进！请确保：

1. 新增内容符合现有格式
2. 包含实际可用的代码示例
3. 添加相应的单元测试
4. 更新相关文档

📄 许可证

MIT License - 查看 LICENSE 文件了解详情。

📈 版本历史

查看 CHANGELOG.md 了解详细的版本更新历史。

📚 相关文档

• 发布指南 (中文) - 如何发布和维护此项目
• 发布指南 (英文) - Publishing and maintenance guide

🎯 使用示例

通过 Cline 使用

在 VS Code 中配置 Cline 的 MCP 服务器（推荐使用 npx）：

{
  "mcpServers": {
    "smartembed": {
      "command": "npx",
      "args": ["@toponextech/smartembed-mcp-server"]
    }
  }
}

或者使用本地安装：

{
  "mcpServers": {
    "smartembed": {
      "command": "@toponextech/smartembed-mcp-server"
    }
  }
}

然后在 Cline 中使用自然语言命令：

• "帮我创建一个 ESP32 的温度传感器项目"
• "诊断这个编译错误：fatal error: DHT.h: No such file or directory"
• "识别我连接的开发板"

📊 知识库统计

• 最佳实践条目：10+ 类别，50+ 条建议
• 错误诊断模式：15+ 种常见错误
• 支持的开发板：15+ 种主流开发板
• 代码示例：100+ 个实用代码片段

更多详情请查看项目文档或联系 Toponex 团队。