# 🔌 MCP STM32 Controller Server / MCP STM32 控制器服务器

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-1.0+-orange.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Control an **STM32 microcontroller** through the **MCP (Model Context Protocol)**. AI assistants can read/write GPIO, control an LED, read ADC, and drive an OLED — all through natural language.
>
> 通过 **MCP（Model Context Protocol）** 协议控制 **STM32 微控制器**。AI 助手可以调用本服务提供的工具来读写 STM32 的 GPIO、控制 LED、读取 ADC、操作 OLED 屏幕等。

---

<!-- ═══════════════════════════════════════════════════════════════ -->
<!--  English                                                       -->
<!-- ═══════════════════════════════════════════════════════════════ -->

## Architecture

```
AI Assistant (Claude) ←→ MCP Server (this program) ←→ UART ←→ STM32 firmware
```

Communication uses a **JSON-line protocol**: one JSON object per line, terminated by `\n`.

---

## Quick Start

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Connect the hardware

- STM32 USART1: PA9 (TX), PA10 (RX)
- Connect to the PC through a USB-TTL module
- Flash the matching firmware on the device (implement the JSON-line protocol described below)

### 3. Start the server

```bash
# auto-detect the serial port
python main.py

# specify a serial port
python main.py --port COM3

# SSE mode (HTTP service)
python main.py --sse --port COM3
```

---

## Tools

| Tool | Description | Arguments |
|------|-------------|-----------|
| `ping` | check whether the STM32 is online | — |
| `set_led` | set the LED brightness | `brightness`: 0-100 |
| `get_led` | read the current LED brightness | — |
| `read_pin` | read a GPIO level | `pin`: "PA0", "PC13", ... |
| `write_pin` | set a GPIO level | `pin` + `value`: 0/1 |
| `read_adc` | read an ADC value | `channel`: 0-2 |
| `oled_clear` | clear the OLED screen | — |
| `oled_print` | print text on the OLED | `x` + `y` + `text` |

## Resources

| URI | Description |
|-----|-------------|
| `stm32://status` | connection status, port info, uptime |

---

## Configuration

Via environment variables or command-line arguments:

| Argument | Env var | Default | Description |
|----------|---------|---------|-------------|
| `--port` | `STM32_PORT` | auto-detect | serial port |
| `--baud` | — | 115200 | baud rate |
| `--sse` | — | false | SSE mode |
| `--sse-port` | — | 8000 | SSE port |

---

## Integrate with Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stm32": {
      "command": "python",
      "args": ["C:/path/to/mcp-stm32-server/main.py", "--port", "COM3"],
      "env": {}
    }
  }
}
```

---

## Wire Protocol (JSON-lines)

Each line is an independent JSON object. The firmware simply echoes a response with the matching `id`.

Request:
```json
{"id":1,"cmd":"set_led","args":{"brightness":75}}
```

Success response:
```json
{"id":1,"status":"ok","data":{"brightness":75}}
```

Error response:
```json
{"id":1,"status":"error","msg":"brightness must be 0-100"}
```

**Firmware contract**: on every received request, reply with one JSON line carrying the same `id`, plus `status` (`"ok"` / `"error"`) and either `data` or `msg`. Boot-log lines that are not valid JSON are skipped by the client automatically.

---

## License

MIT License.

---

<!-- ═══════════════════════════════════════════════════════════════ -->
<!--  中文                                                          -->
<!-- ═══════════════════════════════════════════════════════════════ -->

## 架构

```
AI 助手 (Claude) ←→ MCP Server (本程序) ←→ 串口 ←→ STM32 固件
```

通信使用 **JSON 行协议**，每行一个 JSON 对象，以 `\n` 结尾。

---

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 连接硬件

- STM32 的 USART1：PA9(TX)，PA10(RX)
- 通过 USB-TTL 模块连接电脑
- 在设备端烧录实现下述 JSON 行协议的配套固件

### 3. 启动服务

```bash
# 自动检测串口
python main.py

# 指定串口
python main.py --port COM3

# SSE 模式（HTTP 服务）
python main.py --sse --port COM3
```

---

## 工具列表

| 工具 | 说明 | 参数 |
|------|------|------|
| `ping` | 检测 STM32 在线状态 | 无 |
| `set_led` | 设置 LED 亮度 | `brightness`: 0-100 |
| `get_led` | 读取 LED 亮度 | 无 |
| `read_pin` | 读取 GPIO 电平 | `pin`: "PA0", "PC13" 等 |
| `write_pin` | 设置 GPIO 电平 | `pin` + `value`: 0/1 |
| `read_adc` | 读取 ADC 值 | `channel`: 0-2 |
| `oled_clear` | 清空 OLED 屏幕 | 无 |
| `oled_print` | 在 OLED 上显示文字 | `x` + `y` + `text` |

## 资源

| URI | 说明 |
|-----|------|
| `stm32://status` | 连接状态、串口信息、运行时间 |

---

## 配置

通过环境变量或命令行参数：

| 参数 | 环境变量 | 默认值 | 说明 |
|------|---------|--------|------|
| `--port` | `STM32_PORT` | 自动检测 | 串口号 |
| `--baud` | - | 115200 | 波特率 |
| `--sse` | - | false | SSE 模式 |
| `--sse-port` | - | 8000 | SSE 端口 |

---

## 与 Claude Desktop 集成

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "stm32": {
      "command": "python",
      "args": ["C:/path/to/mcp-stm32-server/main.py", "--port", "COM3"],
      "env": {}
    }
  }
}
```

---

## 协议格式（JSON 行）

每一行是一个独立的 JSON 对象。固件只需回一个 `id` 相同的 JSON 行即可。

请求：
```json
{"id":1,"cmd":"set_led","args":{"brightness":75}}
```

成功响应：
```json
{"id":1,"status":"ok","data":{"brightness":75}}
```

错误响应：
```json
{"id":1,"status":"error","msg":"brightness must be 0-100"}
```

**固件约定**：收到每条请求后，回一行包含相同 `id` 的 JSON，含 `status`（`"ok"` / `"error"`）以及 `data` 或 `msg`。启动时的非 JSON 日志行会被客户端自动跳过。

---

## 许可证

MIT License。