# RoboParts MCP Server

RoboParts MCP (Model Context Protocol) Server 是一个标准化接口，允许 AI Agent（如 Claude、GPT 等）通过 MCP 协议查询机器人零部件数据。AI Agent 可以搜索零部件、获取详细信息、检查兼容性、获取应用推荐并导出 BOM 清单。

## 项目介绍

本 MCP Server 基于 `@modelcontextprotocol/sdk` 构建，使用 stdio 传输协议，直接读取本地 RoboParts API 数据文件（JSON 格式），为 AI Agent 提供结构化的机器人零部件数据查询能力。

### 支持的数据品类

| 品类 | 标识 | 数据文件 | 说明 |
|------|------|----------|------|
| 执行器 | actuators | actuators.json | 舵机、电机控制器等 |
| 传感器 | sensors | sensors.json | LiDAR、IMU、触觉传感器等 |
| 芯片 | chips | chips.json | 计算芯片、MCU 等 |
| 通信协议 | protocols | protocols.json | EtherCAT、CANopen 等 |
| 机器人平台 | platforms | platforms.json | 人形、四足等机器人平台 |
| 大语言模型 | llms | llms.json | GPT-4o、Claude、VLA 模型等 |
| 接口 | interfaces | interfaces.json | USB、MIPI CSI、PCIe 等 |

## 安装说明

### 前置条件

- Node.js >= 18.0.0
- RoboParts API 数据文件位于 `../api/` 目录

### 安装步骤

```bash
cd mcp-server
npm install
```

这将安装 `@modelcontextprotocol/sdk` 依赖。

## 配置说明

### 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加以下配置：

```json
{
  "mcpServers": {
    "roboparts": {
      "command": "node",
      "args": [
        "C:\\Users\\xing\\Desktop\\robopart\\mcp-server\\index.js"
      ]
    }
  }
}
```

> 如果使用 npx，也可以配置为：
> ```json
> {
>   "mcpServers": {
>     "roboparts": {
>       "command": "npx",
>       "args": [
>         "C:\\Users\\xing\\Desktop\\robopart\\mcp-server\\index.js"
>       ]
>     }
>   }
> }
> ```

配置完成后重启 Claude Desktop，即可在对话中使用 RoboParts 工具。

### 在其他 MCP 客户端中配置

任何支持 MCP 协议的客户端均可通过 stdio 方式连接本 Server。启动命令：

```bash
node index.js
# 或
npm start
```

## 可用工具列表

### 1. search_components - 搜索机器人零部件

搜索零部件，支持按品类、关键词、数量筛选。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | 品类：actuators/sensors/chips/protocols/platforms/llms/interfaces |
| keyword | string | 否 | 搜索关键词（匹配名称、厂商、类型、描述等） |
| limit | number | 否 | 返回数量限制，默认 10 |

**返回：** 零部件数组（id, name, category, manufacturer, key_specs）

### 2. get_component_detail - 获取零部件详情

获取单个零部件的完整规格信息。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 是 | 零部件 ID，如 "ACT-001" |
| category | string | 是 | 品类 |

**返回：** 完整的零部件数据对象

### 3. check_compatibility - 检查兼容性

检查两个零部件之间的兼容性，基于协议、接口、电压等维度。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| component1_id | string | 是 | 零件 1 ID |
| component1_category | string | 是 | 零件 1 品类 |
| component2_id | string | 是 | 零件 2 ID |
| component2_category | string | 是 | 零件 2 品类 |

**兼容性检查规则：**

- **执行器 + 芯片**：检查协议匹配（如 DYNAMIXEL Protocol 需要 RS485/TTL 接口）+ 电压范围
- **芯片 + 传感器**：检查接口兼容（如 I2C/SPI/UART/USB）
- **协议 + 接口**：检查物理层兼容性（如 EtherCAT 需要以太网接口）
- **通用检查**：应用场景匹配、ROS2 支持情况

**返回：** 兼容性报告（compatible: boolean, reasons: string[], warnings: string[]）

### 4. recommend_for_application - 应用场景推荐

根据应用场景和预算推荐最优零部件组合。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| application | string | 是 | 应用场景：humanoid/quadruped/robot_arm/amr/industrial |
| budget | number | 否 | 预算上限（CNY） |
| count | number | 否 | 每个品类推荐数量，默认 3 |

**返回：** 推荐组合（actuators, sensors, chips, controllers 各自 top 推荐）

### 5. export_bom - 导出 BOM 清单

从选定的零部件列表导出 BOM（Bill of Materials）清单，计算总成本并提供供应商建议。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_name | string | 是 | 项目名称 |
| items | array | 是 | 零部件列表，每项包含 {id, category, quantity} |

**返回：** BOM 对象（项目名、总成本 USD/CNY、总模块数、items 详情、供应商建议）

## 使用示例

### 示例 1：搜索舵机

```
用户：帮我搜索 DYNAMIXEL 舵机
AI Agent 调用：search_components({ category: "actuators", keyword: "DYNAMIXEL", limit: 5 })
```

### 示例 2：获取零部件详情

```
用户：查看 ACT-001 的详细参数
AI Agent 调用：get_component_detail({ id: "ACT-001", category: "actuators" })
```

### 示例 3：检查兼容性

```
用户：DYNAMIXEL XM540-W270-T 和 NVIDIA Jetson Orin NX 兼容吗？
AI Agent 调用：check_compatibility({
  component1_id: "ACT-001",
  component1_category: "actuators",
  component2_id: "CHIP-001",
  component2_category: "chips"
})
```

### 示例 4：应用推荐

```
用户：我要做一个人形机器人，预算 50000 元，推荐零部件
AI Agent 调用：recommend_for_application({
  application: "humanoid",
  budget: 50000,
  count: 3
})
```

### 示例 5：导出 BOM

```
用户：帮我导出一个项目的 BOM，包括 2 个 ACT-001 舵机和 1 个 CHIP-001 芯片
AI Agent 调用：export_bom({
  project_name: "人形机器人手臂原型",
  items: [
    { id: "ACT-001", category: "actuators", quantity: 2 },
    { id: "CHIP-001", category: "chips", quantity: 1 }
  ]
})
```

## 数据来源

数据文件位于 `../api/` 目录，包含以下 JSON 文件：

- `actuators.json` - 执行器数据（147 条）
- `sensors.json` - 传感器数据（42 条）
- `chips.json` - 芯片数据（95 条）
- `protocols.json` - 通信协议数据（64 条）
- `platforms.json` - 机器人平台数据（23 条）
- `llms.json` - 大语言模型数据（27 条）
- `interfaces.json` - 接口数据（14 条）
- `compatibility_matrix.json` - 兼容性规则矩阵

## 技术架构

```
┌─────────────────┐     stdio      ┌──────────────────┐
│   AI Agent      │◄──────────────►│  MCP Server      │
│ (Claude/GPT)    │   MCP Protocol │  (index.js)      │
└─────────────────┘                └────────┬─────────┘
                                            │ readFileSync
                                            ▼
                                   ┌──────────────────┐
                                   │  Local JSON Data │
                                   │  (../api/*.json) │
                                   └──────────────────┘
```

## 许可证

MIT License