@toponextech/smartembed-mcp-server/README.md

MCP server for intelligent embedded development with PlatformIO - AI-powered project creation, error diagnosis, and device detection

# SmartEmbed MCP Server

[![npm version](https://badge.fury.io/js/@toponextech%2Fsmartembed-mcp-server.svg)](https://badge.fury.io/js/@toponextech%2Fsmartembed-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@toponextech%2Fsmartembed-mcp-server)](https://nodejs.org/)

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

## 🚀 快速安装

### 使用 npm（推荐）

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

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

### 在 Cline 中配置

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

```json
{
  "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`：

```typescript
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`：

```typescript
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 映射：

```typescript
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` 添加新的项目类型：

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

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

## 🔧 开发和测试

### 安装依赖
```bash
npm install
```

### 编译 TypeScript
```bash
npm run build
```

### 运行测试
```bash
npm test
```

### 开发模式
```bash
npm run dev
```

## 📋 知识库维护指南

### 1. 保持知识库更新

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

### 2. 知识库质量标准

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

### 3. 测试新增内容

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

```typescript
// 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](LICENSE) 文件了解详情。

## 📈 版本历史

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

## 📚 相关文档

- [发布指南 (中文)](PUBLISHING_ZH.md) - 如何发布和维护此项目
- [发布指南 (英文)](PUBLISHING.md) - Publishing and maintenance guide

---

## 🎯 使用示例

### 通过 Cline 使用

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

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

或者使用本地安装：

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

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

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

## 📊 知识库统计

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

---

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