# MCPCamPad

**Repository Path**: supergame/mcp-cam-pad

## Basic Information

- **Project Name**: MCPCamPad
- **Description**: 基于 Flutter 的 Android 平板 App，通过 MCP (Model Context Protocol) 连接小智AI平台，实现语音/文本控制 ESP32-S3 摄像头拍照、定时拍照、状态查询，并接收和浏览照片。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCPCamPad - 平板端 MCP 摄像头控制 App

基于 Flutter 的 Android 平板 App，通过 MCP (Model Context Protocol) 连接小智AI平台，实现语音/文本控制 ESP32-S3 摄像头拍照、定时拍照、状态查询，并接收和浏览照片。

## 系统架构

```
用户说话 → 小智AI音箱 → 小智AI云端 → (MCP WebSocket) → 平板App → (MQTT) → ESP32-S3
                                                                              ↓
用户听到回复 ← 小智AI音箱 ← 小智AI云端 ← (MCP WebSocket) ← 平板App ← (HTTP上传) ← ESP32
```

## 环境要求

- **Flutter**: 3.44.5 (stable)
- **Dart**: 3.12.2
- **Android SDK**: 36+
- **Java JDK**: 17+
- **目标平台**: Android 平板

### 国内镜像配置

```powershell
# Pub 仓库
$env:PUB_HOSTED_URL = 'https://pub.flutter-io.cn'
# Flutter SDK 和引擎
$env:FLUTTER_STORAGE_BASE_URL = 'https://storage.flutter-io.cn'
```

### Android SDK 镜像 (gradle.properties)

```properties
android.sdk.mirror=https://mirrors.tuna.tsinghua.edu.cn/android/repository/
```

### Gradle 镜像 (settings.gradle.kts)

```kotlin
pluginManagement {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
    }
}
```

## 快速开始

### 1. 克隆项目

```bash
git clone <仓库地址>
cd MCPCamPad
```

### 2. 安装依赖

```powershell
$env:PUB_HOSTED_URL = 'https://pub.flutter-io.cn'
$env:FLUTTER_STORAGE_BASE_URL = 'https://storage.flutter-io.cn'
flutter pub get
```

### 3. 配置 Android SDK

确保 `ANDROID_HOME` 环境变量指向 Android SDK 路径：

```powershell
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "D:\android", "User")
flutter config --android-sdk D:\android
```

### 4. 运行分析检查

```powershell
flutter analyze
```

### 5. 部署到平板

```powershell
# 查看连接的设备
flutter devices

# 运行到指定设备
flutter run --debug -d <设备ID>
```

## 项目结构

```
lib/
├── main.dart                          # App入口
├── app.dart                           # 根组件 + 底部导航
├── config/
│   └── constants.dart                 # 常量配置
├── models/
│   ├── connection_config.dart         # 连接配置模型
│   └── photo.dart                     # 照片数据模型
├── services/
│   ├── mcp_server_service.dart        # MCP WebSocket 客户端 (连接小智AI)
│   ├── mqtt_service.dart              # MQTT 客户端 (控制ESP32)
│   └── http_image_server.dart         # HTTP 图片接收服务器
├── providers/
│   └── app_state_provider.dart        # 全局状态管理 (Provider)
└── pages/
    ├── control_page.dart              # 控制页面 (拍照/定时)
    ├── settings_page.dart             # 设置页面 (连接配置)
    ├── photo_gallery_page.dart        # 照片浏览页面
    └── photo_detail_page.dart         # 照片详情页面
android/
└── app/src/main/AndroidManifest.xml   # Android 清单 (已配置网络权限)
```

## 核心服务说明

### MCP 服务 (MCP WebSocket Client)

- 以小智AI平台的 MCP 接入点为目标（WebSocket 客户端模式）
- 连接后注册工具 `bemfa_mqtt_control`
- 支持三个操作：`capture`（拍照）、`set_timer`（定时）、`get_status`（查询）
- 支持自动重连（断线后5秒重试）

### MQTT 服务

- 连接巴法云 MQTT Broker: `mqtt.bemfa.com:9501`
- 使用私钥 (Private Key) 作为 ClientId 认证
- 通过主题 `fhq` 发布控制指令和接收状态
- 启动时自动发送 `set_upload_url` 告知 ESP32 上传地址

### HTTP 图片接收服务

- 接收 ESP32 通过 HTTP POST 上传的照片
- 默认端口: 8080
- 上传接口: `POST /upload` (binary JPEG)
- 健康检查: `GET /health`
- 照片列表: `GET /photos`
- 支持 CORS 跨域

## 配置说明

默认配置已内置（设置页面可修改）：

| 配置项 | 默认值 |
|--------|--------|
| 巴法云 MQTT 地址 | mqtt.bemfa.com:9501 |
| 巴法云私钥 | 6ab5a7ead31844b997c0f38411dec607 |
| 控制主题 | fhq |
| 状态主题 | fhq |
| 图片主题 | fhq |
| 小智AI MCP 接入点 | wss://api.xiaozhi.me/mcp/?token=... |
| HTTP 图片服务器端口 | 8080 |

## 构建 APK

```powershell
# Debug APK
flutter build apk --debug

# Release APK (需要签名配置)
flutter build apk --release
```

## 通信协议

### MQTT 指令格式

```json
// 拍照
{"cmd":"capture","seq":"1234567890123"}

// 定时拍照
{"cmd":"set_timer","value":30,"seq":"1234567890123"}

// 查询状态
{"cmd":"get_status","seq":"1234567890123"}

// 设置上传地址 (启动时自动发送)
{"cmd":"set_upload_url","url":"http://192.168.1.211:8080/upload"}
```

### ESP32 响应格式

```json
// 拍照完成
{"cmd":"captured","seq":"1234567890123"}
```

## ESP32 端要点

ESP32-S3 需要：
1. 连接巴法云 MQTT (`mqtt.bemfa.com:9501`)，使用同一私钥
2. 订阅控制主题（如 `fhq`）
3. 收到 `capture` 指令后拍照并通过 HTTP POST 上传到平板的 `/upload` 接口
4. 拍照完成后通过 MQTT 发布 `captured` 响应

## 常见问题

**Q: MQTT 连接失败**
A: 确认巴法云私钥正确，可在 bemfa.com 控制台查看

**Q: MCP 工具注册后小智AI不调用**
A: 确认 MCP 接入点地址正确，后台刷新查看工具列表

**Q: ESP32 拍照后照片传不过来**
A: 确认平板和 ESP32 在同一网络，检查 HTTP 服务器端口（默认8080）未被防火墙拦截

## License

MIT