# MCP串口工具 - AI IDE配置指南
## 概述
本指南帮助你在AI IDE（如Cursor、Claude Desktop、VS Code等）中配置和使用MCP串口工具。
## 配置文件
### 1. Claude Desktop配置
将以下配置保存到Claude Desktop的项目设置中：
```json
{
"mcpServers": [
{
"name": "mcp2serial",
"command": "node D:\\niusulong\\mcp2serial\\dist\\index.js",
"args": ["--config", "D:\\niusulong\\mcp2serial\\config\\ide.json"],
"env": {
"NODE_ENV": "production"
}
}
]
}
```
### 2. Cursor配置
在Cursor的设置中添加：
```json
{
"mcpServers": [
{
"name": "mcp2serial",
"command": "node D:\\niusulong\\mcp2serial\\dist\\index.js",
"args": ["--config", "D:\\niusulong\\mcp2serial\\config\\ide.json"],
"env": {
"NODE_ENV": "production"
}
}
]
}
```
### 3. VS Code 配置
在VS Code中使用MCP扩展，配置 `settings.json`：
```json
{
"mcp.servers": [
{
"name": "mcp2serial",
"command": "node D:\\niusulong\\mcp2serial\\dist\\index.js",
"args": ["--config", "D:\\niusulong\\mcp2serial\\config\\ide.json"]
}
]
}
```
## 工具配置说明
### 基础配置 (config/ide.json)
- **服务器地址**: localhost:3000
- **默认波特率**: 9600
- **数据位**: 8
- **停止位**: 1
- **校验位**: none
- **流控**: none
- **超时**: 5秒
### 可用功能
- **URC检测**: 自动识别和上报URC（如 +CSQ: 23,99）
- **健康检查**: 定期检查系统状态
- **日志记录**: 结构化JSON日志
- **错误处理**: 完善的错误恢复机制
## 使用方法
### 1. 列出可用串口
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "mcp.serial.list",
"params": {}
}
```
### 2. 打开串口
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "mcp.serial.open",
"params": {
"port": "COM1",
"baudrate": 9600,
"data_bits": 8,
"parity": "none",
"stop_bits": 1,
"flow_control": "none"
}
}
```
### 3. 写入数据并读取响应
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "mcp.serial.write",
"params": {
"port": "COM1",
"data": "48656c6c6f", // "Hello" in hex
"timeout_ms": 5000,
"filter_urc": true
}
}
```
### 4. 关闭串口
```json
{
"jsonrpc": "2.0",
"id": 4,
"method": "mcp.serial.close",
"params": {
"port": "COM1"
}
}
```
### 5. 获取端口状态
```json
{
"jsonrpc": "2.0",
"id": 5,
"method": "mcp.serial.status",
"params": {
"port": "COM1"
}
}
```
### 6. 订阅端口事件
```json
{
"jsonrpc": "2.0",
"id": 6,
"method": "mcp.serial.subscribe",
"params": {
"port": "COM1",
"types": ["data", "error", "urc"]
}
}
```
## 常见使用场景
### 1. 与Arduino/ESP32通信
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "mcp.serial.open",
"params": {
"port": "COM3",
"baudrate": 115200,
"data_bits": 8,
"parity": "none",
"stop_bits": 1,
"flow_control": "none"
}
}
```
### 2. 发送AT命令
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "mcp.serial.write",
"params": {
"port": "COM3",
"data": "41544", // "AT" in hex
"timeout_ms": 2000,
"filter_urc": true
}
}
```
### 3. 读取传感器数据
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "mcp.serial.write",
"params": {
"port": "COM3",
"data": "5245444f4e5320", // "READ SENSOR" in hex
"timeout_ms": 3000,
"filter_urc": true
}
}
```
## 错误处理
所有错误都会返回标准的JSON-RPC错误格式：
```json
{
"jsonrpc": "2.0",
"id": "error",
"error": {
"code": -32602,
"message": "Invalid params",
"data": "详细错误信息"
}
}
```
常见错误代码：
- `PORT_NOT_FOUND`: 端口不存在
- `INVALID_CONFIG`: 配置参数无效
- `SYSTEM_ERROR`: 系统内部错误
- `TIMEOUT`: 操作超时
## 注意事项
1. **端口权限**: 确保你的用户有访问串口设备的权限
2. **端口占用**: 确保端口未被其他程序占用
3. **数据格式**: 写入数据必须是十六进制字符串
4. **超时设置**: 根据设备响应特性调整超时时间
## 故障排查
如果遇到问题，可以：
1. 检查串口设备管理器
2. 查看日志文件：`logs/mcp2serial.log`
3. 使用 `mcp.health.status` 检查服务状态
4. 使用 `mcp.serial.list` 验证端口可用性
## 技术支持
- 仓库地址：https://github.com/your-repo/mcp2serial
- 问题反馈：创建Issue并附上日志
- 文档参考：docs/README.md
